Keeping Separate Media Files for Learn Includes 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
For Microsoft Learn include files, do not share media files between includes or articles; use a separate uniquely named media file for each include or article and store it in the media folder associated with that include.
Key details
Core Issuekeeping separate media files for learn includes
RegisterMicrosoft Learn technical documentation
Important caveats
Scope Boundary
This requirement concerns media referenced by reusable include content. It is separate from the rule that `/Includes` folders themselves are excluded from build and should not contain the referenced image files.
Further guidance
Content
For Microsoft Learn include files, do not share media files between includes or articles; use a separate uniquely named media file for each include or article and store it in the media folder associated with that include.
Purpose
Keep Microsoft Learn source readable, accessible, 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.
Markdown reference for Microsoft Learn — Contributor guide↗ (opens in a new tab)Microsoft · Current Microsoft Learn contributor reference for Markdown authoring, including headings/navigation, conceptual images and icons, includes, lists/checklists, nonlocalized strings, alerts, comments, tables, and other Learn extensions.
Keeping Include Media Outside Includes Folders 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.
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.
Keeping Learn Columns to Basic 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.
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.
Using Block Includes for Reusable Sections 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 H2 Headings for Learn Navigation records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
