https://github.com/mzlogin/vim-markdown-toc

A vim 7.4+ plugin to generate table of contents for Markdown files.
https://github.com/mzlogin/vim-markdown-toc

markdown toc vim vim-markdown-toc vim-plugin vim-plugins

Last synced: about 2 months ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/mzlogin/vim-markdown-toc
• Owner: mzlogin
• License: mit
• Created: 2015-12-17T06:32:20.000Z (almost 9 years ago)
• Default Branch: master
• Last Pushed: 2024-04-12T04:03:19.000Z (5 months ago)
• Last Synced: 2024-04-12T09:56:55.103Z (5 months ago)
• Topics: markdown, toc, vim, vim-markdown-toc, vim-plugin, vim-plugins
• Language: Vim Script
• Homepage: http://www.vim.org/scripts/script.php?script_id=5460
• Size: 962 KB
• Stars: 593
• Watchers: 10
• Forks: 58
• Open Issues: 23
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

• awesome - mzlogin/vim-markdown-toc
• awesome-list - vim-markdown-toc

README

        
# vim-markdown-toc

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

[中文版使用指南][7]

## Table of Contents

* [Features](#features)

* [Installation](#installation)

    * [vim-plug](#vim-plug)

    * [Vundle](#vundle)

* [Usage](#usage)

    * [Generate table of contents](#generate-table-of-contents)

    * [Update existing table of contents](#update-existing-table-of-contents)

    * [Remove table of contents](#remove-table-of-contents)

* [Options](#options)

* [Screenshots](#screenshots)

* [References](#references)

## Features

* Generate table of contents for Markdown files.

  Supported Markdown parsers:

  - [x] GFM (GitHub Flavored Markdown)

  - [x] GitLab

  - [x] Redcarpet

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

## Installation

Suggest to manage your vim plugins via [vim-plug][8] or [Vundle][4], so you can install it simply three steps:

### vim-plug

1. add the following line to your vimrc file

    ```

    Plug 'mzlogin/vim-markdown-toc'

    ```

2. `:so $MYVIMRC`

3. `:PlugInstall`

### Vundle

1. add the following line to your vimrc file

    ```

    Plugin 'mzlogin/vim-markdown-toc'

    ```

2. `:so $MYVIMRC`

3. `:PluginInstall`

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

3. `:GenTocGitLab`

    Generate table of contents in [GitLab][9] link style.

    This command is suitable for GitLab repository and wiki.

4. `:GenTocMarked`

    Generate table of contents for [iamcco/markdown-preview.vim][10] which use [Marked][11] 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:

   ```viml

   let g:vmt_auto_update_on_save = 0

   ```

2. `g:vmt_dont_insert_fence`

   default: `0`

   By default, the `:GenTocXXX` commands will add `` 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:

   ```viml

   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_fence_text`

   default: `vim-markdown-toc`

   Inner text of the fence marker for the table of contents, see `g:vmt_dont_insert_fence`.

4. `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]

   

   ```

5. `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']`.

6. `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:

   ```viml

   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.

7. `g:vmt_list_item_char`

    default: `*`

    The list item marker, it can be `*`, `-` or `+`.

8. `g:vmt_include_headings_before`

    default: `0`

    Include headings before the position you are inserting Table of Contents.

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

10. `g:vmt_link`

    default: `1`

    Whether to generate link for headings.

11. `g:vmt_min_level`

    default: `1`

    The minimum level of headings to be included in the table of contents.

12. `g:vmt_max_level`

    default: `6`

    The maximum level of headings to be included in the table of contents.

13. `g:vmt_list_flag_min_width`

    no default value

    The minimum width of the list flag, fill with spaces if necessary.

## Screenshots

* [online demo in English][5]

![](./screenshots/english.gif)

* [online demo in Chinese][6]

![](./screenshots/chinese.gif)

## References

* 

[1]: http://mazhuang.org/2015/12/05/diff-between-gfm-and-redcarpet/

[2]: https://github.github.com/gfm/

[3]: https://github.com/vmg/redcarpet

[4]: http://github.com/VundleVim/Vundle.Vim

[5]: https://github.com/mzlogin/chinese-copywriting-guidelines/blob/Simplified/README.en.md

[6]: https://github.com/mzlogin/awesome-adb

[7]: http://mazhuang.org/2015/12/19/vim-markdown-toc/

[8]: https://github.com/junegunn/vim-plug

[9]: https://docs.gitlab.com/ee/user/markdown.html

[10]:https://github.com/iamcco/markdown-preview.vim

[11]:https://github.com/markedjs/marked