Linking From Microsoft Learn Includes With Longer Relative Paths
Linking From Microsoft Learn Includes With Longer Relative Paths 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 linking from a Microsoft Learn include file to an article, account for the include’s different directory by using the longer relative path from the include location.
Key details
Core Issuelinking from microsoft learn includes with longer relative paths
RegisterMicrosoft Learn technical documentation
Important caveats
Scope Boundary
This page covers hyperlinks authored inside include content. It does not replace the separate rule for the relative `<filepath>` used by the `[!INCLUDE]` directive itself.
Further guidance
Content
Because Microsoft Learn include files are located in another directory, links from an include to an article use a longer relative path such as `../articles/folder/article-name.md`.
Purpose
Keep Microsoft Learn source readable, maintainable, accessible, 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 From Microsoft Learn Selectors 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 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 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 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.
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 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 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 in Learn Include Directives records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
