DocumentationExperience League Authoring Guide

Table of contents editorial guidelines

Last update: Fri Sep 12 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

The TOC.md file is your table of contents (TOC). Navigating through a well-constructed table of contents makes finding information is easy. The most important traits of a TOC are:

  • Parallelism: This is important in any type of list, and your TOC is a list.
  • Brevity: Too many words can get overwhelming.
  • Topic order: Be thinking about the order in which concepts and tasks are presented.
    • Topics should not follow the layout of a product interface. (Changes to UI layouts should not affect your TOC). Ensure that your topics follow a logical task analysis or flow.
  • Navigation: Ensure that the TOC entry matches (or closely matches) other navigation elements like the H1 page name.

TOC entry for a home page (guide name)

The TOC entry that opens your guide’s home should match the H1 on that page. The H1 is your guide’s formal name.

Example guide names and TOC entries:

  • Analytics tutorials
  • Experience Manager 6.5 implementation guide
  • Target practitioner Guide
  • Campaign v8 documentation (use documentation for a collection of child guides)
  • Control Panel user guide

Don’t:

  • Do not use Overview as a parent TOC entry or heading.
  • After using your application name once in the guide’s home (TOC and H1), avoid using it in the TOC or H1, except where leaving it out causes confusion. Fewer words are always best.

Parent TOC entries

A parent TOC entry behaves like a dropdown menu. It includes a collection of clickable concept and task articles. (Child entries.)

Parent entries can be part of the descriptor for child entries.

For consistency and readability, use brief noun phrases (ideally, one to four words). You typically don’t need to use a product name in these entries, unless leaving out the product name creates confusion.

Example parent TOC entries:

  • Get started
  • Segments
  • Planning
  • Admin tools
  • Processing options
  • Activities
  • Audiences

Concept TOC entries

For concepts, use nouns and noun phrases. (Same guidance as above.)

A Concept is a content type that describes a feature and why a customer should use it.

TOC entry for a task article

For a task, begin with a verb. Tasks begin with an active verb. Avoid gerund verbs. Use the singular form, sentence case. Be brief.

If a parent entry is a feature, and the child entries are directly related, the child entries can be single-word verbs. For example:

Single feature examples

  • Segments

    • Overview
    • Create
    • Share

Simple stand-alone examples

  • Create an audience
  • Integrate Analytics and Target
  • Configure processing options
  • Run a Fallout report
  • Print a page

Complex entries with verbs

  • Work with audiences
  • Manage devices
  • Configure a page layout

Numbers in a TOC

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 in a TOC

Except for your formal guide name, the capitalization standard is sentence style. Pay close attention to unnecessary capitalization in TOCs and headings.|

Previous page and Next page buttons

Previous page and Next page buttons enable customers to thumb through your TOC pages, as if thumbing through the pages of a book. These buttons display automatically at the bottom of every page.

If your TOC follows a logical order, the next page that displays should make sense to the customer. ExL is working to allow you to disable these buttons for circumstances in which opening the next page does not make sense in a desired workflow.

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.

  • The TOC.md file can appear as a child of the help folder (not recommended) or in a help > <guide-name> subfolder. We recommend adding the TOC.md to a subfolder under help to allow flexibility for adding more guides to the repo and to enable snippets, which requires a specific structure to be enabled.

  • Each TOC should have content metadata/tagging that applies to the guide level. See metadata.

  • A parent TOC entry (also called a “section heading”) 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 in the same repo). 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.

recommendation-more-help
92f1a422-8a81-400b-85d3-388f0c36dfda