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 app. It simplifies the use of MDX content by handling compilation, caching, and offering server and client components for runtime.

Quickstart

npm i @content-collections/mdx -D

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],
});

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>
  );
}

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. 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.

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.