Add Collapsible Admonitions in Markdown and MDX

Add collapsible admotions to your MD, MDX content.

Use the Tool​

Zero-dependency: <details> (pure Markdown / MDX)​

This is the simplest and most portable solution. example

<details>
  <summary>⚠️ Warning</summary>

  This is a collapsible warning block.

  You can put **Markdown** here.
</details>

With default open

<details open>
  <summary>ℹ️ Note</summary>

  This is expanded by default.
</details>

Pros Works in: GitHub any Markdown renderer MDX Zero setup Native browser behavior Cons No styling (unless you add CSS) No "admonition types" (note, tip, warning, etc.) Repetitive markup When to use Docs MVP Blog posts Anywhere you want portability

Clean MDX way (React component)​

This is the best** balance of flexibility and control.** Step 1: Create component

// components/Admonition.jsx
export default function Admonition({
  type = "note",
  title,
  children,
  defaultOpen = false,
}) {
  return (
    <details open={defaultOpen} className={`admonition ${type}`}>
      <summary>
        <strong>{title || type.toUpperCase()}</strong>
      </summary>

      <div className="content">
        {children}
      </div>
    </details>
  );
}

Step 2: Use in MDX

import Admonition from './components/Admonition'

<Admonition type="warning" title="Be careful">
This action is irreversible.
</Admonition>

Step 3: Optional styling (important)

  border: 1px solid #ddd;
  border-radius: 8px;
  padding: 0.5rem 1rem;
  margin: 1rem 0;
}

.admonition.warning {
  border-color: orange;
  background: #fff7ed;
}

.admonition.note {
  border-color: #3b82f6;
  background: #eff6ff;
}

.admonition summary {
  cursor: pointer;
}

Why this is "clean" Reusable Typed (warning, tip, etc.) Fully controllable UI Works in any MDX environment

Optional upgrade (very nice) You can auto-add icons:

const icons = {
  note: "ℹ️",
  warning: "⚠️",
  tip: "💡",
};

<strong>{icons[type]} {title || type}</strong>

When to use Personal site Custom docs system When you want control without heavy frameworks

Proper way in Docusaurus​

Docusaurus already has admonitions, but not collapsible ones by default.

Default (non-collapsible)

:::warning
This is a warning
:::

Goal: make them collapsible You need to override the Admonition component. Step 1: Swizzle component

npx docusaurus swizzle @docusaurus/theme-classic Admonition

This creates: src/theme/Admonition/index.js Step 2: Modify it

export default function Admonition(props) {
  const {children, title, type} = props;

  return (
    <details className={`admonition admonition-${type}`}>
      <summary>{title || type}</summary>

      <div>
        {children}
      </div>
    </details>
  );
}

Step 3: Add "default open" support (optional) You can pass metadata via MDX:

:::warning{open=true}
This is open by default
:::

Then read it in your component:

const isOpen = props.open === true;

<details open={isOpen}>

Step 4: Styling (important) Docusaurus already has styles - you just need to ensure:

.admonition summary {
  cursor: pointer;
}

Result You keep: Docusaurus syntax (:::warning) Theming Icons And gain: Collapsibility

Alternative (simpler in Docusaurus)​

Instead of swizzling, just use <details> directly in MDX:

<details>
  <summary>⚠️ Warning</summary>

  Content
</details>

But: You lose built-in styling consistency

Final comparison​

Practical recommendation​

If you're building a serious docs site → use MDX component or Docusaurus override If you want speed + portability → use <details> If you're already using Docusaurus → swizzle once and forget

What This Tool Does​

Plain Markdown (MD)​

Standard Markdown has no concept of admonitions at all, let alone collapsible ones. Admonitions (note, tip, etc.) are not part of the Markdown spec Collapsibility is also not part of Markdown So in pure Markdown: ❌ No admonitions ❌ No collapsible behavior You only get collapsible content if you: use raw HTML like <details><summary>...</summary>...</details> or install extensions/plugins

MDX (core MDX)​

MDX allows you to use React components in your Markdown content, which means you can create custom collapsible admonition components. You can define a React component that uses the <details> and <summary> HTML elements to create collapsible sections. This approach gives you full control over the styling and behavior of your admonitions You can create reusable components for different types of admonitions (e.g., Note, Tip, Warning) and use them throughout your MDX content

Docusaurus MDX​

Docusaurus adds admonitions like:

:::note
content
:::

But: These are framework features, not MDX itself They are not collapsible by default

To make them collapsible, you must: customize components or add extra props/plugins

MDX with a library (e.g., mdx-admonitions)​

There are libraries like mdx-admonitions that provide pre-built components for collapsible admonitions in MDX These libraries often come with customizable styles and support for different types of admonitions Using a library can save you time and effort compared to building your own components from scratch However, it may add additional dependencies to your project and may not offer the same level of customization as building your own components

Example: MkDocs / Material / plugins​

Some ecosystems support collapsible admonitions:

??? note "Title"
    Content

??? makes it collapsible ???+ makes it expanded by default But again: This comes from extensions/plugins, not Markdown itself

What problems it solves​

Long, cluttered documentation pages. Standard Markdown lacks a native way to hide optional or deep-dive information inside stylized, expandable sections. Utilizing these approaches allows you to condense walls of text and organize content effectively.

Who should use it​

Technical writers, developer advocates, and engineers building documentation sites (e.g., Docusaurus, Nextra, MkDocs) or technical blogs who want cleaner, more accessible UIs.

Why it matters​

It dramatically enhances readability. By hiding secondary or advanced information natively, you improve the user experience, preventing readers from feeling overwhelmed while still providing comprehensive details for those who want to dig deeper.

How It Works​

Input​

You define your content using standard HTML <details> tags, custom MDX components (like <Admonition>), or framework-specific directives (e.g., :::note).

Processing​

During the build step, the Markdown parser or MDX bundler evaluates the syntax and compiles it down to semantic, interactive HTML <details> and <summary> tags with applied CSS classes.

Limitations​

• Pure Markdown requires raw HTML, which can be verbose to write.
• Custom MDX components are tied to a React/JSX environment.
• Framework-specific syntax (like Docusaurus :::) makes the source markdown less portable to other generators.

Output​

Clean, interactive collapsible blocks rendered natively in the user's browser. They require no extra client-side JavaScript to function toggle states.

Frequently Asked Questions​

Can I use regular Markdown inside the collapsible block?​

Yes! If you are using the raw HTML <details> tag, remember to leave a blank line after the <summary> tag before starting your Markdown. For MDX components or framework admonitions, you can write Markdown inside them naturally.

Is collapsible content SEO friendly?​

Yes. Content inside a semantic <details> HTML tag is fully readable and indexed by Google and other major search engines. It is also natively accessible to screen readers.

Related Tools​

Related Posts​

Markdown Reference Cheatsheet 2025

Markdown is a lightweight markup language that allows you to format plain text. It is widely used for documentation, writing articles, and creating web content.

Github flavored markdown syntax

Markdown for github