Section table of contents (::section-toc)

↑ Docs content model

The ::section-toc directive displays an inline table of contents built from the current page's Markdown headings.

When to use

Use ::section-toc to give readers an in-page jump list of a section's subheadings. Use Docs table of contents instead when you want a TOC of other pages rather than the current page's headings.

Technical details

Markdown

::section-toc

::section-toc[<optional-title>]

::section-toc[<optional-title>]{depth=<optional-depth>}

The displayed table of contents (TOC) is based on the hierarchy of Markdown headings within the current section. Customize it with these options:

• Specifying a title in square brackets displays that title above the TOC.
• Specifying a depth caps the nesting depth of headings included (for example, with depth=1 inside a # heading's section, only a flat list of that section's ## headings is included).

Rules

• The title and depth options are both optional.
• The TOC reflects only headings within the current section, so a heading outside that section's scope is not included.

Style

• Add a section TOC only on long pages where readers benefit from jumping between subsections; short pages don't need one.

Template

Markdown

::section-toc[Optional title]{depth=2}

Examples

Example:

Markdown

## Section 2

::section-toc

::section-toc[Table of Contents]

::section-toc[Shallow Table of Contents]{depth=1}

### Section 2.1

#### Section 2.1.1

### Section 2.2

#### Section 2.2.1

#### Section 2.2.2

## Section 3

Output:

Section 2

• Section 2.1
  • Section 2.1.1
• Section 2.2
  • Section 2.2.1
  • Section 2.2.2

Table of Contents

• Section 2.1
  • Section 2.1.1
• Section 2.2
  • Section 2.2.1
  • Section 2.2.2

Shallow Table of Contents

• Section 2.1
• Section 2.2

Section 2.1

Section 2.1.1

Section 2.2

Section 2.2.1

Section 2.2.2

Section 3

Used in

Content atoms appear in any page section. A section TOC is most useful near the top of a long Concept or reference page.