| title | Components (Sample) |
|---|---|
| description | A small showcase of the built-in MDX components with usage guidelines. |
When to use
- Highlight important warnings or constraints that affect success
- Call out tips that save time or prevent common mistakes
- Emphasize prerequisites, permissions, or irreversible actions
When not to use
- For every minor detail; overuse makes real warnings easy to ignore
- As a replacement for clear prose and headings
- To hide critical blocking information at the bottom of a long page
When to use
- Readers must follow actions in a specific order
- You describe tasks that can be completed in one sitting
- You want to separate conceptual explanation from hands-on actions
When not to use
- For unordered checklists where sequence does not matter
- To document background concepts or architecture
- For long, branching workflows that need their own dedicated guide
When to use
- You show the same idea in multiple languages or platforms
- You provide alternate setup paths, such as CLI versus UI
- You want to keep short variants in one compact section
When not to use
- When one variant is strongly recommended over the others
- For long, independent flows that deserve separate pages
- When content differs so much that readers must read all variants anyway