From c538086f5ad82d57c43726cb4536e36ad5c6320a Mon Sep 17 00:00:00 2001 From: Dave Tang Date: Tue, 23 Jun 2026 16:31:48 +0900 Subject: Add LaTeX support --- README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 45 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 8c92593..b459256 100644 --- a/README.md +++ b/README.md @@ -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 `` in ``) and the plugin ` + @@ -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. -- cgit v1.3.1