{"id":13816802,"url":"https://github.com/naokazuterada/MarkdownTOC","last_synced_at":"2025-05-15T18:32:29.489Z","repository":{"id":7851808,"uuid":"9223748","full_name":"naokazuterada/MarkdownTOC","owner":"naokazuterada","description":" SublimeText3 plugin which generate a table of contents (TOC) in a markdown document.","archived":false,"fork":false,"pushed_at":"2024-06-09T08:32:43.000Z","size":58720,"stargazers_count":306,"open_issues_count":10,"forks_count":48,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-13T11:54:40.702Z","etag":null,"topics":["markdown","python","sublime-text-3","toc-generator"],"latest_commit_sha":null,"homepage":"https://packagecontrol.io/packages/MarkdownTOC","language":"Python","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/naokazuterada.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE-MIT","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,"publiccode":null,"codemeta":null}},"created_at":"2013-04-04T17:33:24.000Z","updated_at":"2025-03-22T13:59:59.000Z","dependencies_parsed_at":"2024-08-04T06:01:18.538Z","dependency_job_id":"0a5ad736-65c4-410d-8c3a-494210064029","html_url":"https://github.com/naokazuterada/MarkdownTOC","commit_stats":{"total_commits":700,"total_committers":20,"mean_commits":35.0,"dds":"0.11857142857142855","last_synced_commit":"b61546d001661d9385423556a62c21c36abc6857"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naokazuterada%2FMarkdownTOC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naokazuterada%2FMarkdownTOC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naokazuterada%2FMarkdownTOC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naokazuterada%2FMarkdownTOC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/naokazuterada","download_url":"https://codeload.github.com/naokazuterada/MarkdownTOC/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254397905,"owners_count":22064581,"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","python","sublime-text-3","toc-generator"],"created_at":"2024-08-04T06:00:21.799Z","updated_at":"2025-05-15T18:32:29.482Z","avatar_url":"https://github.com/naokazuterada.png","language":"Python","funding_links":[],"categories":["Python","Sublime 插件"],"sub_categories":["4K显示器"],"readme":"![MarkdownTOC](./images/title.gif)\n\n![Demo animation of the toc generation](./images/capture.gif)\n\nMarkdownTOC\n===========\n\nSublime Text 3 plugin for generating a Table of Contents (TOC) in a Markdown document.\n\n[![Linux and macOS Build Status](https://api.travis-ci.org/naokazuterada/MarkdownTOC.svg?branch=master\u0026label=Linux+and+macOS+build \"Linux and macOS Build Status\")](https://travis-ci.org/naokazuterada/MarkdownTOC) [![Windows Build Status](https://ci.appveyor.com/api/projects/status/vxj9jbihlrwfa6ui/branch/master?svg=true\u0026label=Windows+build \"Windows Build Status\")](https://ci.appveyor.com/project/naokazuterada/markdowntoc/branch/master) [![codecov](https://codecov.io/gh/naokazuterada/MarkdownTOC/branch/master/graph/badge.svg)](https://codecov.io/gh/naokazuterada/MarkdownTOC) [![Package Control](https://packagecontrol.herokuapp.com/downloads/MarkdownTOC.svg)](https://packagecontrol.io/packages/MarkdownTOC) [![Gitter chat](https://badges.gitter.im/naokazuterada/MarkdownTOC.png)](https://gitter.im/naokazuterada/MarkdownTOC)\n\n---\n\n***Note: v3.0.0 has breaking changes. See [Upgrade Guide](https://github.com/naokazuterada/MarkdownTOC/releases/tag/3.0.0) for more detail.***\n\n---\n\n## Table of Contents\n\n\u003cdetails\u003e\n \u003csummary\u003eClick to open TOC\u003c/summary\u003e\n\u003c!-- MarkdownTOC autolink=\"true\" levels=\"1,2,3,4,5,6\" bracket=\"round\" style=\"unordered\" indent=\"    \" autoanchor=\"false\" markdown_preview=\"github\" --\u003e\n\n- [Quick Start](#quick-start)\n- [Features](#features)\n    - [Insertion of TOC based on headings in Markdown document](#insertion-of-toc-based-on-headings-in-markdown-document)\n    - [Automatic refresh of TOC when Markdown document is saved](#automatic-refresh-of-toc-when-markdown-document-is-saved)\n        - [Supported file extensions](#supported-file-extensions)\n    - [Customizing generation of TOC using attributes](#customizing-generation-of-toc-using-attributes)\n    - [Auto anchoring when heading has anchor defined](#auto-anchoring-when-heading-has-anchor-defined)\n    - [Auto linking for _clickable_ TOC](#auto-linking-for-_clickable_-toc)\n        - [Lowercasing in ids](#lowercasing-in-ids)\n            - [Preserve case](#preserve-case)\n            - [Lowercase all characters](#lowercase-all-characters)\n        - [Manipulation of auto link ids](#manipulation-of-auto-link-ids)\n        - [URI encoding](#uri-encoding)\n        - [Markdown Preview compatible](#markdown-preview-compatible)\n        - [Link Prefix](#link-prefix)\n    - [Control of levels listed in TOC](#control-of-levels-listed-in-toc)\n    - [Ordered or unordered style for TOC elements](#ordered-or-unordered-style-for-toc-elements)\n    - [Customizable list bullets in TOC](#customizable-list-bullets-in-toc)\n    - [Specify custom indentation prefix](#specify-custom-indentation-prefix)\n    - [Preserve images in headings](#preserve-images-in-headings)\n    - [Excluded headings](#excluded-headings)\n- [Usage](#usage)\n- [Tips](#tips)\n    - [How to remove anchors added by MarkdownTOC](#how-to-remove-anchors-added-by-markdowntoc)\n    - [Addressing issues with Github Pages](#addressing-issues-with-github-pages)\n    - [Using MarkdownTOC with Markdownlint](#using-markdowntoc-with-markdownlint)\n- [Limitations](#limitations)\n    - [Headings in lists are not included in the auto-generated table of contents](#headings-in-lists-are-not-included-in-the-auto-generated-table-of-contents)\n- [Attributes](#attributes)\n- [Installation](#installation)\n    - [Using Package Control](#using-package-control)\n    - [From Git](#from-git)\n    - [From downloadable archive](#from-downloadable-archive)\n- [Configuration](#configuration)\n    - [Github Configuration](#github-configuration)\n    - [Configuration and Collaboration](#configuration-and-collaboration)\n- [Compatibility](#compatibility)\n- [Contributing](#contributing)\n- [License](#license)\n- [Author](#author)\n- [References](#references)\n    - [Markdown Table of Contents Generators](#markdown-table-of-contents-generators)\n    - [Recommended plugins for use with MarkdownTOC](#recommended-plugins-for-use-with-markdowntoc)\n\n\u003c!-- /MarkdownTOC --\u003e\n\u003c/details\u003e\n\n## Quick Start\n\n1. [Install](#installation) the **MarkdownTOC** plugin\n1. Open your [Markdown] file\n1. Place the cursor at the position where you want to insert the TOC\n1. Pick from menu: Tools \u003e MarkdownTOC \u003e Insert TOC\n1. And the TOC is inserted in the [Markdown] document\n1. Save the document and you are done\n\nNow you can go on and edit your document further or you can customize you TOC, please read on.\n\n## Features\n\nThe **MarkdownTOC** plugin is rich on features and customization, useful for both work on a single [Markdown] document or if you have several [Markdown] documents that require _special_ TOC generation.\n\n- [Insertion of TOC based on headings in Markdown document](#insertion-of-toc-based-on-headings-in-markdown-document)\n- [Automatic refresh of TOC when Markdown document is saved](#automatic-refresh-of-toc-when-markdown-document-is-saved)\n- [Customizing generation of TOC using attributes](#customizing-generation-of-toc-using-attributes)\n- [Auto anchoring when heading has anchor defined](#auto-anchoring-when-heading-has-anchor-defined)\n- [Auto linking for _clickable_ TOC](#auto-linking-for-clickable-toc)\n    - [Lowercasing in ids](#lowercasing-in-ids)\n        - [Preserve case](#preserve-case)\n        - [Lowercase all characters](#lowercase-all-characters)\n    - [Manipulation of auto link ids](#manipulation-of-auto-link-ids)\n    - [URI encoding](#uri-encoding)\n    - [Markdown Preview compatible](#markdown-preview-compatible)\n    - [Link Prefix](#link-prefix)\n- [Control of levels listed in TOC](#control-of-levels-listed-in-toc)\n- [Ordered or unordered style for TOC elements](#ordered-or-unordered-style-for-toc-elements)\n- [Customizable list bullets in TOC](#customizable-list-bullets-in-toc)\n- [Specify custom indentation prefix](#specify-custom-indentation-prefix)\n- [Preserve images in headings](#preserve-images-in-headings)\n- [Excluded headings](#excluded-heading)\n\n### Insertion of TOC based on headings in Markdown document\n\nWhen you have completed the [installation](#installation) of the plugin, you can insert an automatically generated TOC based on your [Markdown] headings. See the [Quick Start](#quick-start) to get going or the [Usage section](#usage) for details on how to utilize customization and [configuration](#configuration).\n\nFor the following sample [Markdown] document:\n\n```markdown\n\n# Heading 0\n\nHeadings before MarkdownTOC tags will be ignored.\n\n◀ place the cursor here and generate the TOC\n\n# Heading 1\nLorem ipsum...\n\n## Heading 2\nLorem ipsum...\n```\n\nThe **MarkdownTOC** plugin will out of the box generate:\n\n```markdown\n# Heading 0\n\nHeadings before MarkdownTOC tags will be ignored.\n\n\u003c!-- MarkdownTOC --\u003e\n\n- Heading 1\n  - Heading 2\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# Heading 1\nLorem ipsum...\n\n## Heading 2\nLorem ipsum...\n```\n\nAs you can read from the sample above:\n\n1. Headings above the `MarkdownTOC` tag section are ignored, only the rest of the document is considered _in scope_\n\n### Automatic refresh of TOC when Markdown document is saved\n\nIf we edit the [Markdown] document some more and add an additional heading:\n\n```markdown\n## Heading 3\n```\n\nWhen we save the document, the TOC is automatically updated.\n\n```markdown\n\u003c!-- MarkdownTOC --\u003e\n\n- Heading 1\n  - Heading 2\n  - Heading 3\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# Heading 1\nLorem ipsum...\n\n## Heading 2\nLorem ipsum...\n\n## Heading 3\nLorem ipsum... (the added text)\n```\n\nSame goes for deleted headings, these are cleared out.\n\nUpdating the TOC can also be accomplished without saving by picking from the menu: Tools \u003e MarkdownTOC \u003e Update TOC\n\n#### Supported file extensions\n\nMake sure your file's extension is in the following list.\n\n`.md` `.markdown` `.mdown` `.mdwn` `.mkdn` `.mkd` `.mark`\n\n### Customizing generation of TOC using attributes\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" --\u003e\n\n- [Heading 1](#heading-1)\n  - [Heading 2](#heading-2)\n  - [Heading 3](#heading-3)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# Heading 1\nLorem ipsum...\n\n## Heading 2\nLorem ipsum...\n\n## Heading 3\nLorem ipsum... (the added text)\n```\n\n1. TOC tags can overwrite default [attributes](#Attributes) using local settings and influence the rendering of the TOC. See: [Configuration](#configuration) on how to set your own defaults for the plugin\n1. Headings can be automatically linked (see: [auto link](#auto-link))\n1. Headings can have anchors automatically linked (see: [Auto anchoring when heading has anchor defined](#auto-anchoring-when-heading-has-anchor-defined))\n\nThe default behaviour could also be described as:\n\n```markdown\n\u003c!-- MarkdownTOC levels=\"1,2,3,4,5,6\" autolink=\"false\" bracket=\"round\" autoanchor=\"false\" style=\"unordered\" indent=\"\\t\" --\u003e\n```\n\nPlease see: [Github Configuration](#github-configuration) for a guideline to configuring **MarkdownTOC** for [Github] use.\n\n### Auto anchoring when heading has anchor defined\n\nYou can add an HTML anchor (`\u003ca name=\"xxx\"\u003e\u003c/a\u003e`) before your heading automatically.\n\n```markdown\n# Heading with anchor [with-anchor]\n```\n\nThe TOC generation can be specified to respect this and a TOC element of the following format is generated:\n\n```markdown\n- [Heading with anchor](#with-anchor)\n```\n\nPlease note that the default for the attribute: [autoanchor](#autoanchor) is `false`.You can add an HTML anchor (`\u003ca name=\"xxx\"\u003e\u003c/a\u003e`) before the heading automatically.\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" autoanchor=\"true\" --\u003e\n\n- [Changelog](#changelog)\n- [Glossary](#glossary)\n- [API Specification](#api-specification)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n\u003ca name=\"changelog\"\u003e\u003c/a\u003e\n# Changelog\nLorem ipsum...\n\n\u003ca name=\"glossary\"\u003e\u003c/a\u003e\n# Glossary\nLorem ipsum...\n\n\u003ca name=\"api-specification\"\u003e\u003c/a\u003e\n# API Specification\nLorem ipsum...\n```\n\nPlease note that the default for autolink is `false` defined by the [attribute](#attributes) `defaults.autoanchor`. See also: [How to remove anchors added by MarkdownTOC](#how-to-remove-anchors-added-by-markdowntoc).\n\n### Auto linking for _clickable_ TOC\n\nThe plugin can be specified to auto link heading so you get a TOC with _clickable_ hyperlink elements.\n\nThe following sample document:\n\n```markdown\n# Heading 1\nLorem ipsum...\n\n## Heading 2\nLorem ipsum...\n\n## Heading 3\nLorem ipsum...\n```\n\nWith `autolink` set to `true` will render the following:\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" --\u003e\n\n- [Heading 1](#heading-1)\n  - [Heading 2](#heading-2)\n  - [Heading 3](#heading-3)\n  - [Heading 4](#heading-4)\n- [Heading with anchor](#with-anchor)\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n\nThe auto link markup style can be one of:\n\n- `round`, the default, the style supported on [Github]\n- `square`, the [\"Markdown standard reference-style links\"][MarkdownLinks] style.\n\nPlease note that the default for autolink is `false` defined by the [attribute](#attributes) `defaults.autolink`.\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"false\" --\u003e\n\n- MarkdownTOC Plugin for Sublime Text\n  - Feature\n  - Feature\n  - Feature\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" --\u003e\n\n- [MarkdownTOC Plugin for Sublime Text](#markdowntoc-plugin-for-sublime-text)\n  - [Feature](#feature)\n  - [Feature](#feature-1)\n  - [Feature](#feature-2)\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n\n**round**: according to [Github] style.\n\n```markdown\n\u003c!-- MarkdownTOC bracket=\"round\" --\u003e\n\n- [Heading](#heading)\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n\n**square**: according to [\"Markdown standard reference-style links\"][MarkdownLinks].\n\n```markdown\n\u003c!-- MarkdownTOC bracket=\"square\" --\u003e\n\n- [Heading][heading]\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n\nPlease note that the default for bracket is `round` defined by the [attribute](#attributes) `defaults.bracket`.\n\n#### Lowercasing in ids\n\nBy default the plugin lowercases ASCII based alphabets **only** (`a` to `z`) for auto links.\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" --\u003e\n\n- [ПРИМЕР EXAMPLE][ПРИМЕР-example]\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# ПРИМЕР EXAMPLE\n```\n\nThis is same as setting `lowercase` attribute to `only_ascii`.\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" lowercase=\"only_ascii\" --\u003e\n\n- [ПРИМЕР EXAMPLE][ПРИМЕР-example]\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# ПРИМЕР EXAMPLE\n```\n\n##### Preserve case\n\nYou can disable the lowercasing capability by setting the `lowecase` attribute to `false`.\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" lowercase=\"false\" --\u003e\n\n- [One Two Three][One-Two-Three]\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# One Two Three\n```\n\n##### Lowercase all characters\n\nFurther more you can also expand the lowercasing capability by setting the `lowercase` attribute to `all`(or any values other than `false` and `only_ascii`).\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" lowercase=\"all\" --\u003e\n\n- [ПРИМЕР EXAMPLE][пример-example]\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# ПРИМЕР EXAMPLE\n```\n\nYou can also specify this in your [configuration](#configuration) with key `defaults.lowercase`.\n\n#### Manipulation of auto link ids\n\nYou can manipulate your link ids in your [configuration](#configuration) using the key `id_replacements`.\n\n```json\n{\n  \"id_replacements\": [\n    {\n      \"pattern\": \"\\\\s+\",\n      \"replacement\": \"-\"\n    },\n    {\n      \"pattern\": \"!|#|$|\u0026|'|\\\\(|\\\\)|\\\\*|\\\\+|,|/|:|;|=|_|\\\\?|@|\\\\[|\\\\]|`|\\\"|\\\\.|\u003c|\u003e|{|}|™|®|©|\u0026lt;|\u0026gt;|\u0026amp;|\u0026apos;|\u0026quot;|\u0026#60;|\u0026#62;|\u0026#38;|\u0026#39;|\u0026#34;\",\n      \"replacement\": \"\"\n    }\n  ]\n}\n```\n\n1. Regular expression is allowed in each sets\n    - It will be simply expanded into python's `re.sub(pattern, replacement, id)`\n2. The replacement sequence executes from top to bottom\n\nAn example:\n\n```markdown\n# Super Product™\n```\n\nThis heading link of this heading is changed to following id\n\n```markdown\n#super-product\n```\n\n- The `' '` (space) is replaced with `-` (dash), since `' '` is included in the first set\n- The '™' is replaced with _nothing_, since '™' is included in the second set\n\n#### URI encoding\n\nBy default non-ASCII characters in link ids are [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding).\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" --\u003e\n\n- [Ejemplos de español](#ejemplos-de-espa%C3%B1ol)\n- [日本語の例](#%E6%97%A5%E6%9C%AC%E8%AA%9E%E3%81%AE%E4%BE%8B)\n- [Примеры русского](#%D0%9F%D1%80%D0%B8%D0%BC%D0%B5%D1%80%D1%8B-%D1%80%D1%83%D1%81%D1%81%D0%BA%D0%BE%D0%B3%D0%BE)\n- [中国的例子](#%E4%B8%AD%E5%9B%BD%E7%9A%84%E4%BE%8B%E5%AD%90)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# Ejemplos de español\n# 日本語の例\n# Примеры русского\n# 中国的例子\n```\n\nAs mentioned you can disable this by setting the `uri_encoding` attribute to `false`, like so: `uri_encoding=\"false\"`.\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" uri_encoding=\"false\" --\u003e\n\n- [Ejemplos de español](#ejemplos-de-español)\n- [日本語の例](#日本語の例)\n- [Примеры русского](#Примеры-русского)\n- [中国的例子](#中国的例子)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# Ejemplos de español\n# 日本語の例\n# Примеры русского\n# 中国的例子\n```\n\n#### Markdown Preview compatible\n\nIf you want to use **MarkdownTOC** with [Markdown Preview][MarkdownPreview], you should use `markdown_preview` attribute.\nYou can set this attribute to either `markdown` or `github`.\n\nWhen you set it to `markdown`, you can get same links rendered by MarkdownPreview's markdown parser.\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" markdown_preview=\"markdown\" --\u003e\n\n- [Hello 世界 World](#hello-world)\n- [ESPAÑA](#espana)\n- [ПРИМЕР RUSSIAN](#russian)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# Hello 世界 World\n# ESPAÑA\n# ПРИМЕР RUSSIAN\n```\n\nWhen you set it to `github`, you can get same links rendered by MarkdownPreview's github parser.\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" markdown_preview=\"github\" --\u003e\n\n- [Hello 世界 World](#hello-%25E4%25B8%2596%25E7%2595%258C-world)\n- [ESPAÑA](#espa%25C3%25B1a)\n- [ПРИМЕР RUSSIAN](#%25D0%25BF%25D1%2580%25D0%25B8%25D0%25BC%25D0%25B5%25D1%2580-russian)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# Hello 世界 World\n# ESPAÑA\n# ПРИМЕР RUSSIAN\n```\n\nCurrently no other parsers are supported.\n\nIf you want to disable this feature, set it to `false`.\n\n#### Link Prefix\n\nYou can also set _prefix_ of links.\n\n```markdown\n\u003c!-- MarkdownTOC autolink=true link_prefix=\"user-content-\" --\u003e\n\n- [My Heading](#user-content-my-heading)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# My Heading\n```\n\nYou can manipulate this in your [configuration](#configuration) using the key `defaults.link_prefix`.\n\n### Control of levels listed in TOC\n\n```markdown\n# Heading 1\nLorem ipsum...\n\n## Heading 2\nLorem ipsum...\n\n### Heading 3\nLorem ipsum...\n\n#### Heading 4\nLorem ipsum...\n```\n\nWith default levels:\n\n```markdown\n\u003c!-- MarkdownTOC --\u003e\n\n- Heading 1\n  - Heading 2\n    - Heading 3\n      - Heading 4\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n\nWith levels set to 1,2:\n\n```markdown\n\u003c!-- MarkdownTOC levels=\"1,2\" --\u003e\n\n- Heading 1\n  - Heading 2\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n\nPlease note that the default for the [attribute](#attributes) levels is `\"1,2,3,4,5,6\"`, it means all heading sizes will be included.\n\nYou can also specify this in your [configuration](#configuration) with key `defaults.levels`.\n\nThe maximum size for headings is `6` according to the [Markdown specification][Markdown]\n\n### Ordered or unordered style for TOC elements\n\nThe plugin supports two styles of TOC element listing:\n\n- `unordered`\n- `ordered`\n\nA [Markdown] document with the following contents:\n\n```markdown\n# Heading 1\nLorem ipsum...\n\n## Heading 2\nLorem ipsum...\n\n### Heading 3\nLorem ipsum...\n\n### Heading 4\nLorem ipsum...\n\n## Heading 5\nLorem ipsum...\n\n# Heading 6\nLorem ipsum...\n```\n\nWill with style `unordered`:\n\n```markdown\n\u003c!-- MarkdownTOC style=\"unordered\" --\u003e\n\n- Heading 1\n  - Heading 2\n    - Heading 3\n    - Heading 4\n  - Heading 5\n- Heading 6\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n\nAnd with style `ordered`:\n\n```markdown\n\u003c!-- MarkdownTOC style=\"ordered\" --\u003e\n\n1. Heading 1\n  1. Heading 2\n    1. Heading 3\n    1. Heading 4\n  1. Heading 5\n1. Heading 6\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n\nPlease note that the default for the [attribute](#attributes) is: `unordered`.\n\nYou can set your default style in your [configuration](#configuration) with the key `defaults.style`.\n\n### Customizable list bullets in TOC\n\nYou can define the list items used for the TOC for each level. The first item is for the first level, the second for the second and so on until the last one of the list and then it starts over from the beginning.\n\n```markdown\n\u003c!-- MarkdownTOC bullets=\"-,+,*\" --\u003e\n\n- foo\n  + bar\n    * baz\n      - foo\n        + bar\n          * baz\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n\nYou can set default list bullets in your [configuration](#configuration) with the key `defaults.bullets`.\n\nThe example above could also be described as:\n\n```json\n{\n  \"defaults\": {\n    \"bullets\": [\"-\",\"+\",\"*\"]\n  }\n}\n```\n\nYou can also set it in attribute. In this case the values type is **'conmma separated string'**.\n\n```markdown\n\u003c!-- MarkdownTOC bullets=\"-,+,*\" --\u003e\n```\n\n### Specify custom indentation prefix\n\nThe indentation prefix is a specification of the string used to indent the TOC elements.\n\nAn _ugly_ but demonstrative example could be to use an [emoji][emoji].\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" indent=\":point_right: \" --\u003e\n\n- [Heading 1](#heading-1)\n:point_right: - [Heading 2](#heading-2)\n:point_right: :point_right: - [Heading 3](#heading-3)\n:point_right: :point_right: - [Heading 4](#heading-4)\n:point_right: - [Heading 5](#heading-5)\n- [Heading 6](#heading-6)\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n\nPlease note that the default for the [attribute](#attributes) is: `'\\t'`.\n\nYou can set your default indentation in your [configuration](#configuration) with the key `defaults.indent`.\n\n### Preserve images in headings\n\nIf you want to preserve images in headings, set `remove_image` to `false`.\n\n```markdown\n\u003c!-- MarkdownTOC remove_image=\"false\" --\u003e\n\n- ![check](check.png) Everything is OK\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# ![check](check.png) Everything is OK\n```\n\nPlease note that the default for the [attribute](#attributes) is: `false`.\n\n```markdown\n\u003c!-- MarkdownTOC --\u003e\n\n- Everything is OK\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# ![check](check.png) Everything is OK\n```\n\nYou can change your default setting in your [configuration](#configuration) with the key `defaults.remove_image`.\n\n### Excluded headings\n\nYou can exclude certain headings in the TOC by adding a special comment to the line above the line with the heading, as shown below.\n\n```markdown\n\u003c!-- MarkdownTOC:excluded --\u003e\n## This heading will be excluded\n```\n\n## Usage\n\n1. Open your [Markdown] file\n2. Set cursor to position where you want to insert a TOC\n3. Pick from menu: Tools \u003e MarkdownTOC \u003e Insert TOC\n4. TOC is inserted in document\n5. Evaluate your TOC and customize using [attributes](#attributes) or [configuration](#configuration)\n6. Update contents and save...\n7. TOC has been updated\n\n***Don't remove the comment tags if you want to update every time saving.***\n\n## Tips\n\n### How to remove anchors added by MarkdownTOC\n\nIf you want to remove the TOC again, you do not have to go through your complete Markdown and remove all tags manually - just follow this simple guide (see also: [Auto anchoring when heading has anchor defined](#auto-anchoring-when-heading-has-anchor-defined)).\n\n1. Open your [Markdown] file\n2. Set the attribute `autoanchor` to `false`, this clears all anchors\n\n```markdown\n\u003c!-- MarkdownTOC autoanchor=\"false\" --\u003e\n```\n\nPlease see the below animation demonstrating the change\n\n![Demo animation of removal of toc](./images/how_to_remove_the_toc.gif)\n\n\u003col\u003e\u003cli value=\"3\"\u003eNow delete the TOC section from beginning to end and **MarkdownTOC** integration is gone\u003c/li\u003e\u003c/ol\u003e\n\n```markdown\n\u003c!-- MarkdownTOC autoanchor=\"false\" --\u003e\n\n...\n\n\u003c!-- /MarkdownTOC --\u003e\n```\n\nRef: [Github issue #76](https://github.com/naokazuterada/MarkdownTOC/issues/76)\n\n### Addressing issues with Github Pages\n\nIf you are using Github Pages you might experience that some themes do not render heading correctly.\n\nThis can be addressed simply by setting `autoanchor` to `false`\n\n```markdown\n\u003c!-- MarkdownTOC autoanchor=\"false\" --\u003e\n```\n\nAnd when **Jekyll** is done, your headings should render correctly.\n\nRef: [Github issue #81](https://github.com/naokazuterada/MarkdownTOC/issues/81)\n\n### Using MarkdownTOC with Markdownlint\n\nIf you are using [Markdownlint](https://github.com/DavidAnson/markdownlint) (Node implementation), it will report several violations out of the box.\n\nThe basic configuration you can use to address these looks like the following:\n\n```json\n{\n    \"html\": false,\n    \"blanks-around-headings\": false,\n    \"ul-indent\": {\n        \"indent\": 4\n    }\n}\n```\n\n- `html` set to `false`, to allow use of HTML since **MarkdownTOC** relies on HTML tags to assist the Markdown\n- `blanks-around-headings` should be set to `false`, since anchors are places closed to the headings that are listed in the TOC\n- `ul-indent` should have it's parameter `indent` set to `4` to adhere with the default of `4` used by **MarkdownTOC**, whereas **Markdownlint** defaults to `2`\n\nIf you have configured **MarkdownTOC** differently, you can adjust your **Markdownlint** configuration accordingly.\n\nDo note that this tip is based on the **Node** implementation, [available on GitHub](https://github.com/DavidAnson/markdownlint), which uses a project specific `.markdownlint.json` based configuration.\n\n## Limitations\n\n**MarkdownTOC** does come with some limitations.\n\nFor more information on compatibility, please see [the dedicated section](#compatibility).\n\n### Headings in lists are not included in the auto-generated table of contents\n\nExample of [Markdown] heading in a [Markdown] listing, not being included in the auto-generated Table of Contents\n\n```markdown\n- # this is a heading\n```\n\n## Attributes\n\nThe following attributes can be used to control the generation of the TOC.\n\n| attribute              | values                                    | default         |\n|:-----------------------|:------------------------------------------|:----------------|\n| `autoanchor`           | `true`or`false`                           | `false`         |\n| `autolink`             | `true`or`false`                           | `false`         |\n| `bracket`              | `\"round\"`or`\"square\"`                     | `\"round\"`       |\n| `indent`               | string                                    | `\"\\t\"`          |\n| `levels`               | string (decimal list separated with `,`)  | `\"1,2,3,4,5,6\"` |\n| `link_prefix`          | string                                    | `\"\"`            |\n| `bullets`              | string                                    | `\"-\"`           |\n| `lowercase`            | `\"all\"`or`\"only_ascii\"`or`\"false\"`        | `\"only_ascii\"`  |\n| `remove_image`         | `true`or`false`                           | `true`          |\n| `style`                | `\"ordered\"` or `\"unordered\"`              | `\"unordered\"`   |\n| `uri_encoding`         | `true`or`false`                           | `true`          |\n| `markdown_preview`     | `\"\"`or`\"github\"`or`\"markdown\"`            | `\"\"`            |\n\nYou can define your own default values via package preferences, [Sublime Text][SublimeText]'s way of letting users customize [package settings][SublimeTextSettings]. Please see the [Section on Configuration](#Configuration) for more details for **MarkdownTOC**.\n\n## Installation\n\n### Using Package Control\n\n1. Run “Package Control: Install Package” command, find and install `MarkdownTOC` plugin.\n2. Restart [Sublime Text][SublimeText]\n\n\u003e [Package Control][PackageControl]\n\n### From Git\n\n```sh\ngit clone git@github.com:naokazuterada/MarkdownTOC.git ~/Library/Application\\ Support/Sublime\\ Text\\ 3/Packages/MarkdownTOC\n```\n\n### From downloadable archive\n\n1. [Download zip-file](https://github.com/naokazuterada/MarkdownTOC/archive/master.zip) and unpack it.\n2. Open the [Sublime Text][sublimetext] `Packages/` directory (pick menu: Sublime Text \u003e Preferences \u003e Browse Packages).\n3. Move the `MarkdownTOC/` directory into the `Packages/` directory.\n\n## Configuration\n\nYou can use [attributes](#attributes) to customize a TOC in a single [Markdown] document, but if you want to keep the same TOC configuration accross multiple [Markdown] documents, you can configure your own defaults.\n\nPick: `Sublime Text \u003e Preferences \u003e Package Settings \u003e MarkdownTOC \u003e Settings - User`\n\nAlternatively you can create the file `~/Library/Application Support/Sublime Text 3/Packages/User/MarkdownTOC.sublime-settings` by hand.\n\nExample: `MarkdownTOC.sublime-settings`\n\n```json\n{\n  \"defaults\": {\n    \"autolink\": true,\n    \"bracket\": \"square\",\n    \"levels\": \"1,2\",\n    \"indent\": \"    \",\n    \"remove_image\": false,\n    \"bullets\": \"*\",\n    \"style\": \"ordered\"\n  },\n  \"id_replacements\": [\n    {\n      \"pattern\": \"\\\\s+\",\n      \"replacement\": \"-\"\n    },\n    {\n      \"pattern\": \"\u0026lt;|\u0026gt;|\u0026amp;|\u0026apos;|\u0026quot;|\u0026#60;|\u0026#62;|\u0026#38;|\u0026#39;|\u0026#34;|!|#|$|\u0026|'|\\\\(|\\\\)|\\\\*|\\\\+|,|/|:|;|=|_|\\\\?|@|\\\\[|\\\\]|`|\\\"|\\\\.|\u003c|\u003e|{|}|™|®|©\",\n      \"replacement\": \"\"\n    }\n  ]\n}\n```\n\nPlease see the section on [attributes](#attributes) for an overview of values and the [section on customization](#customizing-generation-of-toc-using-attributes).\n\nConfiguration precendence is as follows:\n\n1. Attributes specified in **MarkdownTOC** begin tag (see: [Customizing generation of TOC using attributes](#customizing-generation-of-toc-using-attributes))\n1. **MarkdownTOC** Settings - user (this section)\n1. **MarkdownTOC** Settings - default (see: [Attributes](#attributes))\n\nFor an overview of the specific behaviour behind an attribute, please refer to the below list.\n\n- `defaults.autolink`, (see: [Auto linking for _clickable_ TOC](#auto-linking-for-clickable-toc))\n- `defaults.autoanchor`, (see: [Auto anchoring when heading has anchor defined](#auto-anchoring-when-heading-has-anchor-defined))\n- `defaults.bracket`, (see: [Auto linking for _clickable_ TOC](#auto-linking-for-clickable-toc))\n- `defaults.indent`, (see: [Specify custom indentation prefix](#specify-custom-indentation-prefix))\n- `defaults.link_prefix`, (see: [Link Prefix](#link-prefix))\n- `defaults.levels`, (see: [Control of levels listed in TOC](#control-of-levels-listed-in-toc))\n- `defaults.bullets`, (see: [Customizable list bullets in TOC](#customizable-list-bullets-in-toc))\n- `defaults.lowercase`, (see: [Lowercasing in ids](#lowercasing-in-ids))\n- `defaults.remove_image`, (see: [Preserve images in headings](#maintain-the-images-in-headings))\n- `defaults.style`, (see: [Ordered or unordered style for TOC elements](#ordered-or-unordered-style-for-toc-elements))\n- `defaults.uri_encoding`, (see: [URI encoding](#uri-encoding))\n- `defaults.markdown_preview`, (see: [Markdown Preview compatible](#markdown-preview-compatible))\n- `id_replacements`, (see: [Manipulation of auto link ids](#manipulation-of-auto-link-ids))\n\n### Github Configuration\n\nA configuration for writing Markdown primaily for use on [Github] _could_ look like the following:\n\n```json\n{\n  \"defaults\": {\n    \"autolink\": true,\n    \"bracket\": \"round\",\n    \"lowercase\": \"only_ascii\"\n  }\n}\n```\n\n### Configuration and Collaboration\n\nYou should be aware that if you collaborate with other [Markdown] writers and users of **MarkdownTOC**, you might have changes going back and forth simply due to differing configurations.\n\nIf that is the case and you cannot agree on a configuration, choose configuration using attributes specified in the document instead.\n\nExample of attribute configuration for the above configuration settings in file:\n\n```markdown\n\u003c!-- MarkdownTOC autolink=\"true\" bracket=\"round\" autoanchor=\"true\" --\u003e\n```\n\n## Compatibility\n\nThis is by no means an exhaustive list and you are welcome to provide additional information and feedback. Here is listed what Markdown rendering platforms and tools where compatibility and incompatibily has been asserted with the **MarkdownTOC** plugin.\n\n| Application  | Compatibility |\n| ------------ | ------------- |\n| [Github](https://github.com/) | Compatible |\n| [Gitblit](http://gitblit.com/) 1.6.x | Incompatible |\n| [Gitlab](https://about.gitlab.com/) 8.10.x | Compatible |\n| [BitBucket](https://bitbucket.org/) 5.12.2 | Incompatible |\n\n## Contributing\n\nContributions are most welcome, please see the [guidelines on contributing](https://github.com/naokazuterada/MarkdownTOC/blob/master/.github/CONTRIBUTING.md).\n\n## License\n\n- **MarkdownTOC** is licensed under the [MIT License](https://github.com/naokazuterada/MarkdownTOC/blob/master/LICENSE-MIT)\n\n## Author\n\n- [Naokazu Terada](https://github.com/naokazuterada)\n\n## References\n\n- [Daring Fireballs Markdown Syntax Specification][Markdown]\n- [Sublime Text][SublimeText]\n- [Sublime Text: Package Control][PackageControl]\n- [Emoji cheatsheet][emoji]\n- [GitHub Flavored Markdown][Github]\n- [Markdown Preview][MarkdownPreview]\n\n### Markdown Table of Contents Generators\n\nHere follows a list of other Markdown Table of Contents generators, for inspiration and perhaps even use in the situation where the **MarkdownTOC** Sublime Text plugin is _not the right tool for the job_. Please note that the list is by no means authoritative or exhaustive and is not a list of recommendations, since we can only endorse **MarkdownTOC** our contribution to the Markdown Table of Content generators toolbox.\n\n- [doctoc](https://github.com/thlorenz/doctoc) Node (npm) implementation with CLI interface\n- [markdown-toclify](https://github.com/rasbt/markdown-toclify) Python implementation with CLI interface\n\n### Recommended plugins for use with MarkdownTOC\n\n- [Markdown Numbered Headers](https://packagecontrol.io/packages/Markdown%20Numbered%20Headers) Sublime Text 3 plugin for Markdown, auto insert/update/remove header numbers\n\n[Markdown]: http://daringfireball.net/projects/markdown/syntax\n[MarkdownLinks]: http://daringfireball.net/projects/markdown/syntax#link\n[SublimeText]: http://www.sublimetext.com/\n[SublimeTextSettings]: https://docs.sublimetext.info/en/latest/customization/settings.html\n[PackageControl]: http://wbond.net/sublime_packages/package_control\n[emoji]: http://www.emoji-cheat-sheet.com/\n[Github]: https://help.github.com/articles/basic-writing-and-formatting-syntax/\n[MarkdownPreview]: https://packagecontrol.io/packages/Markdown%20Preview\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaokazuterada%2FMarkdownTOC","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnaokazuterada%2FMarkdownTOC","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaokazuterada%2FMarkdownTOC/lists"}