ctrl+shift+p filters: :st2 :st3 :win :osx :linux
Browse

Markdown​TOC

by naokazuterada ST3

MarkdownTOC(Table Of Contents) Plugin for Sublime Text

Details

  • 2017.10.01.08.14.29
  • github.​com
  • github.​com
  • 2 months ago
  • Just now
  • 5 years ago

Installs

  • Total 18K
  • Win 8K
  • OS X 7K
  • Linux 3K
Nov 23 Nov 22 Nov 21 Nov 20 Nov 19 Nov 18 Nov 17 Nov 16 Nov 15 Nov 14 Nov 13 Nov 12 Nov 11 Nov 10 Nov 9 Nov 8 Nov 7 Nov 6 Nov 5 Nov 4 Nov 3 Nov 2 Nov 1 Oct 31 Oct 30 Oct 29 Oct 28 Oct 27 Oct 26 Oct 25 Oct 24 Oct 23 Oct 22 Oct 21 Oct 20 Oct 19 Oct 18 Oct 17 Oct 16 Oct 15 Oct 14 Oct 13 Oct 12 Oct 11 Oct 10 Oct 9
Windows 6 10 17 6 3 4 7 9 12 13 11 5 5 12 9 9 10 10 5 5 9 11 10 11 6 2 2 12 9 7 6 13 4 2 6 12 8 11 11 6 6 4 11 6 12 7
OS X 12 9 3 4 1 5 5 2 9 5 6 3 2 2 9 5 12 9 2 7 5 8 3 9 6 2 2 5 6 4 3 4 6 4 10 7 9 2 6 1 6 4 8 2 18 5
Linux 1 2 2 3 3 1 3 1 5 3 2 0 0 0 4 2 4 3 1 1 3 2 4 2 3 1 1 4 4 0 3 1 1 1 4 3 1 0 2 2 1 2 4 2 3 4

Readme

Source
raw.​githubusercontent.​com

MarkdownTOC Plugin for Sublime Text 3

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

Linux & macOS Windows Code Coverage
Linux and macOS Build Status Windows Build Status Coverage Status codecov

Table of Contents


Quick Start

  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.


Features

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
  • Customizable list bullets in TOC
  • Specify custom indentation prefix
  • Customizable link prefix

Insertion of TOC based on headings in Markdown document

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:

Error: language “markdown” is not supported
# 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:

Error: language “markdown” is not supported
# Heading 0

Headings before MarkdownTOC tags will be ignored.



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



# 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

Automatic refresh of TOC when Markdown document is saved

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

Error: language “markdown” is not supported
## Heading 4

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

Error: language “markdown” is not supported
- [Heading 1]
  - [Heading 2]
  - [Heading 3]
  - [Heading 4]
