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 /README.md
1 files changed, 283 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.
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 /README.md