Using Custom Link Text With Markdown-Style XRefs 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.
ReviewedEvidence1 sourceSectionWriting & Style
Quick answer
Use Markdown-style XRef syntax such as `[custom text](xref:UID)` when Microsoft Learn needs author-controlled link text instead of the automatic API display text.
Key details
Core Issueusing custom link text with markdown style xrefs
RegisterMicrosoft Learn technical documentation
Important caveats
Scope Boundary
This page covers author-controlled display text. It does not replace automatic `<xref:UID>` display or the separate rules for choosing and encoding the UID.
Further guidance
Content
Microsoft Learn documents Markdown-style XRefs for supplying custom link text while retaining an XRef UID as the link target.
Purpose
Keep Microsoft Learn API-reference links maintainable and predictable while following the current contributor-platform XRef 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.
Avoiding Custom Layouts With Learn Columns records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Avoiding Inline Styling in Link Text records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Not Applying Code Style to Linked Reference Text records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Using Complex Images With Long Descriptions 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 Consistent Bullet Markers in 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 Consistent Bullets in 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 Icon Images Without Alt Text 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 Multi-Selectors in 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.
