Using MDX

Compile MDX with unifast to use JSX expressions and import statements inside Markdown, rendered with React or other JSX runtimes.

MDX lets you use JSX expressions and import statements inside Markdown. unifast compiles MDX to JavaScript modules that can be rendered with React or other JSX runtimes.

Installation

Basic Usage

import { compile } from "@unifast/node";

const source = `
# Hello

<Counter initial={0} />

export const meta = { title: "My Page" };
`;

const result = compile(source, { inputKind: "mdx" });
// result.output is a JavaScript module string

How MDX Works

MDX extends Markdown with two capabilities:

JSX expressions - Use components inline with your content.
ESM imports/exports - Import components and export metadata.

The compiler processes MDX in these steps:

MDX source
  → Parse (Markdown + JSX + ESM)
  → MdAst with JSX/ESM nodes
  → Lower to HAst
  → Emit as JavaScript module

The output is a JavaScript module with a default export function that accepts a components prop for component injection.

Using with React

import { compile } from "@unifast/node";
import { compileToReact } from "@unifast/react";

const source = `# Hello\n\nThis is **MDX**.`;

const result = compile(source, { inputKind: "mdx" });
const Component = compileToReact(result);

// Render in your React app
<Component components={{ h1: MyHeading }} />

Frontmatter in MDX

Combine MDX with the frontmatter plugin to extract metadata:

import { compile, frontmatter } from "@unifast/node";

const source = `---
title: My Article
author: Jane
---

# {frontmatter.title}

Written by {frontmatter.author}.
`;

const result = compile(source, {
  inputKind: "mdx",
  plugins: [frontmatter()],
});

console.log(result.frontmatter);
// { title: "My Article", author: "Jane" }