A vim 7.4+ plugin to generate table of contents for Markdown files.
Generate table of contents for Markdown files.
Supported Markdown parsers:
Update existing table of contents.
Auto update existing table of contents on save.
Note: This plugin only works in Markdown files, that usually have a .[md|mdown|mkd|mkdn|markdown|mdwn|mdx] suffix. To check file type, please run :set ft
, Markdown files will echo filetype=markdown
.
Suggest to manage your vim plugins via vim-plug or Vundle, so you can install it simply three steps:
add the following line to your vimrc file
Plug 'mzlogin/vim-markdown-toc'
:so $MYVIMRC
:PlugInstall
add the following line to your vimrc file
Plugin 'mzlogin/vim-markdown-toc'
:so $MYVIMRC
:PluginInstall
Move the cursor to the line you want to append table of contents, then type a command below suit you. The command will generate headings after the cursor into table of contents.
:GenTocGFM
Generate table of contents in GFM link style.
This command is suitable for Markdown files in GitHub repositories, like README.md
, and Markdown files for GitBook.
:GenTocRedcarpet
Generate table of contents in Redcarpet link style.
This command is suitable for Jekyll or anywhere else use Redcarpet as its Markdown parser.
:GenTocGitLab
Generate table of contents in GitLab link style.
This command is suitable for GitLab repository and wiki.
:GenTocMarked
Generate table of contents for iamcco/markdown-preview.vim which use Marked markdown parser.
You can view here to know differences between GFM and Redcarpet style toc links.
Generally you don't need to do this manually, existing table of contents will auto update on save by default.
The :UpdateToc
command, which is designed to update toc manually, can only work when g:vmt_auto_update_on_save
turned off, and keep insert fence.
:RemoveToc
command will do this for you, just remember keep insert fence option by default.
g:vmt_auto_update_on_save
default: 1
This plugin will update existing table of contents on save automatic.
You can close this feature by add the following line to your vimrc file:
let g:vmt_auto_update_on_save = 0
g:vmt_dont_insert_fence
default: 0
By default, the :GenTocXXX
commands will add <!-- vim-markdown-toc -->
fence to the table of contents, it is designed for feature of auto update table of contents on save and :UpdateToc
command, it won't effect what your Markdown file looks like after parse.
If you don't like this, you can remove the fence by add the following line to your vimrc file:
let g:vmt_dont_insert_fence = 1
But then you will lose the convenience of auto update tables of contents on save and :UpdateToc
command. When you want to update toc, you need to remove existing toc manually and rerun :GenTocXXX
commands.
g:vmt_fence_text
default: vim-markdown-toc
Inner text of the fence marker for the table of contents, see g:vmt_dont_insert_fence
.
g:vmt_fence_closing_text
default: g:vmt_fence_text
Inner text of the closing fence marker. E.g., you could let g:vmt_fence_text = 'TOC'
and let g:vmt_fence_closing_text = '/TOC'
to get
<!-- TOC -->
[TOC]
<!-- /TOC -->
g:vmt_fence_hidden_markdown_style
default: ''
By default, vim-markdown-toc will add the markdown style into the fence of the text for the table of contents. You can avoid this and set a default markdown style with g:vmt_fence_hidden_markdown_style
that is applied if a fence is found containing the g:vmt_fence_text
without any markdown style. Obviously, g:vmt_fence_hidden_markdown_style
has to be supported, i.e. currently one of ['GFM', 'Redcarpet', 'GitLab', 'Marked']
.
g:vmt_cycle_list_item_markers
default: 0
By default, *
is used to denote every level of a list:
* [Level 1](#level-1)
* [Level 1-1](#level-1-1)
* [Level 1-2](#level-1-2)
* [Level 1-2-1](#level-1-2-1)
* [Level 2](level-2)
If you set:
let g:vmt_cycle_list_item_markers = 1
every level will instead cycle between the valid list item markers *
, -
and +
:
* [Level 1](#level-1)
- [Level 1-1](#level-1-1)
- [Level 1-2](#level-1-2)
+ [Level 1-2-1](#level-1-2-1)
* [Level 2](level-2)
This renders the same according to Markdown rules, but might appeal to those who care about readability of the source.
g:vmt_list_item_char
default: *
The list item marker, it can be *
, -
or +
.
g:vmt_include_headings_before
default: 0
Include headings before the position you are inserting Table of Contents.
g:vmt_list_indent_text
default: ''
The indent text of list item. By default, if expandtab
is set, it will be shiftwidth
([2, 5]) number of space, otherwise it will be \t
. If you set this option, it will override the default behavior.
g:vmt_link
default: 1
Whether to generate link for headings.
g:vmt_min_level
default: 1
The minimum level of headings to be included in the table of contents.
g:vmt_max_level
default: 6
The maximum level of headings to be included in the table of contents.
g:vmt_list_flag_min_width
no default value
The minimum width of the list flag, fill with spaces if necessary.