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`.

README.md

@@ -1,6 +1,6 @@
 # preview.nvim
 
-**Universal document previewer for Neovim**
+**Universal previewer for Neovim**
 
 An extensible framework for compiling and previewing _any_ documents (LaTeX,
 Typst, Markdown, etc.)—diagnostics included.
@@ -81,3 +81,8 @@ vim.g.preview = {
   typst = { open = { 'sioyek', '--new-instance' } },
 }
 ```
+
+**Q: How do I set up SyncTeX (forward/inverse search)?**
+
+See `:help preview-synctex` for full recipes covering Zathura, Sioyek, and
+Okular.

doc/preview.txt

@@ -22,10 +22,12 @@ 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|
   9. Health ............................................... |preview-health|
+  10. SyncTeX ............................................. |preview-synctex|
 
 ==============================================================================
 REQUIREMENTS                                           *preview-requirements*
@@ -68,6 +70,10 @@ Provider fields: ~
                                         receives a |preview.Context| and
                                         returns a string[].
 
+  {extra_args}       (string[]|function) Appended to {args} after evaluation.
+                                        Useful for adding flags to a preset
+                                        without replacing its defaults.
+
   {cwd}              (string|function)  Working directory. If a function,
                                         receives a |preview.Context|.
                                         Default: git root or file directory.
@@ -177,13 +183,49 @@ 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)
-  `github`             pandoc → HTML (GitHub-styled, `-f gfm` input)
+  `markdown`           pandoc → HTML (standalone, KaTeX math)
+  `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`)
   `quarto`             quarto render → HTML (scientific publishing)
 
+Math rendering (pandoc presets): ~
+                                                        *preview-math*
+
+The `markdown` and `github` presets use `--katex` by default, which inserts a
+`<script>` tag that loads KaTeX from a CDN at view time. The browser fetches
+the assets once and caches them, so math renders instantly on subsequent loads.
+Requires internet on first view.
+
+For offline use, swap in `--mathml` via `extra_args`. MathML is rendered
+natively by the browser with no external dependencies: >lua
+
+    vim.g.preview = {
+      github = { extra_args = { '--mathml' } },
+    }
+<
+
+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' } },
+    }
+<
+
 ==============================================================================
 COMMANDS                                                  *preview-commands*
 
@@ -272,5 +314,116 @@ Checks: ~
 - Each configured provider's binary is executable
 - Each configured provider's opener binary (if any) is executable
 
+==============================================================================
+SYNCTEX                                                    *preview-synctex*
+
+SyncTeX enables bidirectional navigation between LaTeX source and the
+compiled PDF. The `latex` preset compiles with `-synctex=1` by default.
+
+Forward search (editor -> viewer) requires caching the output path.
+Inverse search (viewer -> editor) requires a fixed Neovim server socket.
+
+The following configs leverage the below basic setup: ~
+
+>lua
+    vim.fn.serverstart('/tmp/nvim-preview.sock')
+
+    local synctex_pdf = {}
+    vim.api.nvim_create_autocmd('User', {
+      pattern = 'PreviewCompileSuccess',
+      callback = function(args)
+        synctex_pdf[args.data.bufnr] = args.data.output
+      end,
+    })
+<
+
+The recipes below bind `<leader>s` for forward search. To scroll the PDF
+automatically on cursor movement, call the forward search function from a
+|CursorMoved| or |CursorHold| autocmd instead.
+
+Viewer-specific recipes: ~
+
+                                                    *preview-synctex-zathura*
+Zathura ~
+
+Inverse search: Ctrl+click.
+
+>lua
+    vim.keymap.set('n', '<leader>s', function()
+      local pdf = synctex_pdf[vim.api.nvim_get_current_buf()]
+      if pdf then
+        vim.fn.jobstart({
+          'zathura', '--synctex-forward',
+          vim.fn.line('.') .. ':0:' .. vim.fn.expand('%:p'), pdf,
+        })
+      end
+    end)
+
+    vim.g.preview = {
+      latex = {
+        open = {
+          'zathura',
+          '--synctex-editor-command',
+          'nvim --server /tmp/nvim-preview.sock'
+            .. [[ --remote-expr "execute('b +%{line} %{input}')"]],
+        },
+      },
+    }
+<
+
+                                                     *preview-synctex-sioyek*
+Sioyek ~
+
+Inverse search: right-click with synctex mode active.
+
+Add to `~/.config/sioyek/prefs_user.config`: >
+    inverse_search_command nvim --server /tmp/nvim-preview.sock --remote-expr "execute('b +%2 %1')"
+<
+
+>lua
+    vim.keymap.set('n', '<leader>s', function()
+      local pdf = synctex_pdf[vim.api.nvim_get_current_buf()]
+      if pdf then
+        vim.fn.jobstart({
+          'sioyek',
+          '--instance-name', 'preview',
+          '--forward-search-file', vim.fn.expand('%:p'),
+          '--forward-search-line', tostring(vim.fn.line('.')),
+          pdf,
+        })
+      end
+    end)
+
+    vim.g.preview = {
+      latex = {
+        open = { 'sioyek', '--instance-name', 'preview' },
+      },
+    }
+<
+
+                                                     *preview-synctex-okular*
+Okular ~
+
+Inverse search (Shift+click): one-time GUI setup via
+Settings -> Configure Okular -> Editor -> Custom Text Editor: >
+    nvim --server /tmp/nvim-preview.sock --remote-expr "execute('b +%l %f')"
+<
+
+>lua
+    vim.keymap.set('n', '<leader>s', function()
+      local pdf = synctex_pdf[vim.api.nvim_get_current_buf()]
+      if pdf then
+        vim.fn.jobstart({
+          'okular', '--unique',
+          ('%s#src:%d:%s'):format(pdf, vim.fn.line('.'), vim.fn.expand('%:p')),
+        })
+      end
+    end)
+
+    vim.g.preview = {
+      latex = { open = { 'okular', '--unique' } },
+    }
+<
+
 ==============================================================================
  vim:tw=78:ts=8:ft=help:norl:

