// How breadcrumbs work on Microsoft Learn: structure, creation, configuration in docfx.json, and best practices for documentation repos.
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 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.
How to create, structure, and configure table of contents (TOC) files for Microsoft Learn documentation using toc.yml and docfx.json.
| name | breadcrumbs |
| description | How breadcrumbs work on Microsoft Learn: structure, creation, configuration in docfx.json, and best practices for documentation repos. |
This skill describes how breadcrumbs are structured, created, and configured for documentation published on Microsoft Learn. Breadcrumbs are navigation links at the top of a page that convey an article's position in the site hierarchy.
Breadcrumbs allow users to navigate through the site hierarchy back to the home page, one level at a time. Most pages should have breadcrumbs.
Breadcrumbs on Learn are intentionally simple and flat. The general pattern is:
Learn / [Offering name]
When an offering belongs to a branded hierarchical family:
Learn / [Offering name] / [Sub-offering name]
Each breadcrumb links to a hub page or, if unavailable, a landing page in a TOC.
[!NOTE] The breadcrumb shows where the TOC sits relative to the rest of the site, not where the user is within the TOC. This is an intentional shift to keep breadcrumbs simpler, shorter, and more coherent.
| Content Type | Structure | Example |
|---|---|---|
| Documentation | Learn / Product family (if applicable) / Offering / Sub-offering (if applicable) | Learn / Azure / Cognitive Services / Custom Vision Service |
| Training paths & modules | Learn / Training / Learning paths & modules | — |
| Training units | Learn / Training / Learning paths & modules / Learning path name | Learn / Training / Learning paths & modules / Introduction to Azure fundamentals |
| Certifications | Learn / Certifications | — |
| Shows | Learn / Shows | — |
| Show episodes | Learn / Shows / Show name | Learn / Shows / AI Show |
| Events | Learn / Events | — |
| Event sessions | Learn / Events / Event name | Learn / Events / Azure Static Web Apps Anniversary |
| Code samples | Learn / Code samples | — |
Look for a breadcrumb/ folder in the root of your docset containing a toc.yml file.
This folder is created during repo provisioning. In some repos the folder is called bread/.
Follow the patterns above. You can map breadcrumbs for all docsets in one file, or create multiple breadcrumb files for special cases.
Locate the index.yml or index.md files for your product or service.
Their URLs are used as breadcrumb link targets.
Use this YAML syntax in /breadcrumb/toc.yml. The "Learn" crumb is added
automatically at build time — do not include it.
items:
- name: Azure
tocHref: /azure/
topicHref: /azure/index
items:
- name: Azure DevOps
tocHref: /azure/devops/
topicHref: /azure/devops/index
items:
- name: Azure Boards
tocHref: /azure/devops/boards/
topicHref: /azure/devops/boards/index
| Property | Description |
|---|---|
name | Display text in the breadcrumb |
tocHref | URL path corresponding to the name. Must start and end with /. Articles whose URL contains this value are mapped to this breadcrumb entry. Can be a relative path to the TOC folder or an absolute path from the site domain. |
topicHref | URL that opens when a user selects the breadcrumb link. Must start with /, be an absolute path from the site domain, and not include a file extension. |
[!IMPORTANT] Breadcrumbs do not work with nested TOCs.
[!TIP] Validate your YAML syntax with a tool like YAML Lint.
Ensure "**/**.yml" is in the files array of the content section:
"content": [
{
"files": ["**/**.md", "**/**.yml"],
"exclude": ["**/obj/**"]
}
]
Add breadcrumb_path to globalMetadata:
"globalMetadata": {
"breadcrumb_path": "/<docset-base-url>/breadcrumb/toc.json"
}
The path uses the docset's base URL plus the breadcrumb folder location.
The file type must be .json (not .yml).
If "extendBreadcrumb": true exists in globalMetadata, remove it or set it
to false. Breadcrumbs should not duplicate the TOC.
Use multiple files only for special cases. To set them up:
breadcrumb/ with additional toc.yml files.fileMetadata in docfx.json to map folders to breadcrumb files:"fileMetadata": {
"breadcrumb_path": {
"folder-a/**/*.md": "/docset/breadcrumb/subfolder-a/toc.json",
"folder-b/**/*.md": "/docset/breadcrumb/subfolder-b/toc.json"
}
}
The breadcrumb and TOC are separate navigation systems:
toc.yml) controls the left-hand sidebar — showing where the
user is within a docset and what sibling/child content is available.breadcrumb/toc.yml) controls the top-of-page links —
showing where the docset sits in the overall site hierarchy.The breadcrumb's tocHref maps URL paths to breadcrumb entries. When using
contextual TOCs (linking to articles in other folders/repos while preserving
your docset's navigation), both the TOC and breadcrumb files must be updated
together. The breadcrumb file needs a mapping so that externally linked articles
show your product's breadcrumb rather than their own.
[!IMPORTANT] Breadcrumbs do not work with nested TOCs. If you nest one
toc.ymlinside another, the nested portion will not generate its own breadcrumb entries.
For TOC creation and contextual TOC details, see the TOC skill.