{"id":13672406,"url":"https://github.com/lzanini/mdbook-katex","last_synced_at":"2025-07-29T18:18:20.613Z","repository":{"id":39860088,"uuid":"313781786","full_name":"lzanini/mdbook-katex","owner":"lzanini","description":"A preprocessor for mdBook, rendering LaTex equations to HTML at build time.","archived":false,"fork":false,"pushed_at":"2024-05-23T02:35:56.000Z","size":959,"stargazers_count":189,"open_issues_count":3,"forks_count":34,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-05-23T02:41:34.641Z","etag":null,"topics":["katex","latex","mdbook","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lzanini.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-18T00:47:39.000Z","updated_at":"2024-05-23T02:48:19.736Z","dependencies_parsed_at":"2022-08-10T02:40:16.510Z","dependency_job_id":"227cf336-a729-48e8-91bd-2aa214829ce3","html_url":"https://github.com/lzanini/mdbook-katex","commit_stats":{"total_commits":267,"total_committers":12,"mean_commits":22.25,"dds":"0.38576779026217234","last_synced_commit":"2070ac63a667fc469c74f782720de29cf82fe66a"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzanini%2Fmdbook-katex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzanini%2Fmdbook-katex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzanini%2Fmdbook-katex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzanini%2Fmdbook-katex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lzanini","download_url":"https://codeload.github.com/lzanini/mdbook-katex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251219601,"owners_count":21554444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["katex","latex","mdbook","rust"],"created_at":"2024-08-02T09:01:34.562Z","updated_at":"2025-04-27T22:32:14.364Z","avatar_url":"https://github.com/lzanini.png","language":"Rust","funding_links":[],"categories":["Rust","Applications","latex"],"sub_categories":[],"readme":"# mdBook-KaTeX\n\n[![Crates.io version](https://img.shields.io/crates/v/mdbook-katex)](https://crates.io/crates/mdbook-katex)\n![Crates.io downloads](https://img.shields.io/crates/d/mdbook-katex)\n\nmdBook-KaTeX is a preprocessor for [mdBook](https://github.com/rust-lang/mdBook), using KaTeX to render LaTeX math expressions.\n\nThere are two working modes:\n\n- [Pre-render Mode](#pre-render-mode-default) (default): pre-renders math expressions at build time using KaTeX,\n    - no client-side JavaScript required,\n    - very fast page load,\n    - customizable macros and separators.\n- [Escape mode](#escape-mode-experimental) (experimental): escapes math expressions to be rendered using either katex.js or MathJax in the browser. May be useful if having problems building mdBook-KaTeX with quickjs.\n\nPre-rendering uses [the katex crate](https://github.com/xu-cheng/katex-rs).\n[List of LaTeX functions supported by KaTeX](https://katex.org/docs/supported.html).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"75%\" height=\"75%\" src=\"https://user-images.githubusercontent.com/71221149/107123378-84acbf80-689d-11eb-811d-26f20e32556c.gif\"\u003e\n\u003c/p\u003e\n\n## Getting Started\n\nFirst, install mdBook-KaTeX\n\n### **Non-Windows** users\n\n```shell\ncargo install mdbook-katex\n```\n\n### Windows users\n\nThe recommended way is to download the latest `x86_64-pc-windows-gnu.zip` from [Releases](https://github.com/lzanini/mdbook-katex/releases) for the full functionality, otherwise, things such matrices will not work fine. See [#67](https://github.com/lzanini/mdbook-katex/issues/67) for the reasons.\n\nAnother way is [Escape mode](#escape-mode-experimental).\n\n### Basic setup\n\nThen, add the following line to your `book.toml` file\n\n```toml\n[preprocessor.katex]\nafter = [\"links\"]\n```\n\nYou can now use `$` and `$$` delimiters for inline and display math expressions within your `.md` files. If you need a regular dollar symbol, you need to escape delimiters with a backslash `\\$`.\n\n```markdown\n# Chapter 1\n\nHere is an inline example, $ \\pi(\\theta) $,\n\nan equation,\n\n$$ \\nabla f(x) \\in \\mathbb{R}^n, $$\n\nand a regular \\$ symbol.\n```\n\nMath expressions will be rendered as HTML when running `mdbook build` or `mdbook serve` as usual.\n\n## Pre-render mode (default)\n\nPre-rendering uses [the katex crate](https://github.com/xu-cheng/katex-rs).\n[List of LaTeX functions supported by KaTeX](https://katex.org/docs/supported.html).\n\n### KaTeX options\n\nMost [KaTeX options](https://katex.org/docs/options.html) are supported via the `katex` crate.\nSpecify these options under `[preprocessor.katex]` in your `book.toml`:\n\n| Argument                                                                                            | Type                                       |\n| :-------------------------------------------------------------------------------------------------- | :----------------------------------------- |\n| [`output`](https://katex.org/docs/options.html#:~:text=default-,output,-string)                     | `\"html\"`, `\"mathml\"`, or `\"htmlAndMathml\"` |\n| [`leqno`](https://katex.org/docs/options.html#:~:text=default-,leqno,-boolean)                      | `boolean`                                  |\n| [`fleqn`](https://katex.org/docs/options.html#:~:text=LaTeX-,fleqn,-boolean)                        | `boolean`                                  |\n| [`throw-on-error`](https://katex.org/docs/options.html#:~:text=package-,throwonerror,-boolean)      | `boolean`                                  |\n| [`error-color`](https://katex.org/docs/options.html#:~:text=errorColor-,errorcolor,-string)         | `string`                                   |\n| [`min-rule-thickness`](https://katex.org/docs/options.html#:~:text=state-,minrulethickness,-number) | `number`                                   |\n| [`max-size`](https://katex.org/docs/options.html#:~:text=true-,maxsize,-number)                     | `number`                                   |\n| [`max-expand`](https://katex.org/docs/options.html#:~:text=maxexpand)                               | `number`                                   |\n| [`trust`](https://katex.org/docs/options.html#:~:text=LaTeX-,trust,-boolean)                        | `boolean`                                  |\n\nThere are also extra options to configure the behaviour of the preprocessor:\n\n| Option             | Description                                                                                               |\n| :----------------- | :-------------------------------------------------------------------------------------------------------- |\n| `no-css`           | Do not inject KaTeX stylesheet link (See [Self-host KaTeX CSS and fonts](#self-host-katex-css-and-fonts)) |\n| `macros`           | Path to macros file (see [Custom macros](#custom-macros))                                                 |\n| `include-src`      | Include math expressions source code (See [Including math Source](#including-math-source))                |\n| `block-delimiter`  | See [Custom delimiter](#custom-delimiter)                                                                 |\n| `inline-delimiter` | See [Custom delimiter](#custom-delimiter)                                                                 |\n| `pre-render`       | See [Escape mode](#escape-mode-experimental)                                                                           |\n\nFor example, the default configuration:\n\n```toml\n[preprocessor.katex]\nafter = [\"links\"]\n# KaTeX options.\noutput = \"html\"\nleqno = false\nfleqn = false\nthrow-on-error = true\nerror-color = \"#cc0000\"\nmin-rule-thickness = -1.0\nmax-size = \"Infinity\"\nmax-expand = 1000\ntrust = false\n# Extra options.\nno-css = false\ninclude-src = false\nblock-delimiter = { left = \"$$\", right = \"$$\" }\ninline-delimiter = { left = \"$\", right = \"$\" }\npre-render = true\n```\n\n### Self-host KaTeX CSS and fonts\n\nKaTeX requires a stylesheet and fonts to render correctly.\n\nBy default, mdBook-KaTeX injects a KaTeX stylesheet link pointing to a CDN.\n\nIf you want to self-host the CSS and fonts instead, you should specify in `book.toml`:\n\n```toml\n[preprocessor.katex]\nno-css = true\n```\n\nand manually add the CSS and fonts to your mdBook project before building it.\n\nSee [mdBook-KaTeX Static CSS Example](https://github.com/SichangHe/mdbook_katex_static_css) for an automated example.\n\n### Custom macros\n\nCustom LaTeX macros must be defined in a `.txt` file, according to the following pattern\n\n```txt\n\\grad:{\\nabla}\n\\R:{\\mathbb{R}^{#1 \\times #2}}\n```\n\nYou need to specify the path of this file in your `book.toml` as follows\n\n```toml\n[preprocessor.katex]\nmacros = \"path/to/macros.txt\"\n```\n\nThese macros can then be used in your `.md` files\n\n```markdown\n# Chapter 1\n\n$$ \\grad f(x) \\in \\R{n}{p} $$\n```\n\n### Including math source\n\nThis option is added so users can have a convenient way to copy the source code of math expressions when they view the book.\n\nWhen `include-src` is set to `true`, each math block is wrapped within a `\u003cdata\u003e` tag with `class=\"katex-src\"` with the included math source code being its `value` attribute.\n\nFor example, before being fed into mdBook,\n\n```markdown\nDefine $f(x)$:\n\n$$\nf(x)=x^2\\\\\nx\\in\\R\n$$\n```\n\nis preprocessed into (the content of the `katex` `span`s are omitted and represented as `…`)\n\n```markdown\nDefine \u003cdata class=\"katex-src\" value=\"f(x)\"\u003e\u003cspan class=\"katex\"\u003e…\u003c/span\u003e\u003c/data\u003e:\n\n\u003cdata class=\"katex-src\" value=\"\u0026#10;f(x)=x^2\\\\\u0026#10;x\\in\\R\u0026#10;\"\u003e\u003cspan class=\"katex-display\"\u003e\u003cspan class=\"katex\"\u003e…\u003c/span\u003e\u003c/span\u003e\u003c/data\u003e\n```\n\nThe math source code is included in a minimal fashion, and it is up to the users to write custom CSS and JavaScript to make use of it.\nFor more information about adding custom CSS and JavaScript in mdBook, see [additional-css and additional-js](https://rust-lang.github.io/mdBook/format/configuration/renderers.html#html-renderer-options).\n\nIf you need more information about this feature, please check the issues or file a new issue.\n\n### Custom delimiter\n\nTo change the delimiters for math expressions, set the `block-delimiter` and `inline-delimiter` under `[preprocessor.katex]`.\nFor example, to use `\\(`and `\\)` for inline math and `\\[` and `\\]` for math block, set\n\n```toml\n[preprocessor.katex]\nblock-delimiter = { left = \"\\\\[\", right = \"\\\\]\" }\ninline-delimiter = { left = \"\\\\(\", right = \"\\\\)\" }\n```\n\nNote that the double backslash above are just used to escape `\\` in the TOML format.\n\n### Caveats\n\n`$\\backslash$` does not work, but you can use `$\\setminus$` instead.\n\nOnly the x86_64 Linux, Windows GNU, and macOS builds have full functionality (matrix, ...) , all other builds have compromised capabilities. See [#39](https://github.com/lzanini/mdbook-katex/issues/39) for the reasons.\n\n## Escape mode (experimental)\n\nEscapes the string needed for a formula in advance so that it remains the original formula after the markdown processor.\n\nDisable pre-render to use \"Escape mode\", and provide your client-side rendering library of choice. An example with `katex.js` included in `head.hbs` (see [index.hbs](https://rust-lang.github.io/mdBook/format/theme/index-hbs.html)) is provided below.\n\n```toml\n[preprocessor.katex]\nafter = [\"links\"]\npre-render = false\nno-css = true\n\n[output.html]\ntheme = \"theme\" # use theme/head.hbs\n```\n\nNote that the [KaTeX Options](#katex-options) are ignored in escape mode.\n\nAn example `head.hbs`:\n\n```html\n\u003clink rel=\"stylesheet\" href=\"https://unpkg.com/katex@latest/dist/katex.min.css\"\u003e\n\u003cscript defer src=\"https://unpkg.com/katex@latest/dist/katex.min.js\"\u003e\u003c/script\u003e\n\u003cscript defer src=\"https://unpkg.com/katex@latest/dist/contrib/auto-render.min.js\"\u003e\u003c/script\u003e\n\n\u003cscript\u003e\ndocument.addEventListener(\"DOMContentLoaded\", function () {\n  renderMathInElement(document.body, {\n    delimiters: [\n      { left: '$$', right: '$$', display: true },\n      { left: '$', right: '$', display: false },\n    ],\n  });\n});\n\u003c/script\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flzanini%2Fmdbook-katex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flzanini%2Fmdbook-katex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flzanini%2Fmdbook-katex/lists"}