*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 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`)

==============================================================================
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 (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, toggled).

==============================================================================
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 auto-compile for the buffer. When enabled, the buffer is
    immediately compiled and automatically recompiled on each save
    (`BufWritePost`). Call again to stop.

preview.status({bufnr?})                                  *preview.status()*
    Returns a |preview.Status| table.

                                                          *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: