From c9d3269689e8204c635eeb40dc93775cb354d145 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Fri, 6 Mar 2026 13:30:17 -0500
Subject: [PATCH] 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`.
---
 doc/preview.txt | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

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*