A fancy table of contents for Markdown in a side split. Moving the cursor in the TOC moves it in the document (and back), with a beacon flash on jump.

Demo

Features

• Two-way cursor follow with a jump beacon
• Typed entries: headings, tasks, code, callouts, tables, images, links, bullets, HTML disclosures and definition terms
• Display modes (full / glyph-only / text-only / minimal) and presets
• level / nested / flat numbering, per-element glyphs and labels
• Fixed or auto width, auto-open/close, debounced + on-save refresh
• Optional markview.nvim glyphs/colours
• Optional devicons language icons
• Optional nvim-treesitter for full HTML file parsing
• Markdown, Vim help (doc/*.txt), HTML, Org, and reStructuredText out of the box; add formats under lua/toc/parsers/

Install

lazy.nvim:

{
  "zerochae/toc.nvim",
  ft = { "markdown", "quarto", "rmd", "mdx", "help", "html", "org", "rst" },
  dependencies = { -- all optional
    "nvim-tree/nvim-web-devicons",
    "OXY2DEV/markview.nvim",
    "nvim-treesitter/nvim-treesitter", -- full HTML parsing (tables, disclosures)
  },
  keys = { { "<leader>t", "<cmd>Toc toggle<cr>", desc = "Toggle TOC" } },
  opts = {},
}

A Nerd Font is needed for the glyphs (except the plain preset).

Markdown and Vim help parse with no dependencies. HTML files use treesitter when its parser is installed (:TSInstall html) and fall back to a limited regex scanner otherwise, so tables and disclosures may be skipped without it.

Usage

:Toc [toggle|open|close|refresh] (default: toggle). Inside the panel: <CR> jump + focus, o jump + stay, J/K next/prev, R refresh, q close.

Configuration

Everything is optional; call require("toc").setup { ... }. A quick start with a preset:

require("toc").setup {
  preset = "compact",         -- compact | boxed | minimal | writing | plain
  width = "auto",             -- or a fixed column count
  numbers = "level",          -- level | nested | flat | false
  labels = true,              -- false = numbers/indices only
  max_level = nil,            -- e.g. 2 to hide anything deeper than H2
}

See the preset gallery for rendered output, and :help toc.nvim for the full option list, highlight groups, and defaults.