breadcrumbs

# Skill: Breadcrumbs on Microsoft Learn ## Purpose 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. ## Overview Breadcrumbs allow users to navigate through the site hierarchy back to the home page, one level at a time. Most pages should have breadcrumbs. ### Pages Without Breadcrumbs - **L1 pages**: Microsoft Learn home, Training home, Q&A home, Code Samples home - **L2 pages**: Hub pages, training browse, certification browse, certification overview, Learn Events - **Search results pages** ## Breadcrumb Structure 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. ### By Content Type | 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` | — | ## Creating a Breadcrumb File ### Step 1: Locate the Breadcrumb Folder 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/`. ### Step 2: Determine Your Structure Follow the patterns above. You can map breadcrumbs for all docsets in one file, or create multiple breadcrumb files for special cases. ### Step 3: Find Your Index Files Locate the `index.yml` or `index.md` files for your product or service. Their URLs are used as breadcrumb link targets. ### Step 4: Add Breadcrumb Entries Use this YAML syntax in `/breadcrumb/toc.yml`. The "Learn" crumb is added automatically at build time — do not include it. ```yaml 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 ``` ### Required Properties | 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](https://www.yamllint.com/). ## Configuring docfx.json ### 1. Include YAML Files in Content Ensure `"**/**.yml"` is in the `files` array of the `content` section: ```json "content": [ { "files": ["**/**.md", "**/**.yml"], "exclude": ["**/obj/**"] } ] ``` ### 2. Set the Breadcrumb Path Add `breadcrumb_path` to `globalMetadata`: ```json "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`). ### 3. Remove extendBreadcrumb If `"extendBreadcrumb": true` exists in `globalMetadata`, remove it or set it to `false`. Breadcrumbs should not duplicate the TOC. ## Multiple Breadcrumb Files Use multiple files only for special cases. To set them up: 1. Create subfolders under `breadcrumb/` with additional `toc.yml` files. 2. Use `fileMetadata` in `docfx.json` to map folders to breadcrumb files: ```json "fileMetadata": { "breadcrumb_path": { "folder-a/**/*.md": "/docset/breadcrumb/subfolder-a/toc.json", "folder-b/**/*.md": "/docset/breadcrumb/subfolder-b/toc.json" } } ``` ## Relationship with TOC The breadcrumb and TOC are separate navigation systems: - The **TOC** (`toc.yml`) controls the left-hand sidebar — showing where the user is within a docset and what sibling/child content is available. - The **breadcrumb** (`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.yml` inside > another, the nested portion will not generate its own breadcrumb entries. For TOC creation and contextual TOC details, see the [TOC skill](..\toc\SKILL.md). ## When to Apply This Skill - When onboarding a new docset and setting up initial breadcrumbs - When restructuring an existing docset's navigation hierarchy - When troubleshooting missing or incorrect breadcrumb display - When adding a new sub-offering under an existing product family ## Reference - [Overview of breadcrumbs](https://learn.microsoft.com/help/platform/breadcrumbs-overview) - [How to create or update a breadcrumb file](https://learn.microsoft.com/help/platform/breadcrumb-create-update)