Linking to YML Files for Split Microsoft Learn Articles
Linking to YML Files for Split Microsoft Learn Articles records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
ReviewedEvidence1 sourceSectionWriting & Style
Quick answer
When a Microsoft Learn article is split between a `.yml` metadata file and a `.md` content file, link to the `.yml` file rather than the `-content.md` file.
Key details
Core Issuelinking to yml files for split microsoft learn articles
RegisterMicrosoft Learn technical documentation
Important caveats
Scope Boundary
This decision is limited to the documented split-article structure where the `.yml` file is the article target and the `.md` file supplies content.
Further guidance
Content
When a Microsoft Learn article is split between a `.yml` metadata file and a `.md` content file, link to the `.yml` file rather than the `-content.md` file.
Purpose
Keep Microsoft Learn source readable, maintainable, reusable, and predictable while following current contributor-platform conventions.
Sources and evidence
Sources are shown with the role they play in this guide. Historical or style-sensitive claims are kept within the evidence boundary described above.
Use links in documentation — Contributor guide↗ (opens in a new tab)Microsoft · Current Microsoft Learn contributor guidance for documentation links, including file-relative and site-relative paths, split-article YML targets, bookmarks, XRef API links, reference-style links, explicit-anchor boundaries, and secure link requirements.
Linking to Microsoft Learn Headings With Bookmark Links records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Linking to Microsoft Learn XRef Method Pages and Overloads records a distinct Microsoft Learn XRef authoring decision and consolidates tightly coupled syntax choices so the public guide stays useful without fragmenting one task into thin pages.
Linking to Third-Party Sites From Microsoft Learn records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using File-Relative Links for Microsoft Learn Articles records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Site-Relative Links for Microsoft Learn Articles records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Formatting Data Matrix Tables for Microsoft Learn records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Keeping Separate Media Files for Learn Includes records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Limiting Alerts in Microsoft Learn Articles records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