flake.nix

@@ -19,9 +19,10 @@
     {
       formatter = forEachSystem (pkgs: pkgs.nixfmt-tree);
 
-      devShells = forEachSystem (pkgs: {
-        default = pkgs.mkShell {
-          packages = [
+      devShells = forEachSystem (
+        pkgs:
+        let
+          devTools = [
             (pkgs.luajit.withPackages (
               ps: with ps; [
                 busted
@@ -32,10 +33,27 @@
             pkgs.stylua
             pkgs.selene
             pkgs.lua-language-server
-            pkgs.plantuml
-            pkgs.mermaid-cli
           ];
-        };
-      });
+        in
+        {
+          default = pkgs.mkShell {
+            packages = devTools;
+          };
+          presets = pkgs.mkShell {
+            packages = devTools ++ [
+              pkgs.typst
+              pkgs.texliveMedium
+              pkgs.tectonic
+              pkgs.pandoc
+              pkgs.asciidoctor
+              pkgs.quarto
+              pkgs.plantuml
+              pkgs.mermaid-cli
+              pkgs.zathura
+              pkgs.sioyek
+            ];
+          };
+        }
+      );
     };
 }

lua/preview/compiler.lua

@@ -3,45 +3,102 @@ local M = {}
 local diagnostic = require('preview.diagnostic')
 local log = require('preview.log')
 
----@type table<integer, preview.Process>
-local active = {}
+---@class preview.BufState
+---@field watching boolean
+---@field process? table
+---@field is_reload? boolean
+---@field provider? string
+---@field output? string
+---@field viewer? table
+---@field viewer_open? boolean
+---@field open_watcher? uv.uv_fs_event_t
+---@field debounce? uv.uv_timer_t
+---@field bwp_autocmd? integer
+---@field unload_autocmd? integer
 
----@type table<integer, integer>
-local watching = {}
-
----@type table<integer, true>
-local opened = {}
-
----@type table<integer, string>
-local last_output = {}
-
----@type table<integer, table>
-local viewer_procs = {}
-
----@type table<integer, uv.uv_fs_event_t>
-local open_watchers = {}
-
-local debounce_timers = {}
+---@type table<integer, preview.BufState>
+local state = {}
 
 local DEBOUNCE_MS = 500
 
 ---@param bufnr integer
-local function stop_open_watcher(bufnr)
-  local w = open_watchers[bufnr]
-  if w then
-    w:stop()
-    w:close()
-    open_watchers[bufnr] = nil
+---@return preview.BufState
+local function get_state(bufnr)
+  if not state[bufnr] then
+    state[bufnr] = { watching = false }
   end
+  return state[bufnr]
+end
+
+---@param bufnr integer
+local function stop_open_watcher(bufnr)
+  local s = state[bufnr]
+  if not (s and s.open_watcher) then
+    return
+  end
+  s.open_watcher:stop()
+  s.open_watcher:close()
+  s.open_watcher = nil
 end
 
 ---@param bufnr integer
 local function close_viewer(bufnr)
-  local obj = viewer_procs[bufnr]
-  if obj then
-    local kill = obj.kill
-    kill(obj, 'sigterm')
-    viewer_procs[bufnr] = nil
+  local s = state[bufnr]
+  if not (s and s.viewer) then
+    return
+  end
+  s.viewer:kill('sigterm')
+  s.viewer = nil
+end
+
+---@param bufnr integer
+---@param name string
+---@param provider preview.ProviderConfig
+---@param ctx preview.Context
+---@param output string
+local function handle_errors(bufnr, name, provider, ctx, output)
+  local errors_mode = provider.errors
+  if errors_mode == nil then
+    errors_mode = 'diagnostic'
+  end
+  if not (provider.error_parser and errors_mode) then
+    return
+  end
+  if errors_mode == 'diagnostic' then
+    diagnostic.set(bufnr, name, provider.error_parser, output, ctx)
+  elseif errors_mode == 'quickfix' then
+    local ok, diags = pcall(provider.error_parser, output, ctx)
+    if ok and diags and #diags > 0 then
+      local items = {}
+      for _, d in ipairs(diags) do
+        table.insert(items, {
+          bufnr = bufnr,
+          lnum = d.lnum + 1,
+          col = d.col + 1,
+          text = d.message,
+          type = d.severity == vim.diagnostic.severity.WARN and 'W' or 'E',
+        })
+      end
+      vim.fn.setqflist(items, 'r')
+      local win = vim.fn.win_getid()
+      vim.cmd.cwindow()
+      vim.fn.win_gotoid(win)
+    end
+  end
+end
+
+---@param bufnr integer
+---@param provider preview.ProviderConfig
+local function clear_errors(bufnr, provider)
+  local errors_mode = provider.errors
+  if errors_mode == nil then
+    errors_mode = 'diagnostic'
+  end
+  if errors_mode == 'diagnostic' then
+    diagnostic.clear(bufnr)
+  elseif errors_mode == 'quickfix' then
+    vim.fn.setqflist({}, 'r')
+    vim.cmd.cwindow()
   end
 end
 
@@ -54,7 +111,23 @@ local function do_open(bufnr, output_file, open_config)
   elseif type(open_config) == 'table' then
     local open_cmd = vim.list_extend({}, open_config)
     table.insert(open_cmd, output_file)
-    viewer_procs[bufnr] = vim.system(open_cmd)
+    log.dbg('opening viewer for buffer %d: %s', bufnr, table.concat(open_cmd, ' '))
+    local proc
+    proc = vim.system(
+      open_cmd,
+      {},
+      vim.schedule_wrap(function()
+        local s = state[bufnr]
+        if s and s.viewer == proc then
+          log.dbg('viewer exited for buffer %d, resetting viewer_open', bufnr)
+          s.viewer = nil
+          s.viewer_open = nil
+        else
+          log.dbg('viewer exited for buffer %d (stale proc, ignoring)', bufnr)
+        end
+      end)
+    )
+    get_state(bufnr).viewer = proc
   end
 end
 
@@ -90,10 +163,30 @@ local function resolve_reload_cmd(provider, ctx)
   return nil
 end
 
+---@param bufnr integer
+---@param s preview.BufState
+local function stop_watching(bufnr, s)
+  s.watching = false
+  M.stop(bufnr)
+  stop_open_watcher(bufnr)
+  close_viewer(bufnr)
+  s.viewer_open = nil
+  if s.bwp_autocmd then
+    vim.api.nvim_del_autocmd(s.bwp_autocmd)
+    s.bwp_autocmd = nil
+  end
+  if s.debounce then
+    s.debounce:stop()
+    s.debounce:close()
+    s.debounce = nil
+  end
+end
+
 ---@param bufnr integer
 ---@param name string
 ---@param provider preview.ProviderConfig
 ---@param ctx preview.Context
+---@param opts? {oneshot?: boolean}
 function M.compile(bufnr, name, provider, ctx, opts)
   opts = opts or {}
 
@@ -109,7 +202,9 @@ function M.compile(bufnr, name, provider, ctx, opts)
     vim.cmd('silent! update')
   end
 
-  if active[bufnr] then
+  local s = get_state(bufnr)
+
+  if s.process then
     log.dbg('killing existing process for buffer %d before recompile', bufnr)
     M.stop(bufnr)
   end
@@ -127,7 +222,7 @@ function M.compile(bufnr, name, provider, ctx, opts)
   end
 
   if output_file ~= '' then
-    last_output[bufnr] = output_file
+    s.output = output_file
   end
 
   local reload_cmd
@@ -155,74 +250,20 @@ function M.compile(bufnr, name, provider, ctx, opts)
             return
           end
           stderr_acc[#stderr_acc + 1] = data
-          local errors_mode = provider.errors
-          if errors_mode == nil then
-            errors_mode = 'diagnostic'
-          end
-          if provider.error_parser and errors_mode then
-            local output = table.concat(stderr_acc)
-            if errors_mode == 'diagnostic' then
-              diagnostic.set(bufnr, name, provider.error_parser, output, ctx)
-            elseif errors_mode == 'quickfix' then
-              local ok, diags = pcall(provider.error_parser, output, ctx)
-              if ok and diags and #diags > 0 then
-                local items = {}
-                for _, d in ipairs(diags) do
-                  table.insert(items, {
-                    bufnr = bufnr,
-                    lnum = d.lnum + 1,
-                    col = d.col + 1,
-                    text = d.message,
-                    type = d.severity == vim.diagnostic.severity.WARN and 'W' or 'E',
-                  })
-                end
-                vim.fn.setqflist(items, 'r')
-                local win = vim.fn.win_getid()
-                vim.cmd.cwindow()
-                vim.fn.win_gotoid(win)
-              end
-            end
-          end
+          handle_errors(bufnr, name, provider, ctx, table.concat(stderr_acc))
         end),
       },
       vim.schedule_wrap(function(result)
-        if active[bufnr] and active[bufnr].obj == obj then
-          active[bufnr] = nil
+        local cs = state[bufnr]
+        if cs and cs.process == obj then
+          cs.process = nil
         end
         if not vim.api.nvim_buf_is_valid(bufnr) then
           return
         end
-
         if result.code ~= 0 then
           log.dbg('long-running process failed for buffer %d (exit code %d)', bufnr, result.code)
-          local errors_mode = provider.errors
-          if errors_mode == nil then
-            errors_mode = 'diagnostic'
-          end
-          if provider.error_parser and errors_mode then
-            local output = (result.stdout or '') .. (result.stderr or '')
-            if errors_mode == 'diagnostic' then
-              diagnostic.set(bufnr, name, provider.error_parser, output, ctx)
-            elseif errors_mode == 'quickfix' then
-              local ok, diagnostics = pcall(provider.error_parser, output, ctx)
-              if ok and diagnostics and #diagnostics > 0 then
-                local items = {}
-                for _, d in ipairs(diagnostics) do
-                  table.insert(items, {
-                    bufnr = bufnr,
-                    lnum = d.lnum + 1,
-                    col = d.col + 1,
-                    text = d.message,
-                    type = d.severity == vim.diagnostic.severity.WARN and 'W' or 'E',
-                  })
-                end
-                vim.fn.setqflist(items, 'r')
-                local win = vim.fn.win_getid()
-                vim.cmd.cwindow()
-                vim.fn.win_gotoid(win)
-              end
-            end
-          end
+          handle_errors(bufnr, name, provider, ctx, (result.stdout or '') .. (result.stderr or ''))
           vim.api.nvim_exec_autocmds('User', {
             pattern = 'PreviewCompileFailed',
             data = {
@@ -236,7 +277,7 @@ function M.compile(bufnr, name, provider, ctx, opts)
       end)
     )
 
-    if provider.open and not opts.oneshot and not opened[bufnr] and output_file ~= '' then
+    if provider.open and not opts.oneshot and not s.viewer_open and output_file ~= '' then
       local pre_stat = vim.uv.fs_stat(output_file)
       local pre_mtime = pre_stat and pre_stat.mtime.sec or 0
       local out_dir = vim.fn.fnamemodify(output_file, ':h')
@@ -244,7 +285,7 @@ function M.compile(bufnr, name, provider, ctx, opts)
       stop_open_watcher(bufnr)
       local watcher = vim.uv.new_fs_event()
       if watcher then
-        open_watchers[bufnr] = watcher
+        s.open_watcher = watcher
         watcher:start(
           out_dir,
           {},
@@ -252,8 +293,12 @@ function M.compile(bufnr, name, provider, ctx, opts)
             if err or vim.fn.fnamemodify(filename or '', ':t') ~= out_name then
               return
             end
-            if opened[bufnr] then
-              stop_open_watcher(bufnr)
+            local cs = state[bufnr]
+            if not cs then
+              return
+            end
+            if cs.viewer_open then
+              log.dbg('watcher fired for buffer %d but viewer already open', bufnr)
               return
             end
             if not vim.api.nvim_buf_is_valid(bufnr) then
@@ -262,42 +307,31 @@ function M.compile(bufnr, name, provider, ctx, opts)
             end
             local new_stat = vim.uv.fs_stat(output_file)
             if not (new_stat and new_stat.mtime.sec > pre_mtime) then
+              log.dbg(
+                'watcher fired for buffer %d but mtime not newer (%d <= %d)',
+                bufnr,
+                new_stat and new_stat.mtime.sec or 0,
+                pre_mtime
+              )
               return
             end
-            stop_open_watcher(bufnr)
+            log.dbg('watcher opening viewer for buffer %d', bufnr)
+            cs.viewer_open = true
             stderr_acc = {}
-            local errors_mode = provider.errors
-            if errors_mode == nil then
-              errors_mode = 'diagnostic'
-            end
-            if errors_mode == 'diagnostic' then
-              diagnostic.clear(bufnr)
-            elseif errors_mode == 'quickfix' then
-              vim.fn.setqflist({}, 'r')
-              vim.cmd.cwindow()
-            end
+            clear_errors(bufnr, provider)
             do_open(bufnr, output_file, provider.open)
-            opened[bufnr] = true
           end)
         )
       end
     end
 
-    active[bufnr] = { obj = obj, provider = name, output_file = output_file, is_reload = true }
-
-    vim.api.nvim_create_autocmd('BufUnload', {
-      buffer = bufnr,
-      once = true,
-      callback = function()
-        M.stop(bufnr)
-        stop_open_watcher(bufnr)
-        if not provider.detach then
-          close_viewer(bufnr)
-        end
-        last_output[bufnr] = nil
-      end,
-    })
+    s.process = obj
+    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 },
@@ -309,37 +343,28 @@ function M.compile(bufnr, name, provider, ctx, opts)
   if provider.args then
     vim.list_extend(cmd, eval_list(provider.args, resolved_ctx))
   end
+  if provider.extra_args then
+    vim.list_extend(cmd, eval_list(provider.extra_args, resolved_ctx))
+  end
 
   log.dbg('compiling buffer %d with provider "%s": %s', bufnr, name, table.concat(cmd, ' '))
 
   local obj
   obj = vim.system(
     cmd,
-    {
-      cwd = cwd,
-      env = provider.env,
-    },
+    { cwd = cwd, env = provider.env },
     vim.schedule_wrap(function(result)
-      if active[bufnr] and active[bufnr].obj == obj then
-        active[bufnr] = nil
+      local cs = state[bufnr]
+      if cs and cs.process == obj then
+        cs.process = nil
       end
       if not vim.api.nvim_buf_is_valid(bufnr) then
         return
       end
-
-      local errors_mode = provider.errors
-      if errors_mode == nil then
-        errors_mode = 'diagnostic'
-      end
-
       if result.code == 0 then
         log.dbg('compilation succeeded for buffer %d', bufnr)
-        if errors_mode == 'diagnostic' then
-          diagnostic.clear(bufnr)
-        elseif errors_mode == 'quickfix' then
-          vim.fn.setqflist({}, 'r')
-          vim.cmd.cwindow()
-        end
+        vim.notify('[preview.nvim]: compilation complete', vim.log.levels.INFO)
+        clear_errors(bufnr, provider)
         vim.api.nvim_exec_autocmds('User', {
           pattern = 'PreviewCompileSuccess',
           data = { bufnr = bufnr, provider = name, output = output_file },
@@ -350,42 +375,21 @@ function M.compile(bufnr, name, provider, ctx, opts)
           r.inject(output_file)
           r.broadcast()
         end
+        cs = state[bufnr]
         if
           provider.open
           and not opts.oneshot
-          and not opened[bufnr]
+          and cs
+          and not cs.viewer_open
           and output_file ~= ''
           and vim.uv.fs_stat(output_file)
         then
+          cs.viewer_open = true
           do_open(bufnr, output_file, provider.open)
-          opened[bufnr] = true
         end
       else
         log.dbg('compilation failed for buffer %d (exit code %d)', bufnr, result.code)
-        if provider.error_parser and errors_mode then
-          local output = (result.stdout or '') .. (result.stderr or '')
-          if errors_mode == 'diagnostic' then
-            diagnostic.set(bufnr, name, provider.error_parser, output, ctx)
-          elseif errors_mode == 'quickfix' then
-            local ok, diagnostics = pcall(provider.error_parser, output, ctx)
-            if ok and diagnostics and #diagnostics > 0 then
-              local items = {}
-              for _, d in ipairs(diagnostics) do
-                table.insert(items, {
-                  bufnr = bufnr,
-                  lnum = d.lnum + 1,
-                  col = d.col + 1,
-                  text = d.message,
-                  type = d.severity == vim.diagnostic.severity.WARN and 'W' or 'E',
-                })
-              end
-              vim.fn.setqflist(items, 'r')
-              local win = vim.fn.win_getid()
-              vim.cmd.cwindow()
-              vim.fn.win_gotoid(win)
-            end
-          end
-        end
+        handle_errors(bufnr, name, provider, ctx, (result.stdout or '') .. (result.stderr or ''))
         vim.api.nvim_exec_autocmds('User', {
           pattern = 'PreviewCompileFailed',
           data = {
@@ -399,20 +403,13 @@ function M.compile(bufnr, name, provider, ctx, opts)
     end)
   )
 
-  active[bufnr] = { obj = obj, provider = name, output_file = output_file }
-
-  vim.api.nvim_create_autocmd('BufUnload', {
-    buffer = bufnr,
-    once = true,
-    callback = function()
-      M.stop(bufnr)
-      if not provider.detach then
-        close_viewer(bufnr)
-      end
-      last_output[bufnr] = nil
-    end,
-  })
+  s.process = obj
+  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 },
@@ -421,39 +418,37 @@ end
 
 ---@param bufnr integer
 function M.stop(bufnr)
-  local proc = active[bufnr]
-  if not proc then
+  local s = state[bufnr]
+  if not s then
+    return
+  end
+  local obj = s.process
+  if not obj then
     return
   end
   log.dbg('stopping process for buffer %d', bufnr)
-  ---@type fun(self: table, signal: string|integer)
-  local kill = proc.obj.kill
-  kill(proc.obj, 'sigterm')
+  obj:kill('sigterm')
 
   local timer = vim.uv.new_timer()
   if timer then
     timer:start(5000, 0, function()
       timer:close()
-      if active[bufnr] and active[bufnr].obj == proc.obj then
-        kill(proc.obj, 'sigkill')
-        active[bufnr] = nil
+      local cs = state[bufnr]
+      if cs and cs.process == obj then
+        obj:kill('sigkill')
+        cs.process = nil
       end
     end)
   end
 end
 
 function M.stop_all()
-  for bufnr, _ in pairs(active) do
-    M.stop(bufnr)
-  end
-  for bufnr, _ in pairs(watching) do
-    M.unwatch(bufnr)
-  end
-  for bufnr, _ in pairs(open_watchers) do
-    stop_open_watcher(bufnr)
-  end
-  for bufnr, _ in pairs(viewer_procs) do
-    close_viewer(bufnr)
+  for bufnr, s in pairs(state) do
+    stop_watching(bufnr, s)
+    if s.unload_autocmd then
+      vim.api.nvim_del_autocmd(s.unload_autocmd)
+    end
+    state[bufnr] = nil
   end
   require('preview.reload').stop()
 end
@@ -464,76 +459,77 @@ end
 ---@param ctx_builder fun(bufnr: integer): preview.Context
 function M.toggle(bufnr, name, provider, ctx_builder)
   local is_longrunning = type(provider.reload) == 'table' or type(provider.reload) == 'function'
+  local s = get_state(bufnr)
 
-  if is_longrunning then
-    if active[bufnr] then
-      M.stop(bufnr)
-      vim.notify('[preview.nvim]: watching stopped', vim.log.levels.INFO)
+  if s.watching then
+    local output = s.output
+    if not s.viewer_open and provider.open and output and vim.uv.fs_stat(output) then
+      log.dbg('toggle reopen viewer for buffer %d', bufnr)
+      s.viewer_open = true
+      do_open(bufnr, output, provider.open)
     else
-      M.compile(bufnr, name, provider, ctx_builder(bufnr))
-      vim.notify('[preview.nvim]: watching with "' .. name .. '"', vim.log.levels.INFO)
+      log.dbg('toggle off for buffer %d', bufnr)
+      stop_watching(bufnr, s)
+      vim.notify('[preview.nvim]: watching stopped', vim.log.levels.INFO)
     end
     return
   end
 
-  if watching[bufnr] then
-    M.unwatch(bufnr)
-    vim.notify('[preview.nvim]: watching stopped', vim.log.levels.INFO)
-    return
+  log.dbg('toggle on for buffer %d', bufnr)
+  s.watching = true
+
+  if s.unload_autocmd then
+    vim.api.nvim_del_autocmd(s.unload_autocmd)
   end
-
-  local au_id = vim.api.nvim_create_autocmd('BufWritePost', {
-    buffer = bufnr,
-    callback = function()
-      if debounce_timers[bufnr] then
-        debounce_timers[bufnr]:stop()
-      else
-        debounce_timers[bufnr] = vim.uv.new_timer()
-      end
-      debounce_timers[bufnr]:start(
-        DEBOUNCE_MS,
-        0,
-        vim.schedule_wrap(function()
-          local ctx = ctx_builder(bufnr)
-          M.compile(bufnr, name, provider, ctx)
-        end)
-      )
-    end,
-  })
-
-  watching[bufnr] = au_id
-  log.dbg('watching buffer %d with provider "%s"', bufnr, name)
-  vim.notify('[preview.nvim]: watching with "' .. name .. '"', vim.log.levels.INFO)
-
-  vim.api.nvim_create_autocmd('BufUnload', {
+  s.unload_autocmd = vim.api.nvim_create_autocmd('BufUnload', {
     buffer = bufnr,
     once = true,
     callback = function()
-      M.unwatch(bufnr)
+      M.stop(bufnr)
       stop_open_watcher(bufnr)
       if not provider.detach then
         close_viewer(bufnr)
       end
-      opened[bufnr] = nil
+      state[bufnr] = nil
     end,
   })
 
-  M.compile(bufnr, name, provider, ctx_builder(bufnr))
+  if not is_longrunning then
+    s.bwp_autocmd = vim.api.nvim_create_autocmd('BufWritePost', {
+      buffer = bufnr,
+      callback = function()
+        local ds = state[bufnr]
+        if not ds then
+          return
+        end
+        if ds.debounce then
+          ds.debounce:stop()
+        else
+          ds.debounce = vim.uv.new_timer()
+        end
+        ds.debounce:start(
+          DEBOUNCE_MS,
+          0,
+          vim.schedule_wrap(function()
+            M.compile(bufnr, name, provider, ctx_builder(bufnr))
+          end)
+        )
+      end,
+    })
+    log.dbg('watching buffer %d with provider "%s"', bufnr, name)
+  end
+
+  vim.notify('[preview.nvim]: compiling with "' .. name .. '"...', vim.log.levels.INFO)
+  M.compile(bufnr, name, provider, ctx_builder(bufnr), { silent = true })
 end
 
 ---@param bufnr integer
 function M.unwatch(bufnr)
-  local au_id = watching[bufnr]
-  if not au_id then
+  local s = state[bufnr]
+  if not s then
     return
   end
-  vim.api.nvim_del_autocmd(au_id)
-  if debounce_timers[bufnr] then
-    debounce_timers[bufnr]:stop()
-    debounce_timers[bufnr]:close()
-    debounce_timers[bufnr] = nil
-  end
-  watching[bufnr] = nil
+  stop_watching(bufnr, s)
   log.dbg('unwatched buffer %d', bufnr)
 end
 
@@ -582,7 +578,8 @@ end
 ---@param bufnr integer
 ---@return boolean
 function M.open(bufnr, open_config)
-  local output = last_output[bufnr]
+  local s = state[bufnr]
+  local output = s and s.output
   if not output then
     log.dbg('no last output file for buffer %d', bufnr)
     return false
@@ -598,26 +595,20 @@ end
 ---@param bufnr integer
 ---@return preview.Status
 function M.status(bufnr)
-  local proc = active[bufnr]
-  if proc then
-    return {
-      compiling = not proc.is_reload,
-      watching = watching[bufnr] ~= nil or proc.is_reload == true,
-      provider = proc.provider,
-      output_file = proc.output_file,
-    }
+  local s = state[bufnr]
+  if not s then
+    return { compiling = false, watching = false }
   end
-  return { compiling = false, watching = watching[bufnr] ~= nil }
+  return {
+    compiling = s.process ~= nil and not s.is_reload,
+    watching = s.watching,
+    provider = s.provider,
+    output_file = s.output,
+  }
 end
 
 M._test = {
-  active = active,
-  watching = watching,
-  opened = opened,
-  last_output = last_output,
-  debounce_timers = debounce_timers,
-  viewer_procs = viewer_procs,
-  open_watchers = open_watchers,
+  state = state,
 }
 
 return M

lua/preview/init.lua

@@ -2,6 +2,7 @@
 ---@field ft? string
 ---@field cmd string[]
 ---@field args? string[]|fun(ctx: preview.Context): string[]
+---@field extra_args? string[]|fun(ctx: preview.Context): string[]
 ---@field cwd? string|fun(ctx: preview.Context): string
 ---@field env? table<string, string>
 ---@field output? string|fun(ctx: preview.Context): string
@@ -94,6 +95,7 @@ function M.setup(opts)
     vim.validate(prefix .. '.cmd', provider.cmd, 'table')
     vim.validate(prefix .. '.cmd[1]', provider.cmd[1], 'string')
     vim.validate(prefix .. '.args', provider.args, { 'table', 'function' }, true)
+    vim.validate(prefix .. '.extra_args', provider.extra_args, { 'table', 'function' }, true)
     vim.validate(prefix .. '.cwd', provider.cwd, { 'string', 'function' }, true)
     vim.validate(prefix .. '.output', provider.output, { 'string', 'function' }, true)
     vim.validate(prefix .. '.error_parser', provider.error_parser, 'function', true)

lua/preview/presets.lua

@@ -115,6 +115,24 @@ local function parse_asciidoctor(output)
   return diagnostics
 end
 
+---@param output string
+---@return preview.Diagnostic[]
+local function parse_mermaid(output)
+  local lnum = output:match('Parse error on line (%d+)')
+  if not lnum then
+    return {}
+  end
+  local msg = output:match('(Expecting .+)') or 'parse error'
+  return {
+    {
+      lnum = tonumber(lnum) - 1,
+      col = 0,
+      message = msg,
+      severity = vim.diagnostic.severity.ERROR,
+    },
+  }
+end
+
 ---@type preview.ProviderConfig
 M.typst = {
   ft = 'typst',
@@ -206,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', '--katex', '-o', ctx.output }
   end,
   output = function(ctx)
     return (ctx.file:gsub('%.md$', '.html'))
@@ -231,7 +249,7 @@ M.github = {
       'gfm',
       ctx.file,
       '-s',
-      '--embed-resources',
+      '--katex',
       '--css',
       'https://cdn.jsdelivr.net/gh/pixelbrackets/gfm-stylesheet@master/dist/gfm.css',
       '-o',
@@ -313,19 +331,7 @@ M.mermaid = {
     return (ctx.file:gsub('%.mmd$', '.svg'))
   end,
   error_parser = function(output)
-    local diagnostics = {}
-    for line in output:gmatch('[^\r\n]+') do
-      local lnum = line:match('^%s*Parse error on line (%d+)')
-      if lnum then
-        table.insert(diagnostics, {
-          lnum = tonumber(lnum) - 1,
-          col = 0,
-          message = line,
-          severity = vim.diagnostic.severity.ERROR,
-        })
-      end
-    end
-    return diagnostics
+    return parse_mermaid(output)
   end,
   clean = function(ctx)
     return { 'rm', '-f', (ctx.file:gsub('%.mmd$', '.svg')) }

spec/compiler_spec.lua

@@ -8,8 +8,13 @@ describe('compiler', function()
     compiler = require('preview.compiler')
   end)
 
+  local function process_done(bufnr)
+    local s = compiler._test.state[bufnr]
+    return not s or s.process == nil
+  end
+
   describe('compile', function()
-    it('spawns a process and tracks it in active table', function()
+    it('spawns a process and tracks it in state', function()
       local bufnr = helpers.create_buffer({ 'hello' }, 'text')
       vim.api.nvim_buf_set_name(bufnr, '/tmp/preview_test.txt')
       vim.bo[bufnr].modified = false
@@ -23,15 +28,16 @@ describe('compiler', function()
       }
 
       compiler.compile(bufnr, 'echo', provider, ctx)
-      local active = compiler._test.active
-      assert.is_not_nil(active[bufnr])
-      assert.are.equal('echo', active[bufnr].provider)
+      local s = compiler._test.state[bufnr]
+      assert.is_not_nil(s)
+      assert.is_not_nil(s.process)
+      assert.are.equal('echo', s.provider)
 
       vim.wait(2000, function()
-        return active[bufnr] == nil
+        return process_done(bufnr)
       end, 50)
 
-      assert.is_nil(active[bufnr])
+      assert.is_nil(compiler._test.state[bufnr].process)
       helpers.delete_buffer(bufnr)
     end)
 
@@ -49,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,
@@ -58,10 +72,12 @@ 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 compiler._test.active[bufnr] == nil
+        return process_done(bufnr)
       end, 50)
 
       helpers.delete_buffer(bufnr)
@@ -124,7 +140,7 @@ describe('compiler', function()
       vim.notify = orig
 
       assert.is_true(notified)
-      assert.is_nil(compiler._test.active[bufnr])
+      assert.is_true(process_done(bufnr))
       helpers.delete_buffer(bufnr)
     end)
 
@@ -186,7 +202,7 @@ describe('compiler', function()
       compiler.compile(bufnr, 'falsecmd', provider, ctx)
 
       vim.wait(2000, function()
-        return compiler._test.active[bufnr] == nil
+        return process_done(bufnr)
       end, 50)
 
       assert.is_false(parser_called)
@@ -218,7 +234,7 @@ describe('compiler', function()
       compiler.compile(bufnr, 'qfcmd', provider, ctx)
 
       vim.wait(2000, function()
-        return compiler._test.active[bufnr] == nil
+        return process_done(bufnr)
       end, 50)
 
       local qflist = vim.fn.getqflist()
@@ -255,7 +271,7 @@ describe('compiler', function()
       compiler.compile(bufnr, 'truecmd', provider, ctx)
 
       vim.wait(2000, function()
-        return compiler._test.active[bufnr] == nil
+        return process_done(bufnr)
       end, 50)
 
       assert.are.equal(0, #vim.fn.getqflist())
@@ -298,7 +314,7 @@ describe('compiler', function()
       compiler.stop(bufnr)
 
       vim.wait(2000, function()
-        return compiler._test.active[bufnr] == nil
+        return process_done(bufnr)
       end, 50)
 
       helpers.delete_buffer(bufnr)
@@ -329,11 +345,12 @@ describe('compiler', function()
       }
 
       compiler.compile(bufnr, 'testprov', provider, ctx)
-      assert.is_not_nil(compiler._test.last_output[bufnr])
-      assert.are.equal('/tmp/preview_test_open.pdf', compiler._test.last_output[bufnr])
+      local s = compiler._test.state[bufnr]
+      assert.is_not_nil(s)
+      assert.are.equal('/tmp/preview_test_open.pdf', s.output)
 
       vim.wait(2000, function()
-        return compiler._test.active[bufnr] == nil
+        return process_done(bufnr)
       end, 50)
 
       helpers.delete_buffer(bufnr)
@@ -341,7 +358,7 @@ describe('compiler', function()
   end)
 
   describe('toggle', function()
-    it('registers autocmd and tracks in watching table', function()
+    it('starts watching and sets watching flag', function()
       local bufnr = helpers.create_buffer({ 'hello' }, 'text')
       vim.api.nvim_buf_set_name(bufnr, '/tmp/preview_test_watch.txt')
 
@@ -351,7 +368,7 @@ describe('compiler', function()
       end
 
       compiler.toggle(bufnr, 'echo', provider, ctx_builder)
-      assert.is_not_nil(compiler._test.watching[bufnr])
+      assert.is_true(compiler.status(bufnr).watching)
 
       helpers.delete_buffer(bufnr)
     end)
@@ -366,10 +383,10 @@ describe('compiler', function()
       end
 
       compiler.toggle(bufnr, 'echo', provider, ctx_builder)
-      assert.is_not_nil(compiler._test.watching[bufnr])
+      assert.is_true(compiler.status(bufnr).watching)
 
       compiler.toggle(bufnr, 'echo', provider, ctx_builder)
-      assert.is_nil(compiler._test.watching[bufnr])
+      assert.is_false(compiler.status(bufnr).watching)
 
       helpers.delete_buffer(bufnr)
     end)
@@ -389,10 +406,10 @@ describe('compiler', function()
       end
 
       compiler.toggle(bufnr, 'echo', provider, ctx_builder)
-      assert.is_not_nil(compiler._test.watching[bufnr])
+      assert.is_true(compiler.status(bufnr).watching)
 
       compiler.stop_all()
-      assert.is_nil(compiler._test.watching[bufnr])
+      assert.is_false(compiler.status(bufnr).watching)
 
       helpers.delete_buffer(bufnr)
     end)

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 and katex 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', '--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, 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,7 +390,7 @@ describe('presets', function()
         'gfm',
         '/tmp/document.md',
         '-s',
-        '--embed-resources',
+        '--katex',
         '--css',
         'https://cdn.jsdelivr.net/gh/pixelbrackets/gfm-stylesheet@master/dist/gfm.css',
         '-o',