Getting Started

Learn how to use Next Docs MDX in your documentation

Introduction

Next Docs MDX is a Next.js plugin that enhances the experience of the official next/mdx package. It parses frontmatter and is bundled with several MDX plugins for building a good documentation site.

This package must be used with next-docs-zeta

Usage

Install Dependencies

npm install next-docs-mdx @types/mdx

Configuration

Add this to your next.config.mjs file:

import createNextDocsMDX from 'next-docs-mdx/config';
 
const withFumaMDX = createNextDocsMDX();
 
/** @type {import('next').NextConfig} */
const config = {
  reactStrictMode: true,
};
 
export default withFumaMDX(config);

Be Careful

The Next.js config must be a .mjs file since it requires ESM-only modules.

Define MDX Components

Create mdx-components.tsx in your root directory.

import type { MDXComponents } from 'mdx/types';
// Assume you're using Next Docs UI
import defaultComponents from 'next-docs-ui/mdx/default';
 
export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    ...defaultComponents,
    ...components,
  };
}

Resolve Files

Create a source.ts file, and use the fromMap method which returns a Page Tree and additional utilities.

Read Pages Conventions to learn how to structure your pages.

source.ts

import { map } from '@/_map';
import { fromMap } from 'next-docs-mdx/map';
 
export const { getPage, pages, tree } = fromMap(map);

The @/_map file will be generated automatically

Start Server

Start the dev server

next dev

A _map.ts file should be created. You can log and see if page tree is built correctly.

Built-in Features

Frontmatter (frontmatter), Table of Contents (toc) and Structurized Data (structuredData) are parsed and exported from MDX files by default, you can use these for implementing a search or TOC section in your docs.

Advanced Usages

MDX Plugins

You can customise the options passed to the MDX processor.

const withNextDocs = createNextDocs({
  mdxOptions: {
    remarkPlugins: [remarkMath],
    // Place it at first so that it won't be changed by rehype-pretty-code
    rehypePlugins: (v) => [rehypeKatex, ...v],
  },
});

Export Properties from `vfile.data`

A remark plugin that turns vfile.data properties into exports is applied by default, you can add additional properties to export.

const withNextDocs = createNextDocs({
  mdxOptions: {
    valueToExport: ['dataName'],
  },
});

Getting Started

On this page