Admonitions in Docusaurus

How to use Docusaurus callout boxes — note, tip, info, caution, danger — plus custom types, icons, and styling

Admonitions are those colored callout boxes you see in good docs — "hey, watch out for this" or "pro tip: do it this way." Docusaurus has them built in. No plugins needed. Just triple-colons and go.

Basic Admonition Syntax

The format is dead simple:

Example

:::type[Optional Title] Content goes here. You can use **any Markdown** inside. :::

That's it. Three colons, the type, optional title in brackets, your content, three colons to close.

The Five Built-in Types

Note

For extra context that's good to know but not critical:

mdx example

:::note

React 18+ is required for this feature. Check your `package.json`
to verify your React version.

:::

Visual Result: A grey/blue box with an "ℹ️" icon and "NOTE" header. Subtle, doesn't scream for attention.

Tip

For helpful suggestions and best practices:

Example

:::tip[Performance Tip] Enable `swcMinify` in your Next.js config for 7x faster builds compared to Terser. :::

Visual Result: A green box with a "💡" lightbulb icon. Green = positive/helpful.

Info

For explanations and context:

Example

:::info[How It Works] Docusaurus compiles MDX at build time, not runtime. This means your interactive components are server-rendered for fast initial page loads. :::

Visual Result: A blue box with an "ℹ️" info icon. More vivid blue than Note — for when you're explaining something.

Caution

For "heads up, this might bite you":

Example

:::caution[Breaking Change in v3.0] The `remarkPlugins` configuration format has changed. Array syntax is now required for plugins with options:

// Before (v2) remarkPlugins: [require('plugin'), { option: true }]

// After (v3) remarkPlugins: [[require('plugin'), { option: true }]]

mdx example

:::

Visual Result: A yellow/amber box with a "⚠️" warning triangle. The warm color says "proceed carefully."

Danger

For serious stuff — data loss, security issues, things that can't be undone:

Example

:::danger[Data Loss Warning] Running `docusaurus clear` will **permanently delete** all cached build artifacts. Make sure you've committed any generated files you want to keep. :::

Visual Result: A red box with a "🔥" or "⛔" icon. Red = stop and pay attention.

Custom Admonition Titles

Override the default title with square brackets:

Example

