docs(presets): rewrite math rendering section for --katex default

Problem: `--embed-resources` with `--mathml` caused pandoc to inline all
assets at compile time, adding ~15s per save for KaTeX-heavy documents.

Solution: Default to `--katex`, which inserts a CDN `<script>` tag and
defers rendering to the browser. Users can opt into `--embed-resources`
or `--mathml` via `extra_args`.

doc/preview.txt

@@ -183,8 +183,8 @@ override individual fields by passing a table instead: >lua
   `latex`              latexmk -pdf → PDF (with clean support)
   `pdflatex`           pdflatex → PDF (single pass, no latexmk)
   `tectonic`           tectonic → PDF (Rust-based LaTeX engine)
-  `markdown`           pandoc → HTML (standalone, embedded)
+  `markdown`           pandoc → HTML (standalone, KaTeX math)
-  `github`             pandoc → HTML (GitHub-styled, `-f gfm` input)
+  `github`             pandoc → HTML (GitHub-styled, `-f gfm`, KaTeX math)
   `asciidoctor`        asciidoctor → HTML (AsciiDoc with SSE reload)
   `plantuml`           plantuml → SVG (UML diagrams, `.puml`)
   `mermaid`            mmdc → SVG (Mermaid diagrams, `.mmd`)
@@ -193,27 +193,36 @@ override individual fields by passing a table instead: >lua
 Math rendering (pandoc presets): ~
                                                         *preview-math*
 
-The `markdown` and `github` presets use `--mathml` by default, which converts
+The `markdown` and `github` presets use `--katex` by default, which inserts a
-TeX math to native MathML markup rendered by the browser. This is the only
+`<script>` tag that loads KaTeX from a CDN at view time. The browser fetches
-math option compatible with `--embed-resources` (self-contained HTML).
+the assets once and caches them, so math renders instantly on subsequent loads.
+Requires internet on first view.
 
-`--mathjax` and `--katex` insert `<script>` tags that load JavaScript and
+For offline use, swap in `--mathml` via `extra_args`. MathML is rendered
-fonts from a CDN at runtime. Pandoc's `--embed-resources` cannot inline these
+natively by the browser with no external dependencies: >lua
-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 = {
+      github = { extra_args = { '--mathml' } },
-        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,
+<
-      },
+
+Note: pandoc's math flags (`--katex`, `--mathml`, `--mathjax`) are mutually
+exclusive — last flag wins. Adding `--mathml` via `extra_args` (which is
+appended after `args`) overrides `--katex`.
+
+Self-contained output with `--embed-resources`: >lua
+
+    vim.g.preview = {
+      github = { extra_args = { '--embed-resources' } },
+    }
+<
+
+This inlines all external resources into the HTML. With `--katex` this adds
+~15s of compile time per save (pandoc fetches KaTeX from the CDN during
+compilation). Pair with `--mathml` to avoid the penalty: >lua
+
+    vim.g.preview = {
+      github = { extra_args = { '--embed-resources', '--mathml' } },
     }
 <
 

lua/preview/compiler.lua

@@ -329,6 +329,9 @@ function M.compile(bufnr, name, provider, ctx, opts)
     s.provider = name
     s.is_reload = true
 
+    if not opts.silent then
+      vim.notify('[preview.nvim]: compiling...', vim.log.levels.INFO)
+    end
     vim.api.nvim_exec_autocmds('User', {
       pattern = 'PreviewCompileStarted',
       data = { bufnr = bufnr, provider = name },
@@ -360,6 +363,7 @@ function M.compile(bufnr, name, provider, ctx, opts)
       end
       if result.code == 0 then
         log.dbg('compilation succeeded for buffer %d', bufnr)
+        vim.notify('[preview.nvim]: compilation complete', vim.log.levels.INFO)
         clear_errors(bufnr, provider)
         vim.api.nvim_exec_autocmds('User', {
           pattern = 'PreviewCompileSuccess',
@@ -403,6 +407,9 @@ function M.compile(bufnr, name, provider, ctx, opts)
   s.provider = name
   s.is_reload = false
 
+  if not opts.silent then
+    vim.notify('[preview.nvim]: compiling...', vim.log.levels.INFO)
+  end
   vim.api.nvim_exec_autocmds('User', {
     pattern = 'PreviewCompileStarted',
     data = { bufnr = bufnr, provider = name },
@@ -512,8 +519,8 @@ function M.toggle(bufnr, name, provider, ctx_builder)
     log.dbg('watching buffer %d with provider "%s"', bufnr, name)
   end
 
-  vim.notify('[preview.nvim]: watching with "' .. name .. '"', vim.log.levels.INFO)
+  vim.notify('[preview.nvim]: compiling with "' .. name .. '"...', vim.log.levels.INFO)
-  M.compile(bufnr, name, provider, ctx_builder(bufnr))
+  M.compile(bufnr, name, provider, ctx_builder(bufnr), { silent = true })
 end
 
 ---@param bufnr integer

lua/preview/presets.lua

@@ -224,7 +224,7 @@ M.markdown = {
   ft = 'markdown',
   cmd = { 'pandoc' },
   args = function(ctx)
-    return { ctx.file, '-s', '--embed-resources', '--mathml', '-o', ctx.output }
+    return { ctx.file, '-s', '--katex', '-o', ctx.output }
   end,
   output = function(ctx)
     return (ctx.file:gsub('%.md$', '.html'))
@@ -249,8 +249,7 @@ M.github = {
       'gfm',
       ctx.file,
       '-s',
-      '--embed-resources',
+      '--katex',
-      '--mathml',
       '--css',
       'https://cdn.jsdelivr.net/gh/pixelbrackets/gfm-stylesheet@master/dist/gfm.css',
       '-o',

spec/compiler_spec.lua

@@ -55,6 +55,14 @@ describe('compiler', function()
         end,
       })
 
+      local notified = false
+      local orig = vim.notify
+      vim.notify = function(msg)
+        if msg:find('compiling') then
+          notified = true
+        end
+      end
+
       local provider = { cmd = { 'echo', 'ok' } }
       local ctx = {
         bufnr = bufnr,
@@ -64,7 +72,9 @@ describe('compiler', function()
       }
 
       compiler.compile(bufnr, 'echo', provider, ctx)
+      vim.notify = orig
       assert.is_true(fired)
+      assert.is_true(notified)
 
       vim.wait(2000, function()
         return process_done(bufnr)

spec/presets_spec.lua

@@ -294,11 +294,11 @@ describe('presets', function()
       assert.are.same({ 'pandoc' }, presets.markdown.cmd)
     end)
 
-    it('returns args with standalone, embed-resources, and mathml flags', function()
+    it('returns args with standalone and katex flags', function()
       local args = presets.markdown.args(md_ctx)
       assert.is_table(args)
       assert.are.same(
-        { '/tmp/document.md', '-s', '--embed-resources', '--mathml', '-o', '/tmp/document.html' },
+        { '/tmp/document.md', '-s', '--katex', '-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, mathml, and css flags', function()
+    it('returns args with standalone, katex, and css flags', function()
       local args = presets.github.args(md_ctx)
       assert.is_table(args)
       assert.are.same({
@@ -390,8 +390,7 @@ describe('presets', function()
         'gfm',
         '/tmp/document.md',
         '-s',
-        '--embed-resources',
+        '--katex',
-        '--mathml',
         '--css',
         'https://cdn.jsdelivr.net/gh/pixelbrackets/gfm-stylesheet@master/dist/gfm.css',
         '-o',