开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

MarkdownTOC

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.

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 anchoring when heading has anchor defined
• Auto linking for clickable TOC
  • Lowercasing in ids
    • Preserve case
    • Lowercase all characters
  • Manipulation of auto link ids
  • URI encoding
  • Markdown Preview compatible
  • Link Prefix
• Control of levels listed in TOC
• Ordered or unordered style for TOC elements
• Customizable list bullets in TOC
• Specify custom indentation prefix
• Preserve images in headings
• Excluded headings

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:

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

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:

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

Supported file extensions

Make sure your file's extension is in the following list.

.md .markdown .mdown .mdwn .mkdn .mkd .mark

Customizing generation of TOC using attributes

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

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

Auto anchoring when heading has anchor defined

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.

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:

# 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 Github
• square, 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.

Lowercasing in ids

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

Preserve case

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

Lowercase all characters

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.

Manipulation of auto link ids

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

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

1. Regular expression is allowed in each sets
   • It will be simply expanded into python's re.sub(pattern, replacement, id)
2. The replacement sequence executes from top to bottom

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

URI encoding

By 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
# 日本語の例
# Примеры русского
# 中国的例子

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.

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

Link Prefix

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.

Control of levels listed in TOC

# 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

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:

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

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.

<!-- 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="-,+,*" -->

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.

<!-- 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 k