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.
ReviewedEvidence1 sourceSectionWriting & Style
Quick answer
For a complex Microsoft Learn image, use the Learn image extension with `type="complex"`, supply `source` and `alt-text`, place the long description inside the directive, and close it with `:::image-end`.
Key details
Core Issuecomplex image long descriptions
RegisterMicrosoft Learn technical documentation
Important caveats
Scope Boundary
This is Microsoft Learn syntax for complex images. The long description supplements, rather than replaces, concise alternative text.
Further guidance
Content
For a complex Microsoft Learn image, use the Learn image extension with `type="complex"`, supply `source` and `alt-text`, place the long description inside the directive, and close it with `:::image-end`.
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 Automatic Borders on Learn 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 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.
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 Numbered Lists With All Ones 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 Standard Conceptual Images in 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.
