*render.nvim.txt*                     Async document compilation for Neovim

Author: Raphael
License: MIT

==============================================================================
INTRODUCTION                                                      *render.nvim*

render.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. render.nvim is purely an orchestration framework.

==============================================================================
REQUIREMENTS                                            *render.nvim-requirements*

- Neovim >= 0.10.0
- A compiler binary for each configured provider (e.g. `typst`, `latexmk`)

==============================================================================
INSTALLATION                                            *render.nvim-installation*

With luarocks (recommended):
>
    :Rocks install render.nvim
<

With lazy.nvim:
>lua
    {
      'barrettruth/render.nvim',
    }
<

==============================================================================
CONFIGURATION                                        *render.nvim-configuration*

Configure via the `vim.g.render` global table before the plugin loads.

                                                              *render.Config*
Fields:~

  `debug`            boolean|string   Enable debug logging. A string value
                                    is treated as a log file path.
                                    Default: `false`

  `providers`        table            Provider configurations keyed by name.
                                    Default: `{}`

  `providers_by_ft`  table            Maps filetypes to provider names.
                                    Default: `{}`

                                                      *render.ProviderConfig*
Provider fields:~

  `cmd`              string[]         The compiler command (required).

  `args`             string[]|function  Additional arguments. If a function,
                                      receives a |render.Context| and returns
                                      a string[].

  `cwd`              string|function   Working directory. If a function,
                                      receives a |render.Context|. Default:
                                      git root or file directory.

  `env`              table             Environment variables.

  `output`           string|function   Output file path. If a function,
                                      receives a |render.Context|.

  `error_parser`     function          Receives (stderr, |render.Context|)
                                      and returns vim.Diagnostic[].

  `clean`            string[]|function  Command to remove build artifacts.
                                       If a function, receives a
                                       |render.Context|.

                                                          *render.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:~
>lua
    vim.g.render = {
      providers = {
        typst = {
          cmd = { 'typst', 'compile' },
          args = function(ctx)
            return { ctx.file }
          end,
          output = function(ctx)
            return ctx.file:gsub('%.typ$', '.pdf')
          end,
          error_parser = function(stderr, ctx)
            local diagnostics = {}
            for line, col, msg in stderr:gmatch('error:.-(%d+):(%d+):%s*(.-)%\n') do
              table.insert(diagnostics, {
                lnum = tonumber(line) - 1,
                col = tonumber(col) - 1,
                message = msg,
                severity = vim.diagnostic.severity.ERROR,
              })
            end
            return diagnostics
          end,
        },
        latexmk = {
          cmd = { 'latexmk' },
          args = { '-pdf', '-interaction=nonstopmode' },
          clean = { 'latexmk', '-c' },
        },
      },
      providers_by_ft = {
        typst = 'typst',
        tex = 'latexmk',
      },
    }
<

==============================================================================
COMMANDS                                                *render.nvim-commands*

:Render [subcommand]                                                 *:Render*

    Subcommands:~

    `compile`    Compile the current buffer (default if omitted).
    `stop`       Kill active compilation for the current buffer.
    `clean`      Run the provider's clean command.
    `status`     Echo compilation status (idle or compiling).

==============================================================================
API                                                          *render.nvim-api*

render.compile({bufnr?})                                   *render.compile()*
    Compile the document in the given buffer (default: current).

render.stop({bufnr?})                                         *render.stop()*
    Kill the active compilation process for the buffer.

render.clean({bufnr?})                                       *render.clean()*
    Run the provider's clean command for the buffer.

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

                                                            *render.Status*
Status fields:~

  `compiling`    boolean    Whether compilation is active.
  `provider`     string?    Name of the active provider.
  `output_file`  string?    Path to the output file.

render.get_config()                                     *render.get_config()*
    Returns the resolved |render.Config|.

==============================================================================
EVENTS                                                    *render.nvim-events*

render.nvim fires User autocmds with structured data:

`RenderCompileStarted`   Compilation began.
                        data: `{ bufnr, provider }`

`RenderCompileSuccess`   Compilation succeeded (exit code 0).
                        data: `{ bufnr, provider, output }`

`RenderCompileFailed`    Compilation failed (non-zero exit).
                        data: `{ bufnr, provider, code, stderr }`

Example:~
>lua
    vim.api.nvim_create_autocmd('User', {
      pattern = 'RenderCompileSuccess',
      callback = function(args)
        local data = args.data
        vim.notify('Compiled ' .. data.output .. ' with ' .. data.provider)
      end,
    })
<

==============================================================================
HEALTH                                                    *render.nvim-health*

Run `:checkhealth render` to verify:

- Neovim version >= 0.10.0
- Each configured provider's binary is executable
- Filetype-to-provider mappings are valid

==============================================================================
 vim:tw=78:ts=8:ft=help:norl: