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 /README.md | |
| parent | 2b9d10dd8eb94e5c55d12698fb4b1acf7a7c6352 (diff) | |
Add LaTeX support
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 50 |
1 files changed, 45 insertions, 5 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. |