Working with TOC.md files

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

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.

Editing the TOC.md

User guide structure

• Add appropriate metadata to the top of the TOC.md file. See the next section about using metadata in the TOC.md file.
• 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.

Metadata in the TOC.md file

The TOC.md isn’t rendered as a web page, so metadata you specify doesn’t affect SEO (search-engine optimization). However, metadata you add to the TOC is useful in two ways:

• Add user-guide-description for the landing pages to pick up when the guide is referenced in one or more landing pages. Note that user-guide-title isn’t necessary; the Head 1 title text is used (see next). You can also use breadcrumb-title in the TOC to specify a shorter breadcrumb title.
• Add metadata such as role: Admin or level: Beginner to use as the default for all articles in the guide. That way, you won’t need to specify that metadata in each article. You can override the TOC metadata in an article if necessary. Example: role: Admin, Developer or level: Experienced.

For more info, see Metadata.

Head 1 title and anchor

Example: # Adobe Target Admin Guide {#admin}

The Head 1 text is used in the breadcrumb (unless you specify breadcrumb-title metadata). The guide anchor ID ({#admin} in the above example) is used in the URL of every article of the guide. In the example above, the URLs of that guide would start like this:

https://experienceleague.adobe.com/docs/target/admin/

The rest of the URL derives from other anchors in the TOC as well as the filename. See User Guide Setup - How URLs are generated.

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}

In our example, articles in the release notes section would start with this URL:

https://experienceleague.adobe.com/docs/target/admin/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)

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. You can specify this metadata in the metadata.md, the TOC.md file, or any article. 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 in the same file.

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