Using Neorg for TODO tracking in Neovim

Enable TODO tracking in Neorg

You can track TODO items directly in .norg files with customizable keywords and automatic checkbox toggling.

Minimal configuration

Add the following snippet to your Neovim init.lua (or equivalent) to load Neorg, ensure Treesitter parsing, and map a key to toggle the TODO state:

-- init.lua
require('neorg').setup{
  load = {
    ['core.defaults'] = {},
    ['core.norg.concealer'] = {},
    ['core.norg.dirman'] = {
      config = { workspaces = { notes = '~/notes' } },
    },
    ['core.norg.completion'] = {
      config = { engine = 'nvim-cmp' },
    },
    ['core.norg.journal'] = {},
    ['core.norg.todo'] = {}, -- enables TODO tracking
    ['core.norg.export'] = {},
    ['core.norg.esupports.hypenates'] = {},
    ['core.norg.esupports.metanvim'] = {},
  },
}
-- Treesitter parser for norg
vim.treesitter.language.register('norg', 'norg')
-- Key mapping to toggle TODO state (example uses tc)
vim.keymap.set('n', 'tc', function()
  require('core.norg.todo').toggle_todo()
end, { desc = 'Toggle TODO in Neorg' })

After reloading Neovim, run :Neorg sync-parsers to ensure the parser is up‑to‑date.

Using TODO toggling

Create a file ~/notes/tasks.norg and insert a line such as:

* TODO Write documentation

Place the cursor on the line and press tc. The line will change to:

* DONE Write documentation

Neorg updates the mode line to show the current TODO keyword, and the checkbox (if you use the concealer) toggles automatically.

Limits and common mistakes

• Neorg’s community is smaller than Org‑mode’s, so third‑party exporters (HTML, PDF) are limited; native export is mainly to Markdown.
• The parser can become unstable with very large .norg files; splitting notes into smaller files helps.
• Advanced Org features like clock tables, Babel source blocks, or complex property drawers are not supported.
• Do not mix .norg with other filetypes in the same buffer without proper ftplugin settings; doing so can break highlighting and the TODO toggle.
• Always use a recent Neorg release (>= 7.0.0) with Neovim ≥ 0.8; older versions lack the core.norg.todo module.