Vim folding as a table of contents

The Problem

It’s easy to get lost while moving around in a long file. Sometimes the IDE is able to digest it and offer folding and navigation features, but not always… This is usually the case when dealing with long configuration files (e.g. tmux.conf or .bahsrc).

The Solution

One nice way I have found to help is by using vim folding markers in comments to add that missing structure.

It is not intrusive and portable, so I think it’s a pretty elegant solution!

Here is how it works

[1/2] Set the folding method to marker

I usually just add this modeline[^1] at the end of the file. This uses the default {{{ marker, but you can override that if you prefer something else

# Inside of a comment, replace '#' as required
# vim: fdm=marker:fen:fdl=0:

[2/2] Place your markers

I use only “level 1” markers {{{1 so that they stay visible at the highest folding level, but you can fold them if you prefer by using higher levels (e.g. {{{2)

# {{{1 This is a "Heading 1"
...
#   {{{1 This is a "Heading 2"
...
#     {{{1 This is a "Heading 3"
...

The spacing before the markers is just there help visualize the levels. You do need the # to put it in a comment though

Here’s an example in a small file

Before folding

-- {{{1 Disable autoformat for some filetypes
vim.api.nvim_create_autocmd({ "FileType" }, {
  pattern = { "python", "toml" },
  callback = function()
    vim.b.autoformat = false
  end,
})

-- {{{1 Add new filetype patterns

-- |  {{{1 nix
vim.filetype.add({
  filename = { ["flake.lock"] = "json" },
})

-- |  {{{1 poetry
vim.filetype.add({
  filename = { ["poetry.lock"] = "toml" },
})

-- |  {{{1 docker
vim.filetype.add({
  pattern = { ["[Dd]ockerfile.*"] = "dockerfile" },
})

-- vim: fdm=marker:fen:fdl=0:

After folding

-- {{{1 Disable autoformat for some filetypes
-- {{{1 Add new filetype patterns
-- |  {{{1 nix
-- |  {{{1 poetry
-- |  {{{1 docker