Admonitions in Markdown
Admonitions are specially formatted blocks that highlight important information, show tips, display warnings, or notes in your Markdown files. The standard Markdown syntax doesn't include admonitions, however some extended Markdown flavors and documentation platforms provide ways to create these.
As each markdown processor differs in its syntax/approach, this lesson will provide some alternatives using the standard syntax along with HTML fallbacks.
Why use admonitions?
Admonitions are useful for various reasons:
- Highlight important information - Raise warnings, requirements, or prerequisites.
- Display tips or advice - Tips can be useful for documentation or tutorials.
- Enhancd visuals - Breaks up long sections of text and improves readability.
- Improve scannability - Help readers locate important notes at a glance.
- Establish conventions - Create consistent patterns for presenting certain types of content.
Common admonition types
Most documentation systems support several types of admonitions including:
| Type | Description |
|---|---|
| Warning | Warn readers about issues, errors, or potential problems. |
| Info | Additional background information |
| Note | Notes for general information. |
| Tip | Useful advice or best practices. |
| Caution | Advice the user to be cautious. |
| Important | Key information for the reader. |
| Example | Practical demonstrations, examples, or sample code. |
| Question | Frequently asked questions or quiz sections. |
| Success | Confirmation messages or completion criteria. |
| Danger | Critical/dangerous warning messages. |
Admonition syntax/support can vary depending on your markdown processor or editor.
Using with blockquotes
To replicate a similar style which works in all markdown processors, a blockquote can be used (combined with a emoji if required 😄):
Syntax:
> :warning: **Warning:** NPM must be installed to proceed.
> :fire: **Tip:** Insert emojis into your markdown pages.
> :memo: **Note:** Admonition syntax is not supported in all markdown processors.
> :heart: **Success:** Lesson complete, you are making great progress!.
Result:
⚠️ Warning: NPM must be installed to proceed.
🔥 Tip: Insert emojis into your markdown pages.
📝 Note: Admonition syntax is not supported in all markdown processors.
❤️ Success: Lesson complete, you are making great progress!.
General HTML Approach
You can use HTML with CSS classes if admonition is not available in your Markdown editor:
Syntax:
<div class="note">
<h4>Note</h4>
<p>Admonition/note using HTML and CSS.</p>
</div>
CSS:
.note {
margin: 10px;
padding: 5px 10px;
background-color:rgb(93, 92, 92);
border-radius: 5px;
border-left: 10px solid rgb(91, 135, 179);
}
Note
Admonition/note using HTML and CSS.
Bootstrap-style alerts with HTML
Syntax:
<div style="background-color: #fff3cd; color: #856404; padding: 15px; border-radius: 5px; border-left: 5px solid #ffeeba;">
<strong>Warning!</strong> Backup your work before proceeding.
</div>
Result:
Details/Summary using HTML
Syntax:
<details>
<summary><strong>Click to expand</strong></summary>
<p>Hidden content will be revealed when expanded.</p>
</details>
Result:
Click to expand
Hidden content will be revealed when expanded.