Working with TOC.md files

The TOC.md file determines the user guide content, structure, and appearance in the left navigation.

user guide structure

The TOC anchor IDs also plays a major role in the article URL. An article URL consists of the Git repo name, the article name, and the anchor IDs in the TOC.md file.

user guide path

Editing the TOC.md

User guide structure

  • Add appropriate metadata to the top of the TOC.md file. Metadata used at the top of the TOC.md is applied to every article in the user guide. See Metadata.
  • Add nested bullet items to create the user guide structure. Create section headings and child items as bullet items. A child item can be either an article link or another section heading.
  • For a file to be rendered, it must be included in the TOC.

User guide name that appears in header

Use the heading 1 title to specify the user guide name that appears in the help page header. Example:

# Adobe Target Help {#using} or # Analytics Admin Guide {#admin}

The anchor (such as {#using}) is used in URLs.

Section headings

Create an anchor ID for every section heading. A section heading cannot be a link. Keep in mind that section headings are part of the page URL. Keep them short. If you change anchor IDs, you’ll change the page URLs for all the content in that section. Example:

+ Target release notes {#release-notes}

Use standard Markdown link syntax to link to articles. In a TOC, each link should be a bullet item in the appropriate location. Example:

+ [Getting started overview](introduction/getting-started.md)

Changing the right nav levels

Use mini-toc-levels metadata to determine how many levels of headings are displayed in the right nav. The default number of levels is 2. You can specify 1-6 levels. See Metadata.

Notes and tips

  • If you want a file to be rendered on experienceleague.adobe.com, it must be in the TOC. However, if you don’t want that file to appear in the generated left nav, use hidefromtoc metadata. See Hiding files.

  • Use a consistent bullet style in the TOC.md style. Files were migrated with + symbols, so either stick with those or change everything to a different supported format such as * or -. Just don’t use multiple styles.

  • Create short names for article titles. For example, you can shorten:

    + [Introduction to Adobe Target](c-intro/intro.md)

    to

    + [Introduction](c-intro/intro.md)

On this page