The Art of the TOC

The ‘TOC.md’ file is your table of contents (TOC). Navigating through a well-constructed table of contents makes finding information as easy and enjoyable as riding a bike.

Simple navigation, readability, consistency

To enhance readability:

  • Nouns for concepts and overviews
  • Verbs for tasks
  • Parallel parts of speech in lists

alt text

To navigate like a sailor:

  • Match page name where possible
  • Reduce words (avoid different words)
  • Breadcrumbs: short as possible without confusion

toc alignment

To stay consistent:

  • Follow the standards for writing headings, overviews, concepts, and tasks (content types) in Authoring Guide

alt text

Technical requirements for a table of contents

Validation breaks if technical requirements aren’t followed for TOCs. If the style guidelines aren’t followed, navigation becomes messy and confusing.

Think carefully about organization, page titles, and keeping TOC entries parallel.

  • Each guide requires a TOC.md.
  • Each TOC should have content metadata/tagging that applies to the guide level. See metadata.
  • A parent TOC entry groups its child pages. The parent is not a page. It doesn’t contain a link and therefore does not open a page, but each parent must contain an anchor. This anchor is used in the URLs for child pages.
    • Example TOC syntax: Getting Started with AEM Forms {#getting-started-with-forms}
  • TOC page links use this syntax: + [Article name](article.md)).
  • TOC page entries can be a shortened version of the article title where necessary. Follow the standards for writing headings, overviews, concepts, and tasks (content types) in this guide.
  • Avoid adding the same file multiple times to a TOC (or to multiple TOCs). Doing so causes odd behavior.
  • If your repo contains multiple user guides, your user guide directories must be at the same level, such as the subdirectories within the help directory.
  • Each user guide directory must have a TOC file. You cannot nest user guides. See Multiple User Guides. for more information.

Style guidelines for a table of contents

Follow these guidelines for TOCs:

Published Description
Parent entries Parent TOC entries are most often concepts (nouns) with child tasks (verbs). Keep them parallel. Parallel means that each entry begins the same structurally, using the same parts of speech (noun or verb).
Overview entries Use nouns or noun phrases, and keep them generally short. Your overview entry and page name should not be Overview (one word).
Example: For the audiences feature, the overview name should be Overview of audiences.
Concept entries Use nouns or noun phrases, and keep them generally short.
Example: Experiences and offers
Task entries Use active, infinitive form (not gerund form), present tense verbs, and keep them generally short.
Example: Create an activity
Be specific. Add extra words only for clarity or as keywords as needed. For example, add the feature or product name if not using them can cause confusion. Confusion might arise if similar tasks can be done in two products.
Think hard about the verb you use. What verb would a user search for? Create and add mean different things. Set up and configure have different meanings. See Word choice in the MSFT Style Guide for guidance.
Numbers Avoid numbering your headings. A heading is not a step. In tutorials, you can, as needed, use Part 1 or Step 1 for the heading, but this usage should be rare and unnecessary. Also, a page name might appear out-of-context in a Google search. It needs to make sense when seen as a stand-alone name.
Capitalization The standard is sentence style. Avoid a mixture of sentence and headline style.

On this page