2d212aa220
* refactor(config): replace array preset syntax with preset_name = true Problem: setup() mixed array entries (preset names) and hash entries (custom providers keyed by filetype), requiring verbose vim.tbl_deep_extend boilerplate to override presets. Solution: unify under a single key=value model. Keys are preset names or filetypes; true registers the preset as-is, a table deep-merges with the matching preset (or registers a custom provider if no preset matches), and false is a no-op. Array entries are dropped. Also adds -f gfm to presets.github args so pandoc parses input as GFM. * ci: format * fix(presets): parenthesize gsub output to suppress redundant-return-value
239 lines
8.8 KiB
Text
239 lines
8.8 KiB
Text
*preview.nvim.txt* Async document compilation for Neovim
|
|
|
|
Author: Raphael
|
|
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 zero provider defaults. Users must explicitly configure
|
|
their compiler commands. preview.nvim is purely an orchestration framework.
|
|
|
|
==============================================================================
|
|
REQUIREMENTS *preview.nvim-requirements*
|
|
|
|
- Neovim >= 0.11.0
|
|
- A compiler binary for each configured provider (e.g. `typst`, `latexmk`)
|
|
|
|
==============================================================================
|
|
INSTALLATION *preview.nvim-installation*
|
|
|
|
With luarocks (recommended):
|
|
>
|
|
:Rocks install preview.nvim
|
|
<
|
|
|
|
With lazy.nvim:
|
|
>lua
|
|
{
|
|
'barrettruth/preview.nvim',
|
|
}
|
|
<
|
|
|
|
==============================================================================
|
|
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 (stderr, |preview.Context|)
|
|
and returns vim.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.
|
|
Presets default to `{ 'xdg-open' }`.
|
|
|
|
*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.
|
|
|
|
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 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:~
|
|
|
|
`compile` Compile the current buffer (default if omitted).
|
|
`stop` Kill active compilation for the current buffer.
|
|
`clean` Run the provider's clean command.
|
|
`toggle` Toggle auto-compile on save for the current buffer.
|
|
`status` Echo compilation status (idle, compiling, watching).
|
|
|
|
==============================================================================
|
|
API *preview.nvim-api*
|
|
|
|
preview.compile({bufnr?}) *preview.compile()*
|
|
Compile the document in the given buffer (default: current).
|
|
|
|
preview.stop({bufnr?}) *preview.stop()*
|
|
Kill the active compilation process for the buffer.
|
|
|
|
preview.clean({bufnr?}) *preview.clean()*
|
|
Run the provider's clean command for the buffer.
|
|
|
|
preview.toggle({bufnr?}) *preview.toggle()*
|
|
Toggle watch mode for the buffer. When enabled, the buffer is
|
|
immediately compiled and automatically recompiled on each save
|
|
(`BufWritePost`). Call again to stop watching.
|
|
|
|
preview.status({bufnr?}) *preview.status()*
|
|
Returns a |preview.Status| table.
|
|
|
|
*preview.Status*
|
|
Status fields:~
|
|
|
|
`compiling` boolean Whether compilation is active.
|
|
`watching` boolean Whether watch mode 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 }`
|
|
|
|
`PreviewWatchStarted` Watch mode enabled for a buffer.
|
|
data: `{ bufnr, provider }`
|
|
|
|
`PreviewWatchStopped` Watch mode disabled for a buffer.
|
|
data: `{ bufnr }`
|
|
|
|
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:
|