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.
ReviewedEvidence1 sourceSectionWriting & Style
Quick answer
Use a block include for substantial reusable content such as a paragraph, shared procedure, or shared section; do not use a block include for content smaller than a sentence.
Key details
Core Issueblock include reuse
RegisterMicrosoft Learn technical documentation
Important caveats
Scope Boundary
Microsoft Learn also supports inline includes. This page specifically covers when the contributor guide recommends block includes for larger reusable units.
Further guidance
Content
Use a block include for substantial reusable content such as a paragraph, shared procedure, or shared section; do not use a block include for content smaller than a sentence.
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 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.
Using Absolute URLs for Non-Documentation Microsoft Properties 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 Fenced Code Blocks for Longer Code 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 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.
Using Inline Includes Inside Sentences 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 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.
