Add additional features

author: Dave Tang <davetingpongtang@gmail.com> 2026-06-23 17:18:06 +0900
committer: Dave Tang <davetingpongtang@gmail.com> 2026-06-23 17:18:06 +0900
commit: 3b36213ea3cc221d00b06f9340c8fac9e45ecf5c (patch)
tree: 8463d87defb8fb9067d56b84ac7c09f49fcfb68d /README.md
parent: c538086f5ad82d57c43726cb4536e36ad5c6320a (diff)
1 files changed, 153 insertions, 16 deletions
diff --git a/README.md b/README.md
index b459256..3d1b0e4 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ The final layout this guide produces, relative to your document root:
 ├── _sidebar.md         ← Sidebar navigation
 ├── getting-started.md  ← Example page
 └── assets/
+    ├── SHA256SUMS       ← SHA-256 of every downloaded asset
     ├── js/
     │   ├── docsify.min.js
     │   ├── search.min.js
@@ -30,10 +31,19 @@ The final layout this guide produces, relative to your document root:
     │   ├── prism-bash.min.js
     │   ├── prism-yaml.min.js
     │   ├── prism-python.min.js
-    │   └── prism-r.min.js
+    │   ├── prism-r.min.js
+    │   ├── docsify-plugin-flexible-alerts.min.js
+    │   ├── docsify-tabs.min.js
+    │   ├── docsify-pagination.min.js
+    │   ├── medium-zoom.min.js
+    │   ├── docsify-sidebar-collapse.min.js
+    │   ├── mermaid.min.js
+    │   └── docsify-mermaid.js
     └── css/
         ├── vue.css
         ├── katex.min.css
+        ├── medium-zoom.css
+        ├── sidebar.min.css
         └── fonts/
             └── KaTeX_*.woff2   (20 KaTeX font files)
 ```
@@ -53,19 +63,19 @@ 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.
+All files are downloaded from jsDelivr once and served locally thereafter. See all [docsify CDN files](https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/) on jsDelivr.
 
 ```bash
 # Docsify core
-curl -L "https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js" \
+curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/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" \
+curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/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" \
+curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/themes/vue.css" \
   -o assets/css/vue.css
 ```
 
@@ -93,21 +103,21 @@ Docsify's bundled Prism.
 This guide adds bash, yaml, python, and r:
 
 ```bash
-curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js" \
+curl -L "https://cdn.jsdelivr.net/npm/prismjs@1.30.0/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" \
+curl -L "https://cdn.jsdelivr.net/npm/prismjs@1.30.0/components/prism-yaml.min.js" \
   -o assets/js/prism-yaml.min.js
 
-curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-python.min.js" \
+curl -L "https://cdn.jsdelivr.net/npm/prismjs@1.30.0/components/prism-python.min.js" \
   -o assets/js/prism-python.min.js
 
-curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-r.min.js" \
+curl -L "https://cdn.jsdelivr.net/npm/prismjs@1.30.0/components/prism-r.min.js" \
   -o assets/js/prism-r.min.js
 ```
 
 To highlight more languages, download additional `prism-<lang>.min.js` files (browse the
-[Prism components](https://cdn.jsdelivr.net/npm/prismjs@1/components/)) and add a matching
+[Prism components](https://cdn.jsdelivr.net/npm/prismjs@1.30.0/components/)) and add a matching
 `<script>` tag in Step 3. A few Prism languages depend on others — if one does, download
 its dependency too (Docsify already provides `clike`, the most common base grammar).
 
@@ -119,7 +129,7 @@ assets above, it is fetched once and served locally thereafter:
 
 ```bash
 # Copy-to-clipboard plugin
