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.
ReviewedEvidence1 sourceSectionWriting & Style
Quick answer
Use H2 headings strategically in Microsoft Learn because H2s automatically appear in the published page’s right-hand navigation menu, while lower-level headings do not.
Key details
Core IssueH2 navigation
RegisterMicrosoft Learn technical documentation
Important caveats
Scope Boundary
This navigation behavior is Microsoft Learn-specific. It complements, rather than replaces, the separate requirement that a Learn Markdown file contain exactly one H1.
Further guidance
Content
Use H2 headings strategically in Microsoft Learn because H2s automatically appear in the published page’s right-hand navigation menu, while lower-level headings do not.
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.
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 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.
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.
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 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.
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 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.
