Toc

Skill: Table of Contents (TOC) on Microsoft Learn

Purpose

This skill describes how to create, structure, and configure table of contents files (toc.yml) for documentation published on Microsoft Learn. The TOC defines the left-hand navigation structure of a docset.

Goals for TOCs

• Present a useful amount of content while staying scannable
• Match the customer's likely use cases for a product or technology
• Allow rapid zooming in and out among topics
• Help users form mental models of how a product is organized

YAML TOC Format

TOCs must be YAML (not Markdown). Create a file named toc.yml (always lowercase).

Basic Structure

items:
- name: Tutorial
  items:
  - name: Introduction
    href: tutorial.md
  - name: Step 1
    href: step-1.md
  - name: Step 2
    href: step-2.md

Parent nodes contain an items list of children. If you add an href to a parent node, the build system automatically creates a duplicate child node with the parent's name and link — the parent itself becomes an expander only.

Node Properties

[!WARNING] Do not use maintainContext. It is no longer supported. Use contextual TOC links instead (see Contextual TOCs).

Advanced Example

- name: Dev sandbox
  href: index.md
  displayName: Home
- name: Conceptual pages
  expanded: true
  items:
  - name: Overview
    href: ./conceptual/index.md
  - name: Code samples
    href: ./conceptual/code.md
- name: Reference Pages
  items:
  - name: IDictionary
    href: ./reference/System.Collection.IDictionary.yml
  - name: String
    href: ./reference/System.String.yml

[!TIP] Validate your YAML with YAML Lint. Add items: as the first line to avoid parser errors.

docfx.json Configuration

Ensure "**/**.yml" is listed as a content file type so the build picks up TOC files:

"build": {
  "content": [
    {
      "files": ["**/*.md", "**/**.yml"],
      "exclude": ["**/obj/**"]
    }
  ]
}

Single vs. Multiple TOCs

Single TOC

Best for most products and services. One toc.yml plus one landing page. Top-level (L1) nodes represent the main content categories.

Multiple TOCs

For large products with diverse content areas, connect multiple TOCs via a central hub page. The hub page itself has no TOC — it links to landing pages, each with its own focused TOC.

Decision factors:

• Product complexity and breadth of content
• Number of files — each TOC should cover a meaningful end-to-end task area
• Shared content — more sharing favors a single TOC

TOC and Product Directory

The TOC structure should relate to the product directory (the landing/hub page that showcases the product's content areas) but does not need to be a 1:1 match. The TOC may group or split content differently than the product directory to best serve navigation within the docset.

[!TIP] For reference images showing product directory layouts, see the Microsoft Learn static media index.

Nested TOCs

Nest one TOC inside another by pointing href to a child toc.yml:

items:
- name: Azure overview
  href: azure-overview.md
- name: Extensibility
  href: extensibility/toc.yml
- name: Reference
  href: azure-reference.md

Users stay in the containing TOC when selecting nested links. If the node linked to extensibility/overview.md instead of extensibility/toc.yml, selecting it would navigate the user to a different TOC.

[!NOTE] If a user arrives at a nested TOC article via search, the full parent TOC is displayed, not just the nested portion.

TOC Best Practices

Content and Context

• All articles in a TOC should display the same TOC — don't surprise users by landing them in a different TOC
• All links should go to articles, not to other TOCs (use hub pages for that)
• Selecting the rightmost breadcrumb should always return to the current TOC

Size Guidelines

• Keep 3–12 items per section. Fewer than 3 may not warrant a section; more than 12 becomes hard to scan.
• Avoid going more than 3 levels deep.