Using File-Relative Links for Microsoft Learn Articles
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.
ReviewedEvidence1 sourceSectionWriting & Style
Quick answer
Within a Microsoft Learn docset, use file links to connect articles with relative `.md` paths and forward slashes, such as `article-name.md` or `../article-name.md`.
Key details
Core Issueusing file-relative links for microsoft learn articles
RegisterMicrosoft Learn technical documentation
Important caveats
Scope Boundary
Microsoft distinguishes file links from URL links and uses file links for article-to-article links within the current docset. This page does not apply that rule to links outside the docset.
Further guidance
Content
Within a Microsoft Learn docset, use file links to connect articles with relative `.md` paths and forward slashes, such as `article-name.md` or `../article-name.md`.
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.
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.
Using Relative Paths for Microsoft Learn Conceptual Images 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 XRef Links for Microsoft Learn API References 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 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.
Using Reference-Style Links in 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 Secure External Links in 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.
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.
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.
