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.
ReviewedEvidence1 sourceSectionWriting & Style
Quick answer
Microsoft Learn allows reference-style Markdown links to move long link targets out of running source text; include a space after the colon in the link-reference definition.
Key details
Core Issueusing reference-style links in microsoft learn
RegisterMicrosoft Learn technical documentation
Important caveats
Scope Boundary
This is an optional source-readability pattern, not a requirement to replace inline links. Microsoft warns that omitting the space after the colon can break links to other technical articles.
Further guidance
Content
Microsoft Learn allows reference-style Markdown links to move long link targets out of running source text; include a space after the colon in the link-reference definition.
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 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.
Using Capitalized INCLUDE Syntax 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 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 Next-Step Action Buttons 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 One H1 in Microsoft Learn Markdown 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.
Using Standard Conceptual Images 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 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.
