checkmate.nvim
A full-featured, Markdown-based todo/task management plugin for Neovim with metadata, custom states, and archiving.
What is checkmate.nvim?
Checkmate.nvim is a Neovim plugin that transforms the editor into a powerful task manager using standard Markdown files. It allows users to create, toggle, and manage todos directly within Markdown documents using familiar syntax like `- [ ]` and `- [x]`. The plugin keeps all task data in a portable, plain-text format compatible with any Markdown editor.
Neovim users who manage tasks or project notes in Markdown files and want a integrated, keyboard-driven workflow without leaving their editor. It's particularly suited for developers, technical writers, or anyone maintaining documentation with actionable items.
Developers choose Checkmate.nvim for its deep integration with Neovim's ecosystem while maintaining data portability through standard Markdown. Its unique selling point is extensive customization—including custom todo states, metadata annotations, and smart toggling rules—without locking users into a proprietary format.
Overview
A full-featured, Markdown-based Neovim todo plugin
Use Cases
Best For
- Managing project todos and tasks directly within Neovim using Markdown files.
- Creating customizable task workflows with states beyond simple checked/unchecked (e.g., 'in-progress', 'on-hold').
- Adding structured metadata like priorities (`@priority(high)`) and timestamps (`@started`) to todos with visual styling.
- Automatically archiving completed tasks into a dedicated section at the bottom of a Markdown buffer.
- Visualizing task progress with completion counts (e.g., '1/4') for parent todos with subtasks.
- Integrating todo management with popular Neovim pickers like telescope.nvim, snacks.nvim, or mini.pick for quick navigation.
Not Ideal For
- Teams needing real-time collaboration or cloud-synced task management across multiple users.
- Projects requiring advanced task features like recurring reminders, dependencies, or calendar integration.
- Users who primarily edit Markdown in non-Neovim editors and need full compatibility with custom todo states (e.g., `- [.]`).
- Neovim newcomers unfamiliar with Lua configuration or plugin ecosystems seeking a zero-setup solution.
Pros & Cons
Pros
Todos are stored as standard Markdown syntax (`- [ ]`, `- [x]`), ensuring compatibility with any Markdown editor and long-term data portability, as emphasized in the philosophy.
Supports custom todo states (e.g., 'in-progress', 'on-hold'), metadata annotations like `@priority(high)`, and configurable smart toggling rules, allowing tailored workflows without proprietary lock-in.
Out-of-the-box picker support for snacks.nvim, mini.pick, and telescope.nvim enables seamless todo navigation and selection, integrating with popular Neovim tools.
Includes automatic archiving of completed todos, completion counts for parent items, and list continuation in insert mode, mimicking modern task app behavior within the editor.
Cons
Custom todo states (e.g., `- [.]`) are not CommonMark-compliant and may break rendering in other Markdown editors, limiting portability despite the plain-text format.
Setting up custom states, metadata, and pickers requires Lua knowledge and manual tweaking, with no GUI or wizard for beginners, as evidenced by the extensive config examples.
Missing features like recurring tasks, reminders, or cross-file todo management are acknowledged in the roadmap, making it less suited for complex project management needs.
The built-in linter for Markdown formatting may interfere with other linting tools like conform.nvim or prettier, and disabling it requires manual config changes.
Open Source Alternative To
checkmate.nvim is an open-source alternative to the following products:
Todoist is a popular task management and to-do list application available across multiple platforms, helping users organize projects and tasks.
TickTick is a task management and to-do list application that helps users organize tasks, set reminders, and collaborate with teams across multiple platforms.
Any.do is a task management and to-do list application available on web, mobile, and desktop platforms. It helps users organize tasks, set reminders, and collaborate on shared lists.
Frequently Asked Questions
Related Projects
neorgModernity meets insane extensibility. The future of organizing your life in Neovim.
orgmodeOrgmode clone written in Lua for Neovim 0.12.0+.
obsidian.nvimObsidian 🤝 Neovim (actively maintained version)
telekasten.nvimA Neovim (lua) plugin for working with a markdown zettelkasten / wiki and mixing it with a journal, based on telescope.nvim
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.