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}

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}

Links to articles

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)

Notes and tips

  • If you want a file to be rendered on experienceleague.adobe.com, it must be in the TOC.

  • 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