-curl -L "https://cdn.jsdelivr.net/npm/docsify-copy-code@3/dist/docsify-copy-code.min.js" \
+curl -L "https://cdn.jsdelivr.net/npm/docsify-copy-code@3.0.2/dist/docsify-copy-code.min.js" \
   -o assets/js/docsify-copy-code.min.js
 ```
 
@@ -167,6 +177,76 @@ Add the stylesheet (a `<link>` in `<head>`) and the plugin `<script>` (after
 `docsify.min.js`) to `index.html` — see Step 3. KaTeX then renders math automatically,
 with no extra configuration.
 
+### Diagrams (Mermaid)
+
+Turn fenced `mermaid` blocks into flowcharts, sequence diagrams, and the like. Mermaid is
+one large but self-contained file (~3 MB, no external fonts); the
+[docsify-mermaid](https://www.npmjs.com/package/docsify-mermaid) plugin wires it into
+Docsify (it uses Mermaid v11's `run()` API).
+
+```bash
+# Mermaid renderer (large, self-contained)
+curl -L "https://cdn.jsdelivr.net/npm/mermaid@11.15.0/dist/mermaid.min.js" \
+  -o assets/js/mermaid.min.js
+
+# docsify-mermaid plugin
+curl -L "https://cdn.jsdelivr.net/npm/docsify-mermaid@2.0.1/dist/docsify-mermaid.js" \
+  -o assets/js/docsify-mermaid.js
+```
+
+Load both after `docsify.min.js` and add `mermaid.initialize({ startOnLoad: false })`
+(see Step 3). A fenced block tagged `mermaid` then renders as a diagram:
+
+    ```mermaid
+    graph TD; A[Start] --> B{Works?} --> C[Ship];
+    ```
+
+### UX Plugins
+
+Five small self-hosted plugins. Each loads after `docsify.min.js`; alerts, tabs, and
+pagination inject their own CSS, while image-zoom and sidebar-collapse ship a stylesheet.
+
+```bash
+# Callout boxes:  > [!NOTE] / [!TIP] / [!WARNING] / [!ATTENTION]
+curl -L "https://cdn.jsdelivr.net/npm/docsify-plugin-flexible-alerts@1.3.0/dist/docsify-plugin-flexible-alerts.min.js" \
+  -o assets/js/docsify-plugin-flexible-alerts.min.js
+
+# Tabbed content blocks
+curl -L "https://cdn.jsdelivr.net/npm/docsify-tabs@1.6.3/dist/docsify-tabs.min.js" \
+  -o assets/js/docsify-tabs.min.js
+
+# Previous/next links in the page footer
+curl -L "https://cdn.jsdelivr.net/npm/docsify-pagination@2.10.1/dist/docsify-pagination.min.js" \
+  -o assets/js/docsify-pagination.min.js
+
+# Click-to-zoom images (generic library + its stylesheet; wired via a hook in Step 3)
+curl -L "https://cdn.jsdelivr.net/npm/medium-zoom@1.1.0/dist/medium-zoom.min.js" \
+  -o assets/js/medium-zoom.min.js
+curl -L "https://cdn.jsdelivr.net/npm/medium-zoom@1.1.0/dist/style.css" \
+  -o assets/css/medium-zoom.css
+
+# Collapsible sidebar (+ its stylesheet)
+curl -L "https://cdn.jsdelivr.net/npm/docsify-sidebar-collapse@1.3.5/dist/docsify-sidebar-collapse.min.js" \
+  -o assets/js/docsify-sidebar-collapse.min.js
+curl -L "https://cdn.jsdelivr.net/npm/docsify-sidebar-collapse@1.3.5/dist/sidebar.min.css" \
+  -o assets/css/sidebar.min.css
+```
+
+Once wired into `index.html` (Step 3):
+
+- **Alerts** — blockquotes tagged `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, or `> [!ATTENTION]`.
+- **Tabs** — wrap alternatives between `tabs:start` / `tabs:end` comments (syntax below).
+- **Pagination, image zoom, collapsible sidebar** — automatic; no special syntax.
+
+Tab block syntax:
+
+    <!-- tabs:start -->
+    #### **Python**
+    `print("hi")`
+    #### **R**
+    `print("hi")`
+    <!-- tabs:end -->
+
 ---
 
 ## Step 3: Create `index.html`
@@ -183,6 +263,8 @@ Create `index.html`:
   <title>My Docs</title>
   <link rel="stylesheet" href="assets/css/vue.css">
   <link rel="stylesheet" href="assets/css/katex.min.css">
+  <link rel="stylesheet" href="assets/css/sidebar.min.css">
+  <link rel="stylesheet" href="assets/css/medium-zoom.css">
 </head>
 <body>
   <div id="app"></div>
@@ -191,7 +273,15 @@ Create `index.html`:
       name: 'My Docs',
       loadSidebar: true,   // enables _sidebar.md
       subMaxLevel: 2,      // auto-generate H2 entries in sidebar
-      search: 'auto'       // enables the search plugin
+      search: 'auto',      // enables the search plugin
+      plugins: [
+        // medium-zoom: click an image in the content to enlarge it
+        function (hook) {
+          hook.doneEach(function () {
+            if (window.mediumZoom) mediumZoom('.markdown-section img');
+          });
+        }
+      ]
     }
   </script>
   <script src="assets/js/docsify.min.js"></script>
