docs(presets): improve math rendering section with KaTeX recipes

Problem: the math docs only showed a full `args` override for KaTeX,
without explaining the tradeoffs or offering a simpler alternative.

Solution: add an `extra_args` one-liner recipe (simple but slow due to
`--embed-resources` inlining fonts), keep the `args` override as the
fast option, and explain why `--mathjax` fails entirely.
This commit is contained in:
Barrett Ruth 2026-03-06 14:08:22 -05:00
parent f5651cc3fc
commit 047e169c21
Signed by: barrett
GPG key ID: A6C96C9349D2FC81

View file

@ -197,13 +197,19 @@ The `markdown` and `github` presets use `--mathml` by default, which converts
TeX math to native MathML markup rendered by the browser. This is the only TeX math to native MathML markup rendered by the browser. This is the only
math option compatible with `--embed-resources` (self-contained HTML). math option compatible with `--embed-resources` (self-contained HTML).
`--mathjax` and `--katex` insert `<script>` tags that load JavaScript and `--katex` and `--mathjax` load fonts and JavaScript from a CDN. With
fonts from a CDN at runtime. Pandoc's `--embed-resources` cannot inline these `--embed-resources`, pandoc inlines these dependencies — KaTeX adds ~15s of
dynamic dependencies, so math fails to render in the output. compile time and ~1.7MB to the output; MathJax fails entirely because it
loads modules dynamically at runtime (pandoc/pandoc#682).
To use KaTeX or MathJax instead, override `args` to drop `--embed-resources` KaTeX via `extra_args` (simple, slow — self-contained output): >lua
(the output will require internet access). For example, to work with
github-flavored markdown (gfm): >lua vim.g.preview = {
github = { extra_args = { '--katex' } },
}
<
KaTeX via `args` override (fast — requires internet): >lua
vim.g.preview = { vim.g.preview = {
github = { github = {