Home

• Metadata (how-to's and recipes)

Integrations

Markdown plugins

checkmate.nvim is generally compatible with popular Markdown renderer plugins—minor tweaks to configs are occasionally needed based on individual preferences.

In general, checkmate.nvim will convert Markdown checkboxes to an in-buffer, Unicode-like representation (☐, ✔, ⊝, etc), which effectively isolates Checkmate as the stylistic owner of these lines (since the other plugins likely only parse Markdown [ ] or [x]).

If you'd like another plugin to maintain stylistic control of the checkbox/todo lines, tell checkmate.nvim to only use Markdown representation. This keeps the in-buffer and on-disk representation pure Markdown, allowing other plugins to parse and apply their logic/styling.

Disable checkmate styling

1. In todo_states opt, set the marker of the default unchecked and checked states to regular Markdown:

-- checkmate.Config
todo_states = {
  unchecked = {
    marker = "[ ]",
  },
  checked = {
    marker = "[x]",
  }
},

2. To disable checkmate.nvim highlight groups, set style to false.

-- checkmate.Config
style = false

When false, checkmate.nvim highlights are not registered, including those defined in metadata.style.

Disable external plugin styling/functionality

Alternatively, you can use a Markdown renderer plugin but specifically ignore checkboxes to allow checkmate.nvim to handle all functionality and styling for this domain.

render-markdown.nvim (verified as of v8.9.0)

-- in setup() or opts table
{
  checkbox = {
      enabled = false
  }
}

markview.nvim (verified as of v27.0.0)

-- in setup() or opts table
{
  markdown_inline = {
    checkboxes = {
      enable = false
    }
  }
}

Other plugins

snacks.nvim

You can easily use checkmate with a scratch buffer via the following strategy:

Within the snacks opts setup a keymap, or call Snacks.scratch.open() however you prefer:

keys = {
  {
    "<leader>T.",
    function()
      -- Can implement your own logic for saving files by cwd, project, git branch, etc.
      local data = vim.fn.stdpath("data")
      local root = data .. "/snacks/todo"
      vim.fn.mkdir(root, "p")
      local file = root .. "/todo.md" -- IMPORTANT: must match checkmate `files` pattern

      ---@diagnostic disable-next-line: missing-fields
      Snacks.scratch.open({
        ft = "markdown",
        file = file,
      })
    end,
    desc = "Toggle Scratch Todo",
  },
}

The critical piece is that the filename must the files patten matcher in checkmate's config.

You could also use the default Snacks file naming logic and just ensure the checkmate files pattern includes that file. Snacks.scratch seems to save files with .markdown extension, so this could be one way.

Undo Behavior

Persistent undo: Disabled for Checkmate-managed buffers. Checkmate keeps Unicode in the buffer but saves Markdown to disk; Neovim only restores undo histories that match the exact file bytes, so cross-session undo would be inconsistent. Normal in-session undo/redo works as expected. This is simply a limitation of Checkmate's design.