preserveAdmonitions

Keep Docusaurus admonitions intact during formatting

Keep Docusaurus admonitions (:::note, :::tip, :::warning, etc.) intact during formatting.

The formatter preserves admonition syntax (:::note, :::tip, etc.) because its line-based approach does not modify content that isn’t specifically targeted by a formatting rule. The admonition blocks pass through the AST processing via a dedicated plugin that recognizes them as container directives and preserves their structure.

What is Docusaurus?

Docusaurus is a static site generator built by Meta for documentation websites. It uses MDX as its content format and provides a special “admonition” syntax using ::: fences to render callout boxes (notes, tips, warnings, etc.) in documentation pages. This syntax is not part of standard markdown or MDX — it is a Docusaurus-specific extension, so generic markdown formatters would break it.

Options

The enabled toggle exists for forward compatibility, but currently the preservation behavior is always active regardless of this setting. The admonition plugin runs during AST processing independently of this flag.

Config

{
  "preserveAdmonitions": {
    "enabled": true
  }
}

Examples

Simple admonition

The following admonition is preserved exactly as written:

:::note
This is a note admonition.
:::

Stays as-is after formatting.

Admonition with title

:::tip[Pro Tip]
This is a professional tip with a custom title.
:::

Stays as-is after formatting.

Admonition with rich content

:::warning
Be careful with this operation:

- Item 1
- Item 2

```js
dangerousOperation();
```

:::

The entire admonition block is preserved, including nested lists and code blocks.

Multiple admonition types

All Docusaurus admonition types are supported:

:::note
Note content
:::

:::tip
Tip content
:::

:::info
Info content
:::

:::caution
Caution content
:::

:::warning
Warning content
:::

:::danger
Danger content
:::