Table of Contents Extension

Vladimir Schneider edited this page Mar 12, 2018 · 1 revision

Table of contents for your document can be generated for standard markdown parsers that do not support a table of contents element.

The table of contents tag was chosen to appear as an unused reference definition that will not render on plain vanilla markdown processors. Markdown Navigator automatically updates the lines after the tag when you format the element or document with Update TOC option enabled in Code Style > Markdown.

  • :warning: Some parsers require a blank line above the first list item. For maximum compatibility enable the Generate blank line spacer option in parser settings.

    If you have any list items following the table of contents that match the list style of the table of contents, then other parsers will include them in the table of contents list. To prevent the merging of table of contents generated list with a list following the TOC add an HTML block comment after the TOC.

Enabling Table Of Contents

Enable Table of Contents in Languages & Frameworks > Markdown > Parser.

Screenshot Parser TOC

In Code Style > Markdown in the Table of Contents section you can choose among the following default options to use unless it is given in the [TOC]:# element text.

TOC Format Options

The TOC options are available in code style settings and in the Edit Table of Contents options intention. The latter will show a preview of your TOC element with heading from the same file and will allow you to copy the options you select to project code style settings. It is probably the most comfortable way to configure your TOC settings and TOC markdown elements.

Refactoring Screen Shot Edit TOC Options

  • On format document or element: do not change, update, remove generated toc text.
  • On save document: format or no action.
  • Markdown or HTML versions.
  • to use only the heading text or include inline formatting
  • use bullet or number lists.
  • generate hierarchical table of contents or flat, reversed sorted.

The TOC tag has the following format: [TOC style]: # "Title"

  1. style consists of space separated list of options:

    • levels=levelList where level list is a comma separated list of levels or ranges. Default is to include heading levels 2 and 3. Examples:

      • levels=4 include levels 2,3 and 4
      • levels=2-4 include levels 2,3 and 4. same as levels=4
      • levels=2-4,5 include levels 2,3,4 and 5
      • levels=1,3 include levels 1 and 3
    • html generate HTML version of the TOC

    • markdown generate Markdown version of the TOC

    • text to only include the text of the heading

    • formatted to include text and inline formatting

    • bullet to use a bullet list for the TOC items

    • numbered to use a numbered list for TOC items

    • numbered to use a numbered list for TOC items

    • hierarchy hierarchical list of headings

    • flat flat list of headings

    • reversed flat reversed list of headings

    • increasing flat, alphabetically increasing by heading text

    • decreasing flat, alphabetically decreasing by heading text

  2. "Title" specifies the text for the table of contents heading. If omitted or blank then no heading will be generated for the table of contents. # prefix in the title will specify the header level to use for the heading above the table of contents listing. If no # prefix is used then the heading level will be taken from project settings.

The lines after the [TOC]: # tag are updated to reflect the content of the document.

Assuming these headers in the document the table of contents will have the following content:

# Heading **some bold** 1
## Heading 1.1 _some italic_
### Heading 1.1.1
### Heading 1.1.2  **_some bold italic_**
# Heading 2
### Heading 2.0.1

Markdown version:

[TOC levels=1-3]: # "#### Table of Contents"
#### Table of Contents
- [Heading **some bold** 1](#heading-some-bold-1)
    - [Heading 1.1 _some italic_](#heading-11-some-italic)
        - [Heading 1.1.1](#heading-111)
        - [Heading 1.1.2  **_some bold italic_**](#heading-112--some-bold-italic)
- [Heading 2](#heading-2)
    - [Heading 2.0.1](#heading-201)

Table of Contents

HTML version:

[TOC levels=1-3]: # "#### Table of Contents"
<div><h4>Table of Contents</h4>
    <li><a href="#heading-some-bold-1">Heading some bold 1</a>
      <li><a href="#heading-111">Heading 1.1.1</a></li>
      <li><a href="#heading-112--some-bold-italic">Heading 1.1.2  some bold italic</a>
    <li><a href="#heading-2">Heading 2</a>
      <li><a href="#heading-201">Heading 2.0.1</a></li>
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.