Sublime Text plugin for generating a Table of Contents (TOC) in a Markdown document.

Linux & OSX	Windows

• Quick Start
• Features
  • Insertion of TOC based on headings in Markdown document
  • Automatic refresh of TOC when Markdown document is saved
  • Customizing generation of TOC using attributes
  • Auto anchoring when heading has anchor defined
  • Auto linking for clickable TOC
    • Lowercase only ASCII characters in auto link ids
    • Manipulation of auto link ids
  • Control of depth listed in TOC
  • Ordered or unordered style for TOC elements
  • Specify custom indentation prefix
• Usage
• Attributes
• Installation
  • Using Package Control
  • From Git
  • From downloadable archive
• Configuration
  • Github Configuration
  • Configuration and Collaboration
• Contributing
• License
• Author
• References

1. Install the MarkdownTOC plugin
2. Open your Markdown file
3. Place the cursor at the position where you want to insert the TOC
4. Pick from menu: Tools > MarkdownTOC > Insert TOC
5. And the TOC is inserted in the Markdown document
6. Save the document and you are done

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.

• Insertion of TOC based on headings in Markdown document
• Automatic refresh of TOC when Markdown document is saved
• Customizing generation of TOC using attributes
• Auto link when heading has anchor defined
• Auto linking for clickable TOC
• Manipulation of auto link ids
• Control of depth listed in TOC
• Ordered or unordered style for TOC elements
• Specify custom indentation prefix

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.

:point_left: place the cursor here and generate the TOC

# Heading 1
Lorem ipsum...

## Heading 2
Lorem ipsum...

## Heading 3
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]
  - [Heading 3]

<!-- /MarkdownTOC -->

# Heading 1
Lorem ipsum...

## Heading 2
Lorem ipsum...

## Heading 3
Lorem ipsum...

As you can read from the sample above:

1. Headings above the MarkdownTOC tag section are ignored, only the rest of the document is considered in scope

If we edit the Markdown document some more and add an additional heading:

## Heading 4

When we save the document, the TOC is automatically updated.

<!-- MarkdownTOC -->

- [Heading 1]
  - [Heading 2]
  - [Heading 3]
  - [Heading 4]
