From 7a7c407d97d9115c05cc162e050c3e2b48dddc77 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Wed, 4 Mar 2026 13:10:34 -0500 Subject: [PATCH 1/5] refactor: rename build to compile and watch to toggle in public API Problem: the code used build/watch while the help file already documented compile/toggle, creating a confusing mismatch. Solution: rename M.build() to M.compile() and M.watch() to M.toggle() in init.lua, update handler keys in commands.lua, and update the test file to match. --- lua/preview/commands.lua | 8 ++++---- lua/preview/init.lua | 8 ++++---- spec/commands_spec.lua | 8 ++++---- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/lua/preview/commands.lua b/lua/preview/commands.lua index c91f4de..eec51c9 100644 --- a/lua/preview/commands.lua +++ b/lua/preview/commands.lua @@ -1,8 +1,8 @@ local M = {} local handlers = { - build = function() - require('preview').build() + compile = function() + require('preview').compile() end, stop = function() require('preview').stop() @@ -10,8 +10,8 @@ local handlers = { clean = function() require('preview').clean() end, - watch = function() - require('preview').watch() + toggle = function() + require('preview').toggle() end, open = function() require('preview').open() diff --git a/lua/preview/init.lua b/lua/preview/init.lua index acceea5..421ba65 100644 --- a/lua/preview/init.lua +++ b/lua/preview/init.lua @@ -39,10 +39,10 @@ ---@class preview ---@field setup fun(opts?: table) ----@field build fun(bufnr?: integer) +---@field compile fun(bufnr?: integer) ---@field stop fun(bufnr?: integer) ---@field clean fun(bufnr?: integer) ----@field watch fun(bufnr?: integer) +---@field toggle fun(bufnr?: integer) ---@field open fun(bufnr?: integer) ---@field status fun(bufnr?: integer): preview.Status ---@field statusline fun(bufnr?: integer): string @@ -144,7 +144,7 @@ function M.build_context(bufnr) end ---@param bufnr? integer -function M.build(bufnr) +function M.compile(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() local name = M.resolve_provider(bufnr) if not name then @@ -176,7 +176,7 @@ function M.clean(bufnr) end ---@param bufnr? integer -function M.watch(bufnr) +function M.toggle(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() local name = M.resolve_provider(bufnr) if not name then diff --git a/spec/commands_spec.lua b/spec/commands_spec.lua index 32da224..9b63f87 100644 --- a/spec/commands_spec.lua +++ b/spec/commands_spec.lua @@ -14,10 +14,10 @@ describe('commands', function() end) describe('dispatch', function() - it('does not error on :Preview with no provider', function() + it('does not error on :Preview compile with no provider', function() require('preview.commands').setup() assert.has_no.errors(function() - vim.cmd('Preview build') + vim.cmd('Preview compile') end) end) @@ -42,10 +42,10 @@ describe('commands', function() end) end) - it('does not error on :Preview watch with no provider', function() + it('does not error on :Preview toggle with no provider', function() require('preview.commands').setup() assert.has_no.errors(function() - vim.cmd('Preview watch') + vim.cmd('Preview toggle') end) end) end) From 46cbf41612dc8455ec98e81788c984dd30452c03 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Wed, 4 Mar 2026 13:10:52 -0500 Subject: [PATCH 2/5] refactor(commands): make toggle the default subcommand Problem: bare :Preview ran a one-shot compile, but users reaching for a "preview" plugin expect it to start previewing (i.e. watch mode). Solution: change the fallback subcommand from compile to toggle so :Preview starts/stops auto-compile on save. --- lua/preview/commands.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lua/preview/commands.lua b/lua/preview/commands.lua index eec51c9..14199ab 100644 --- a/lua/preview/commands.lua +++ b/lua/preview/commands.lua @@ -33,7 +33,7 @@ local handlers = { ---@param args string local function dispatch(args) - local subcmd = args ~= '' and args or 'build' + local subcmd = args ~= '' and args or 'toggle' local handler = handlers[subcmd] if handler then handler() @@ -58,7 +58,7 @@ function M.setup() complete = function(lead) return complete(lead) end, - desc = 'Build, stop, clean, watch, open, or check status of document preview', + desc = 'Toggle, compile, clean, open, or check status of document preview', }) end From 1d0077ab600122c3a10bd0807bf7c33f5a29c1d4 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Wed, 4 Mar 2026 13:11:14 -0500 Subject: [PATCH 3/5] refactor(commands): remove stop subcommand Problem: :Preview stop had a subtle distinction from toggle-off (kill process but keep autocmd) that nobody reaches for deliberately from the command line. Solution: remove stop from the command dispatch table. The Lua API require('preview').stop() remains as a programmatic escape hatch. --- lua/preview/commands.lua | 3 --- spec/commands_spec.lua | 7 ------- 2 files changed, 10 deletions(-) diff --git a/lua/preview/commands.lua b/lua/preview/commands.lua index 14199ab..a2e0470 100644 --- a/lua/preview/commands.lua +++ b/lua/preview/commands.lua @@ -4,9 +4,6 @@ local handlers = { compile = function() require('preview').compile() end, - stop = function() - require('preview').stop() - end, clean = function() require('preview').clean() end, diff --git a/spec/commands_spec.lua b/spec/commands_spec.lua index 9b63f87..5cca5a2 100644 --- a/spec/commands_spec.lua +++ b/spec/commands_spec.lua @@ -21,13 +21,6 @@ describe('commands', function() end) end) - it('does not error on :Preview stop', function() - require('preview.commands').setup() - assert.has_no.errors(function() - vim.cmd('Preview stop') - end) - end) - it('does not error on :Preview status', function() require('preview.commands').setup() assert.has_no.errors(function() From 098f822ec2fca44a8eec0787ba9142dd97caf2d2 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Wed, 4 Mar 2026 13:11:57 -0500 Subject: [PATCH 4/5] docs: update help file for new command surface and document reload Problem: the help file listed compile as the default subcommand, still included the stop subcommand, omitted the reload provider field, and had a misleading claim about shipping with zero defaults. Solution: make toggle the default in the commands section, remove stop from subcommands, add reload to provider fields, fix the introduction text, reorder API entries to match new primacy, and add an output path override example addressing #26/#27. --- doc/preview.nvim.txt | 47 +++++++++++++++++++++++++++++++------------- 1 file changed, 33 insertions(+), 14 deletions(-) diff --git a/doc/preview.nvim.txt b/doc/preview.nvim.txt index c8bc708..a3d4981 100644 --- a/doc/preview.nvim.txt +++ b/doc/preview.nvim.txt @@ -10,8 +10,8 @@ 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. +The plugin ships with opt-in presets for common tools (Typst, LaTeX, Pandoc) +and supports fully custom providers. See |preview.nvim-presets|. ============================================================================== REQUIREMENTS *preview.nvim-requirements* @@ -93,6 +93,14 @@ Provider fields:~ |vim.ui.open()|. A string[] is run as a command with the output path appended. + `reload` boolean|string[]|function + Reload the output after recompilation. + `true` uses a built-in SSE server for + HTML files. A string[] is run as a + command. If a function, receives a + |preview.Context| and returns a + string[]. + *preview.Context* Context fields:~ @@ -115,6 +123,17 @@ Example overriding a preset field:~ }) < +Example overriding the output path (e.g. latexmk `$out_dir`):~ +>lua + require('preview').setup({ + latex = { + output = function(ctx) + return 'build/' .. vim.fn.fnamemodify(ctx.file, ':t:r') .. '.pdf' + end, + }, + }) +< + Example with a fully custom provider (key is not a preset name):~ >lua require('preview').setup({ @@ -160,30 +179,30 @@ COMMANDS *preview.nvim-commands* Subcommands:~ - `compile` Compile the current buffer (default if omitted). - `stop` Kill active compilation for the current buffer. + `toggle` Toggle auto-compile on save (default if omitted). + `compile` One-shot compile of the current buffer. `clean` Run the provider's clean command. - `toggle` Toggle auto-compile on save for the current buffer. `open` Open the last compiled output without recompiling. `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 auto-compile for the buffer. When enabled, the buffer is immediately compiled and automatically recompiled on each save (`BufWritePost`). Call again to stop. +preview.compile({bufnr?}) *preview.compile()* + One-shot compile the document in the given buffer (default: current). + +preview.stop({bufnr?}) *preview.stop()* + Kill the active compilation process for the buffer. Programmatic + escape hatch — not exposed as a subcommand. + +preview.clean({bufnr?}) *preview.clean()* + Run the provider's clean command for the buffer. + preview.open({bufnr?}) *preview.open()* Open the last compiled output for the buffer without recompiling. From 86a3523f2d4735a6d1aeaa5f5be5389aa014f61e Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Wed, 4 Mar 2026 14:21:12 -0500 Subject: [PATCH 5/5] ci: scripts --- .luarc.json | 8 +++++++- .styluaignore | 1 + flake.nix | 2 ++ scripts/ci.sh | 10 ++++++++++ 4 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 .styluaignore create mode 100755 scripts/ci.sh diff --git a/.luarc.json b/.luarc.json index 23646d3..3f6276a 100644 --- a/.luarc.json +++ b/.luarc.json @@ -2,7 +2,13 @@ "runtime.version": "LuaJIT", "runtime.path": ["lua/?.lua", "lua/?/init.lua"], "diagnostics.globals": ["vim", "jit"], - "workspace.library": ["$VIMRUNTIME/lua", "${3rd}/luv/library"], + "workspace.library": [ + "$VIMRUNTIME/lua", + "${3rd}/luv/library", + "${3rd}/busted/library", + "${3rd}/luassert/library" + ], "workspace.checkThirdParty": false, + "workspace.ignoreDir": [".direnv"], "completion.callSnippet": "Replace" } diff --git a/.styluaignore b/.styluaignore new file mode 100644 index 0000000..9b42106 --- /dev/null +++ b/.styluaignore @@ -0,0 +1 @@ +.direnv/ diff --git a/flake.nix b/flake.nix index 7413113..0243f3e 100644 --- a/flake.nix +++ b/flake.nix @@ -16,6 +16,8 @@ forEachSystem = f: nixpkgs.lib.genAttrs (import systems) (system: f nixpkgs.legacyPackages.${system}); in { + formatter = forEachSystem (pkgs: pkgs.nixfmt-tree); + devShells = forEachSystem (pkgs: { default = pkgs.mkShell { packages = [ diff --git a/scripts/ci.sh b/scripts/ci.sh new file mode 100755 index 0000000..e06bf09 --- /dev/null +++ b/scripts/ci.sh @@ -0,0 +1,10 @@ +#!/bin/sh +set -eu + +nix develop --command stylua --check . +git ls-files '*.lua' | xargs nix develop --command selene --display-style quiet +nix develop --command prettier --check . +nix fmt +git diff --exit-code -- '*.nix' +nix develop --command lua-language-server --check . --checklevel=Warning +nix develop --command busted