Getting Started

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.

Usage

Install Dependencies

Notice that the package doesn't include loader by default.

npm install next-docs-mdx @next/mdx @mdx-js/loader @mdx-js/react @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)

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

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

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

A Table of Contents (toc) and Structurized Data (structuredData) is 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 @next/mdx.

const withNextDocs = createNextDocs({
  mdxOptions: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex]
  }
})

Export Properties from vfile.data

A remark plugin that turns vfile.data properties into exports is applied by default, you can pass the property names via dataExports.

const withNextDocs = createNextDocs({
  dataExports: ['data']
})