- [Heading with anchor](#with-anchor)

<!-- /MarkdownTOC -->

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

<!-- MarkdownTOC style="round" autolink="true" -->

- [Heading 1]
  - [Heading 2]
  - [Heading 3]
  - [Heading 4]
- [Heading with anchor](#with-anchor)

<!-- /MarkdownTOC -->

1. TOC tags can overwrite default attributes using local settings and influence the rendering of the TOC. See: Configuration on how to set your own defaults for the plugin
2. Headings can be automatically linked (see: auto link)
3. Headings can have anchors automatically linked (see: Auto anchoring when heading has anchor defined)

The default behaviour could also be described as:

<!-- MarkdownTOC depth="2" autolink="false" bracket="square" 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" bracket="round" -->

- [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 default_autoanchor.

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" bracket="round" -->

- [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:

• square, the default
• round, the style supported on Github

Please note that the default for autolink is false defined by the attribute default_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 -->

square: according to "Markdown standard reference-style links".

<!-- MarkdownTOC bracket="square" -->

- [Heading][heading]

<!-- /MarkdownTOC -->

round: according to Github style.

<!-- MarkdownTOC bracket="round" -->

- [Heading](#heading)

<!-- /MarkdownTOC -->

Please note that the default for bracket is square defined by the attribute default_bracket.

The plugin lowercase all alphabets within auto link ids default.

<!-- MarkdownTOC autolink=true -->

- [ПРИМЕР EXAMPLE][пример-example]

<!-- /MarkdownTOC -->

# ПРИМЕР EXAMPLE

But you can also squeeze its target only ascii alphabets(a to z) with lowercase_only_ascii=true attribute.

<!-- MarkdownTOC autolink=true lowercase_only_ascii=true -->

- [ПРИМЕР EXAMPLE][ПРИМЕР-example]

<!-- /MarkdownTOC -->

# ПРИМЕР EXAMPLE

You can manipulate your link ids in your configuration using the key id_replacements.

{
  "id_replacements": {
    "-": " ",
    "" : ["&lt;","&gt;","&amp;","&apos;","&quot;","&#60;","&#62;","&#38;","&#39;","&#34;","!","#","$","&","'","(",")","*","+",",","/",":",";","=","?","@","[","]","`","\"", ".","<",">","{","}","™","®","©"]
  }
}

1. The set specified as values string(s) will be replaced with the key string.
2. The replacement sequence executes from top to bottom and left to right

An example:

# Super Product™

This heading link of this heading is changed to following id

#super-product

• The ' ' (space) is replaced with - (dash), since ' ' is included in the first set
• The '™' is replaced with nothing, since '™' is included in the second set

# Heading 1

Lorem ipsum...

## Heading 2

Lorem ipsum...

### Heading 3

Lorem ipsum...

#### Heading 2

With default depth:

<!-- MarkdownTOC -->

- [Heading 1]
  - [Heading 2]

<!-- /MarkdownTOC -->

With depth set to 4:

<!-- MarkdownTOC depth="4" -->

- [Heading 1]
  - [Heading 2]
    - [Heading 3]
      - [Heading 4]

<!-- /MarkdownTOC -->

Please note that the default for the attribute depth is 2. Specifying 0 means indefinite and means all heading sizes will be included.

You can also specify this in your configuration with key default_depth.

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

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" bracket="round" 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 default_indent.

1. Open your Markdown file
2. Set cursor to position where you want to insert a TOC
3. Pick from menu: Tools > MarkdownTOC > Insert TOC
4. TOC is inserted in document
5. Evaluate your TOC and customize using attributes or configuration
6. Update contents and save...
7. TOC has been updated

Don't remove the comment tags if you want to update every time saving.

The following attributes can be used to control the generation of the TOC.

You can define your own default values via package preferences, Sublime Texts way of letting users customize package settings. Please see the Section on Configuration for more details for MarkdownTOC.

1. Run “Package Control: Install Package” command, find and install MarkdownTOC plugin.
2. Restart Sublime Text

Package Control

git clone git@github.com:naokazuterada/MarkdownTOC.git ~/Library/Application\ Support/Sublime\ Text\ 3/Packages/MarkdownTOC

1. Download zip-file and unpack it.
2. Open the Sublime Text Packages/ directory (pick menu: Sublime Text > Preferences > Browse Packages).
3. Move the 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

{
  "default_autoanchor": false,
  "default_autolink": false,
  "default_bracket": "square",
  "default_depth": 2,
  "default_indent": "\t",
  "default_lowercase_only_ascii": false,
  "default_style": "unordered",
  "id_replacements": {
    "-": " ",
    "" : ["&lt;","&gt;","&amp;","&apos;","&quot;","&#60;","&#62;","&#38;","&#39;","&#34;","!","#","$","&","'","(",")","*","+",",","/",":",";","=","?","@","[","]","`","\"", ".","<",">","{","}","™","®","©"]
  }
}

Please see the section on attributes for an overview of values and the section on customization.

Configuration precendence is as follows:

1. Attributes specified in MarkdownTOC begin tag (see: Customizing generation of TOC using attributes)
2. MarkdownTOC Settings - user (this section)
3. MarkdownTOC Settings - default (see: Attributes)

For an overview of the specific behaviour behind an attribute, please refer to the below list.

• default_autolink, (see: Auto linking for clickable TOC)
• default_autoanchor, (see: Auto anchoring when heading has anchor defined)
• default_bracket, (see: Auto linking for clickable TOC)
• default_depth, (see: Control of depth listed in TOC)
• default_indent, (see: Specify custom indentation prefix)
• default_lowercase_only_ascii, (see: Lowercase only ASCII characters in anchor)
• default_style, (see: Ordered or unordered style for TOC elements)
• id_replacements, (see: Manipulation of auto link ids)

A configuration for writing Markdown primaily for use on Github could look like the following:

{
  "default_autolink": true,
  "default_bracket": "round",
  "default_lowercase_only_ascii": true
}

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" -->

Contributions are most welcome, please see the guidelines on contributing.

• MarkdownTOC is licensed under the MIT License

• Naokazu Terada

• Daring Fireballs Markdown Syntax Specification
• Sublime Text
• Sublime Text: Package Control
• Emoji cheatsheet
• Github flavoured markdown