Callouts, tabs, and grids
Use structure to separate a caveat, present alternatives, or give readers a choice of starting points.
Callouts and details
A note is always visible. A details block can start closed or open.
Before you begin
Create a clean working directory and record the version you are using.
Review the target
Confirm the destination before running a command that changes data.
Why use a staging environment?
It gives reviewers a place to exercise the release before readers see it.
An open detail
This detail starts expanded, but can be collapsed by the reader.
Show Markdown source
!!! note "Before you begin"
Create a clean working directory and record the version you are using.
!!! warning "Review the target"
Confirm the destination before running a command that changes data.
??? tip "Why use a staging environment?"
It gives reviewers a place to exercise the release before readers see it.
???+ example "An open detail"
This detail starts expanded, but can be collapsed by the reader.
Alternative paths
Tabs keep equivalent instructions together. Each selection shows one path.
Show Markdown source
Cards and mixed content
Cards are useful for a small collection of equally important options.
-
Plan
Identify the audience and define the outcome.
-
Draft
Write a short example and explain its result.
-
Review
Test the example and check the links.