feat: rename watch → toggle, auto-compile on start, built-in opener

Problem: :Preview watch only registered a BufWritePost autocmd without
compiling immediately, required boilerplate to open output files after
first compilation, and was misleadingly named.

Solution: Rename watch → toggle throughout. M.toggle now compiles
immediately on activation. Add an open field to ProviderConfig: true
calls vim.ui.open(), a string[] runs the command with the output path
appended, tracked per-buffer so the file opens only once. All presets
default to { 'xdg-open' }. Health check validates opener binaries.
Guard the async compile callback against invalid buffer ids.

2026-03-02 23:37:44 -05:00

1.7 KiB

Raw Blame History

preview.nvim

Async document compilation for Neovim

An extensible framework for compiling documents (LaTeX, Typst, Markdown, etc.) asynchronously with error diagnostics.

Features

Async compilation via vim.system()
Compiler errors as native vim.diagnostic
User events for extensibility (PreviewCompileStarted, PreviewCompileSuccess, PreviewCompileFailed)
Built-in presets for Typst, LaTeX, Markdown, and GitHub-flavored Markdown
:checkhealth integration
Zero dependencies beyond Neovim 0.11.0+

Requirements

Neovim 0.11.0+

Installation

Install with your package manager of choice or via luarocks:

luarocks install preview.nvim

Documentation

:help preview.nvim

FAQ

Q: How do I define a custom provider?

require('preview').setup({
  typst = {
    cmd = { 'typst', 'compile' },
    args = function(ctx)
      return { ctx.file }
    end,
    output = function(ctx)
      return ctx.file:gsub('%.typ$', '.pdf')
    end,
  },
})

Q: How do I override a preset?

local presets = require('preview.presets')
require('preview').setup({
  typst = vim.tbl_deep_extend('force', presets.typst, {
    env = { TYPST_FONT_PATHS = '/usr/share/fonts' },
  }),
})

Q: How do I automatically open the output file?

Set open = true on your provider (all built-in presets have this enabled) to open the output with vim.ui.open() after the first successful compilation. For a specific application, pass a command table:

typst = vim.tbl_deep_extend('force', presets.typst, {
  open = { 'sioyek', '--new-instance' },
})

See :h preview.nvim for more information.

1.7 KiB Raw Blame History