:::tip[Did You Know?] You can use emoji in admonition titles! 🎉 ::: :::caution[⚠️ Deprecated Since v2.4] This API will be removed in the next major version. ::: :::note[📝 Author's Note] This section assumes familiarity with React hooks. :::

Nested Content in Admonitions

You can put anything inside — code blocks, tables, lists, even other components:

Example

:::info[Configuration Reference] Here's the complete configuration for MDX plugins: | Option | Type | Default | Description | |--------|------|---------|-------------| | `format` | string | `'mdx'` | MDX format version | | `remarkPlugins` | array | `[]` | Remark plugins | | `rehypePlugins` | array | `[]` | Rehype plugins | **Example configuration:**

module.exports = { markdown: { format: 'mdx', }, };

mdx example


You can also include images and links inside admonitions.

:::

Nested Admonitions

You can nest them by using more colons on the outer one:

Example

::::note[Outer Admonition] This is the outer admonition content. :::tip[Inner Tip] This tip is nested inside the note! ::: Back to the outer content. ::::

Visual Result: A note box containing a visually indented tip box inside it. The nesting shows through layered backgrounds.

Lists and Steps Inside Admonitions

Example

:::tip[Setup Checklist] Before proceeding, make sure you have: 1. ✅ Node.js 18+ installed 2. ✅ npm or yarn available 3. ✅ Git initialized in your project 4. ✅ A `docusaurus.config.js` file If any of these are missing, see the [prerequisites](/docs/prerequisites). :::

Custom Admonition Types

You can invent your own types — exercise boxes, quizzes, whatever makes sense for your content.

Step 1: Define the Custom Admonition Component

Example

import React from 'react'; import DefaultAdmonitionTypes from '@theme-original/Admonition/Types'; function ExerciseAdmonition(props) { return ( <div style={{ border: '2px solid #7c4dff', borderRadius: '8px', padding: '16px', backgroundColor: '#f3e8ff', marginBottom: '16px', }}> <div style={{ fontWeight: 'bold', marginBottom: '8px' }}> 🏋️ {props.title || 'Exercise'} </div> <div>{props.children}</div> </div> ); } function QuizAdmonition(props) { return ( <div style={{ border: '2px solid #ff6b35', borderRadius: '8px', padding: '16px', backgroundColor: '#fff3e0', marginBottom: '16px', }}> <div style={{ fontWeight: 'bold', marginBottom: '8px' }}> 🧠 {props.title || 'Quiz'} </div> <div>{props.children}</div> </div> ); } const AdmonitionTypes = { ...DefaultAdmonitionTypes, 'exercise': ExerciseAdmonition, 'quiz': QuizAdmonition, }; export default AdmonitionTypes;

Step 2: Use Custom Admonitions in MDX

Example

:::exercise[Try It Yourself] Create a Docusaurus site and add three different admonition types to a single page. Experiment with nested content. ::: :::quiz[Knowledge Check] What's the difference between `:::caution` and `:::danger`? :::

Custom Admonition Icons

You can swap the default icons through CSS or by swizzling:

css title="src/css/custom.css" example

/* Override the note icon */
.alert--note .admonition-icon svg {
  fill: #1a73e8;
}

/* Override the tip icon with a custom emoji-based approach */
.alert--tip::before {
  content: '🚀';
  font-size: 1.2em;
}

/* Change admonition heading styles */
.admonition-heading h5 {
  font-size: 0.9rem;
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

Using SVG Icons via Swizzling

bash example

npm run swizzle @docusaurus/theme-classic Admonition/Icon/Note -- --wrap

jsx title="src/theme/Admonition/Icon/Note.js" example

import React from 'react';

export default function AdmonitionIconNote(props) {
  return (
    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" {...props}>
      <path d="M8 1a7 7 0 100 14A7 7 0 008 1zm0 3a1 1 0 110 2 1 1 0 010-2zm2 8H6v-1h1V7H6V6h3v5h1v1z"/>
    </svg>
  );
}

Styling Admonitions

Global CSS Customization

Example

/* Make all admonitions have rounded corners */ .theme-admonition { border-radius: 12px; border-left-width: 5px; } /* Custom colors for dark mode */ [data-theme='dark'] .alert--note { background-color: rgba(56, 133, 254, 0.1); border-color: #3885fe; } [data-theme='dark'] .alert--tip { background-color: rgba(0, 200, 83, 0.1); border-color: #00c853; } [data-theme='dark'] .alert--danger { background-color: rgba(255, 23, 68, 0.1); border-color: #ff1744; } /* Compact admonitions */ .theme-admonition.compact { padding: 8px 12px; font-size: 0.9em; }

Inline Styling with className

Docusaurus doesn't natively support className on admonitions directly, but you can wrap them:

mdx example

<div className="compact-admonitions">

:::tip
Short and sweet tip.
:::

:::note
Brief note.
:::

</div>

Best Practices for Admonitions

:::tip[Admonition Guidelines]

Don't overuse — More than 2-3 per page dilutes their impact
Choose the right type — Match severity to content importance
Keep them concise — Long admonitions lose the "callout" benefit
Use custom titles — Specific titles are more helpful than generic ones
Reserve danger — Only for truly critical warnings about data loss or security

:::

Configuration in docusaurus.config.js

Admonitions work out of the box. But if you've added custom types, register their keywords:

Example

module.exports = { presets: [ [ 'classic', { docs: { admonitions: { keywords: [ 'note', 'tip', 'info', 'caution', 'danger', // Add custom keywords here 'exercise', 'quiz', ], extendDefaults: true, }, }, }, ], ], };

Admonitions are one of those features that make docs actually scannable. They break up walls of text, draw eyes to what matters, and give readers clear signals about severity. Use them well and your docs feel polished. Overuse them and everything feels like a warning.

Basic Admonition Syntax

The format is dead simple:

Example

:::type[Optional Title] Content goes here. You can use **any Markdown** inside. :::

That's it. Three colons, the type, optional title in brackets, your content, three colons to close.

The Five Built-in Types

Note

For extra context that's good to know but not critical:

mdx example

:::note

React 18+ is required for this feature. Check your `package.json`
to verify your React version.

:::

Visual Result: A grey/blue box with an "ℹ️" icon and "NOTE" header. Subtle, doesn't scream for attention.

Tip

For helpful suggestions and best practices:

Example

:::tip[Performance Tip] Enable `swcMinify` in your Next.js config for 7x faster builds compared to Terser. :::

Visual Result: A green box with a "💡" lightbulb icon. Green = positive/helpful.

Info

For explanations and context:

Example

:::info[How It Works] Docusaurus compiles MDX at build time, not runtime. This means your interactive components are server-rendered for fast initial page loads. :::

Visual Result: A blue box with an "ℹ️" info icon. More vivid blue than Note — for when you're explaining something.

Caution

For "heads up, this might bite you":

Example

:::caution[Breaking Change in v3.0] The `remarkPlugins` configuration format has changed. Array syntax is now required for plugins with options:

// Before (v2) remarkPlugins: [require('plugin'), { option: true }]

// After (v3) remarkPlugins: [[require('plugin'), { option: true }]]

mdx example

:::

Visual Result: A yellow/amber box with a "⚠️" warning triangle. The warm color says "proceed carefully."

Danger

For serious stuff — data loss, security issues, things that can't be undone:

Example

:::danger[Data Loss Warning] Running `docusaurus clear` will **permanently delete** all cached build artifacts. Make sure you've committed any generated files you want to keep. :::

Visual Result: A red box with a "🔥" or "⛔" icon. Red = stop and pay attention.

Custom Admonition Titles

Override the default title with square brackets:

Example

Nested Content in Admonitions

You can put anything inside — code blocks, tables, lists, even other components:

Example

module.exports = { markdown: { format: 'mdx', }, };

mdx example


You can also include images and links inside admonitions.

:::

Nested Admonitions

You can nest them by using more colons on the outer one:

Example

::::note[Outer Admonition] This is the outer admonition content. :::tip[Inner Tip] This tip is nested inside the note! ::: Back to the outer content. ::::

Visual Result: A note box containing a visually indented tip box inside it. The nesting shows through layered backgrounds.

Lists and Steps Inside Admonitions

Example

Custom Admonition Types

You can invent your own types — exercise boxes, quizzes, whatever makes sense for your content.

Step 1: Define the Custom Admonition Component

Example

Step 2: Use Custom Admonitions in MDX

Example

Custom Admonition Icons

You can swap the default icons through CSS or by swizzling:

css title="src/css/custom.css" example

/* Override the note icon */
.alert--note .admonition-icon svg {
  fill: #1a73e8;
}

/* Override the tip icon with a custom emoji-based approach */
.alert--tip::before {
  content: '🚀';
  font-size: 1.2em;
}

/* Change admonition heading styles */
.admonition-heading h5 {
  font-size: 0.9rem;
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

Using SVG Icons via Swizzling

bash example

npm run swizzle @docusaurus/theme-classic Admonition/Icon/Note -- --wrap

jsx title="src/theme/Admonition/Icon/Note.js" example

import React from 'react';

export default function AdmonitionIconNote(props) {
  return (
    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" {...props}>
      <path d="M8 1a7 7 0 100 14A7 7 0 008 1zm0 3a1 1 0 110 2 1 1 0 010-2zm2 8H6v-1h1V7H6V6h3v5h1v1z"/>
    </svg>
  );
}

Styling Admonitions

Global CSS Customization

Example

Inline Styling with className

Docusaurus doesn't natively support className on admonitions directly, but you can wrap them:

mdx example

<div className="compact-admonitions">

:::tip
Short and sweet tip.
:::

:::note
Brief note.
:::

</div>

Best Practices for Admonitions

:::tip[Admonition Guidelines]

Don't overuse — More than 2-3 per page dilutes their impact
Choose the right type — Match severity to content importance
Keep them concise — Long admonitions lose the "callout" benefit
Use custom titles — Specific titles are more helpful than generic ones
Reserve danger — Only for truly critical warnings about data loss or security

:::

Configuration in docusaurus.config.js

Admonitions work out of the box. But if you've added custom types, register their keywords:

Example

Basic Admonition Syntax

The Five Built-in Types

Note

Tip

Info

Caution

Danger

Custom Admonition Titles

Nested Content in Admonitions

Nested Admonitions

Lists and Steps Inside Admonitions

Custom Admonition Types

Step 1: Define the Custom Admonition Component

Step 2: Use Custom Admonitions in MDX

Custom Admonition Icons

Using SVG Icons via Swizzling

Styling Admonitions

Global CSS Customization

Inline Styling with className

Best Practices for Admonitions

Configuration in docusaurus.config.js

Continue learning this concept

Basic Admonition Syntax

The Five Built-in Types

Note

Tip

Info

Caution

Danger

Custom Admonition Titles

Nested Content in Admonitions

Nested Admonitions

Lists and Steps Inside Admonitions

Custom Admonition Types

Step 1: Define the Custom Admonition Component

Step 2: Use Custom Admonitions in MDX

Custom Admonition Icons

Using SVG Icons via Swizzling

Styling Admonitions

Global CSS Customization

Inline Styling with className

Best Practices for Admonitions

Configuration in docusaurus.config.js

Continue learning this concept