Initial set of instructions for setting up Docsify

author: Dave Tang <davetingpongtang@gmail.com> 2026-06-23 09:44:07 +0900
committer: Dave Tang <davetingpongtang@gmail.com> 2026-06-23 09:44:07 +0900
commit: e28c074e15dd093f3acd7a3cce10afae149003cd (patch)
tree: 6bef6a7f865c3531082f94c9a6d35979c94999ea
2 files changed, 476 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4b32e46
--- /dev/null
+++ b/README.md
@@ -0,0 +1,283 @@
+# Docsify: Self-Hosted Setup on Apache 2
+
+A complete guide to running Docsify on Apache 2 with no external CDN dependencies. We follow the [manual creation](https://docsify.js.org/#/quickstart?id=manual-initialization) but download the JavaScript and CSS files locally so we don't have to worry if the domain cdn.jsdelivr.net get seized (who knows what's going to happen in the future).
+
+---
+
+## Prerequisites
+
+- Apache 2.4+
+- `curl` (for downloading assets)
+
+---
+
+## Directory Structure
+
+The final layout this guide produces, relative to your document root:
+
+```
+./
+├── index.html          ← Docsify entry point
+├── README.md           ← Homepage content
+├── _sidebar.md         ← Sidebar navigation
+├── getting-started.md  ← Example page
+└── assets/
+    ├── js/
+    │   ├── docsify.min.js
+    │   └── search.min.js
+    └── css/
+        └── vue.css
+```
+
+All commands in this guide assume you have already `cd`'d into your document root.
+
+---
+
+## Step 1: Create the Directory Structure
+
+```bash
+mkdir -p assets/js
+mkdir -p assets/css
+```
+
+---
+
+## Step 2: Download Docsify Assets
+
+All files are downloaded from jsDelivr once and served locally thereafter. See all [docsify CDN files](https://cdn.jsdelivr.net/npm/docsify@4/lib/) on jsDelivr.
+
+```bash
+# Docsify core
+curl -L "https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js" \
+  -o assets/js/docsify.min.js
+
+# Search plugin
+curl -L "https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js" \
+  -o assets/js/search.min.js
+
+# Theme (Vue — clean, light)
+curl -L "https://cdn.jsdelivr.net/npm/docsify@4/themes/vue.css" \
+  -o assets/css/vue.css
+```
+
+### Alternative Themes
+
+Replace `vue.css` in the command above with any of the following if preferred; see all [themes](https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/themes/).
+
+* buble.css
+* dark.css
+* dolphin.css
+* pure.css
+* vue.css
+
+### Optional: Syntax Highlighting
+
+If your documentation includes fenced code blocks, download Prism and the language components you need:
+
+```bash
+# Prism core (required)
+curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js" \
+  -o assets/js/prism-core.min.js
+
+# Language components — add as many as needed
+curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js" \
+  -o assets/js/prism-bash.min.js
+
+curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js" \
+  -o assets/js/prism-yaml.min.js
+
+curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-javascript.min.js" \
+  -o assets/js/prism-javascript.min.js
+```
+
+Then add each `<script>` tag for these files to `index.html` (see Step 3).
+
+---
+
+## Step 3: Create `index.html`
+
+Create `index.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>My Docs</title>
+  <link rel="stylesheet" href="assets/css/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'My Docs',
+      loadSidebar: true,   // enables _sidebar.md
+      subMaxLevel: 2,      // auto-generate H2 entries in sidebar
+      search: 'auto'       // enables the search plugin
+    }
+  </script>
+  <script src="assets/js/docsify.min.js"></script>
+  <script src="assets/js/search.min.js"></script>
+
+  <!-- Remove the lines below if you did not download Prism -->
+  <script src="assets/js/prism-core.min.js"></script>
+  <script src="assets/js/prism-bash.min.js"></script>
+  <script src="assets/js/prism-yaml.min.js"></script>
+  <script src="assets/js/prism-javascript.min.js"></script>
+</body>
+</html>
+```
+
+> **Note:** Docsify uses hash-based routing by default, producing URLs like
+> `/docs/#/page-name`. This requires no Apache configuration whatsoever.
+
+---
+
+## Step 4: Create Boilerplate Content
+
+### Homepage — `README.md`
+
+Docsify uses `README.md` in each directory as its index page, just like GitHub.
+
+Create `README.md`:
+
+```markdown
+# Welcome
+
+This is the home page of your documentation site.
+Edit `README.md` to replace this content.
+
+## Quick Links
+
+- [Getting Started](getting-started.md)
+```
+
+### Sidebar — `_sidebar.md`
+
+The sidebar lists your pages and their navigation structure.
+
+Create `_sidebar.md`:
+
+```markdown
+- [Home](/)
+- [Getting Started](getting-started.md)
+```
+
+Add a new `- [Title](filename.md)` entry here each time you create a new page.
+
+### Example Page — `getting-started.md`
+
+Create `getting-started.md`:
+
+```markdown
+# Getting Started
+
+This is an example page. Replace this content with your own documentation.
+
+## Section One
+
+Write your content here using standard Markdown.
+
+## Section Two
+
+Docsify will automatically generate sidebar anchors for H2 headings
+when `subMaxLevel: 2` is set in `index.html`.
+```
+
+---
+
+## Step 5: Set File Permissions
+
+Since you are creating these files yourself, you already own them. Just ensure they
+are readable by Apache:
+
+```bash
+find . -type f -exec chmod 644 {} \;
+find . -type d -exec chmod 755 {} \;
+```
+
+---
+
+## Apache Configuration
+
+No Apache configuration is required. Docsify's default hash-based routing means every
+request is for a real file (`index.html`, a `.md` file, or an asset) — Apache serves
+them as ordinary static files without any rewrite rules or special directives.
+
+---
+
+## Verify the Setup
+
+After completing the steps above, confirm the file layout looks correct:
+
+```bash
+find . -not -path '*/\.*' | sort
+```
+
+Expected output:
+
+```
+.
+./README.md
+./_sidebar.md
+./assets
+./assets/css
+./assets/css/vue.css
+./assets/js
+./assets/js/docsify.min.js
+./assets/js/search.min.js
+./getting-started.md
+./index.html
+```
+
+Then open `http://your-server/docs/` in a browser. You should see the rendered
+homepage with a sidebar and search bar — no external requests are made.
+
+---
+
+## Adding New Pages
+
+1. Create a `.md` file in the docs directory (or a subdirectory).
+2. Add a corresponding entry to `_sidebar.md`.
+
+Example for a new page `reference.md`:
+
+```markdown
+- [Home](/)
+- [Getting Started](getting-started.md)
+- [Reference](reference.md)
+```
+
+For subdirectories, nest entries with indentation:
+
+```markdown
+- [Home](/)
+- [Getting Started](getting-started.md)
+- **Advanced**
+  - [Configuration](advanced/configuration.md)
+  - [Deployment](advanced/deployment.md)
+```
+
+---
+
+## Upgrading Docsify
+
+Since files are self-hosted, upgrades are manual. Re-run the `curl` commands from
+Step 2 with a specific version to update:
+
+```bash
+# Pin to a specific version (replace 4.13.1 with the target version)
+curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/docsify.min.js" \
+  -o assets/js/docsify.min.js
+
+curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/plugins/search.min.js" \
+  -o assets/js/search.min.js
+
+curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/themes/vue.css" \
+  -o assets/css/vue.css
+```
+
+Check the [Docsify releases page](https://github.com/docsifyjs/docsify/releases)
+for the latest version number before upgrading.
diff --git a/scripts/setup.sh b/scripts/setup.sh
new file mode 100755
index 0000000..d3d188e
--- /dev/null
+++ b/scripts/setup.sh
@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# setup-docsify.sh — Bootstrap a self-hosted Docsify site on Apache 2.
+#
+# Run this script from your Apache document root:
+#   cd /path/to/docroot
+#   bash setup-docsify.sh [--with-prism]
+#
+# Options:
+#   --with-prism   Also download Prism and enable syntax highlighting in index.html
+
+set -euo pipefail
+
+# ── Configuration ───────────────────────────────────────────────────────────────
+# Use "4" for the latest 4.x release, or pin to a specific version e.g. "4.13.1"
+DOCSIFY_VERSION="4"
+PRISM=false
+
+# ── Argument parsing ────────────────────────────────────────────────────────────
+for arg in "$@"; do
+  case "$arg" in
+    --with-prism) PRISM=true ;;
+    *) echo "Unknown option: $arg" >&2; exit 1 ;;
+  esac
+done
+
+# ── Output helpers ──────────────────────────────────────────────────────────────
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+step() { echo -e "\n${BLUE}${BOLD}==> $1${NC}"; }
+ok()   { echo -e "  ${GREEN}✓${NC}  $1"; }
+die()  { echo -e "  ${RED}✗${NC}  $1" >&2; exit 1; }
+
+# ── Preflight checks ────────────────────────────────────────────────────────────
+step "Preflight checks"
+
+command -v curl &>/dev/null \
+  || die "curl is required but not found. Install curl and try again."
+ok "curl $(curl --version | head -1 | awk '{print $2}')"
+
+if [[ -f index.html ]]; then
+  echo -e "  ${RED}!${NC}  index.html already exists in: $(pwd)"
+  echo -e "       This script will overwrite index.html and all boilerplate .md files."
+  read -r -p "       Continue? [y/N] " reply
+  [[ "${reply,,}" == "y" ]] || { echo "Aborted."; exit 0; }
+fi
+
+echo -e "  Working in: $(pwd)"
+
+# ── Step 1: Directories ─────────────────────────────────────────────────────────
+step "Step 1 — Creating directory structure"
+
+mkdir -p assets/js assets/css
+ok "assets/js/"
+ok "assets/css/"
+
+# ── Step 2: Download Docsify assets ─────────────────────────────────────────────
+step "Step 2 — Downloading Docsify assets"
+
+CDN="https://cdn.jsdelivr.net/npm"
+
+fetch() {
+  local url="$1" dest="$2"
+  curl -sL --fail "$url" -o "$dest" || die "Failed to download: $url"
+  ok "$dest"
+}
+
+fetch "${CDN}/docsify@${DOCSIFY_VERSION}/lib/docsify.min.js"        assets/js/docsify.min.js
+fetch "${CDN}/docsify@${DOCSIFY_VERSION}/lib/plugins/search.min.js" assets/js/search.min.js
+fetch "${CDN}/docsify@${DOCSIFY_VERSION}/themes/vue.css"             assets/css/vue.css
+
+if [[ "$PRISM" == true ]]; then
+  echo ""
+  echo "  Downloading Prism syntax highlighting..."
+  fetch "${CDN}/prismjs@1/components/prism-core.min.js"        assets/js/prism-core.min.js
+  fetch "${CDN}/prismjs@1/components/prism-bash.min.js"        assets/js/prism-bash.min.js
+  fetch "${CDN}/prismjs@1/components/prism-yaml.min.js"        assets/js/prism-yaml.min.js
+  fetch "${CDN}/prismjs@1/components/prism-javascript.min.js"  assets/js/prism-javascript.min.js
+fi
+
+# ── Step 3: index.html ──────────────────────────────────────────────────────────
+step "Step 3 — Creating index.html"
+
+# index.html is assembled in parts so the Prism <script> block can be
+# included or omitted cleanly. The heredoc delimiters are single-quoted
+# ('HTML_HEAD') to prevent the shell from expanding $docsify.
+{
+  cat << 'HTML_HEAD'
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>My Docs</title>
+  <link rel="stylesheet" href="assets/css/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'My Docs',
+      loadSidebar: true,   // enables _sidebar.md
+      subMaxLevel: 2,      // auto-generate H2 entries in sidebar
+      search: 'auto'       // enables the search plugin
+    }
+  </script>
+  <script src="assets/js/docsify.min.js"></script>
+  <script src="assets/js/search.min.js"></script>
+HTML_HEAD
+
+  if [[ "$PRISM" == true ]]; then
+    cat << 'HTML_PRISM'
+
+  <!-- Prism syntax highlighting -->
+  <script src="assets/js/prism-core.min.js"></script>
+  <script src="assets/js/prism-bash.min.js"></script>
+  <script src="assets/js/prism-yaml.min.js"></script>
+  <script src="assets/js/prism-javascript.min.js"></script>
+HTML_PRISM
+  fi
+
+  cat << 'HTML_FOOT'
+</body>
+</html>
+HTML_FOOT
+} > index.html
+
+ok "index.html"
+
+# ── Step 4: Boilerplate content ─────────────────────────────────────────────────
+step "Step 4 — Creating boilerplate content"
+
+cat > README.md << 'EOF'
+# Welcome
+
+This is the home page of your documentation site.
+Edit `README.md` to replace this content.
+
+## Quick Links
+
+- [Getting Started](getting-started.md)
+EOF
+ok "README.md"
+
+cat > _sidebar.md << 'EOF'
+- [Home](/)
+- [Getting Started](getting-started.md)
+EOF
+ok "_sidebar.md"
+
+cat > getting-started.md << 'EOF'
+# Getting Started
+
+This is an example page. Replace this content with your own documentation.
+
+## Section One
+
+Write your content here using standard Markdown.
+
+## Section Two
+
+Docsify will automatically generate sidebar anchors for H2 headings
+when `subMaxLevel: 2` is set in `index.html`.
+EOF
+ok "getting-started.md"
+
+# ── Step 5: Permissions ─────────────────────────────────────────────────────────
+step "Step 5 — Setting file permissions"
+
+find . -type f -exec chmod 644 {} \;
+find . -type d -exec chmod 755 {} \;
+ok "Files: 644 | Directories: 755"
+
+# ── Verify ───────────────────────────────────────────────────────────────────────
+step "Verifying file layout"
+
+find . -not -path '*/\.*' | sort
+
+# ── Done ─────────────────────────────────────────────────────────────────────────
+echo ""
+echo -e "${GREEN}${BOLD}Setup complete.${NC}"
+echo -e "Open your site in a browser to verify."
+
+if [[ "$PRISM" == true ]]; then
+  echo ""
+  echo -e "Prism is enabled for: bash, yaml, javascript."
+  echo -e "To add more languages, download additional prism-*.min.js files"
+  echo -e "into assets/js/ and add their <script> tags to index.html."
+fi
author	Dave Tang <davetingpongtang@gmail.com>	2026-06-23 09:44:07 +0900
committer	Dave Tang <davetingpongtang@gmail.com>	2026-06-23 09:44:07 +0900
commit	e28c074e15dd093f3acd7a3cce10afae149003cd (patch)
tree	6bef6a7f865c3531082f94c9a6d35979c94999ea