vim-markdown-toc

A vim plugin to generate table of contents for Markdown files.

中文版使用指南

Table of Contents

• Features
• Installation
• Usage
  • Generate table of contents
  • Update existing table of contents
• Options
• Screenshots
• References

Features

• Generate table of contents for Markdown files.

  Supported Markdown parsers:

  • GFM (GitHub Flavored Markdown)
  • Redcarpet

• Update existing table of contents.

• Auto update existing table of contents on save.

Installation

Suggest to manage your vim plugins via Vundle 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.

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 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 link style.

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

You can view here 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.

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 contens 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.

Screenshots

• online demo in English

• online demo in Chinese

References

• https://github.com/ajorgensen/vim-markdown-toc