Sublime Text 3 plugin for generating a Table of Contents (TOC) in a Markdown document.
Note: v3.0.0 has breaking changes. See Upgrade Guide for more detail.
Now you can go on and edit your document further or you can customize you TOC, please read on.
The 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.
When you have completed the installation of the plugin, you can insert an automatically generated TOC based on your Markdown headings. See the Quick Start to get going or the Usage section for details on how to utilize customization and configuration.
For the following sample Markdown document:
# Heading 0
Headings before MarkdownTOC tags will be ignored.
◀ place the cursor here and generate the TOC
# Heading 1
Lorem ipsum...
## Heading 2
Lorem ipsum...
The MarkdownTOC plugin will out of the box generate:
# Heading 0
Headings before MarkdownTOC tags will be ignored.
<!-- MarkdownTOC -->
- Heading 1
- Heading 2
<!-- /MarkdownTOC -->
# Heading 1
Lorem ipsum...
## Heading 2
Lorem ipsum...
As you can read from the sample above:
MarkdownTOC
tag section are ignored, only the rest of the document is considered in scopeIf we edit the Markdown document some more and add an additional heading:
## Heading 3
When we save the document, the TOC is automatically updated.
<!-- MarkdownTOC -->
- Heading 1
- Heading 2
- Heading 3
<!-- /MarkdownTOC -->
# Heading 1
Lorem ipsum...
## Heading 2
Lorem ipsum...
## Heading 3
Lorem ipsum... (the added text)
Same goes for deleted headings, these are cleared out.
Updating the TOC can also be accomplished without saving by picking from the menu: Tools > MarkdownTOC > Update TOC
Make sure your file's extension is in the following list.
.md
.markdown
.mdown
.mdwn
.mkdn
.mkd
.mark
<!-- MarkdownTOC autolink="true" -->
- [Heading 1](#heading-1)
- [Heading 2](#heading-2)
- [Heading 3](#heading-3)
<!-- /MarkdownTOC -->
# Heading 1
Lorem ipsum...
## Heading 2
Lorem ipsum...
## Heading 3
Lorem ipsum... (the added text)
The default behaviour could also be described as:
<!-- MarkdownTOC levels="1,2,3,4,5,6" autolink="false" bracket="round" autoanchor="false" style="unordered" indent="\t" -->
Please see: Github Configuration for a guideline to configuring MarkdownTOC for Github use.
You can add an HTML anchor (<a name="xxx"></a>
) before your heading automatically.
# Heading with anchor [with-anchor]
The TOC generation can be specified to respect this and a TOC element of the following format is generated:
- [Heading with anchor](#with-anchor)
Please note that the default for the attribute: autoanchor is false
.You can add an HTML anchor (<a name="xxx"></a>
) before the heading automatically.
<!-- MarkdownTOC autolink="true" autoanchor="true" -->
- [Changelog](#changelog)
- [Glossary](#glossary)
- [API Specification](#api-specification)
<!-- /MarkdownTOC -->
<a name="changelog"></a>
# Changelog
Lorem ipsum...
<a name="glossary"></a>
# Glossary
Lorem ipsum...
<a name="api-specification"></a>
# API Specification
Lorem ipsum...
Please note that the default for autolink is false
defined by the attribute defaults.autoanchor
. See also: How to remove anchors added by MarkdownTOC.
The plugin can be specified to auto link heading so you get a TOC with clickable hyperlink elements.
The following sample document:
# Heading 1
Lorem ipsum...
## Heading 2
Lorem ipsum...
## Heading 3
Lorem ipsum...
With autolink
set to true
will render the following:
<!-- MarkdownTOC autolink="true" -->
- [Heading 1](#heading-1)
- [Heading 2](#heading-2)
- [Heading 3](#heading-3)
- [Heading 4](#heading-4)
- [Heading with anchor](#with-anchor)
<!-- /MarkdownTOC -->
The auto link markup style can be one of:
round
, the default, the style supported on Githubsquare
, the "Markdown standard reference-style links" style.Please note that the default for autolink is false
defined by the attribute defaults.autolink
.
<!-- MarkdownTOC autolink="false" -->
- MarkdownTOC Plugin for Sublime Text
- Feature
- Feature
- Feature
<!-- /MarkdownTOC -->
<!-- MarkdownTOC autolink="true" -->
- [MarkdownTOC Plugin for Sublime Text](#markdowntoc-plugin-for-sublime-text)
- [Feature](#feature)
- [Feature](#feature-1)
- [Feature](#feature-2)
<!-- /MarkdownTOC -->
round: according to Github style.
<!-- MarkdownTOC bracket="round" -->
- [Heading](#heading)
<!-- /MarkdownTOC -->
square: according to "Markdown standard reference-style links".
<!-- MarkdownTOC bracket="square" -->
- [Heading][heading]
<!-- /MarkdownTOC -->
Please note that the default for bracket is round
defined by the attribute defaults.bracket
.
By default the plugin lowercases ASCII based alphabets only (a
to z
) for auto links.
<!-- MarkdownTOC autolink="true" -->
- [ПРИМЕР EXAMPLE][ПРИМЕР-example]
<!-- /MarkdownTOC -->
# ПРИМЕР EXAMPLE
This is same as setting lowercase
attribute to only_ascii
.
<!-- MarkdownTOC autolink="true" lowercase="only_ascii" -->
- [ПРИМЕР EXAMPLE][ПРИМЕР-example]
<!-- /MarkdownTOC -->
# ПРИМЕР EXAMPLE
You can disable the lowercasing capability by setting the lowecase
attribute to false
.
<!-- MarkdownTOC autolink="true" lowercase="false" -->
- [One Two Three][One-Two-Three]
<!-- /MarkdownTOC -->
# One Two Three
Further more you can also expand the lowercasing capability by setting the lowercase
attribute to all
(or any values other than false
and only_ascii
).
<!-- MarkdownTOC autolink="true" lowercase="all" -->
- [ПРИМЕР EXAMPLE][пример-example]
<!-- /MarkdownTOC -->
# ПРИМЕР EXAMPLE
You can also specify this in your configuration with key defaults.lowercase
.
You can manipulate your link ids in your configuration using the key id_replacements
.
{
"id_replacements": [
{
"pattern": "\\s+",
"replacement": "-"
},
{
"pattern": "!|#|$|&|'|\\(|\\)|\\*|\\+|,|/|:|;|=|_|\\?|@|\\[|\\]|`|\"|\\.|<|>|{|}|™|®|©|<|>|&|'|"|<|>|&|'|"",
"replacement": ""
}
]
}
re.sub(pattern, replacement, id)
An example:
# Super Product™
This heading link of this heading is changed to following id
#super-product
' '
(space) is replaced with -
(dash), since ' '
is included in the first setBy default non-ASCII characters in link ids are URL encoded.
<!-- MarkdownTOC autolink="true" -->
- [Ejemplos de español](#ejemplos-de-espa%C3%B1ol)
- [日本語の例](#%E6%97%A5%E6%9C%AC%E8%AA%9E%E3%81%AE%E4%BE%8B)
- [Примеры русского](#%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)
- [中国的例子](#%E4%B8%AD%E5%9B%BD%E7%9A%84%E4%BE%8B%E5%AD%90)
<!-- /MarkdownTOC -->
# Ejemplos de español
# 日本語の例
# Примеры русского
# 中国的例子
As mentioned you can disable this by setting the uri_encoding
attribute to false
, like so: uri_encoding="false"
.
<!-- MarkdownTOC autolink="true" uri_encoding="false" -->
- [Ejemplos de español](#ejemplos-de-español)
- [日本語の例](#日本語の例)
- [Примеры русского](#Примеры-русского)
- [中国的例子](#中国的例子)
<!-- /MarkdownTOC -->
# Ejemplos de español
# 日本語の例
# Примеры русского
# 中国的例子
If you want to use MarkdownTOC with Markdown Preview, you should use markdown_preview
attribute.
You can set this attribute to either markdown
or github
.
When you set it to markdown
, you can get same links rendered by MarkdownPreview's markdown parser.
<!-- MarkdownTOC autolink="true" markdown_preview="markdown" -->
- [Hello 世界 World](#hello-world)
- [ESPAÑA](#espana)
- [ПРИМЕР RUSSIAN](#russian)
<!-- /MarkdownTOC -->
# Hello 世界 World
# ESPAÑA
# ПРИМЕР RUSSIAN
When you set it to github
, you can get same links rendered by MarkdownPreview's github parser.
<!-- MarkdownTOC autolink="true" markdown_preview="github" -->
- [Hello 世界 World](#hello-%25E4%25B8%2596%25E7%2595%258C-world)
- [ESPAÑA](#espa%25C3%25B1a)
- [ПРИМЕР RUSSIAN](#%25D0%25BF%25D1%2580%25D0%25B8%25D0%25BC%25D0%25B5%25D1%2580-russian)
<!-- /MarkdownTOC -->
# Hello 世界 World
# ESPAÑA
# ПРИМЕР RUSSIAN
Currently no other parsers are supported.
If you want to disable this feature, set it to false
.
You can also set prefix of links.
<!-- MarkdownTOC autolink=true link_prefix="user-content-" -->
- [My Heading](#user-content-my-heading)
<!-- /MarkdownTOC -->
# My Heading
You can manipulate this in your configuration using the key defaults.link_prefix
.
# Heading 1
Lorem ipsum...
## Heading 2
Lorem ipsum...
### Heading 3
Lorem ipsum...
#### Heading 4
Lorem ipsum...
With default levels:
<!-- MarkdownTOC -->
- Heading 1
- Heading 2
- Heading 3
- Heading 4
<!-- /MarkdownTOC -->
With levels set to 1,2:
<!-- MarkdownTOC levels="1,2" -->
- Heading 1
- Heading 2
<!-- /MarkdownTOC -->
Please note that the default for the attribute levels is "1,2,3,4,5,6"
, it means all heading sizes will be included.
You can also specify this in your configuration with key defaults.levels
.
The maximum size for headings is 6
according to the Markdown specification
The plugin supports two styles of TOC element listing:
unordered
ordered
A Markdown document with the following contents:
# Heading 1
Lorem ipsum...
## Heading 2
Lorem ipsum...
### Heading 3
Lorem ipsum...
### Heading 4
Lorem ipsum...
## Heading 5
Lorem ipsum...
# Heading 6
Lorem ipsum...
Will with style unordered
:
<!-- MarkdownTOC style="unordered" -->
- Heading 1
- Heading 2
- Heading 3
- Heading 4
- Heading 5
- Heading 6
<!-- /MarkdownTOC -->
And with style ordered
:
<!-- MarkdownTOC style="ordered" -->
1. Heading 1
1. Heading 2
1. Heading 3
1. Heading 4
1. Heading 5
1. Heading 6
<!-- /MarkdownTOC -->
Please note that the default for the attribute is: unordered
.
You can set your default style in your configuration with the key defaults.style
.
You 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.
<!-- MarkdownTOC bullets="-,+,*" -->
- foo
+ bar
* baz
- foo
+ bar
* baz
<!-- /MarkdownTOC -->
You can set default list bullets in your configuration with the key defaults.bullets
.
The example above could also be described as:
{
"defaults": {
"bullets": ["-","+","*"]
}
}
You can also set it in attribute. In this case the values type is 'conmma separated string'.
<!-- MarkdownTOC bullets="-,+,*" -->
The indentation prefix is a specification of the string used to indent the TOC elements.
An ugly but demonstrative example could be to use an emoji.
<!-- MarkdownTOC autolink="true" indent=":point_right: " -->
- [Heading 1](#heading-1)
:point_right: - [Heading 2](#heading-2)
:point_right: :point_right: - [Heading 3](#heading-3)
:point_right: :point_right: - [Heading 4](#heading-4)
:point_right: - [Heading 5](#heading-5)
- [Heading 6](#heading-6)
<!-- /MarkdownTOC -->
Please note that the default for the attribute is: '\t'
.
You can set your default indentation in your configuration with the key defaults.indent
.
If you want to preserve images in headings, set remove_image
to false
.
<!-- MarkdownTOC remove_image="false" -->
- ![check](check.png) Everything is OK
<!-- /MarkdownTOC -->
# ![check](check.png) Everything is OK
Please note that the default for the attribute is: false
.
<!-- MarkdownTOC -->
- Everything is OK
<!-- /MarkdownTOC -->
# ![check](check.png) Everything is OK
You can change your default setting in your configuration with the key defaults.remove_image
.
You can exclude certain headings in the TOC by adding a special comment to the line above the line with the heading, as shown below.
<!-- MarkdownTOC:excluded -->
## This heading will be excluded
Don't remove the comment tags if you want to update every time saving.
If 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).
autoanchor
to false
, this clears all anchors<!-- MarkdownTOC autoanchor="false" -->
Please see the below animation demonstrating the change
<!-- MarkdownTOC autoanchor="false" -->
...
<!-- /MarkdownTOC -->
Ref: Github issue #76
If you are using Github Pages you might experience that some themes do not render heading correctly.
This can be addressed simply by setting autoanchor
to false
<!-- MarkdownTOC autoanchor="false" -->
And when Jekyll is done, your headings should render correctly.
Ref: Github issue #81
If you are using Markdownlint (Node implementation), it will report several violations out of the box.
The basic configuration you can use to address these looks like the following:
{
"html": false,
"blanks-around-headings": false,
"ul-indent": {
"indent": 4
}
}
html
set to false
, to allow use of HTML since MarkdownTOC relies on HTML tags to assist the Markdownblanks-around-headings
should be set to false
, since anchors are places closed to the headings that are listed in the TOCul-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
If you have configured MarkdownTOC differently, you can adjust your Markdownlint configuration accordingly.
Do note that this tip is based on the Node implementation, available on GitHub, which uses a project specific .markdownlint.json
based configuration.
MarkdownTOC does come with some limitations.
For more information on compatibility, please see the dedicated section.
Example of Markdown heading in a Markdown listing, not being included in the auto-generated Table of Contents
- # this is a heading
The following attributes can be used to control the generation of the TOC.
attribute | values | default |
---|---|---|
autoanchor |
true orfalse |
false |
autolink |
true orfalse |
false |
bracket |
"round" or"square" |
"round" |
indent |
string | "\t" |
levels |
string (decimal list separated with , ) |
"1,2,3,4,5,6" |
link_prefix |
string | "" |
bullets |
string | "-" |
lowercase |
"all" or"only_ascii" or"false" |
"only_ascii" |
remove_image |
true orfalse |
true |
style |
"ordered" or "unordered" |
"unordered" |
uri_encoding |
true orfalse |
true |
markdown_preview |
"" or"github" or"markdown" |
"" |
You can define your own default values via package preferences, Sublime Text's way of letting users customize package settings. Please see the Section on Configuration for more details for MarkdownTOC.
MarkdownTOC
plugin.git clone git@github.com:naokazuterada/MarkdownTOC.git ~/Library/Application\ Support/Sublime\ Text\ 3/Packages/MarkdownTOC
Packages/
directory (pick menu: Sublime Text > Preferences > Browse Packages).MarkdownTOC/
directory into the Packages/
directory.You can use 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.
Pick: Sublime Text > Preferences > Package Settings > MarkdownTOC > Settings - User
Alternatively you can create the file ~/Library/Application Support/Sublime Text 3/Packages/User/MarkdownTOC.sublime-settings
by hand.
Example: MarkdownTOC.sublime-settings
{
"defaults": {
"autolink": true,
"bracket": "square",
"levels": "1,2",
"indent": " ",
"remove_image": false,
"bullets": "*",
"style": "ordered"
},
"id_replacements": [
{
"pattern": "\\s+",
"replacement": "-"
},
{
"pattern": "<|>|&|'|"|<|>|&|'|"|!|#|$|&|'|\\(|\\)|\\*|\\+|,|/|:|;|=|_|\\?|@|\\[|\\]|`|\"|\\.|<|>|{|}|™|®|©",
"replacement": ""
}
]
}
Please see the section on attributes for an overview of values and the section on customization.
Configuration precendence is as follows:
For an overview of the specific behaviour behind an attribute, please refer to the below list.
defaults.autolink
, (see: Auto linking for clickable TOC)defaults.autoanchor
, (see: Auto anchoring when heading has anchor defined)defaults.bracket
, (see: Auto linking for clickable TOC)defaults.indent
, (see: Specify custom indentation prefix)defaults.link_prefix
, (see: Link Prefix)defaults.levels
, (see: Control of levels listed in TOC)defaults.bullets
, (see: Customizable list bullets in TOC)defaults.lowercase
, (see: Lowercasing in ids)defaults.remove_image
, (see: Preserve images in headings)defaults.style
, (see: Ordered or unordered style for TOC elements)defaults.uri_encoding
, (see: URI encoding)defaults.markdown_preview
, (see: Markdown Preview compatible)id_replacements
, (see: Manipulation of auto link ids)A configuration for writing Markdown primaily for use on Github could look like the following:
{
"defaults": {
"autolink": true,
"bracket": "round",
"lowercase": "only_ascii"
}
}
You 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.
If that is the case and you cannot agree on a configuration, choose configuration using attributes specified in the document instead.
Example of attribute configuration for the above configuration settings in file:
<!-- MarkdownTOC autolink="true" bracket="round" autoanchor="true" -->
This 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.
Application | Compatibility |
---|---|
Github | Compatible |
Gitblit 1.6.x | Incompatible |
Gitlab 8.10.x | Compatible |
BitBucket 5.12.2 | Incompatible |
Contributions are most welcome, please see the guidelines on contributing.
Here 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.