From 36e49cbd41191ab8404fb51d83727738065add03 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com>
Date: Fri, 6 Mar 2026 13:39:22 -0500
Subject: [PATCH] fix(presets): add `--mathml` to pandoc markdown args (#53)

* 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/preview.txt         | 28 ++++++++++++++++++++++++++++
 lua/preview/presets.lua |  3 ++-
 spec/presets_spec.lua   |  7 ++++---
 3 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/doc/preview.txt b/doc/preview.txt
index 6bf5171..3912a41 100644
--- a/doc/preview.txt
+++ b/doc/preview.txt
@@ -22,6 +22,7 @@ CONTENTS                                                   *preview-contents*
   3. Install ............................................... |preview-install|
   4. Configuration ........................................... |preview-config|
   5. Presets ............................................... |preview-presets|
+     - Math rendering ....................................... |preview-math|
   6. Commands ............................................. |preview-commands|
   7. Lua API ................................................... |preview-api|
   8. Events ............................................... |preview-events|
@@ -189,6 +190,33 @@ override individual fields by passing a table instead: >lua
   `mermaid`            mmdc → SVG (Mermaid diagrams, `.mmd`)
   `quarto`             quarto render → HTML (scientific publishing)
 
+Math rendering (pandoc presets): ~
+                                                        *preview-math*
+
+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.
+
+To use KaTeX or MathJax instead, override `args` to drop `--embed-resources`
+(the output will require internet access): >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,
+          }
+        end,
+      },
+    }
+<
+
 ==============================================================================
 COMMANDS                                                  *preview-commands*
 
diff --git a/lua/preview/presets.lua b/lua/preview/presets.lua
index d4b03cc..1f333bf 100644
--- a/lua/preview/presets.lua
+++ b/lua/preview/presets.lua
@@ -224,7 +224,7 @@ M.markdown = {
   ft = 'markdown',
   cmd = { 'pandoc' },
   args = function(ctx)
-    return { ctx.file, '-s', '--embed-resources', '-o', ctx.output }
+    return { ctx.file, '-s', '--embed-resources', '--mathml', '-o', ctx.output }
   end,
   output = function(ctx)
     return (ctx.file:gsub('%.md$', '.html'))
@@ -250,6 +250,7 @@ M.github = {
       ctx.file,
       '-s',
       '--embed-resources',
+      '--mathml',
       '--css',
       'https://cdn.jsdelivr.net/gh/pixelbrackets/gfm-stylesheet@master/dist/gfm.css',
       '-o',
diff --git a/spec/presets_spec.lua b/spec/presets_spec.lua
index 2160dfa..573b1ef 100644
--- a/spec/presets_spec.lua
+++ b/spec/presets_spec.lua
@@ -294,11 +294,11 @@ describe('presets', function()
       assert.are.same({ 'pandoc' }, presets.markdown.cmd)
     end)
 
-    it('returns args with standalone and embed-resources flags', function()
+    it('returns args with standalone, embed-resources, and mathml flags', function()
       local args = presets.markdown.args(md_ctx)
       assert.is_table(args)
       assert.are.same(
-        { '/tmp/document.md', '-s', '--embed-resources', '-o', '/tmp/document.html' },
+        { '/tmp/document.md', '-s', '--embed-resources', '--mathml', '-o', '/tmp/document.html' },
         args
       )
     end)
@@ -382,7 +382,7 @@ describe('presets', function()
       assert.are.same({ 'pandoc' }, presets.github.cmd)
     end)
 
-    it('returns args with standalone, embed-resources, and css flags', function()
+    it('returns args with standalone, embed-resources, mathml, and css flags', function()
       local args = presets.github.args(md_ctx)
       assert.is_table(args)
       assert.are.same({
@@ -391,6 +391,7 @@ describe('presets', function()
         '/tmp/document.md',
         '-s',
         '--embed-resources',
+        '--mathml',
         '--css',
         'https://cdn.jsdelivr.net/gh/pixelbrackets/gfm-stylesheet@master/dist/gfm.css',
         '-o',