vim-markdown-toc : A plugin to generate table of contents for Markdown files.
| script karma |
Rating 62/23,
Downloaded by 3820 |
Comments, bugs, improvements
|
Vim wiki
|
| created by |
| Ma Zhuang |
| |
| script type |
| utility |
| |
| description |
In GitHub: https://github.com/mzlogin/vim-markdown-toc
## Screenshots
https://raw.githubusercontent.com/mzlogin/vim-markdown-toc/master/screenshots/english.gif
https://raw.githubusercontent.com/mzlogin/vim-markdown-toc/master/screenshots/chinese.gif
## Features
* Generate table of contents for Markdown files.
Supported Markdown parsers:
- [x] GFM (GitHub Flavored Markdown)
- [x] GitLab
- [x] Marked
- [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.
## 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 `<!-- 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:
```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 -->
[TOC]
<!-- /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. |
| |
| install details |
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` |
| |
script versions (upload new version)
Click on the package to download.
ip used for rating: 216.73.216.130
|
