Complete Guide to Admonitions

What are Admonitions?

Admonitions are special callout boxes that help emphasize important information in your posts. They come in different types with distinct colors and icons to convey different types of messages.

Available Admonition Types

This blog supports 6 types of admonitions, each with a unique purpose and visual style.

Note (Blue)

Use for general information, tips, or supplementary details.

Note

This is a note admonition. It’s perfect for providing additional context or highlighting interesting facts that supplement the main content.

Syntax:

:::note
Your note content here.
:::

Tip (Green)

Use for helpful suggestions, best practices, or pro tips.

Tip

This is a tip admonition. Use it to share helpful advice, shortcuts, or best practices that can improve the reader’s experience or workflow!

Syntax:

:::tip
Your tip content here.
:::

Info (Cyan)

Use for informational messages or FYI content.

Info

This is an info admonition. Perfect for sharing factual information, definitions, or explanatory content that readers should know.

Syntax:

:::info
Your info content here.
:::

Warning (Orange)

Use for cautions, potential pitfalls, or things to watch out for.

Warning

This is a warning admonition. Use it to alert readers about potential issues, deprecated features, or situations that require caution.

Syntax:

:::warning
Your warning content here.
:::

Danger (Red)

Use for critical warnings, breaking changes, or severe issues.

Danger

This is a danger admonition. Reserve this for critical warnings, breaking changes, security issues, or scenarios that could cause serious problems.

Syntax:

:::danger
Your danger content here.
:::

Success (Green)

Use for confirmations, completed tasks, or positive outcomes.

Success

This is a success admonition. Great for showing completion, success messages, or positive results!

Syntax:

:::success
Your success content here.
:::

Advanced Features

Custom Titles

You can customize the title of any admonition:

Note

Custom Title

This note has a custom title instead of the default “Note”.

Syntax:

:::note[Custom Title]
Your content here.
:::

Multiple Paragraphs

Admonitions support multiple paragraphs and complex formatting:

Tip

This is the first paragraph with some bold text.

This is the second paragraph with italic text.

List item 1
List item 2
List item 3

And even code blocks:

```javascript console.log(‘Hello from admonition!’); ```

Syntax:

:::tip
First paragraph.

Second paragraph.

- List items
- Work too

\`\`\`javascript
console.log('Code works!');
\`\`\`
:::

Collapsible Admonitions

All admonitions are collapsible by default! Click the title to expand/collapse the content.

Info

Click the title above to see how this works! The content can be toggled on and off, making it easy to hide details until needed.

Use Cases & Examples

Documentation

Note

API Version: This endpoint is available in API v2.0 and later.

Tutorials

Tip

Pro Tip: Always test your changes locally before deploying to production!

Warnings

Warning

Deprecated: This method will be removed in version 3.0. Please use the new newMethod() instead.

Critical Issues

Danger

Security Alert: Never commit API keys or sensitive credentials to version control!

Success Messages

Success

Setup Complete: Your development environment is now ready to use!

Best Practices

When to Use Each Type

Type	Use For	Examples
Note	General info, context	Background information, interesting facts
Tip	Helpful suggestions	Best practices, shortcuts, optimizations
Info	Factual information	Definitions, explanations, clarifications
Warning	Cautions	Potential issues, deprecations, gotchas
Danger	Critical warnings	Security issues, breaking changes, data loss
Success	Positive outcomes	Completions, achievements, confirmations