Skip to main content

Admonitions

Admonitions let you highlight important information in your docs using a simple Markdown syntax.

They render as colorful callout boxes like Tips, Notes, Warnings, etc.

Basic Syntax​

Wrap your text with 3 colons and specify a type:

:::note

This is a note block with **Markdown** support.

:::
http://localhost:3000
note

This is a note block with Markdown support.

Supported types: note, tip, info, warning, danger

Examples​

:::tip
Great for best practices or quick advice.
:::

:::info
Use to provide additional context.
:::

:::warning
Warn users of potential issues.
:::

:::danger
Critical alerts or breaking changes.
:::
http://localhost:3000
tip

Great for best practices or quick advice.

info

Use to provide additional context.

warning

Warn users of potential issues.

danger

Critical alerts or breaking changes.

Adding a Custom Title​

You can provide a custom title (with Markdown too):

:::note[Your **Custom** _Title_]

This callout uses a custom title.

:::
http://localhost:3000
Your Custom Title

This callout uses a custom title.

Nested Admonitions​

Admonitions can be nested for layered messages. Use more colons : for each parent level:

::::info[Outer]

Outer content

:::warning[Inner]
Inner content
:::

::::
http://localhost:3000
Outer

Outer content

Inner

Inner content

Using MDX Inside​

Admonitions fully support MDX components.

:::tip[Tabbed Example]

<Tabs>
  <TabItem value="react" label="React">React example 🚀</TabItem>
  <TabItem value="vue" label="Vue">Vue example 🌿</TabItem>
</Tabs>

:::
http://localhost:3000
Tabbed Example
React example 🚀

Using in JSX​

Outside Markdown, use the React component directly:

MyPage.jsx
import Admonition from '@theme/Admonition';

export default function MyPage() {
  return (
    <Admonition type="tip" icon="💡" title="Did you know?">
      You can use Admonitions directly in JSX too!
    </Admonition>
  );
}
http://localhost:3000
💡Did you know?

You can use Admonitions directly in JSX too!

Customizing Admonitions​

Custom Icons or Styling​

You can override default icons by swizzling the Admonition theme component:

src/theme/Admonition.js
import React from 'react';
import Admonition from '@theme-original/Admonition';
import MyIcon from '@site/static/img/custom-icon.svg';

export default function AdmonitionWrapper(props) {
  if (props.type === 'info') {
    return <Admonition icon={<MyIcon />} {...props} />;
  }
  return <Admonition {...props} />;
}

Add New Types​

Add a new keyword in docusaurus.config.js:

docusaurus.config.js
export default {
  presets: [
    [
      'classic',
      {
        docs: {
          admonitions: {
            keywords: ['my-callout'],
            extendDefaults: true,
          },
        },
      },
    ],
  ],
};

Then create a custom renderer:

src/theme/Admonition/Types.js
import React from 'react';
import DefaultTypes from '@theme-original/Admonition/Types';

function MyCallout(props) {
  return (
    <div style={{border: '2px dashed #ff9800', padding: 12}}>
      <h4>{props.title || '⚡ My Callout'}</h4>
      {props.children}
    </div>
  );
}

export default {
  ...DefaultTypes,
  'my-callout': MyCallout,
};

Now you can use:

:::my-callout[Custom Callout]
This is a completely custom admonition.
:::

Best Practices​

  • Always leave blank lines inside admonitions to avoid Prettier formatting issues.
  • Use icons and concise titles to improve readability.
  • Keep admonitions focused—avoid stuffing too much content.