MDX components & callouts: Markdown with superpowers

When the lines between data and presentation blur, MDX is your friend. You can mix JSX-flavoured components inside Markdown without leaving the authoring flow.

This post is itself an .mdx file. Open src/content/posts/en/mdx-components-and-callouts.mdx to see exactly how the demos below are written.

When to use .md vs .mdx

Both formats live side-by-side in the same posts/ folder — the build picks them up via **/*.{md,mdx}.

The <Callout> component

The theme ships a small, accessible Callout component you can import in any MDX post:

---
title: Example
---

import Callout from '../../../components/Callout.astro';

<Callout type="info" title="Heads up">
  This is an info callout.
</Callout>

It supports four semantic variants — they share daisyUI’s semantic colour tokens, so they stay readable in both themes.

Inline JavaScript expressions

MDX evaluates { ... } as JavaScript at build time. Today is Sun Aug 23 2026 according to the build server, and 2 + 2 is 4.

Variables defined at the top of the file are also in scope:

export const release = 'v6.0.0';

The latest release is **{release}**.

Importing other components

You are not limited to Callout. Any Astro component can be imported with a relative path. From a post at src/content/posts/en/foo.mdx, the path to a component is ../../../components/Foo.astro:

import Panel from '../../../components/Panel.astro';

<Panel>
  <p>Embedded Panel content here.</p>
</Panel>

Slots and children

Astro components inside MDX accept default slots. Anything between the opening and closing tag is passed as <slot />:

<Callout type="success">
  **Anything** can go in here — _Markdown_, [links](/), even nested components.
</Callout>

Named slots work too if your component declares them:

<MyWidget>
  <Fragment slot="header">A heading</Fragment>
  Body content goes in the default slot.
</MyWidget>

A cookbook: building your own callout

Want a <Tip> shorthand? Drop a tiny wrapper into src/components/Tip.astro:

---
import Callout from './Callout.astro';
---

<Callout type="info" title="Tip">
  <slot />
</Callout>

…then use it from any MDX file:

import Tip from '../../../components/Tip.astro';

<Tip>Restart `bun run dev` after editing `astro.config.mjs`.</Tip>

Tables and other Markdown features still work

Inside MDX, GFM tables, footnotes, and task lists keep working unchanged:

Comments are explicitly enabled here

This post sets comments: true to demonstrate that flag. To turn comments off on a single post, set comments: false instead — see the frontmatter reference and the Giscus post for the full picture.