toc

name: toc description: > How to create, structure, and configure table of contents (TOC) files for Microsoft Learn documentation using toc.yml and docfx.json.

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.

Labels and Links

• TOC labels should be short but match the article's H1
• Parent nodes should expand, not be links (the build duplicates linked parents)
• External links must live in a Resources node; all other nodes should link to Microsoft Learn content

Common Mistakes to Avoid

Contextual TOCs

When your TOC links to articles in another folder or repo, the user's navigation context (TOC, breadcrumbs, header) normally changes. A contextual TOC preserves your docset's context instead.

Three Files Involved

[!IMPORTANT] Publish breadcrumb and context file changes before publishing TOC changes. Contextual links can't be previewed until these files are live.

Forced TOC and Breadcrumb Paths

Append query parameters to the href in your TOC:

# Forced TOC only
- name: Secure SQL data
  href: ../sql-database/sql-database-always-encrypted.md?toc=/azure/key-vault/general/toc.json

# Forced TOC + breadcrumb
- name: Secure SQL data
  href: ../sql-database/sql-database-always-encrypted.md?toc=/azure/key-vault/general/toc.json&bc=/azure/key-vault/general/breadcrumb/toc.json

Context Files (Optional Shorthand)

A context file combines brand, breadcrumb, and TOC into a single reference:

### YamlMime: ContextObject
brand: azure
breadcrumb_path: ../breadcrumb/toc.yml
toc_rel: ../toc.yml

Then reference it in your TOC with a single parameter:

- name: SCCM Run Scripts
  href: /sccm/apps/deploy-use/create-deploy-scripts?context=/azure/key-vault/context/kv-context

[!NOTE] Context files have limitations with moniker views (e.g., ?view=azurermps-6.2.0). In those cases, use explicit ?toc= and &bc= parameters instead.

Relationship Between TOC and Breadcrumbs

The TOC and breadcrumb are separate navigation systems with different purposes:

• The TOC (toc.yml) provides left-hand navigation within a docset — showing where the user is and what content is available nearby.
• The breadcrumb (breadcrumb/toc.yml) provides top-of-page links showing where the docset sits in the overall site hierarchy.

The breadcrumb's tocHref property maps URL paths to breadcrumb entries. When using contextual TOCs, the breadcrumb file must also be updated so that externally linked articles show your product's breadcrumb rather than their own.

For breadcrumb file creation and configuration details, see the breadcrumbs skill.

When to Apply This Skill

• When creating a new docset and its initial navigation structure
• When reorganizing content into new sections or sub-products
• When linking to articles outside your docset while preserving context
• When deciding between single vs. multiple TOCs for a large product

Reference

• Overview of TOCs
• How to set up a contextual TOC