barrett/preview.nvim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 5

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

Browse source 
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
1 changed files with 12 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

18
doc/preview.txt
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
math option compatible with `--embed-resources` (self-contained HTML).
`--mathjax` and `--katex` insert `<script>` tags that load JavaScript and
fonts from a CDN at runtime. Pandoc's `--embed-resources` cannot inline these
dynamic dependencies, so math fails to render in the output.
`--katex` and `--mathjax` load fonts and JavaScript from a CDN. With
`--embed-resources`, pandoc inlines these dependencies — KaTeX adds ~15s of
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`
(the output will require internet access). For example, to work with
github-flavored markdown (gfm): >lua
KaTeX via `extra_args` (simple, slow — self-contained output): >lua
vim.g.preview = {
github = { extra_args = { '--katex' } },
}
<
KaTeX via `args` override (fast — requires internet): >lua
vim.g.preview = {
github = {