@@ -204,6 +294,18 @@ Create `index.html`:
   <script src="assets/js/prism-yaml.min.js"></script>
   <script src="assets/js/prism-python.min.js"></script>
   <script src="assets/js/prism-r.min.js"></script>
+
+  <!-- UX plugins (callout boxes, tabs, prev/next pagination, image zoom, collapsible sidebar) -->
+  <script src="assets/js/docsify-plugin-flexible-alerts.min.js"></script>
+  <script src="assets/js/docsify-tabs.min.js"></script>
+  <script src="assets/js/docsify-pagination.min.js"></script>
+  <script src="assets/js/medium-zoom.min.js"></script>
+  <script src="assets/js/docsify-sidebar-collapse.min.js"></script>
+
+  <!-- Diagrams: Mermaid + docsify integration (disable Mermaid's own auto-run) -->
+  <script src="assets/js/mermaid.min.js"></script>
+  <script src="assets/js/docsify-mermaid.js"></script>
+  <script>mermaid.initialize({ startOnLoad: false });</script>
 </body>
 </html>
 ```
@@ -303,13 +405,23 @@ Expected output:
 ./README.md
 ./_sidebar.md
 ./assets
+./assets/SHA256SUMS
 ./assets/css
 ./assets/css/katex.min.css
+./assets/css/medium-zoom.css
+./assets/css/sidebar.min.css
 ./assets/css/vue.css
 ./assets/js
 ./assets/js/docsify-copy-code.min.js
 ./assets/js/docsify-katex.js
+./assets/js/docsify-mermaid.js
+./assets/js/docsify-pagination.min.js
+./assets/js/docsify-plugin-flexible-alerts.min.js
+./assets/js/docsify-sidebar-collapse.min.js
+./assets/js/docsify-tabs.min.js
 ./assets/js/docsify.min.js
+./assets/js/medium-zoom.min.js
+./assets/js/mermaid.min.js
 ./assets/js/prism-bash.min.js
 ./assets/js/prism-python.min.js
 ./assets/js/prism-r.min.js
@@ -350,6 +462,29 @@ For subdirectories, nest entries with indentation:
 
 ---
 
+## Reproducibility & Resilience
+
+Self-hosting protects your **live** site if jsDelivr ever disappears. To also protect your
+ability to **rebuild** it, do two things:
+
+1. **Pin and vendor.** Every asset version is pinned, and the downloaded files are plain
+   static assets. Commit the entire `assets/` directory to your repository. You can then
+   redeploy — or rebuild on a fresh machine with no network access — without depending on
+   jsDelivr at all.
+
+2. **Verify integrity.** `scripts/setup.sh` writes `assets/SHA256SUMS`, a SHA-256 checksum
+   of every downloaded file. Commit it alongside `assets/`, then check the assets at any
+   time (after a server move, or to detect corruption or tampering):
+
+   ```bash
+   (cd assets && sha256sum -c SHA256SUMS)
+   ```
+
+   Every file should report `OK`. After re-running `setup.sh` to upgrade, `git diff` on
+   `SHA256SUMS` shows exactly which assets changed.
+
+---
+
 ## Upgrading Docsify
 
 Since files are self-hosted, upgrades are manual. Re-run the `curl` commands from
@@ -367,10 +502,12 @@ curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/themes/vue.css" \
   -o assets/css/vue.css
 ```
 
-The Prism components (`prismjs@1`), the copy-code plugin (`docsify-copy-code@3`), and the
-math plugin (`docsify-katex@1.4.4` with `katex@0.11.1`) are versioned independently of
-Docsify; re-run their Step 2 commands the same way when you want to update them. If you
-bump KaTeX, re-download the stylesheet **and** its fonts together so they stay in sync.
+Every asset version is pinned — in the Step 2 commands above and in the variables at the
+top of `scripts/setup.sh`. The Prism components, copy-code, Mermaid, the UX plugins, and
+the math plugin (`docsify-katex@1.4.4` with a matching `katex` stylesheet **and** fonts)
+are versioned independently of Docsify, so upgrade each by changing its version number and
+re-downloading. Afterwards regenerate `assets/SHA256SUMS` — re-running `scripts/setup.sh`
+does this — and re-verify.
 
 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 17:18:06 +0900
committer	Dave Tang <davetingpongtang@gmail.com>	2026-06-23 17:18:06 +0900
commit	3b36213ea3cc221d00b06f9340c8fac9e45ecf5c (patch)
tree	8463d87defb8fb9067d56b84ac7c09f49fcfb68d /README.md
parent	c538086f5ad82d57c43726cb4536e36ad5c6320a (diff)