markdown-toc.nvim

Right-column TOC sidebar for markdown buffers, driven by treesitter. The sidebar buffer is set to filetype = markdown, so render-markdown.nvim styles the headings to match the source buffer.

Install (lazy.nvim)

{
  "aldevv/markdown-toc.nvim",
  dependencies = { "MeanderingProgrammer/render-markdown.nvim" },
  ft = { "markdown" },
  opts = {},
}

That's it. No setup body needed; opts = {} calls require("markdown-toc").setup({}) and registers the FileType autocmd.

Default keymaps (markdown buffers)

Key	Action
go	toggle sidebar
]h	next parent heading (cursor under ### → next ##)
[h	previous parent heading

Inside the sidebar

Key	Action
<CR>	jump to heading, close sidebar, focus source
o / double-click	jump, leave sidebar open, focus source
<Tab>	preview-jump, stay in the sidebar
q / go	close sidebar

Customise

require("markdown-toc").setup({
  width = 36,
  keymaps = {
    toggle      = "go",
    parent_next = "]h",
    parent_prev = "[h",
    sidebar = {
      enter   = "<CR>",
      open    = "o",
      preview = "<Tab>",
      close   = { "q", "go" },
    },
  },
})

Why depend on render-markdown?

The sidebar is rendered as plain markdown (# heading, ## subheading, …). render-markdown takes care of the per-level styling so the sidebar always matches whatever colour scheme / icon set you've configured for normal markdown buffers. No duplicate highlight definitions, no drift when you swap colorschemes.

License

MIT