Skip to main content
  1. Posts/

Generating Table of Contents for Markdown with Tagbar

··355 words·2 mins·
Note Nvim Markdown Tags Vim
Table of Contents

I have been using Vim plugin Tagbar for viewing and navigating tags inside my source file. However, for Markdown files, there is no support out of the box. In this post, I would like to share how to set up tagbar to show tags for Markdown.

Markdown set up
#

The tagbar wiki has instructions on setting up Markdown support. Using markdown2ctags is the best way among the three methods given. Unfortunately, it is not detailed enough and only works for Linux-like systems.

The original script has some issues when running it in Python 3 and with Markdown files containing Unicode characters. I have modified the original script and make it work in Python 3. You can find it here.

Linux
#

For Linux, put the script to folder tools under Neovim config directory1. You have to give it execution right (this is very crucial but the author fails to say so):

chmod u+x markdown2ctags.py

Inside Nvim config, add the following settings:

" Add support for markdown files in tagbar.
if has('win32')
    let g:md_ctags_bin=fnamemodify(stdpath('config')."\\tools\\markdown2ctags.exe", ":p")
else
    let g:md_ctags_bin=fnamemodify(stdpath('config')."/tools/markdown2ctags.py", ":p")
endif
let g:tagbar_type_markdown = {
    \ 'ctagstype': 'markdown.pandoc',
    \ 'ctagsbin' : g:md_ctags_bin,
    \ 'ctagsargs' : '-f - --sort=yes',
    \ 'kinds' : [
        \ 's:sections',
        \ 'i:images'
    \ ],
    \ 'sro' : '|',
    \ 'kind2scope' : {
        \ 's' : 'section',
    \ },
    \ 'sort': 0,
    \ }

Windows
#

For Windows, you can not directly run a script without using python. We have to convert the Python script to a standalone executable, i.e., markdown2ctags.exe. We can use pyinstaller to convert the script to executable files:

pyinstaller --onefile --console markdown2ctags.py

The above command will create the executable under the dist folder in the current working directory2. Then you should copy it to the tools folder under the Neovim config directory.

After all these set up, you should be able to see the table of contents in tagbar windows after using TagbarOpen command.

References
#


  1. Use echo stdpath('config') command inside Nvim to show the config path. ↩︎

  2. For details on how to generate exe file from python script, see this post ↩︎

Related

Fixing the nerdtree Window Problem with `bd` Command in Nvim
··175 words·1 min
Note Nvim Vim Linux
Show Git Diff When Doing Git Commit
··260 words·2 mins
Git Nvim Vim Diff
Markdown Writing Tricks
··807 words·4 mins
Note Markdown