Next.js + MDX Enhanced

Are you using Next.js with MDX and wanted layouts and front matter? That's exactly what this plugin will do for you! 🌟

For example, if have a site that displays content (e.g. documentation) that looks like:

MyDocsApp
├─ pages
│  ├ index.jsx
│  └ docs
│    ├ intro.mdx
│    └ advanced.mdx
├─ layouts
│  └ docs-page.jsx
└ next.config.js

And you want the following:

feature	next-mdx-enhanced	@next/mdx
MDX files render as a navigable page	✅	✅
MDX files render with a common layout	✅	❌
An index page that contains a navigable link to each MDX	✅	❌

Installation

Install the package:

$ npm install next-mdx-enhanced

Open the .gitgnore file and add the .mdx-data directory:

# .gitignore

# Ignore next-mdx-enhanced cache directory
.mdx-data

This directory is populated with cache files as an optimization.

Usage & Options

Open the next.config.js file and instantiate it as a Next.js plugin:

// next.config.js
const withMdxEnhanced = require('next-mdx-enhanced')

module.exports = withMdxEnhanced({
  layoutPath: 'layouts',
  defaultLayout: true,
  fileExtensions: ['mdx'],
  remarkPlugins: [],
  rehypePlugins: [],
  extendFrontMatter: {
    process: (mdxContent, frontMatter) => {},
    phase: 'prebuild|loader|both',
  },
})(/* your normal nextjs config */)

layoutPath

string | optional | default: layouts

The directory used to resolve the page layout when layout key present in MDX front matter. Value is resolved relative to project root.

defaultLayout

boolean | optional

Set value to true to treat index.[extension] within layoutPath as the default layout for any .mdx file that a layout has not been specified for.

fileExtensions

array | optional | default: ['mdx']

Array of file extensions that should be processed as MDX pages.

remarkPlugins

array | optional

Array of remark plugins used to transform .mdx files.

rehypePlugins

array | optional

Array of rehype plugins used to transform .mdx files.

extendFrontMatter

object | optional

Property	Type	Description
`process`	`function`	A hook function whose return value will be appended to the processed front matter. This function is given access to the source `.mdx` content as the first parameter and the processed front matter as the second parameter.
`phase`	`string`	Used to specify when to run the `process` function. Eligible values are `prebuild`, `loader`, `both`. Defaults to `both` if not specified.

scan

object | optional

Object of scan objects containing the following parameters

Property	Type	Description
`pattern`	`RegEx`	A RegEx to use for scanning `.mdx` content, enables Layout customization
`transform`	`function(match: Array[]): any` optional	An optional callback function that transforms the result of the match operation. This function is passed an Array of any matching `.mdx` content that is returned by `content.match(pattern)` operation utilizing the `pattern` RegEx.

See "Scanning MDX Content" for more details.

onContent

function(mdxContent) | optional

This function runs on each build of an MDX page. All metadata and full text content are passed to this function as its only argument.

Useful for indexing your content for site search or any other purpose where you'd like to capture content on build.

Layouts

Each MDX file may define the name of layout within its front matter.

Given an MDX page named pages/docs/intro.mdx:

---
layout: 'docs-page'
title: 'Introduction'
---

Here's some *markdown* content!

This loads the content within the layout defined at:

MyDocsApp
...
└─ layouts
   └ docs-page.jsx # SEE supported extensions below
...

The plugin's layoutPath option defaults to layouts.

The file extension of the template must be one of configured pageExtensions.

The template, defined in layouts/docs-page.jsx, looks like the following:

export default function Layout(frontMatter) {
  return ({ children: content }) => {
    // React hooks, for example `useState` or `useEffect`, go here.
    return (
      <div>
        <h1>{frontMatter.title}</h1>
        {content}
      </div>
    )
  }
}

The default export function receives the front matter object, frontMatter, as a parameter. This function returns a rendering function. The rendering function receives an object that contains the the page content as children that is destructured and reassigned to content.

