Folding sections of Markdown in Vim
TIL: Vim is able to fold sections or Markdown on their headings 💡
What is folding 🤔
Vimʼs documentation describes “folding” as:
Folding is used to show a range of lines in the buffer as a single line on the screen. Like a piece of paper which is folded to make it shorter: +------------------------+ | line 1 | | line 2 | | line 3 | |_______________________ | \ \ \________________________\ / folded lines / /________________________/ | line 12 | | line 13 | | line 14 | +------------------------+ The text is still in the buffer, unchanged. Only the way lines are displayed is affected by folding. The advantage of folding is that you can get a better overview of the structure of text, by folding lines of a section and replacing it with a line that indicates that there is a section.
When editing large documents, I personally find it handy to temporarily fold and “hide away” certain parts I currently donʼt care about.
Folding Markdown 🗂
Out of the box, Vim and Neovim currently wonʼt know “how” to fold Markdown sections. Their included default vim-markdown filetype and syntax plugin however offers an undocumented setting to enable just this:
let g:markdown_folding = 1
There is an open pull request include this in the official documentation, but it is not merged yet.
Flicking this switch turns my
.md buffers into something like this:
+--- 32 lines: ## What is folding 🤔··········································· +--- 23 lines: ## Folding Markdown 🗂···········································
||open current fold|
||recursively open current fold|
||close current fold|
||recursively close current fold|
||toggle current fold|
||recursively open/close current fold|
||close all folds|
||open all folds|
First look 👀
With Markdown-folding enabled, Vim will default to the fully “folded” view when opening a Markdown buffer. I personally prefer to start with the “full” document though. According to this Stackoverflow thread there are a few ways out of this behavior.
I went for setting a custom
foldlevelstart value in my configuration. It instructs Vim how or if a buffer should be folded when one starts editing:
'foldlevelstart' 'fdls' number (default: -1) global Sets 'foldlevel' when starting to edit another buffer in a window. Useful to always start editing with all folds closed (value zero), some folds closed (one) or no folds closed (99). This is done before reading any modeline, thus a setting in a modeline overrules this option. Starting to edit a file for |diff-mode| also ignores this option and closes all folds. It is also done before BufReadPre autocommands, to allow an autocmd to overrule the 'foldlevel' value for specific files. When the value is negative, it is not used.
I went for starting with all folds open in Markdown buffers:
au FileType markdown setlocal foldlevel=99
Happy folding 🗺