doc: improve preview-math section phrasing (#54)

* fix(presets): add `--mathml` to `markdown` and `github` pandoc args

Problem: pandoc's default HTML math renderer cannot handle most TeX and
dumps raw LaTeX source into the output. `--mathjax` and `--katex` are
incompatible with `--embed-resources` because pandoc cannot inline
dynamically-loaded JavaScript modules and fonts.

Solution: add `--mathml` to both `markdown` and `github` preset args.
MathML is rendered natively by all modern browsers with no external
dependencies, making it the only math option compatible with
self-contained HTML output.

* docs(presets): add math rendering section with KaTeX recipe

Problem: the `markdown` and `github` presets now default to `--mathml`
but users may want KaTeX or MathJax rendering instead, and the
incompatibility with `--embed-resources` is non-obvious.

Solution: add a `preview-math` section to the presets docs explaining
the default, why `--katex`/`--mathjax` require dropping
`--embed-resources`, and a concrete recipe for KaTeX with `github`.

* test(presets): update `markdown` and `github` args assertions for `--mathml`

* doc: cleanup

* chore: remove debug files
This commit is contained in:
Barrett Ruth 2026-03-06 13:49:15 -05:00 committed by GitHub
parent 36e49cbd41
commit aeea1bd8fa
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -202,15 +202,22 @@ fonts from a CDN at runtime. Pandoc's `--embed-resources` cannot inline these
dynamic dependencies, so math fails to render in the output.
To use KaTeX or MathJax instead, override `args` to drop `--embed-resources`
(the output will require internet access): >lua
(the output will require internet access). For example, to work with
github-flavored markdown (gfm): >lua
vim.g.preview = {
github = {
args = function(ctx)
return {
'-f', 'gfm', ctx.file, '-s', '--katex',
'--css', 'https://cdn.jsdelivr.net/gh/pixelbrackets/gfm-stylesheet@master/dist/gfm.css',
'-o', ctx.output,
'-f',
'gfm',
ctx.file,
'-s',
'--katex',
'--css',
'https://cdn.jsdelivr.net/gh/pixelbrackets/gfm-stylesheet@master/dist/gfm.css',
'-o',
ctx.output,
}
end,
},