diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 169 |
1 files changed, 153 insertions, 16 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. |