MDX Content Authoring

MDX extends Markdown with the ability to import and use Astro components inline with content. The project supports MDX files (.mdx) in all content collections alongside standard Markdown (.md).

When to use MDX vs Markdown

• Use .md for standard text content — articles, documentation pages, simple informational pages. This covers the vast majority of authoring needs.
• Use .mdx when content needs embedded components — interactive demos, custom layouts within content, data-driven sections, or any case where a component provides clear value over Markdown-only content.

Note: For most content authoring needs, standard Markdown is sufficient and preferred. MDX adds build complexity and should be used only when embedded components provide clear value.

Basic MDX syntax

MDX files use the same frontmatter as Markdown files. Component imports go after the frontmatter block, before body content:

---
title: My Page
description: Example MDX page
datePublished: 2026-03-14
draft: false
---

import Hero from "@core/components/sections/Hero.astro";
import FeatureGrid from "@core/components/sections/FeatureGrid.astro";

Regular markdown content works as expected. **Bold**, _italic_, lists, and
all standard Markdown syntax is supported between components.

<Hero heading="Welcome" subheading="An embedded component" />

More markdown content after the component.

<FeatureGrid
  features={[
    { title: "Fast", description: "Built for performance" },
    { title: "Accessible", description: "WCAG 2.2 AA baseline" },
  ]}
/>

Importing components

Use the project’s path aliases for imports:

Alias	Resolves to	Use for
@core/	src/core/	Core-owned components, config, styles
@site/	src/site/	Site-specific components and overrides
@/	src/	General src-root imports (lib, utilities)

Frontmatter

MDX files use the same frontmatter schema as .md files. The content collection type determines which fields are available:

• pages and articles — use the shared content schema (title, description, slug, draft, dates, tags, categories, layout overrides).
• docs — use the docs schema (title, description, docId, topic, audience, docType, order, and docs-specific fields).
• fragments — use the fragment schema (title, notes, fragmentId, tags, draft).

Frontmatter validation is identical regardless of file extension. A .mdx file in the docs collection must satisfy the same schema as a .md file in that collection.

Component props

Props must be valid JSX expressions. String props use quotes; expressions use curly braces:

<!-- String prop -->

<Hero heading="Welcome to our site" />

<!-- Expression prop (array, object, boolean, number) -->

<FeatureGrid columns={3} features={[{ title: "Item" }]} />

<!-- Boolean shorthand -->

<Section centered />

Limitations and caveats

• Build-time only — MDX files are processed at build time. There is no client-side MDX rendering.
• Data attributes — Vanilla JS interactive attributes (data-slot, data-state) work in MDX the same as in .astro files. No special syntax considerations apply.
• Markdown between components — Standard Markdown syntax works between component tags but not inside component tags. Content inside a component must use HTML or be passed as props.
• No # headings — The frontmatter title renders as the page H1. Start body headings at ##, the same as Markdown files.

Content collections

MDX entries are treated identically to Markdown entries in content collections. The same frontmatter validation, slug generation, and rendering pipeline applies. There is no difference in how the build system processes .md vs .mdx beyond the additional component import capability.