diff options
| -rw-r--r-- | README.md | 169 | ||||
| -rwxr-xr-x | scripts/setup.sh | 77 |
2 files changed, 220 insertions, 26 deletions
@@ -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. diff --git a/scripts/setup.sh b/scripts/setup.sh index bdebe9b..f083c12 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -6,8 +6,10 @@ # bash setup-docsify.sh # # Downloads Docsify core, the search plugin, the Vue theme, the copy-to-clipboard -# plugin, extra Prism languages (bash, yaml, python, r), and KaTeX math rendering — -# all served locally, no external CDN dependencies at runtime. +# plugin, extra Prism languages (bash, yaml, python, r), KaTeX math, Mermaid diagrams, +# and UX plugins (alerts, tabs, pagination, image zoom, collapsible sidebar) — +# all served locally, no external CDN dependencies at runtime. Versions are pinned and +# a SHA-256 manifest (assets/SHA256SUMS) is written for reproducible, verifiable rebuilds. # # Re-running in an existing site is safe: it refreshes the assets and regenerates # index.html, but never overwrites Markdown files (README.md, _sidebar.md, and any @@ -16,8 +18,11 @@ 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" +# All versions are pinned exactly for reproducible, CDN-independent rebuilds. Bump a +# version here, re-run, and commit the refreshed assets/ + assets/SHA256SUMS. +DOCSIFY_VERSION="4.13.1" +PRISM_VERSION="1.30.0" +COPY_CODE_VERSION="3.0.2" # KaTeX stylesheet/font version — must match the renderer bundled in docsify-katex@1.4.4 KATEX_VERSION="0.11.1" @@ -82,16 +87,16 @@ fetch "${CDN}/docsify@${DOCSIFY_VERSION}/lib/plugins/search.min.js" assets/js/s fetch "${CDN}/docsify@${DOCSIFY_VERSION}/themes/vue.css" assets/css/vue.css # Copy-to-clipboard plugin (injects its own CSS — no separate stylesheet needed) -fetch "${CDN}/docsify-copy-code@3/dist/docsify-copy-code.min.js" assets/js/docsify-copy-code.min.js +fetch "${CDN}/docsify-copy-code@${COPY_CODE_VERSION}/dist/docsify-copy-code.min.js" assets/js/docsify-copy-code.min.js # Extra Prism languages. Docsify already bundles Prism core plus html/css/clike/ # javascript, so we only add the languages it does NOT ship. Never download # prism-core here — a standalone core replaces Docsify's Prism and silently breaks # highlighting for every language loaded after it. -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-python.min.js" assets/js/prism-python.min.js -fetch "${CDN}/prismjs@1/components/prism-r.min.js" assets/js/prism-r.min.js +fetch "${CDN}/prismjs@${PRISM_VERSION}/components/prism-bash.min.js" assets/js/prism-bash.min.js +fetch "${CDN}/prismjs@${PRISM_VERSION}/components/prism-yaml.min.js" assets/js/prism-yaml.min.js +fetch "${CDN}/prismjs@${PRISM_VERSION}/components/prism-python.min.js" assets/js/prism-python.min.js +fetch "${CDN}/prismjs@${PRISM_VERSION}/components/prism-r.min.js" assets/js/prism-r.min.js # Math: docsify-katex@1.4.4 bundles the KaTeX renderer (2.x is broken). KaTeX's # stylesheet loads its fonts from ./fonts/ beside it, so the woff2 files go in @@ -104,6 +109,29 @@ for f in $(grep -oE 'fonts/KaTeX_[^)]+\.woff2' assets/css/katex.min.css | sort - done ok "assets/css/fonts/ ($(ls -1 assets/css/fonts | wc -l) KaTeX woff2 files)" +# UX plugins — each loads after docsify; alerts/tabs/pagination inject their own CSS. +fetch "${CDN}/docsify-plugin-flexible-alerts@1.3.0/dist/docsify-plugin-flexible-alerts.min.js" assets/js/docsify-plugin-flexible-alerts.min.js +fetch "${CDN}/docsify-tabs@1.6.3/dist/docsify-tabs.min.js" assets/js/docsify-tabs.min.js +fetch "${CDN}/docsify-pagination@2.10.1/dist/docsify-pagination.min.js" assets/js/docsify-pagination.min.js +# Image zoom: medium-zoom is a generic library (a hook in index.html applies it) + its CSS +fetch "${CDN}/medium-zoom@1.1.0/dist/medium-zoom.min.js" assets/js/medium-zoom.min.js +fetch "${CDN}/medium-zoom@1.1.0/dist/style.css" assets/css/medium-zoom.css +# Collapsible sidebar — needs its own stylesheet +fetch "${CDN}/docsify-sidebar-collapse@1.3.5/dist/docsify-sidebar-collapse.min.js" assets/js/docsify-sidebar-collapse.min.js +fetch "${CDN}/docsify-sidebar-collapse@1.3.5/dist/sidebar.min.css" assets/css/sidebar.min.css + +# Diagrams: Mermaid (self-contained, ~3 MB) + docsify-mermaid, which turns ```mermaid +# fenced blocks into diagrams (it uses Mermaid v11's run() API). +fetch "${CDN}/mermaid@11.15.0/dist/mermaid.min.js" assets/js/mermaid.min.js +fetch "${CDN}/docsify-mermaid@2.0.1/dist/docsify-mermaid.js" assets/js/docsify-mermaid.js + +# Record SHA-256 checksums of every downloaded asset. Commit assets/ together with this +# manifest to rebuild without jsDelivr and to verify integrity later with: +# (cd assets && sha256sum -c SHA256SUMS) +( cd assets && find . -type f ! -name SHA256SUMS \( -name '*.js' -o -name '*.css' -o -name '*.woff2' \) \ + -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS ) +ok "assets/SHA256SUMS ($(wc -l < assets/SHA256SUMS) files)" + # ── Step 3: index.html ────────────────────────────────────────────────────────── step "Step 3 — Creating index.html" @@ -119,6 +147,8 @@ cat > index.html << '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> @@ -127,7 +157,15 @@ cat > index.html << '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> @@ -140,6 +178,18 @@ cat > index.html << '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> HTML @@ -217,3 +267,10 @@ echo -e "this setup adds bash, yaml, python, and r. To add more languages, downl echo -e "additional prism-<lang>.min.js files into assets/js/ and add their <script>" echo -e "tags to index.html. Copy-to-clipboard buttons are enabled on all code blocks." echo -e "LaTeX math renders via KaTeX (inline \$...\$ and block \$\$...\$\$)." +echo 'Mermaid diagrams render from ```mermaid fenced blocks.' +echo 'UX: callout boxes (> [!NOTE]), tabs, prev/next pagination, image zoom, and a' +echo 'collapsible sidebar are enabled.' +echo "" +echo -e "Asset versions are pinned and checksummed in assets/SHA256SUMS" +echo -e "(verify any time with: cd assets && sha256sum -c SHA256SUMS)." +echo -e "Commit assets/ to Git to rebuild without depending on jsDelivr." |