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.
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:
For more info, see Metadata.
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.
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/
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)
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.
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)