v0.12.0

0.12.0 (2025-11-15)

⚠ BREAKING CHANGES

• API return values standardized
  Public API functions now return consistent boolean values indicating whether an action was queued/scheduled, not whether the buffer was immediately updated. Since many updates occur asynchronously or within transactions, the return value was often ambiguous.
  This is only breaking if your configuration or plugin code was explicitly depending on previous return values (rare).
• allow create to use position opt in visual mode (#207)
  This augments the existing behavior of the create API. Visual-mode create previously only converted non-todo lines into todos. It now supports inserting new todos above/below the selection—matching normal-mode behavior.
• Keymap configuration no longer merges with defaults
  The keys table now replaces defaults instead of merging.
  This avoids duplicated mappings and surprising behavior, but requires copying defaults manually when you want to modify only a subset.
• Metadata callbacks (e.g., on_add, on_remove, on_change) now receive the public checkmate.Todo type rather than the internal checkmate.TodoItem type
  This could break existing callbacks, but should not change capabilities as most functionality is still present on the Todo class.
• ui.picker no longer accepts a function
  Users should now customize pickers via picker_opts or by providing a custom_picker function to APIs that support it. If this limits your workflow, please report an issue.
• Hard deprecation (removal) of config's todo_markers (previously soft deprecated).

Features

Upgraded Picker System

A major feature of this release is a brand new picker integration. We continue to provide out-of-the-box support for popular external pickers: snacks.nvim, mini.pick, and telescope. Checkmate will auto-detect an installed picker and/or allow extensive picker customization. (#220) (0dd9e91)

• Added a checkmate.PickerOpts type that can used for per-call picker customization, allowing backend-specific overrides.
• Refined the design for a custom_picker function utilized by some APIs (e.g. select_metadata_value, select_todo)
  • Your function receives Checkmate context
  • You drive the picker
  • You call the provided complete() callback to finalize behavior

For example, this allows a user to call their own external picker to populate a list of values that can be used to update a metadata tag, e.g., a snacks Files picker. In other word, this allows you to leverage the power of dedicated picker plugins to update Checkmate todos.

This also allows you to implement your own picker, e.g. fzf-lua, with Checkmate data passed in.

Example: using a snacks. files picker to update a metadata value:

require("checkmate").select_metadata_value({
  custom_picker = function(ctx, complete)
    require("snacks").picker.files({
      confirm = function(picker, item)
        if item then
          vim.schedule(function()
            complete(item.text)
          end)
        end
        picker:close()
      end,
    })
  end,
})

• Add opts to select_metadata_value that allows:
  • Using a position opt to locate the metadata rather than default which is cursor position (#212) (57ea1d0)
  • Customizing the picker via picker_opts (see checkmate.PickerOpts type)
  • The user to pass a bespoke picker implementation via custom_picker function that receives the metadata context and a complete() callback (#205) (0b70ee6)

Todo Search/Finding

Another exciting feature of this release is the get_todos and select_todo API. The former allows you to gather todos from a buffer (with some optional filtering), which you can then use to populate qflists, pickers, UI's, etc. The latter uses the picker system to provide an awesome UI for quickly finding todos. Given the configuration opts, this can be extensively customized to your liking.

Two new APIs (#223) (ceb94ba):

• get_todos()
  Collect todos from a buffer with optional filtering—useful for qf lists, UIs, external pickers, etc.

• select_todo()
  Opens a picker-driven UI for rapidly jumping to a todo

Example of select_todo() using snacks.picker

Additional features

• add update_metadata API (#209) (84356f2)
  • This will update existing metadata value. If the metadata doesn't exist, this is a no-op. Includes a :Checkmate metadata update user command.
  • Clarifies add_metadata to have add-or-update behavior (i.e. upsert).
• api: add additional helpers to Todo class (#215) (e6dd02b)
  • row: 0-based row of the todo (the line containing the list marker and todo marker)
  • is_checked(): whether todo state is explicitly "checked"
  • is_unchecked(): whether todo state is explicitly "unchecked"
  • is_complete(): whether todo state type is "complete"
  • is_incomplete(): whether todo state type is "incomplete"
  • is_inactive(): whether todo state type is "inactive"
• api: add bufnr to checkmate.Todo representing the source buffer (b400115)
• api: allow create to use position opt in visual mode (#207) (44cb47e)
  • Allows a position opt in visual mode, which will perform a create todo line similar to normal mode. Previously, visual mode create only converted non-todos to todos, but this allows creating new todos above or below the visual selection.
• api: update return values and documentation of public API (#216) (994c296)
• config: add ability to disable checkmate style/highlights with style false (#218) (6ce6e87)
  • to disable all Checkmate highlight groups, including metadata highlighting. This may be helpful for those trying to integrate with Markdown renderer plugins.

• Replaces the _todo_item field on checkmate.Todo with a _get_todo_item function to lazy get the internal todo item. This is non-breaking since the _todo_item field is not guaranteed stable. Documentation updated.
• Updated checkhealth for better reporting

Bug Fixes

• api: allow limited operations on undefined metadata (#214) (f8da74a)
• api: fix unexpected handling of list continuation when the split content is a todo (#206) (ebc9cbc)
• api: remove lingering _todo_item field on Todo (13a7181)
• api: use buffer local helper in BufWrite (c2c5aa3)
• commands: update user commands (#211) (47be9e7)
• config: bug in keys config, unintentional merge, duplicate keymaps (#202) (57bedf4)
• deprecate set_todo_item, instead use set_todo_state (#210) (b660ad8)

Deprecations

• set_todo_item is soft deprecated. Use set_todo_state instead.
• :Checkmate remove_all_metadata is soft deprecated. Use :Checkmate metadata remove_all instead.
• Config ui.picker option of false is soft deprecated. Use "native" to use vim.ui.select as the preferred picker.

Refactors

• Reorganized main init.lua module to better distinguish public API
• Refined metadata.picker to integrate with new picker system
• Modularized some of the larger files (api.lua, util.lua)
  • New Buffer and TodoItem classes (internal use only)
• Improve state management of tests (minimal_init), reorganized test helpers, add new TestCase strategy for test setup and assertions

v0.11.2

0.11.2 (2025-10-11)

Bug Fixes

• metadata: remove picker highlight and animation (#199) (5ffa4af)

v0.11.1

0.11.1 (2025-10-10)

Bug Fixes

• config: improve config validation and checkhealth (#191) (cd9948f)
• highlights: adds nil check to Normal group 'fg' to address #196 (#197) (4aeb383)
• typo in select_metadata_value() api (#195) (9d73cde)

v0.11.0

0.11.0 (2025-10-01)

⚠ BREAKING CHANGES

• api: changes intended behavior of archive to include all "completed" state type (#186). Previously, archive functionality only collected todos with the "checked" state. However, with the introduction of custom todo states and state_types, this change now aligns with user expectations, i.e. all "completed" type todos are collected for archival.

Major Features

• add remove API that converts todo lines back to regular text (#172) ([8f84322]. (8f84322)). This includes options for preserve_list_marker and remove_metadata (both true by default).
• improve create API and add 'list continuation' feature (#170) (882b34d). This is a major upgrade todo creation capabilities, expanding the create API for more customization. Additionally, this release adds "todo list continuation" feature which allows for the automatic creation of new todo lines in insert mode. By default <CR> creates a new todo line underneath and <S-CR> creates a nested todo. These list_continuation opts, including the insert mode keymapping are configurable, allowing users to integrate with other list continuation plugins, e.g. auto-pairs.

Minor Features

• highlights: improve performance, especially for Insert mode and large buffers (#176) (fd26dc8)
• update get_todo API (#174) (af9fd70). This also addresses an off-by-one bug in get_todo position suggested in #183.

Bug Fixes

• remove() todo bug when metadata with on_remove handler is removed (#177) (5f41aab)
• add 'redraw' before deferred highlighting to keep UI snappy (#181) (73da29d)
• api: bugs with process_buffer triggering, autocmds and debouncing (d8f4c59)
• api: changes intended behavior of archive to include all "completed" state type (#186) (7760aa0)
• refactored and fixed archive system (#187) (ba6132b)
• various bug fixes, some refactoring (#184) (d8f4c59)

Performance Improvements

• improve transaction callbacks (#178) (602ead8)
• small fixes to debug profiler (#179) (ba8b813)
• various fixes/refactors for efficiency (#180) (23fee44)

v0.10.1

0.10.1 (2025-07-28)

⚠ BREAKING CHANGES

Should affect very few users and breaking change is only related to logging.

• Removes use_buffer opts from config.log. Will just write to log file if use_file is enabled and when logging meets level threshold. This update does make use_file enabled by default with a log level of warn so that users can at least send in debug info if problems occur. Default log file is at vim.fn.stdpath("log") with filename "checkmate.log" (this can be modified with file_path opt).

Code Refactoring

• organize config, improve logging/debugging(#164) (186228c)

v0.10.0

0.10.0 (2025-07-26)

⚠ BREAKING CHANGES

• Remove todo_action_depth option.
  • Found it complicated rather than helped. Additionally, was more of an internal that probably didn't need to be exposed in the first place.
  • New behavior: todos can be interacted with from any depth within the todo's hierarchy as long as it isn't within a nested todo.
• Changed highlight group definitions for what is considered a todo's main versus additional content.
  • Checkmate*MainContent should now capture the first todo line plus any continuation lines (in Treesitter this is the first inline node).
  • Checkmate*AdditionalContent should now include all other content associated with the list item, including additional paragraphs and nested non-todo list items
  • As a result, the may require users to edit their styles opt if visual appearance is different.
• While not breaking per se, this release updates some fundamental behavior related to wrapping:
  • For todo item lines that are hard wrapped, metadata will now be correctly parsed and usable on these continuation lines.
  • This means that adding a new metadata will default to the last line of any continuation lines present under the main todo item line.
  • Metadata sort_order (where lower numbers should come first in the todo line) should still be respected.
  • For todo item lines that are not hard wrapped, there should not be any appreciable change in behavior.

Features

• Add multi-line support to todo content (#139)

  • Previously, todos were largely seen as single line items that could be soft-wrapped, i.e., all metadata needed to be on the main line. This would break with hard-wrapped todo lines.
  • Now, todo content can span multiple lines, metadata can be parsed even if it is hard-wrapped, etc. This allows greater flexibility with various buffer formatters.

• Custom todo states

  • This release adds support for adding additional todo states, beyond the default "unchecked" and "checked". These todo states can be configured to show their own marker and Markdown representation (when saved to disk). (#153)
  • For example, some users may want an "in_progress" state with a ⊖ icon, or "cancelled" ✘, etc.
  • To support this, a new cycle API is introduced to allow switching between all todo states. This includes corresponding :Checkmate cycle_next and :Checkmate cycle_previous user commands.
  • Custom states are not compliant with CommonMark spec or Github-flavored Markdown. For example, an "in progress" state might be saved as - [.] (this can be defined in the todo state's markdown field). Therefore, while they will work in the Checkmate buffer, they may not be parsed correctly in other apps without additional configuration.

• Snippets API

  • Add checkmate.snippets API for LuaSnip integration (#152)
  • This provides helper functions to build todos and metadata snippets (Lua based) that can be loaded by LuaSnip
  • This feature effectively allows templating todo items or common combinations of metadata
  • Currently offers todo() which builds a todo item with various metadata and values, and metadata() which builds a single metadata/value snippet
  • See Snippets on the Wiki for more information.

• Adds enable/disable plugin commands + public api (#129)

  • Allows for enabling and disabling Checkmate globally

• Move README.md assets out of repo to Github user-attachments to reduce plugin size

Deprecations

• The previous soft deprecations are now fully deprecated/removed (risk of error):
  • checkmate.Action (for keymaps) is removed. Use checkmate.KeymapConfig instead.
  • checkmate.StyleKey (for style option) is removed. Use checkmate.HighlightGroup instead.
  • Legacy, top-level commands such as CheckmateToggle are removed. Use Checkmate <subcommand> syntax instead.
• config.todo_markers is now deprecated (with backwards compatibility) - use todo_states instead

Bug Fixes

• cycle api should propagate state similar to toggle (#155) (51a854f)
• health: fix checkhealth to show correct config validation errors (#154) (605adbb)
• parser: fix bug with finding first inline range with setext heading (#149) (9bf370c)
• refine todo states implementation (#156) (3d4c94d)

v0.9.2

0.9.2 (2025-06-27)

Bug Fixes

• api: ensure that file ends with new line (#141) (4a5e28c)
• api: fixes missing BufWritePre and BufWritePost calls (#137) (da388a6)
• docs: fixes duplicate table of contents in vimdoc (#135) (72a6be4)

New Contributors

• @mahyarmirrashed made their first contribution in #141

v0.9.1

0.9.1 (2025-06-19)

Bug Fixes

• api: fixes subtle bug in api shutdown process (#126) (be98986)
• fixes bug in async handling of metadata 'choices' function (#128) (cf8b7ef)

v0.9.0

0.9.0 (2025-06-19)

⚠ BREAKING CHANGES

• config: no longer apply default metadata props to a modified default metadata in config (#95) User configs that relied on the 'default' metadata being merged in with their own will need to copy the default (see README). This is to avoid unexpected behavior from unrecognized merging.

Features

• improved keymapping config, deprecated checkmate.Action (#119) (899337b) (should integrate with which-key.nvim #118)
• new features for metadata (#116) (116b272)
  • provides a MetadataContext to metadata config functions such as get_value, style, and choices. This allows for more powerful, context-aware metadata customization
  • new select_metadata_value with picker UI (or custom picker implementation) to easily fetch and select a metadata's value. See the choices option in the metadata properties
  • Jump to next/previous metadata with new commands/api
• simplify highlight groups and style configuration (#124) (ea73174)
• updated user commands to use nested subcommands (#109) (8b87942)

Deprecated

• Top-level user commands, e.g. :CheckmateToggle, :CheckmateArchive, etc. are deprecated. Instead, use :Checkmate [subcommand] syntax. Legacy commands remain for backwards compatibility but will be removed in next release.
• checkmate.Action strings were previously used for mapping keys. These are deprecated and users should now use a checkmate.KeymapConfig which is a dict-like table or a sequence of {rhs, desc?, modes?}
• checkmate.StyleKey strings were previously used in style to configure a hl_group. The new approach is to use checkmate.HighlightGroup which mirrors the actual name--removing this confusing layer of abstraction

Bug Fixes

• config: no longer apply default metadata props to a modified default metadata in config (#95) (1d68a40)
• fixes bugs with sync/async processing of metadata 'choices' fn (#121) (22a9157)
• highlights: ensures treesitter markdown highlights are ON by default (#115) (d289ebe)
• pre release fixes (d62dcb3)
• various bug fixes (#117) (116b272)

v0.8.4

0.8.4 (2025-06-15)

Bug Fixes

• highlights: fixes several subtle bugs with list marker highlights (#114) (e47b286)
• parser: fixes incorrect parsing of metadata tags and values (#111) (dd2b77d)