preview.nvim

Universal previewer for Neovim

An extensible framework for compiling and previewing any documents (LaTeX, Typst, Markdown, etc.)—diagnostics included.

Note

Due to GitHub's historic unreliability, active development is hosted on Forgejo. GitHub is maintained as a read-only mirror. See :help preview-migration to optionally update your plugin source configuration.

Features

• Async compilation via vim.system()
• Built-in presets for Typst, LaTeX (latexmk, pdflatex, tectonic), Markdown, GitHub-flavored Markdown, AsciiDoc, PlantUML, Mermaid, and Quarto
• Compiler errors via vim.diagnostic or quickfix
• Full compiler output via :Preview output
• Previewer auto-close on buffer deletion

Requirements

• Neovim 0.11+

Installation

With vim.pack (Neovim 0.12+):

vim.g.preview = { typst = true, latex = true }

vim.pack.add({
  'https://git.barrettruth.com/barrettruth/preview.nvim',
})

Or via luarocks:

luarocks install preview.nvim

Quick Start

Enable exactly the providers you need before preview.nvim loads.

vim.g.preview = { typst = true }

Open a Typst document and start the watch preview from that buffer.

:Preview

When you only need a single build, run the compile subcommand instead of starting the watcher.

:Preview compile

If a compile fails, inspect the raw compiler log after checking diagnostics or quickfix.

:Preview output

After a successful build, reopen the last artifact without recompiling.

:Preview open

Documentation

:help preview

FAQ

Q: How do I define a custom provider?

vim.g.preview = {
  rst = {
    cmd = { 'rst2html' },
    args = function(ctx)
      return { ctx.file, ctx.output }
    end,
    output = function(ctx)
      return ctx.file:gsub('%.rst$', '.html')
    end,
    failure_summary = function(result)
      return result.output:match('^ERROR:%s*(.+)$')
    end,
  },
}

Q: How do I override a preset?

vim.g.preview = {
  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 in toggle/watch mode. For a specific application, pass a command table:

vim.g.preview = {
  typst = { open = { 'sioyek', '--new-instance' } },
}

Q: Markdown compilation drops .html files in my working directory. How do I send output to /tmp instead?

Override the output field. The args function references ctx.output, so the compiled file lands wherever output points:

vim.g.preview = {
  github = {
    output = function(ctx)
      return '/tmp/' .. vim.fn.fnamemodify(ctx.file, ':t:r') .. '.html'
    end,
  },
}

Q: How do I set up SyncTeX (forward/inverse search)?

See :help preview-synctex for full recipes covering Zathura, Sioyek, and Okular.

Q: How do I inspect the full compiler output?

If a compile fails, check diagnostics or quickfix first when available. For the raw compiler output, use:

:Preview output

Compilation failures intentionally use a short notification. Providers can optionally define failure_summary(result, ctx) to customize that message. The full raw compiler output is available through :Preview output and require('preview').result(). One-shot providers replace the stored output on each compile. Long-running providers such as typst watch show the current watch-session log.