<div align="center"> <img width="350" alt="checkmate_logo" src="https://github.com/user-attachments/assets/01c8e335-b8a0-47d5-b480-8ad8957c7b5f" />

Get stuff done

<p align="center"> <a href="#table-of-contents">Table of Contents</a>&nbsp;&bull;&nbsp; <a href="https://github.com/bngarren/checkmate.nvim/wiki">Wiki</a> </p> </div><br/>

<i>A Markdown-based todo/task plugin for Neovim.</i>

Features

• Create and toggle Markdown todos
• Customizable markers and styling
• Compatible with popular Neovim Markdown plugins (e.g., render-markdown, markview)
• Metadata e.g. @tag(value) annotations with extensive customization
  • e.g. @started, @done, @priority, @your-custom-tag
• Todo completion counts/percentage
• Smart toggling behavior
• Archive (reorganize) completed todos
• Todo templates with LuaSnip snippet integration
• Custom todo states
  • More than just "checked" and "unchecked", e.g. "partial", "in-progress", "on-hold"
• Automatic todo creation (list continuation in insert mode)
• Out-of-the-box picker integration with support for snacks.nvim, mini.pick, telescope

Check out the wiki for additional documentation and recipes, including:

• Advanced metadata
• Snippets
• How to setup a per-project, low-friction checkmate.nvim buffer with snacks.nvim

<br/> <img width="1200" height="204" alt="checkmate_example_simple" src="https://github.com/user-attachments/assets/6eecda10-109a-442f-b709-83ed35065bf9" /> <img width="1200" height="341" alt="checkmate_demo_complex" src="https://github.com/user-attachments/assets/8bbb9b20-23f7-4f82-b2b3-a8e8d2d9d4c5" />

https://github.com/user-attachments/assets/d5fa2fc8-085a-4cee-9763-a392d543347e

<!-- panvimdoc-ignore-start -->

Table of Contents

• Installation
• Requirements
• Usage
• Commands
• Configuration
  • Keymaps
  • Styling
  • Todo states
  • Todo counts
  • Smart toggle
  • Pickers
• Metadata
• Archiving
• Integrations
• Linting
• Roadmap
• Contributing
• Credits

<!-- panvimdoc-ignore-end -->

<a id="installation"><a/>

Installation

Requirements

• Neovim 0.10 or higher

Using lazy.nvim

{
  "bngarren/checkmate.nvim",
  ft = "markdown", -- Lazy loads for Markdown files matching patterns in 'files'
  opts = {
    -- files = { "*.md" }, -- any .md file (instead of defaults)
  },
}

If you'd like stable-ish version during pre-release, can add a minor version to the lazy spec:

{
  version = "~0.12.0" -- pins to minor 0.12.x
}

<a id="usage"><a/>

Usage

1. Open or Create a Todo File

Checkmate automatically activates when you open a Markdown file that matches your configured file name patterns.

Default patterns:

• todo or TODO (exact filename)
• todo.md or TODO.md
• Files with .todo extension (e.g., project.todo, work.todo.md)

<br>

[!NOTE] Checkmate only activates for files with the "markdown" filetype. Files without extensions need their filetype set to markdown (:set filetype=markdown)

<br>

You can customize which files activate Checkmate using the files configuration option:

files = {
  "*.md",              -- Any markdown file (basename matching)
  "**/todo.md",        -- 'todo.md' anywhere in directory tree
  "project/todo.md",   -- Any path ending with 'project/todo.md'
  "/absolute/path.md", -- Exact absolute path match
}

Patterns support Unix-style globs including *, **, ?, [abc], and {foo,bar}

2. Create Todos

• Use the mapped key (default: <leader>Tn) or the :Checkmate create command
• Or manually using Markdown syntax:

- [ ] Unchecked todo
- [x] Checked todo

(These will automatically convert when you leave insert mode!)

3. Manage Your Tasks

• Toggle items with :Checkmate toggle (default: <leader>Tt)
• Check items with :Checkmate check (default: <leader>Tc)
• Uncheck items with :Checkmate uncheck (default: <leader>Tu)
• Cycle to other custom states with :Checkmate cycle_next (default: <leader>T=) and :Checkmate cycle_previous (default <leader>T-)
• Select multiple items in visual mode and use the same commands
• Archive completed todos with :Checkmate archive (default: <leader>Ta)
• Search for your todos with :Checkmate select_todo or corresponding API

Enhance your todos with custom metadata with quick keymaps!

Your buffer is saved as regular Markdown which means it's compatible with any Markdown editor!

<a id="commands"><a/>

Commands

User commands

:Checkmate [subcommand]

| subcommand | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | archive | Archive all completed todo items in the buffer. This extracts them and moves them to a bottom section. See api archive() and Archiving section. | | check | Mark the todo item under the cursor as checked. See api check() | | create | In normal mode, converts the current line into a todo (or if already a todo, creates a sibling below). In visual mode, converts each selected line into a todo. In insert mode, creates a new todo on the next line and keeps you in insert mode. For more advanced placement, indentation, and state options, see the create(opts) API. | | cycle_next | Cycle a todo's state to the next available. See api cycle() | | cycle_previous | Cycle a todo's state to the previous. See api cycle() | | lint | Lint this buffer for Checkmate formatting issues. Runs automatically on InsertLeave and TextChanged. See api lint() and Linting section. | | metadata add | Add a metadata tag to the todo under the cursor or within the selection. Usage: :Checkmate metadata add <key> [value]. See api add_metadata(key, value) and Metadata section. | | metadata jump_next | Move the cursor to the next metadata tag for the todo item under the cursor. See api jump_next_metadata() | | metadata jump_previous | Move the cursor to the previous metadata tag for the todo item under the cursor. See api jump_previous_metadata() | | metadata remove | Remove a specific metadata tag from the todo under the cursor or within the selection. Usage: :Checkmate metadata remove <key>. See api remove_metadata(key) | | metadata select_value | Select a value from the 'choices' option for the metadata tag under the cursor. See api select_metadata_value() | | metadata toggle | Toggle a metadata tag on/off for the todo under the cursor or within the selection. Usage: `:Chec