From aeea1bd8fa75af0c58ef4693f32e278339610dc0 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com>
Date: Fri, 6 Mar 2026 13:49:15 -0500
Subject: [PATCH] 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
---
 doc/preview.txt | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/doc/preview.txt b/doc/preview.txt
index 3912a41..ed3c13e 100644
--- a/doc/preview.txt
+++ b/doc/preview.txt
@@ -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,
       },