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.
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`.
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.
* refactor(compiler): replace 7 state tables with unified `BufState`
Problem: `compiler.lua` tracked per-buffer state across 7 separate
module-level tables, causing scattered cleanup, triplicated
error-handling blocks, accumulating `BufUnload` autocmds on every
compile, and a race condition where `active[bufnr]` (cleared
asynchronously on process exit) was used as the toggle on/off gate.
Solution: Consolidate all per-buffer state into a single `state` table
holding a `preview.BufState` record per buffer. Extract `handle_errors`
and `clear_errors` helpers. Move `BufUnload` lifecycle entirely into
`M.toggle` with `unload_autocmd` tracking to prevent accumulation.
Toggle now gates on `s.watching` (synchronous boolean) and reopens a
closed viewer when watching is active rather than stopping.
* fix(compiler): split nil guard in `M.stop` for type narrowing
* ci: typing
* docs: add SyncTeX section with viewer recipes
Problem: SyncTeX setup for forward/inverse search was undocumented,
forcing users to figure out viewer-specific CLI flags on their own.
Solution: Add `preview-synctex` vimdoc section with shared setup and
per-viewer recipes for Zathura, Sioyek, and Okular. Add FAQ entry
in README pointing to the new section.
* build: add `zathura` and `sioyek` to nix dev shell
* docs: fix Okular inverse search instructions
Problem: Okular settings path was incomplete and didn't mention the
trigger keybinding.
Solution: Update to full path (Settings -> Configure Okular -> Editor)
and note that Shift+click triggers inverse search.
* feat: add `extra_args` provider field
Problem: Overriding a single flag (e.g. `-outdir=build`) required
redefining the entire `args` function, duplicating all preset defaults.
Solution: Add `extra_args` field that appends to the resolved `args`
after evaluation. Accepts a static table or a context function.
* docs: document `extra_args` provider field
* feat: add `mermaid` preset
Problem: no built-in support for compiling mermaid diagrams via `mmdc`.
Solution: add a `mermaid` preset that compiles `.mmd` files to SVG and
parses `Parse error on line N` diagnostics from stderr. Add
`mermaid-cli` to the nix dev shell.
* refactor(presets): simplify `mermaid` error parser
Problem: the inline `mermaid` error_parser looped over every line and
used the `Parse error on line N:` header as the message, losing the
useful `Expecting ..., got ...` token detail.
Solution: extract `parse_mermaid` alongside the other parse functions,
use a single `output:match` (mermaid's JISON parser stops at the first
error), and surface the `Expecting ..., got ...` line as the message.
* ci: format
* ci: format
Problem: the single dev shell mixed dev tooling (linters, test runner)
with preset compiler tools, causing heavy rebuilds (e.g. Chromium for
`mermaid-cli`) for contributors who only need the dev tools.
Solution: extract dev tooling into a shared `devTools` list and expose
two shells — `default` for development and `presets` for running all
built-in preset compilers (`typst`, `texliveMedium`, `tectonic`,
`pandoc`, `asciidoctor`, `quarto`, `plantuml`, `mermaid-cli`).
Problem: the README and vimdoc presets list omitted `plantuml` and
`mermaid` after both were added.
Solution: add both presets to the vimdoc table and the README features
blurb.
Problem: no built-in support for compiling mermaid diagrams via `mmdc`.
Solution: add a `mermaid` preset that compiles `.mmd` files to SVG and
parses `Parse error on line N` diagnostics from stderr. Add
`mermaid-cli` to the nix dev shell.
Problem: PlantUML (`.puml`) diagrams have no built-in preview support,
and Neovim lacks filetype detection for PlantUML files.
Solution: Add a `plantuml` preset that compiles to SVG via `plantuml
-tsvg`, with an error parser for `Error line N` diagnostics. Register
`.puml` and `.pu` extensions via `vim.filetype.add` when the preset is
configured. Add `plantuml` to the nix dev shell.
Problem: The vimdoc used `preview.nvim.txt` filename and
`*preview.nvim-xyz*` tags, inconsistent with other plugins.
Solution: Rename to `preview.txt`, normalize tags to `*preview-xyz*`,
add contents/install sections, and use `{field} (type)` formatting.
Problem: viewer processes launched via a string[] `open` command were
always killed on buffer deletion with no way to opt out. Configuring
the plugin also required an explicit `setup()` call in a `config`
hook, preventing config from being declared before the plugin loads.
Solution: add a `detach` boolean to `ProviderConfig` that skips
SIGTERM on buffer unload. Auto-call `setup()` from `vim.g.preview`
at module load time, enabling config via lazy.nvim's `init` hook.
Update vimdoc and README accordingly.
* fix(compiler): open quickfix in background, retain focus on source buffer
* fix(compiler): use cwindow and win_gotoid for quickfix focus management
* fix: unused var warning and update typst reload test for short format
* fix: remove testing files
Problem: Long-running providers (e.g. `typst watch`) never exit on
compile error, so the exit callback never fired and diagnostics/quickfix
were never populated. The `typst watch` `reload` command also lacked
`--diagnostic-format short`, producing unparseable verbose output.
Solution: Add a `stderr` streaming callback to the long-running
`vim.system` call that accumulates chunks and re-parses on each new
chunk, populating diagnostics or quickfix in real time. When the
fs_event fires (successful compile), clear `stderr_acc` and the
reported errors. Add `--diagnostic-format short` to the typst `reload`
command to match the one-shot `args` format.
* fix(compiler): defer open until successful compile, close viewer on :bd
Problem: For long-running providers (e.g. `typst watch`), the viewer
was opened immediately on toggle start by checking if the output file
existed on disk. A stale PDF from a prior session satisfied that check,
so a failed compile still opened the viewer. Additionally, viewer
processes spawned via a table `open` command were untracked, so `:bd`
killed the compiler but left the viewer running.
Solution: Replace the immediate open with a `vim.uv.new_fs_event`
directory watcher that fires only when the output file's `mtime`
advances past its pre-compile value, proving the current session wrote
it. Add `viewer_procs` and `open_watchers` tables with `close_viewer`
and `stop_open_watcher` helpers; all `BufUnload` paths and `stop_all`
now tear down both. Extract `do_open` to deduplicate the open branching
logic across three call sites.
* docs: document viewer auto-close behaviour and limitations in `open` field
* ci: format
* docs: pre-release polish
Update README preset list to include pdflatex, tectonic, asciidoctor,
and quarto. Fix custom provider FAQ example to use a non-preset key.
Clarify open field fires on toggle/watch mode only, not :Preview compile.
Expand intro to mention AsciiDoc and Quarto alongside existing tools.
* docs: update slogan to universal document previewer
* ci: format
Problem: asciidoctor exits 0 on errors so error_parser never ran.
typst, pdflatex, and tectonic had no clean subcommand. auto-open
fired on :Preview compile, surprising users who just want a build.
Solution: pass --failure-level ERROR in asciidoctor args. Add clean
commands to typst (rm pdf), pdflatex (rm pdf/aux/log/synctex.gz),
and tectonic (rm pdf). Gate auto-open on not opts.oneshot so it
only fires during toggle/watch mode.
Problem: --configpath is resolved relative to the workspace root passed
to --check (lua/), not CWD. So .luarc.json was looked up at lua/.luarc.json
and not found, leaving vim and jit as undefined globals.
Solution: expand to an absolute path with $(pwd) at shell invocation
time, matching what the GitHub CI action already does.
Problem: lua-language-server --check lua/ treats lua/ as its workspace
root and fails to find .luarc.json in the project root, so diagnostics
globals (vim, jit) are not loaded and every vim.* reference is flagged
as undefined-global.
Solution: pass --configpath .luarc.json explicitly, matching what the
GitHub CI action already does.
Problem: reload_spec.lua called io.open() without nil checks, causing
need-check-nil warnings. Adding ${3rd}/busted and ${3rd}/luassert to
workspace.library caused lua-language-server 3.7.4 to run diagnostics
on its own bundled meta files, surfacing pre-existing cast-local-type
bugs in luassert's annotations that are not ours to fix.
Solution: use assert(io.open(...)) in reload_spec.lua to satisfy the
nil check. Remove busted/luassert library paths from .luarc.json since
they only benefit spec/ which is not type-checked in CI. Narrow the
lua-language-server check in scripts/ci.sh to lua/ to match CI.
* feat(presets): add pdflatex preset
Adds a direct pdflatex preset for users who want single-pass
compilation without latexmk orchestration. Uses -file-line-error
for parseable diagnostics and reuses the existing parse_latexmk
error parser since both emit the same file:line: message format.
* feat(presets): add tectonic preset
Adds a tectonic preset for the modern Rust-based LaTeX engine, which
auto-downloads packages and requires no TeX installation. Reuses
parse_latexmk since tectonic emits the same file:line: message
diagnostic format.
* feat(presets): add asciidoctor preset
Adds an asciidoctor preset for AsciiDoc → HTML compilation with SSE
live-reload. Includes a parse_asciidoctor error parser handling the
"asciidoctor: SEVERITY: file: line N: message" format for both
ERROR and WARNING diagnostics.
* feat(presets): add quarto preset
Adds a quarto preset for .qmd scientific documents rendering to
self-contained HTML with SSE live-reload. Uses --embed-resources
to avoid a _files directory in the common case. No error_parser
since quarto errors are heterogeneous (mixed R/Python/pandoc output).
* refactor: apply stylua formatting to new preset code
* fix(commands): register VimLeavePre to call stop_all
Problem: spawned compiler processes and watching autocmds were never
cleaned up when Neovim exited, leaving orphaned processes running.
Solution: register a VimLeavePre autocmd in commands setup that calls
compiler.stop_all(), which kills active processes, unwatches all
buffers, and stops the reload server.
* fix(compiler): replace BufWipeout with BufUnload
Problem: cleanup autocmds used BufWipeout, which only fires for
:bwipeout. The common :bdelete path (used by most buffer managers
and nvim_buf_delete) fires BufUnload but not BufWipeout, so processes
and watches leaked on normal buffer deletion.
Solution: switch all three cleanup autocmds from BufWipeout to
BufUnload, which fires for both :bdelete and :bwipeout.
* fix(init): guard against unnamed buffer in public API
Problem: calling compile/toggle/clean/open on an unsaved scratch
buffer passed an empty string as ctx.file, producing nonsensical
output paths like ".pdf" and silently passing empty strings to
compiler binaries.
Solution: add an early return with a WARN notification in compile,
toggle, clean, and open when the buffer has no file name.
* fix(compiler): add fs_stat check to one-shot open path
Problem: the long-running process path already guarded opens with
vim.uv.fs_stat(), but the one-shot compile path and M.open() did not.
Compilation can exit 0 and produce no output, and output files can be
externally deleted between compile and open.
Solution: add the same fs_stat guard to the one-shot open branch and
to M.open() before attempting to launch the viewer.
* fix(compiler): check executable before spawning process
Problem: if a configured binary was missing or not in PATH, vim.system
would fail silently or with a cryptic OS error. The user had no
actionable feedback without running :checkhealth.
Solution: check vim.fn.executable() at the start of M.compile() and
notify with an ERROR-level message pointing to :checkhealth preview
if the binary is not found.
* fix(compiler): reformat one-shot open condition for line length
Problem: the added fs_stat condition exceeded stylua's line length
limit on the one-shot open guard.
Solution: split the boolean condition across multiple lines to match
the project's stylua formatting rules.
* refactor: rename build to compile and watch to toggle in public API
Problem: the code used build/watch while the help file already
documented compile/toggle, creating a confusing mismatch.
Solution: rename M.build() to M.compile() and M.watch() to M.toggle()
in init.lua, update handler keys in commands.lua, and update the test
file to match.
* refactor(commands): make toggle the default subcommand
Problem: bare :Preview ran a one-shot compile, but users reaching for a
"preview" plugin expect it to start previewing (i.e. watch mode).
Solution: change the fallback subcommand from compile to toggle so
:Preview starts/stops auto-compile on save.
* refactor(commands): remove stop subcommand
Problem: :Preview stop had a subtle distinction from toggle-off (kill
process but keep autocmd) that nobody reaches for deliberately from
the command line.
Solution: remove stop from the command dispatch table. The Lua API
require('preview').stop() remains as a programmatic escape hatch.
* docs: update help file for new command surface and document reload
Problem: the help file listed compile as the default subcommand, still
included the stop subcommand, omitted the reload provider field, and
had a misleading claim about shipping with zero defaults.
Solution: make toggle the default in the commands section, remove stop
from subcommands, add reload to provider fields, fix the introduction
text, reorder API entries to match new primacy, and add an output path
override example addressing #26/#27.
* fix(compiler): skip reload command for one-shot builds
Problem: compile() unconditionally resolved the reload command, so
:Preview build on a provider with reload = function/table (e.g. typst)
would start a long-running process (typst watch) instead of a one-shot
compile (typst compile). Error diagnostics were also lost because
typst watch does not exit non-zero on input errors.
Solution: add an opts parameter to compile() with a oneshot flag.
M.build() passes { oneshot = true } so resolve_reload_cmd() is
skipped and the one-shot path is always taken. toggle() continues
to call compile() without the flag, preserving long-running behavior
for watch mode.
* fix(compiler): respect provider open config in M.open()
Problem: :Preview open always called vim.ui.open regardless of the
provider's open field. Providers configured with a custom opener
(e.g. open = { 'sioyek', '--new-instance' }) were ignored, so the
first build opened with sioyek but :Preview open fell back to the
system default.
Solution: init.lua resolves the provider's open config and passes it
to compiler.open(). If open_config is a table, the custom command is
spawned with the output path appended. Otherwise vim.ui.open is used
as before.
* fix: normalize notify prefix to [preview.nvim]: everywhere
Problem: some vim.notify calls used [preview.nvim] (no colon) while
others used [preview.nvim]: — inconsistent with the log module format.
Solution: add the missing colon and space to all notify calls in
init.lua and compiler.lua so every user-facing message matches the
[preview.nvim]: prefix used by the log module.
* ci: format
* fix(compiler): check output exists before opening from long-running process
Problem: for long-running processes (typst watch), M.compile() calls
the opener immediately after vim.system() returns, before the process
has produced any output. On first run the output file does not exist
yet, so the opener is called on a nonexistent path.
Solution: guard the open block with vim.uv.fs_stat so it only fires
if the output file already exists at spawn time.
* style(compiler): reformat long condition for stylua
* fix(compiler): guard active entry before clearing in process callback
Problem: when M.compile() is called while a previous process is still
running, the old process's vim.schedule_wrap callback unconditionally
sets active[bufnr] = nil, wiping the new process from the tracking
table. status() incorrectly returns idle and stop() becomes a no-op
against the still-running process.
Solution: capture obj as an upvalue in each callback and only clear
active[bufnr] if it still points to the same process object.
* fix(compiler): hoist obj declaration before vim.system closure
Problem: lua-language-server flagged obj as an undefined global in
both vim.schedule_wrap callbacks because local obj = vim.system(...)
puts the variable out of scope inside the closure at declaration time.
At runtime the guard active[bufnr].obj == obj evaluated obj as nil,
so the clear was always skipped and the process remained tracked
indefinitely.
Solution: split into local obj / obj = vim.system(...) so the
upvalue is in scope when the closure is defined.
* fix(reload): bind SSE server to port 0 for OS-assigned port
Problem: the SSE reload server hardcoded port 5554, causing silent
failure when that port was already in use. bind() would fail but its
return value was never checked; listen() would also error and silently
drop via the if err then return end guard. inject() still wrote the
dead EventSource URL into the HTML, so the browser would connect to
whatever was on 5554 — or nothing — and live reload would silently
stop working.
Solution: bind to port or 0 so the OS assigns a free port, then call
getsockname() after bind to capture the actual port into actual_port.
inject() reads actual_port in preference to the hardcoded constant,
and stop() resets it. PORT = 5554 is kept only as a last-resort
fallback in inject() if actual_port is unset.
* fix(compiler): resolve output into ctx before evaluating clean command
Problem: M.clean() passes the raw ctx (no output field) to the
provider's clean function. Built-in presets work around this by
recomputing the output path inline, but custom providers using
ctx.output in their clean function receive nil.
Solution: resolve output_file from provider.output before eval, extend
ctx into resolved_ctx with the output field, and use resolved_ctx when
evaluating clean and cwd — consistent with how M.compile() handles args.
Problem: the SSE reload server hardcoded port 5554, causing silent
failure when that port was already in use. bind() would fail but its
return value was never checked; listen() would also error and silently
drop via the if err then return end guard. inject() still wrote the
dead EventSource URL into the HTML, so the browser would connect to
whatever was on 5554 — or nothing — and live reload would silently
stop working.
Solution: bind to port or 0 so the OS assigns a free port, then call
getsockname() after bind to capture the actual port into actual_port.
inject() reads actual_port in preference to the hardcoded constant,
and stop() resets it. PORT = 5554 is kept only as a last-resort
fallback in inject() if actual_port is unset.
* feat(reload): add SSE live-reload server module
Problem: HTML output from pandoc has no live-reload; the browser must
be refreshed manually after each compile.
Solution: add lua/preview/reload.lua — a minimal SSE-only TCP server.
start() binds 127.0.0.1:5554 and keeps EventSource connections alive;
broadcast() pushes a reload event to all clients; inject() appends an
EventSource script before </body> (or at EOF) on every compile so
pandoc overwrites do not lose the tag.
* refactor(presets): add reload field, remove synctex field
Problem: the synctex field only handled PDF forward search and left
HTML live-preview and typst watch mode unsupported.
Solution: add reload = function(ctx) returning { 'typst', 'watch',
ctx.file } to typst (long-running watch mode), reload = true to
markdown and github (SSE push after each pandoc compile), and remove
synctex = true from latex (the -synctex=1 arg in latex.args remains
for .synctex.gz generation).
* refactor(init): replace synctex field and validation with reload
Problem: ProviderConfig still declared synctex and validated it, but
the field is being dropped in favour of the general-purpose reload.
Solution: replace the synctex annotation and vim.validate call with the
reload field, accepting boolean | string[] | function.
* feat(compiler): support long-running watch processes and SSE reload
Problem: compile() only supports one-shot invocations, requiring a
BufWritePost autocmd for watch mode and leaving HTML without live-
reload.
Solution: resolve_reload_cmd() maps provider.reload (function or table)
to a command; when present, compile() spawns it as a long-running
process instead of building a one-shot cmd from provider.cmd + args.
toggle() detects long-running providers and toggles the process
directly instead of registering a BufWritePost autocmd. When
reload = true and output is .html, the SSE server is invoked after
each successful compile. status() reports is_reload processes as
watching, not compiling. stop_all() also stops the SSE server.
* fix(compiler): format is_longrunning and annotate is_reload field
Problem: stylua required is_longrunning to be on one line; lua-ls
warned about undefined field is_reload on preview.Process.
Solution: inline the boolean expression and add is_reload? to the
preview.Process annotation.
* refactor: rename compile/toggle commands to build/watch
Problem: `compile` and `toggle` are accurate but unintuitive — `compile`
sounds academic and `toggle` says nothing about what it toggles.
Solution: rename the public API and `:Preview` subcommands to `build`
(one-shot) and `watch` (live preview). Internal compiler functions are
unchanged. No aliases for old names — clean break.
Problem: presets that need the output path in their args function
(markdown, github) had to recompute it inline, duplicating the same
gsub expression already in the output field.
Solution: resolve output_file first in M.compile, then extend ctx with
output = output_file into a resolved_ctx before evaluating args and cwd.
Presets can now reference ctx.output directly. Add output? to the
preview.Context type annotation.
Problem: all parse errors went to vim.diagnostic with no way to silence
them or route them to the quickfix list. Users wanting quickfix-style
error navigation had no option.
Solution: add an errors field to ProviderConfig accepting false,
'diagnostic' (default), or 'quickfix'. false suppresses error handling
entirely. 'quickfix' converts parsed diagnostics to qflist items
(1-indexed), calls setqflist, and opens the window. On success,
'quickfix' mode clears the qflist the same way 'diagnostic' mode clears
vim.diagnostic.
Problem: :Preview toggle gave no feedback, leaving the user to guess
whether watching was enabled or disabled.
Solution: emit vim.notify messages when toggling on ("watching with
\"<provider>\"") and off ("watching stopped"). Also normalize the
[preview.nvim] prefix in commands.lua to include the colon.
Problem: all three built-in error parsers were broken against real
compiler output. Typst set source to the relative file path, overriding
the provider name. LaTeX errors go to stdout but the parser only
received stderr. Pandoc's pattern matched "Error at" but not the real
"Error parsing YAML metadata at" format, and single-line parsing missed
multiline messages.
Solution: pass combined stdout+stderr to error_parser so LaTeX stdout
errors are visible. Remove source = file from the Typst parser so
diagnostic.lua defaults it to the provider name. Rewrite the Pandoc
parser with line-based lookahead: match (line N, column N) regardless
of prefix text, skip YAML parse exception lines when looking ahead for
the human-readable message. Rename stderr param to output throughout
diagnostic.lua, presets.lua, and init.lua annotations.