Front Matter

The front matter can be imported into your index pages and your templates. This enables you to create index pages or provide navigation across all your pages.

Create an index page

Given an index page named pages/index.jsx:

MyDocsApp
├─ pages
│  ├ index.jsx
│  └ docs
│    ├ intro.mdx
│    └ advanced.mdx
├─ layouts
│  └ docs-page.jsx
└ next.config.js

With the content:

import Link from 'next/link'
import { frontMatter as introData } from './docs/intro.mdx'
import { frontMatter as advancedData } from './docs/advanced.mdx'

export default function DocsPage() {
  const docsPages = [introData, advancedData]

  return (
    <>
      <h1>Docs Index</h1>
      <ul>
        {docsPages.map((page) => (
          <li key={page.__resourcePath}>
            <Link href={formatPath(page.__resourcePath)}>
              <a>{page.title}</a>
            </Link>
          </li>
        ))}
      </ul>
    </>
  )
}

function formatPath(p) {
  return p.replace(/\.mdx$/, '')
}

This creates an index page of all the MDX pages found within docs.

Let's examine the contents of the index page step-by-step:

import { frontMatter as introData } from './docs/intro.mdx'
import { frontMatter as advancedData } from './docs/advanced.mdx'

First, the index page imports the destructured and renamed front matter from each of the docs pages. The front matter contains the title and location.

Don't repeat yourself: As the number of MDX pages grows, importing each front matter creates more maintenance that can be relieved by babel-plugin-import-glob-array. This plugin would enable you to specify this replacement those two imports with this file glob pattern: import {frontMatter as docsPages} from './docs/*.mdx'

Let's examine the code that renders each link:

export default function DocsPage() {
  const docsPages = [introData, advancedData]

  return (
    <>
      <h1>Docs Index</h1>
      <ul>
        {docsPages.map((page) => (
          <li key={page.__resourcePath}>
            <Link href={formatPath(page.__resourcePath)}>
              <a>{page.title}</a>
            </Link>
          </li>
        ))}
      </ul>
    </>
  )
}

function formatPath(p) {
  return p.replace(/\.mdx$/, '')
}

The __resourcePath is a property that stores the relative path to the MDX file and is automatically included in the front matter. The helper function formatPath strips the file extension to create a well-formed path to give to the NextJS <Link> component.

Performance tip: A description or summary field could be added to the front matter to keep the import small while enabling the index page to give a preview of the content.

This same procedure can also be done for layout files.

Implementation note: This plugin injects a babel plugin that extracts the front matter to temporary files. This removes the circular dependency created when a template imports a MDX page that imports that same template.

Scanning MDX Content

Sample next.config.js entry:

// in next.config.js
withMdxEnhanced({
  scan: [
    {
      someImportantKey: {
        pattern: /<SomeComponent.*name=['"](.*)['"].*\/>/,
        transform: (arr) => arr[1], // Optionally get a specific value back via a function;
        // if `transform` is omitted, any and all matches will be returned in an array
      },
    },
  ],
})

If an MDX page uses <SomeComponent />

---
layout: 'docs-page'
title: 'Advanced Docs'
---

import SomeComponent from '../../components/SomeComponent'

This is some _really_ **advanced** docs content!

<SomeComponent name="Find this text" />

This will produce an array of matches returned to your layout by the plugin.

__scans: {
  someImportantKey: ['Find this text']
}

Consume these values in the layout with the __scans key that is passed in attached to the front matter data.

export default function layoutWrapper(frontMatter) {
  const __scans = frontMatter.__scans
  return function Layout({ children }) {
    return (
   <>
    {/*..begin Layout..*/}
        {__scans.someImportantKey && (
          <h1>{__scans.someImportantKey}</h1> // returns <h1>Find this text</h1>
        )}
    {/*..end Layout..*/}
  </>

For more reference and an example use case please see the /scan-mdx-content/ test.

jemjam/next-mdx-enhanced