From 047e169c2148472a4ca7a219b154227bbef3f664 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Fri, 6 Mar 2026 14:08:22 -0500
Subject: [PATCH] docs(presets): improve math rendering section with KaTeX
 recipes

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.
---
 doc/preview.txt | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/doc/preview.txt b/doc/preview.txt
index ed3c13e..fb133d8 100644
--- a/doc/preview.txt
+++ b/doc/preview.txt
@@ -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 = {