*preview.nvim.txt* Async document compilation for Neovim Author: Barrett Ruth License: MIT ============================================================================== INTRODUCTION *preview.nvim* preview.nvim is an extensible framework for compiling documents asynchronously in Neovim. It provides a unified interface for any compilation workflow — LaTeX, Typst, Markdown, or anything else with a CLI compiler. The plugin ships with opt-in presets for common tools (Typst, LaTeX, Pandoc) and supports fully custom providers. See |preview.nvim-presets|. ============================================================================== REQUIREMENTS *preview.nvim-requirements* - Neovim >= 0.11.0 - A compiler binary for each configured provider (e.g. `typst`, `latexmk`) ============================================================================== SETUP *preview.nvim-setup* Load preview.nvim with your package manager. For example, with lazy.nvim: >lua { 'barrettruth/preview.nvim', } < Call |preview.setup()| to configure providers before use. ============================================================================== CONFIGURATION *preview.nvim-configuration* Configure via `require('preview').setup()`. *preview.setup()* setup({opts?}) `opts` is a table where keys are preset names or filetypes. For each key `k` with value `v` (excluding `debug`): - If `k` is a preset name and `v` is `true`, the preset is registered as-is under its filetype. - If `k` is a preset name and `v` is a table, it is deep-merged with the preset and registered under the preset's filetype. - If `k` is not a preset name and `v` is a table, it is registered directly as a custom provider keyed by filetype `k`. - If `v` is `false`, the entry is skipped (no-op). See |preview.nvim-presets| for available preset names. Fields:~ `debug` boolean|string Enable debug logging. A string value is treated as a log file path. Default: `false` *preview.ProviderConfig* Provider fields:~ `cmd` string[] The compiler command (required). `args` string[]|function Additional arguments. If a function, receives a |preview.Context| and returns a string[]. `cwd` string|function Working directory. If a function, receives a |preview.Context|. Default: git root or file directory. `env` table Environment variables. `output` string|function Output file path. If a function, receives a |preview.Context|. `error_parser` function Receives (output, |preview.Context|) and returns vim.Diagnostic[]. `errors` false|'diagnostic'|'quickfix' How parse errors are reported. `false` suppresses error handling. `'quickfix'` populates the quickfix list and opens it. Default: `'diagnostic'`. `clean` string[]|function Command to remove build artifacts. If a function, receives a |preview.Context|. `open` boolean|string[] Open the output file after the first successful compilation. `true` uses |vim.ui.open()|. A string[] is run as a command with the output path appended. `reload` boolean|string[]|function Reload the output after recompilation. `true` uses a built-in SSE server for HTML files. A string[] is run as a command. If a function, receives a |preview.Context| and returns a string[]. *preview.Context* Context fields:~ `bufnr` integer Buffer number. `file` string Absolute file path. `root` string Project root (git root or file directory). `ft` string Filetype. `output` string? Resolved output file path (set after `output` is evaluated, available to `args` functions). Example enabling presets:~ >lua require('preview').setup({ typst = true, latex = true, github = true }) < Example overriding a preset field:~ >lua require('preview').setup({ typst = { open = { 'sioyek', '--new-instance' } }, }) < Example overriding the output path (e.g. latexmk `$out_dir`):~ >lua require('preview').setup({ latex = { output = function(ctx) return 'build/' .. vim.fn.fnamemodify(ctx.file, ':t:r') .. '.pdf' end, }, }) < Example with a fully custom provider (key is not a preset name):~ >lua require('preview').setup({ rst = { cmd = { 'rst2html' }, args = function(ctx) return { ctx.file } end, output = function(ctx) return ctx.file:gsub('%.rst$', '.html') end, }, }) < ============================================================================== PRESETS *preview.nvim-presets* preview.nvim ships with pre-built provider configurations for common tools. Import them from `preview.presets`: `presets.typst` typst compile → PDF `presets.latex` latexmk -pdf → PDF (with clean support) `presets.pdflatex` pdflatex → PDF (single pass, no latexmk) `presets.tectonic` tectonic → PDF (Rust-based LaTeX engine) `presets.markdown` pandoc → HTML (standalone, embedded) `presets.github` pandoc → HTML (GitHub-styled, `-f gfm` input) `presets.asciidoctor` asciidoctor → HTML (AsciiDoc with SSE reload) `presets.quarto` quarto render → HTML (scientific publishing) Enable presets with `preset_name = true`: >lua require('preview').setup({ typst = true, latex = true, github = true }) < Override individual fields by passing a table instead of `true`: >lua require('preview').setup({ typst = { env = { TYPST_FONT_PATHS = '/usr/share/fonts' } }, }) < ============================================================================== COMMANDS *preview.nvim-commands* :Preview [subcommand] *:Preview* Subcommands:~ `toggle` Toggle auto-compile on save (default if omitted). `compile` One-shot compile of the current buffer. `clean` Run the provider's clean command. `open` Open the last compiled output without recompiling. `status` Echo compilation status (idle, compiling, watching). ============================================================================== API *preview.nvim-api* preview.toggle({bufnr?}) *preview.toggle()* Toggle auto-compile for the buffer. When enabled, the buffer is immediately compiled and automatically recompiled on each save (`BufWritePost`). Call again to stop. preview.compile({bufnr?}) *preview.compile()* One-shot compile the document in the given buffer (default: current). preview.stop({bufnr?}) *preview.stop()* Kill the active compilation process for the buffer. Programmatic escape hatch — not exposed as a subcommand. preview.clean({bufnr?}) *preview.clean()* Run the provider's clean command for the buffer. preview.open({bufnr?}) *preview.open()* Open the last compiled output for the buffer without recompiling. preview.status({bufnr?}) *preview.status()* Returns a |preview.Status| table. preview.statusline({bufnr?}) *preview.statusline()* Returns a short status string for statusline integration: `'compiling'`, `'watching'`, or `''` (idle). *preview.Status* Status fields:~ `compiling` boolean Whether compilation is active. `watching` boolean Whether auto-compile is active. `provider` string? Name of the active provider. `output_file` string? Path to the output file. preview.get_config() *preview.get_config()* Returns the resolved |preview.Config|. ============================================================================== EVENTS *preview.nvim-events* preview.nvim fires User autocmds with structured data: `PreviewCompileStarted` Compilation began. data: `{ bufnr, provider }` `PreviewCompileSuccess` Compilation succeeded (exit code 0). data: `{ bufnr, provider, output }` `PreviewCompileFailed` Compilation failed (non-zero exit). data: `{ bufnr, provider, code, stderr }` Example:~ >lua vim.api.nvim_create_autocmd('User', { pattern = 'PreviewCompileSuccess', callback = function(args) local data = args.data vim.notify('Compiled ' .. data.output .. ' with ' .. data.provider) end, }) < ============================================================================== HEALTH *preview.nvim-health* Run `:checkhealth preview` to verify: - Neovim version >= 0.11.0 - Each configured provider's binary is executable - Each configured provider's opener binary (if any) is executable - Each configured provider's filetype mapping is valid ============================================================================== vim:tw=78:ts=8:ft=help:norl: