Barrett Ruth
098f822ec2
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.
263 lines
10 KiB
Text
263 lines
10 KiB
Text
*preview.nvim.txt* Async document compilation for Neovim
|
|
|
|
Author: Barrett Ruth <br.barrettruth@gmail.com>
|
|
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.markdown` pandoc → HTML (standalone, embedded)
|
|
`presets.github` pandoc → HTML (GitHub-styled, `-f gfm` input)
|
|
|
|
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:
|