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: [],
usesSrc: false
extendFrontMatter: {
process: (mdxContent, frontMatter) => {},
phase: 'prebuild|loader|both',
},
reExportDataFetching: false,
})(/* 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.
usesSrc
boolean
| optional | default:checks for src/pages to set the flag
It dictates if next mdx enhanced should use the src/pages for looking for the pages' folder. Otherwise, it will use the pages in the top-level directory. Also, if not set, it automatically checks for the src/pages directories.
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.
reExportDataFetching
boolean
| optional
If you export getStaticProps
and/or getServerSideProps
from your layout, and wish for those to be re-exported from each of your mdx pages, set this option to true
.
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:
// This function must be named otherwise it disables Fast Refresh.
export default function DocsPage({ children, frontMatter }) {
// React hooks, for example `useState` or `useEffect`, go here.
return (
<div>
<h1>{frontMatter.title}</h1>
{children}
</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.