ワンクリックで
toc
// How to create, structure, and configure table of contents (TOC) files for Microsoft Learn documentation using toc.yml and docfx.json.
// How to create, structure, and configure table of contents (TOC) files for Microsoft Learn documentation using toc.yml and docfx.json.
Required when reviewing, updating, auditing, or creating any concept documentation page. Covers code accuracy checks against source repos, language parity across zone pivots, parity table comments, and structural consistency.
How to reference code from sample repos in Agent Framework docs pages using :::code directives, snippet tags, zone pivots, and highlight attributes.
How to configure cross-repository references (CRR) and create API class links for Microsoft Learn docs in this repository.
How breadcrumbs work on Microsoft Learn: structure, creation, configuration in docfx.json, and best practices for documentation repos.
How to delete, rename, or move articles on Microsoft Learn while preserving Platform IDs, preventing broken links, and managing redirects.
Conceptual organization of Agent Framework documentation and samples. For language-specific details (file naming, provider setup, code patterns), see each code repo's skills files.
| name | toc |
| description | How to create, structure, and configure table of contents (TOC) files for Microsoft Learn documentation using toc.yml and docfx.json. |
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.
TOCs must be YAML (not Markdown). Create a file named toc.yml (always lowercase).
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.
| Property | Required | Description |
|---|---|---|
name | Yes | Display text for the TOC node. Cannot include a colon (:). |
href | No | Path the node leads to. Omit for parent-only nodes. |
displayName | No | Additional search terms for TOC filtering (comma-separated). Not displayed to users. |
uid | No | Identifier for reference documentation (e.g., System.String). |
items | No | Child nodes, each with the same available properties. |
expanded | No | Set to true to expand this node by default on page load. Only one root-level node can be expanded. |
[!WARNING] Do not use
maintainContext. It is no longer supported. Use contextual TOC links instead (see Contextual TOCs).
- 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.
Ensure "**/**.yml" is listed as a content file type so the build picks up TOC files:
"build": {
"content": [
{
"files": ["**/*.md", "**/**.yml"],
"exclude": ["**/obj/**"]
}
]
}
Best for most products and services. One toc.yml plus one landing page.
Top-level (L1) nodes represent the main content categories.
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:
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.
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.
| ❌ Don't | ✅ Do |
|---|---|
| Link to the same file more than once | Use a single link per article |
| Link to a different TOC from within a TOC | Use a contextual TOC instead |
| Duplicate info from hub/landing pages | Provide complementary structure |
Include root folder in href (/docs/marketplace/overview.md) | Use relative path (marketplace/overview.md) |
Begin href with a slash (/collaborate/overview.md) | Omit leading slash (collaborate/overview.md) |
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.
| File | Purpose |
|---|---|
toc.yml | Links to external articles with forced context parameters |
breadcrumb/toc.yml | Maps external article URLs to your breadcrumb hierarchy |
context/context.yml | (Optional) Bundles brand, breadcrumb, and TOC references |
[!IMPORTANT] Publish breadcrumb and context file changes before publishing TOC changes. Contextual links can't be previewed until these files are live.
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
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.
The TOC and breadcrumb are separate navigation systems with different purposes:
toc.yml) provides left-hand navigation within a docset —
showing where the user is and what content is available nearby.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.