Using Site-Relative Links for Microsoft Learn Articles
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.
ReviewedEvidence1 sourceSectionWriting & Style
Quick answer
Use a Microsoft Learn site-relative URL when the link should be rooted at `https://learn.microsoft.com`; omit the locale and use a leading `/` for an absolute repository-root path rather than `~/`.
Key details
Core Issueusing site-relative links for microsoft learn articles
RegisterMicrosoft Learn technical documentation
Important caveats
Scope Boundary
Microsoft uses URL links outside the current docset or between autogenerated reference and conceptual content. The same guidance says `~/` can produce invalid GitHub source links, so the site/root-relative owner also owns the queued tilde-path prohibition.
Further guidance
Content
Use a Microsoft Learn site-relative URL when the link should be rooted at `https://learn.microsoft.com`; omit the locale and use a leading `/` for an absolute repository-root path rather than `~/`.
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 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 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.
