diff options
| author | Dave Tang <davetingpongtang@gmail.com> | 2026-06-23 16:31:48 +0900 |
|---|---|---|
| committer | Dave Tang <davetingpongtang@gmail.com> | 2026-06-23 16:31:48 +0900 |
| commit | c538086f5ad82d57c43726cb4536e36ad5c6320a (patch) | |
| tree | 52d4eb7592306bd7ff1d75eca98d2dc3336bec6e | |
| parent | 2b9d10dd8eb94e5c55d12698fb4b1acf7a7c6352 (diff) | |
Add LaTeX support
| -rw-r--r-- | README.md | 50 | ||||
| -rwxr-xr-x | scripts/setup.sh | 25 |
2 files changed, 66 insertions, 9 deletions
@@ -26,12 +26,16 @@ The final layout this guide produces, relative to your document root: │ ├── docsify.min.js │ ├── search.min.js │ ├── docsify-copy-code.min.js + │ ├── docsify-katex.js │ ├── prism-bash.min.js │ ├── prism-yaml.min.js │ ├── prism-python.min.js │ └── prism-r.min.js └── css/ - └── vue.css + ├── vue.css + ├── katex.min.css + └── fonts/ + └── KaTeX_*.woff2 (20 KaTeX font files) ``` All commands in this guide assume you have already `cd`'d into your document root. @@ -135,6 +139,34 @@ copyCode: { } ``` +### Math (LaTeX via KaTeX) + +Render LaTeX math — inline like `$x^2 + y^2 = z^2$` and block like `$$ ... $$` — with the +[docsify-katex](https://github.com/upupming/docsify-katex) plugin. **Pin version 1.4.4**: +it bundles the KaTeX renderer (the 2.x releases are broken). The only extra assets are +KaTeX's stylesheet and the fonts it references. + +```bash +# docsify-katex plugin (bundles the KaTeX renderer) +curl -L "https://cdn.jsdelivr.net/npm/docsify-katex@1.4.4/dist/docsify-katex.js" \ + -o assets/js/docsify-katex.js + +# KaTeX stylesheet — pin to the version bundled by docsify-katex@1.4.4 (0.11.1) +curl -L "https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css" \ + -o assets/css/katex.min.css + +# KaTeX fonts — the stylesheet loads these from ./fonts/, so they must sit beside it. +# Modern browsers use woff2, so only those (20 files) are needed. +mkdir -p assets/css/fonts +for f in $(grep -oE 'fonts/KaTeX_[^)]+\.woff2' assets/css/katex.min.css | sort -u); do + curl -L "https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/$f" -o "assets/css/$f" +done +``` + +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. + --- ## Step 3: Create `index.html` @@ -150,6 +182,7 @@ Create `index.html`: <meta name="viewport" content="width=device-width, initial-scale=1"> <title>My Docs</title> <link rel="stylesheet" href="assets/css/vue.css"> + <link rel="stylesheet" href="assets/css/katex.min.css"> </head> <body> <div id="app"></div> @@ -164,6 +197,7 @@ Create `index.html`: <script src="assets/js/docsify.min.js"></script> <script src="assets/js/search.min.js"></script> <script src="assets/js/docsify-copy-code.min.js"></script> + <script src="assets/js/docsify-katex.js"></script> <!-- Extra Prism languages — Docsify bundles Prism core + html/css/js. Load after docsify. --> <script src="assets/js/prism-bash.min.js"></script> @@ -257,7 +291,9 @@ them as ordinary static files without any rewrite rules or special directives. After completing the steps above, confirm the file layout looks correct: ```bash -find . -not -path '*/\.*' | sort +# The 20 KaTeX font files are summarised rather than listed individually +find . -not -path '*/\.*' -not -path './assets/css/fonts*' | sort +echo "./assets/css/fonts/ ($(ls -1 assets/css/fonts | wc -l) KaTeX woff2 files)" ``` Expected output: @@ -268,9 +304,11 @@ Expected output: ./_sidebar.md ./assets ./assets/css +./assets/css/katex.min.css ./assets/css/vue.css ./assets/js ./assets/js/docsify-copy-code.min.js +./assets/js/docsify-katex.js ./assets/js/docsify.min.js ./assets/js/prism-bash.min.js ./assets/js/prism-python.min.js @@ -279,6 +317,7 @@ Expected output: ./assets/js/search.min.js ./getting-started.md ./index.html +./assets/css/fonts/ (20 KaTeX woff2 files) ``` Then open `http://your-server/docs/` in a browser. You should see the rendered @@ -328,9 +367,10 @@ curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/themes/vue.css" \ -o assets/css/vue.css ``` -The Prism components (`prismjs@1`) and the copy-code plugin (`docsify-copy-code@3`) -are versioned independently of Docsify; re-run their Step 2 commands with a pinned -version number the same way when you want to update them. +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. 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 d77d23e..bdebe9b 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -6,8 +6,8 @@ # bash setup-docsify.sh # # Downloads Docsify core, the search plugin, the Vue theme, the copy-to-clipboard -# plugin, and extra Prism languages (bash, yaml, python, r) — all -# served locally, no external CDN dependencies at runtime. +# plugin, extra Prism languages (bash, yaml, python, r), and KaTeX math rendering — +# all served locally, no external CDN dependencies at runtime. # # 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 @@ -18,6 +18,8 @@ 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" +# KaTeX stylesheet/font version — must match the renderer bundled in docsify-katex@1.4.4 +KATEX_VERSION="0.11.1" # ── Argument check ────────────────────────────────────────────────────────────── if [[ $# -gt 0 ]]; then @@ -59,7 +61,7 @@ echo -e " Working in: $(pwd)" # ── Step 1: Directories ───────────────────────────────────────────────────────── step "Step 1 — Creating directory structure" -mkdir -p assets/js assets/css +mkdir -p assets/js assets/css assets/css/fonts ok "assets/js/" ok "assets/css/" @@ -91,6 +93,17 @@ fetch "${CDN}/prismjs@1/components/prism-yaml.min.js" assets/js/prism-yaml.mi 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 +# 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 +# assets/css/fonts/. Stylesheet + fonts are pinned to the bundled KaTeX (KATEX_VERSION). +fetch "${CDN}/docsify-katex@1.4.4/dist/docsify-katex.js" assets/js/docsify-katex.js +fetch "${CDN}/katex@${KATEX_VERSION}/dist/katex.min.css" assets/css/katex.min.css +for f in $(grep -oE 'fonts/KaTeX_[^)]+\.woff2' assets/css/katex.min.css | sort -u); do + curl -sL --fail "${CDN}/katex@${KATEX_VERSION}/dist/$f" -o "assets/css/$f" \ + || die "Failed to download: $f" +done +ok "assets/css/fonts/ ($(ls -1 assets/css/fonts | wc -l) KaTeX woff2 files)" + # ── Step 3: index.html ────────────────────────────────────────────────────────── step "Step 3 — Creating index.html" @@ -105,6 +118,7 @@ cat > index.html << 'HTML' <meta name="viewport" content="width=device-width, initial-scale=1"> <title>My Docs</title> <link rel="stylesheet" href="assets/css/vue.css"> + <link rel="stylesheet" href="assets/css/katex.min.css"> </head> <body> <div id="app"></div> @@ -119,6 +133,7 @@ cat > index.html << 'HTML' <script src="assets/js/docsify.min.js"></script> <script src="assets/js/search.min.js"></script> <script src="assets/js/docsify-copy-code.min.js"></script> + <script src="assets/js/docsify-katex.js"></script> <!-- Extra Prism languages — Docsify bundles Prism core + html/css/js. Load after docsify. --> <script src="assets/js/prism-bash.min.js"></script> @@ -189,7 +204,8 @@ ok "Files: 644 | Directories: 755" # ── Verify ─────────────────────────────────────────────────────────────────────── step "Verifying file layout" -find . -not -path '*/\.*' | sort +find . -not -path '*/\.*' -not -path './assets/css/fonts*' | sort +echo "./assets/css/fonts/ ($(ls -1 assets/css/fonts 2>/dev/null | wc -l) KaTeX woff2 files)" # ── Done ───────────────────────────────────────────────────────────────────────── echo "" @@ -200,3 +216,4 @@ echo -e "Syntax highlighting: html, css, and javascript are built into Docsify;" echo -e "this setup adds bash, yaml, python, and r. To add more languages, download" 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 \$\$...\$\$)." |