sponsor Vim development Vim logo Vim Book Ad

vim-markdown-toc : A plugin to generate table of contents for Markdown files.

 script karma  Rating 58/22, Downloaded by 2815  Comments, bugs, improvements  Vim wiki

created by
Ma Zhuang
script type
In GitHub: https://github.com/mzlogin/vim-markdown-toc

## Screenshots


## Features

* Generate table of contents for Markdown files.

  Supported Markdown parsers:

  - [x] GFM (GitHub Flavored Markdown)
  - [x] Redcarpet

* Update existing table of contents.

* Auto update existing table of contents on save.

## Usage

### Generate table of contents

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.

1. `:GenTocGFM`

    Generate table of contents in [GFM][2] link style.

    This command is suitable for Markdown files in GitHub repositories, like `README.md`, and Markdown files for GitBook.

2. `:GenTocRedcarpet`

    Generate table of contents in [Redcarpet][3] link style.

    This command is suitable for Jekyll or anywhere else use Redcarpet as its Markdown parser.

You can view [here][1] to know differences between *GFM* and *Redcarpet* style toc links.

### Update existing table of contents

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.

### Remove table of contents

`:RemoveToc` command will do this for you, just remember keep insert fence option by default.

## Options

1. `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

2. `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.

3. `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.
install details
Suggest to manage your vim plugins via [Vundle][4] so you can install it simply three steps:

1. add the following line to your vimrc file

    Plugin 'mzlogin/vim-markdown-toc'

2. `:so $MYVIMRC`

3. `:PluginInstall`

Installation with vim-plug is likeness.

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
vim-markdown-toc-1.4.0.tar.gz v1.4.0 2018-05-11 7.4 Ma Zhuang Make the TOC fence text be configurable, support assign markdown style in modeline.
vim-markdown-toc-1.3.0.tar.gz 1.3.0 2017-11-27 7.4 Ma Zhuang Add support for GitLab, add option `list_indent_text`, add support for Cyrillic in headings
vim-markdown-toc-1.2.2.tar.gz v1.2.2 2017-08-16 7.0 Ma Zhuang Add option to cycle list item markers, add command to remove toc
vim-markdown-toc-1.2.1.tar.gz v1.2.1 2016-11-23 7.0 Ma Zhuang Compatible with old regexp engine.
vim-markdown-toc-1.2.tar.gz v1.2 2016-11-07 7.0 Ma Zhuang Compatibility enhancement
vim-markdown-toc-1.0.tar.gz v1.0 2016-10-19 7.0 Ma Zhuang Add features: update existing toc, auto update toc on save.
vim-markdown-toc-0.1.tar.gz v0.1 2016-10-10 7.0 Ma Zhuang Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.