{"id":13727497,"url":"https://github.com/mzlogin/vim-markdown-toc","last_synced_at":"2025-04-04T21:08:50.191Z","repository":{"id":37458392,"uuid":"48156915","full_name":"mzlogin/vim-markdown-toc","owner":"mzlogin","description":"A vim 7.4+ plugin to generate table of contents for Markdown files.","archived":false,"fork":false,"pushed_at":"2024-04-12T04:03:19.000Z","size":985,"stargazers_count":593,"open_issues_count":23,"forks_count":58,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-04-12T09:56:55.103Z","etag":null,"topics":["markdown","toc","vim","vim-markdown-toc","vim-plugin","vim-plugins"],"latest_commit_sha":null,"homepage":"http://www.vim.org/scripts/script.php?script_id=5460","language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mzlogin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":"https://mazhuang.org/donate/"}},"created_at":"2015-12-17T06:32:20.000Z","updated_at":"2024-04-15T03:52:57.939Z","dependencies_parsed_at":"2024-01-10T20:11:17.567Z","dependency_job_id":"2182bdcf-5067-4446-80da-d126b4503e90","html_url":"https://github.com/mzlogin/vim-markdown-toc","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mzlogin%2Fvim-markdown-toc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mzlogin%2Fvim-markdown-toc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mzlogin%2Fvim-markdown-toc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mzlogin%2Fvim-markdown-toc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mzlogin","download_url":"https://codeload.github.com/mzlogin/vim-markdown-toc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249526,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","toc","vim","vim-markdown-toc","vim-plugin","vim-plugins"],"created_at":"2024-08-03T01:04:02.320Z","updated_at":"2025-04-04T21:08:50.164Z","avatar_url":"https://github.com/mzlogin.png","language":"Vim Script","readme":"# vim-markdown-toc\n\nA vim 7.4+ plugin to generate table of contents for Markdown files.\n\n[中文版使用指南][7]\n\n## Table of Contents\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [Features](#features)\n* [Installation](#installation)\n    * [vim-plug](#vim-plug)\n    * [Vundle](#vundle)\n* [Usage](#usage)\n    * [Generate table of contents](#generate-table-of-contents)\n    * [Update existing table of contents](#update-existing-table-of-contents)\n    * [Remove table of contents](#remove-table-of-contents)\n* [Options](#options)\n* [Screenshots](#screenshots)\n* [References](#references)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## Features\n\n* Generate table of contents for Markdown files.\n\n  Supported Markdown parsers:\n\n  - [x] GFM (GitHub Flavored Markdown)\n  - [x] GitLab\n  - [x] Redcarpet\n\n* Update existing table of contents.\n\n* Auto update existing table of contents on save.\n\n*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`.*\n\n## Installation\n\nSuggest to manage your vim plugins via [vim-plug][8] or [Vundle][4], so you can install it simply three steps:\n\n### vim-plug\n\n1. add the following line to your vimrc file\n\n    ```\n    Plug 'mzlogin/vim-markdown-toc'\n    ```\n\n2. `:so $MYVIMRC`\n\n3. `:PlugInstall`\n\n### Vundle\n\n1. add the following line to your vimrc file\n\n    ```\n    Plugin 'mzlogin/vim-markdown-toc'\n    ```\n\n2. `:so $MYVIMRC`\n\n3. `:PluginInstall`\n\n## Usage\n\n### Generate table of contents\n\nMove 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.\n\n1. `:GenTocGFM`\n\n    Generate table of contents in [GFM][2] link style.\n\n    This command is suitable for Markdown files in GitHub repositories, like `README.md`, and Markdown files for GitBook.\n\n2. `:GenTocRedcarpet`\n\n    Generate table of contents in [Redcarpet][3] link style.\n\n    This command is suitable for Jekyll or anywhere else use Redcarpet as its Markdown parser.\n\n3. `:GenTocGitLab`\n\n    Generate table of contents in [GitLab][9] link style.\n\n    This command is suitable for GitLab repository and wiki.\n\n4. `:GenTocMarked`\n\n    Generate table of contents for [iamcco/markdown-preview.vim][10] which use [Marked][11] markdown parser.\n\nYou can view [here][1] to know differences between *GFM* and *Redcarpet* style toc links.\n\n### Update existing table of contents\n\nGenerally you don't need to do this manually, existing table of contents will auto update on save by default.\n\nThe `: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.\n\n### Remove table of contents\n\n`:RemoveToc` command will do this for you, just remember keep insert fence option by default.\n\n## Options\n\n1. `g:vmt_auto_update_on_save`\n\n   default: `1`\n\n   This plugin will update existing table of contents on save automatic.\n\n   You can close this feature by add the following line to your vimrc file:\n\n   ```viml\n   let g:vmt_auto_update_on_save = 0\n   ```\n\n2. `g:vmt_dont_insert_fence`\n\n   default: `0`\n\n   By default, the `:GenTocXXX` commands will add `\u003c!-- vim-markdown-toc --\u003e` 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.\n\n   If you don't like this, you can remove the fence by add the following line to your vimrc file:\n\n   ```viml\n   let g:vmt_dont_insert_fence = 1\n   ```\n\n   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.\n\n3. `g:vmt_fence_text`\n\n   default: `vim-markdown-toc`\n\n   Inner text of the fence marker for the table of contents, see `g:vmt_dont_insert_fence`.\n\n4. `g:vmt_fence_closing_text`\n\n   default: `g:vmt_fence_text`\n\n   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\n\n   ```\n   \u003c!-- TOC --\u003e\n   [TOC]\n   \u003c!-- /TOC --\u003e\n   ```\n\n5. `g:vmt_fence_hidden_markdown_style`\n\n   default: `''`\n\n   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']`.\n\n6. `g:vmt_cycle_list_item_markers`\n\n   default: `0`\n\n   By default, `*` is used to denote every level of a list:\n\n   ```\n   * [Level 1](#level-1)\n       * [Level 1-1](#level-1-1)\n       * [Level 1-2](#level-1-2)\n           * [Level 1-2-1](#level-1-2-1)\n   * [Level 2](level-2)\n   ```\n\n   If you set:\n\n   ```viml\n   let g:vmt_cycle_list_item_markers = 1\n   ```\n\n   every level will instead cycle between the valid list item markers `*`, `-` and `+`:\n\n   ```\n   * [Level 1](#level-1)\n       - [Level 1-1](#level-1-1)\n       - [Level 1-2](#level-1-2)\n           + [Level 1-2-1](#level-1-2-1)\n   * [Level 2](level-2)\n   ```\n\n   This renders the same according to Markdown rules, but might appeal to those who care about readability of the source.\n\n7. `g:vmt_list_item_char`\n\n    default: `*`\n\n    The list item marker, it can be `*`, `-` or `+`.\n\n8. `g:vmt_include_headings_before`\n\n    default: `0`\n\n    Include headings before the position you are inserting Table of Contents.\n\n9. `g:vmt_list_indent_text`\n\n    default: `''`\n\n    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.\n\n10. `g:vmt_link`\n\n    default: `1`\n\n    Whether to generate link for headings.\n\n11. `g:vmt_min_level`\n\n    default: `1`\n\n    The minimum level of headings to be included in the table of contents.\n\n12. `g:vmt_max_level`\n\n    default: `6`\n\n    The maximum level of headings to be included in the table of contents.\n\n13. `g:vmt_list_flag_min_width`\n\n    no default value\n\n    The minimum width of the list flag, fill with spaces if necessary.\n\n## Screenshots\n\n* [online demo in English][5]\n\n![](./screenshots/english.gif)\n\n* [online demo in Chinese][6]\n\n![](./screenshots/chinese.gif)\n\n## References\n\n* \u003chttps://github.com/ajorgensen/vim-markdown-toc\u003e\n\n[1]: http://mazhuang.org/2015/12/05/diff-between-gfm-and-redcarpet/\n[2]: https://github.github.com/gfm/\n[3]: https://github.com/vmg/redcarpet\n[4]: http://github.com/VundleVim/Vundle.Vim\n[5]: https://github.com/mzlogin/chinese-copywriting-guidelines/blob/Simplified/README.en.md\n[6]: https://github.com/mzlogin/awesome-adb\n[7]: http://mazhuang.org/2015/12/19/vim-markdown-toc/\n[8]: https://github.com/junegunn/vim-plug\n[9]: https://docs.gitlab.com/ee/user/markdown.html\n[10]:https://github.com/iamcco/markdown-preview.vim\n[11]:https://github.com/markedjs/marked\n","funding_links":["https://mazhuang.org/donate/"],"categories":["Editors","Vim Script","Vim script","Language Specific"],"sub_categories":["VI(m)","Markdown"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmzlogin%2Fvim-markdown-toc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmzlogin%2Fvim-markdown-toc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmzlogin%2Fvim-markdown-toc/lists"}