mdx.mdx

---
title: MDX
---

The `@content-collections/mdx` package offers a function to compile MDX content within the `transform` function and provides runtime components for displaying MDX content in a [React](https://reactjs.org) app. It simplifies the use of MDX content by handling compilation, caching, and offering server and client components for runtime.

## Quickstart

<div className="steps">
<div className="step">

Install the package:

```package-install
npm i @content-collections/mdx -D
```

</div>
<div className="step">

Transform the content to a MDX component:

```ts
import { defineCollection, defineConfig } from "@content-collections/core";
import { compileMDX } from "@content-collections/mdx";

const posts = defineCollection({
  name: "posts",
  directory: "content",
  include: "*.mdx",
  schema: (z) => ({
    title: z.string(),
  }),
  transform: async (document, context) => {
    const mdx = await compileMDX(context, document);
    return {
      ...document,
      mdx,
    };
  },
});

export default defineConfig({
  collections: [posts],
});
```

</div>
<div className="step">

Use the generated MDX in your application.

```tsx
import { allPosts } from "content-collections";
import { MDXContent } from "@content-collections/mdx/react";

export default function App() {
  return (
    <main>
      <h1>Posts</h1>
      <ul>
        {allPosts.map((post) => (
          <li key={post._meta.path}>
            <h2>{post.title}</h2>
            <MDXContent code={post.mdx} />
          </li>
        ))}
      </ul>
    </main>
  );
}
```

</div>
</div>

## API

The package includes two parts: the `compileMDX` function for use in the transform function, and runtime components for rendering MDX content.

### compileMDX

The function, `compileMDX`, which takes two required arguments: the context object and the document and a third optional argument, the options object.

The document must have a `content` field of the type `string` and should contain the raw MDX content. The document also needs to have the `_meta` field with the file information. In most uses cases the document which is passed to the transform function can be used directly.

The context object is required to cache the compiled HTML. The context object is passed to the transform function and should be passed to the `compileMDX` function.

The options object is optional and can be used to tweak the output of the compiled MDX. The options object can have the following properties:

#### `remarkPlugins` (optional)

An array of remark plugins to use. The default value is an empty array.

#### `rehypePlugins` (optional)

An array of rehype plugins to use. The default value is an empty array.

#### `cwd` (optional)

The current working directory.

#### `files` (optional)

A function which takes a file appender as an argument. The file appender can be used to add additional imports to the compilation. The appender provides the following methods:

- `appender.content(importPath: string, content: string)`: Add an import with the provided content.
- `appender.file(importPath: string, filePath: string)`: Add an import with the content from the file system.
- `appender.directory(importPath: string, directoryPath: string)`: Add each file as import from the directory.

It is not neccessary to use plugins for frontmatter, because the frontmatter is already parsed by Content Collections.

The `compileMDX` function returns a promise that resolves to a string with the compiled MDX component.

## Runtime Components

The package includes runtime components for the use with [React](https://reactjs.org/). The runtime parts are located in the `@content-collections/mdx/react` module.

### MDXContent

The `MDXContent` component is used to render the compiled MDX content. The component takes the following props:

#### `code` (required)

The compiled MDX content as a string.

#### `components` (optional)

An object containing components for MDX content. The components prop can override the default components. For more details, refer to the [MDX documentation](https://mdxjs.com/table-of-components/#components).

### useMDXComponent

The `useMDXComponent` hook is requires the raw MDX content as parameter and returns a React component. The component can be used to render the MDX content. The hook takes the following arguments:

#### `components` (optional)

An object containing components for MDX content. The components prop can override the default components. For more details, refer to the [MDX documentation](https://mdxjs.com/table-of-components/#components).