- [Heading with anchor](#with-anchor)

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

Customizing generation of TOC using attributes

Error: language “markdown” is not supported
- [Heading 1]
  - [Heading 2]
  - [Heading 3]
  - [Heading 4]
- [Heading with anchor](#with-anchor)
  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:

Error: language “markdown” is not supported

Please see: Github Configuration for a guideline to configuring MarkdownTOC for Github use.

Auto anchoring when heading has anchor defined

You can add an HTML anchor (<a name="xxx"></a>) before your heading automatically.

Error: language “markdown” is not supported
# Heading with anchor [with-anchor]

The TOC generation can be specified to respect this and a TOC element of the following format is generated:

Error: language “markdown” is not supported
- [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.

Error: language “markdown” is not supported
- [Changelog](#changelog)
- [Glossary](#glossary)
- [API Specification](#api-specification)



<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. See also: How to remove anchors added by MarkdownTOC.

Auto linking for clickable TOC

The plugin can be specified to auto link heading so you get a TOC with clickable hyperlink elements.

The following sample document:

Error: language “markdown” is not supported
# Heading 1
Lorem ipsum...

## Heading 2
Lorem ipsum...

## Heading 3
Lorem ipsum...

With autolink set to true will render the following:

Error: language “markdown” is not supported
- [Heading 1](#heading-1)
  - [Heading 2](#heading-2)
  - [Heading 3](#heading-3)
  - [Heading 4](#heading-4)
- [Heading with anchor](#with-anchor)

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.

Error: language “markdown” is not supported
- MarkdownTOC Plugin for Sublime Text
  - Feature
  - Feature
  - Feature
Error: language “markdown” is not supported
- [MarkdownTOC Plugin for Sublime Text](#markdowntoc-plugin-for-sublime-text)
  - [Feature](#feature)
  - [Feature](#feature-1)
  - [Feature](#feature-2)

square: according to “Markdown standard reference-style links”.

Error: language “markdown” is not supported
- [Heading][heading]

round: according to Github style.

Error: language “markdown” is not supported
- [Heading](#heading)

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

Lowercase only ASCII characters in auto link ids

By default the plugin lowercases ASCII based alphabets only (a to z) for auto links.

Error: language “markdown” is not supported
- [ПРИМЕР EXAMPLE][ПРИМЕР-example]



# ПРИМЕР EXAMPLE

You can expand the lowercasing capability by setting the lowecase_only_ascii attribute to false.

Error: language “markdown” is not supported
- [ПРИМЕР EXAMPLE][пример-example]



# ПРИМЕР EXAMPLE

Preserve case

You can disable the lowercasing capability by setting the lowecase attribute to false.

Error: language “markdown” is not supported
- [One Two Three][One-Two-Three]



# One Two Three

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

Manipulation of auto link ids

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:

Error: language “markdown” is not supported
# Super Product™

This heading link of this heading is changed to following id

Error: language “markdown” is not supported
#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

URI encoding

By default non-ASCII characters in link ids are URL encoded.

Error: language “markdown” is not supported
- [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]



# Ejemplos de español
# 日本語の例
# Примеры русского
# 中国的例子

As mentioned you can disable this by setting the uri_encoding attribute to false, like so: uri_encoding="false".

Error: language “markdown” is not supported
- [Ejemplos de español][ejemplos-de-español]
- [日本語の例][日本語の例]
- [Примеры русского][Примеры-русского]
- [中国的例子][中国的例子]



# Ejemplos de español
# 日本語の例
# Примеры русского
# 中国的例子

Markdown Preview compatible

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.

Error: language “markdown” is not supported
- [Hello 世界 World][hello-world]
- [ESPAÑA][espana]
- [ПРИМЕР RUSSIAN][russian]



# Hello 世界 World
# ESPAÑA
# ПРИМЕР RUSSIAN

When you set it to github, you can get same links rendered by MarkdownPreview's github parser.

Error: language “markdown” is not supported
- [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]



# Hello 世界 World
# ESPAÑA
# ПРИМЕР RUSSIAN

Currently no other parsers are supported.

If you want to disable this feature, set it to false.

Link Prefix

You can also set prefix of links.

Error: language “markdown” is not supported
- [My Heading][user-content-my-heading]



# My Heading

You can manipulate this in your configuration using the key default_link_prefix.

Control of depth listed in TOC

Error: language “markdown” is not supported
# Heading 1

Lorem ipsum...

## Heading 2

Lorem ipsum...

### Heading 3

Lorem ipsum...

#### Heading 2

With default depth:

Error: language “markdown” is not supported
- [Heading 1]
  - [Heading 2]

With depth set to 4:

Error: language “markdown” is not supported
- [Heading 1]
  - [Heading 2]
    - [Heading 3]
      - [Heading 4]

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

Ordered or unordered style for TOC elements

The plugin supports two styles of TOC element listing:

  • unordered
  • ordered

A Markdown document with the following contents:

Error: language “markdown” is not supported
# 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:

Error: language “markdown” is not supported
- Heading 1
  - Heading 2
    - Heading 3
    - Heading 4
  - Heading 5
- Heading 6

And with style ordered:

Error: language “markdown” is not supported
1. Heading 1
  1. Heading 2
    1. Heading 3
    1. Heading 4
  1. Heading 5
1. Heading 6

Please note that the default for the attribute is: unordered.

You can set your default style in your configuration with the key default_style.

Customizable list bullets in TOC

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.

Error: language “markdown” is not supported
- foo
  + bar
    * baz
      - foo
        + bar
          * baz

You can set default list bullets in your configuration with the key default_list_bullets.

The example above could also be described as:

{
  "default_list_bullets": "-+*"
}

And the value could also be array.

{
  "default_list_bullets": ["-","+","*"]
}

Specify custom indentation prefix

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.

Error: language “markdown” is not supported
- [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)

Please note that the default for the attribute is: '\t'.

You can set your default indentation in your configuration with the key default_indent.

Preserve images in headings

If you want to preserve images in headings, set remove_image to false.

Error: language “markdown” is not supported
- ![check](check.png) Everything is OK



# ![check](check.png) Everything is OK

Please note that the default for the attribute is: false.

Error: language “markdown” is not supported
- Everything is OK



# ![check](check.png) Everything is OK

You can change your default setting in your configuration with the key default_remove_image.

Usage

  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.

Tips

How to remove anchors added by MarkdownTOC

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

  1. Open your Markdown file
  2. Set the attribute autoanchor to false, this clears all anchors
Error: language “markdown” is not supported

Please see the below animation demonstrating the change

  1. Now delete the TOC section from beginning to end and **MarkdownTOC** integration is gone
Error: language “markdown” is not supported
...

Ref: Github issue #76

Addressing issues with Github Pages

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

Error: language “markdown” is not supported

And when Jekyll is done, your headings should render correctly.

Ref: Github issue #81

Limitations

MarkdownTOC does come with some limitations.

For more information on compatibility, please see the dedicated section.

Headings in lists are not included in the auto-generated table of contents

Example of Markdown heading in a Markdown listing, not being included in the auto-generated Table of Contents

Error: language “markdown” is not supported
- # this is a heading

Attributes

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

attribute values default key in configuration/settings
autoanchor trueorfalse false default_autoanchor
autolink trueorfalse false default_autolink
bracket squareorround "square" default_bracket
depth integer (0 means no limit) 2 default_depth
indent string "\t" default_indent
link_prefix string "" default_link_prefix
list_bullets string "-" default_list_bullets
lowercase trueorfalse true default_lowercase
lowercase_only_ascii trueorfalse true default_lowercase_only_ascii
remove_image trueorfalse true default_remove_image
style ordered or unordered unordered default_style
uri_encoding trueorfalse true default_uri_encoding
markdown_preview falseorgithubormarkdown false default_markdown_preview

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.

Installation

Using Package Control

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

Package Control

From Git

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

From downloadable archive

  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.

Configuration

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_link_prefix": "",
  "default_list_bullets": "-",
  "default_lowercase": true,
  "default_lowercase_only_ascii": true,
  "default_remove_image": true,
  "default_style": "unordered",
  "default_uri_encoding": true,
  "default_markdown_preview": false,
  "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.

Github Configuration

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

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

Configuration and Collaboration

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:

Error: language “markdown” is not supported

Compatibility

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

Contributing

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

License

Author

References

Markdown Table of Contents Generators

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.

  • doctoc Node (npm) implementation with CLI interface
  • markdown-toclify Python implementation with CLI interface

Recommended plugins for use with MarkdownTOC