MDX
Adds trusted MDX content to Riebeckite. MDX pages support Markdown, JSX, JavaScript expressions, ESM imports and exports, and local Hono JSX components.
Installation
npm install @riebeckite/plugin-mdx
Configuration
import { defineConfig } from "@riebeckite/core";
import mdx from "@riebeckite/plugin-mdx";
export default defineConfig({
plugins: [mdx({ trusted: true })],
});
trusted: true is required. MDX evaluates authored JavaScript during server rendering and static generation, so only enable it for content you trust. The plugin throws during configuration when it is omitted.
Writing MDX
Place .mdx files in the configured content directory. Frontmatter and publishing metadata work the same way as Markdown files.
---
title: Release notes
publish: true
---
export const version = "1.0";
import { Badge } from "./badge";
# Version {version}
<Badge>Stable</Badge>
The MDX module and its relative imports are resolved through Vite. JSX is rendered with the Hono JSX runtime for development SSR and production SSG.
Static relative imports are tracked by incremental builds. Changing an imported local file rebuilds its MDX page, and adding or removing an .mdx file reloads the development server.
Search, excerpts, reading time, and headings are derived from a static text projection of the MDX source. The projection parses MDX into its syntax tree, keeps Markdown structure such as headings, paragraphs, lists, and links, and drops frontmatter, import/export declarations, JavaScript expressions, and JSX attributes. Static Markdown inside JSX children is kept. Components are not executed for these derived outputs, so text a component generates at render time is not included. Invalid MDX fails the build instead of producing a partial projection.
Components
Pass components available to every MDX page with components.
plugins: [
mdx({
trusted: true,
components: { Callout },
}),
]
Use local relative imports when a component belongs to one page or a group of pages.
Plugin components registered through the Plugin API components registry are also available to every MDX page. Use them as JSX with the same props as the Markdown fence:
<CodeCopy text="npm install" label="Copy command" copiedLabel="Copied" />
MDX receives one shared registry, not a separate component implementation. A component passed through mdx({ components }) with the same name overrides the Plugin component for that MDX page. Interactive Plugin components load and hydrate only when a page renders them.
Markdown coexistence
Markdown remains unchanged. Do not create .md and .mdx files with the same slug: Riebeckite reports the collision instead of choosing one arbitrarily.
Preview
The package preview renders Markdown only. Preview MDX pages through the site development server, which resolves MDX and its imports with Vite.
Powered by Riebeckite