@saschazar/next-mdx-extended

📦 Next.js MDX extended plugin

Easily wrap MDX pages in React components for Next.js

A Next.js plugin for wrapping Markdown/MDX files in React components, with URL rewriting options. Now supporting serverless Next.js rewrites.

Features

This project was heavily influenced by @next/mdx and of course next-mdx-enhanced.

The underlying standalone Webpack loader may be found here: @saschazar/mdx-extended-loader.

Features	@saschazar/next-mdx-extended	@next/mdx
.md files	✔️	✔️
.mdx files	✔️	✔️
custom layouts	✔️	✖️
URL rewriting	✔️	✖️
generating a JSON Feed	✔️	✖️

Given the following project tree:

MyApp
|
├─ pages
|  ├ index.jsx
|  ├ about.mdx
|  ├─ blog
|     ├ 2020-01-01_first-blog-post.mdx
|
├─ layouts
   ├ index.jsx
   ├ custom.jsx

Without any custom options, both .mdx files would be wrapped in layouts/index.jsx and the final HTML root would look like this:

├  index.html
├  about.html
├─ blog
   ├─ 2020
      ├ first-blog-post.html

Installation

yarn add @saschazar/next-mdx-extended

or

npm install --save @saschazar/next-mdx-extended

(Of course, a working Next.js environment is advised to be set up beforehand.)

Compatibility

Next v9.5

⚠️ Caution: Rewrites are out of experimental since next@~9.5.0. Therefore a major release to v4.0.0 became necessary for ensuring compatibility to next.config.js.

Next v9.4

⚠️ Caution: next@~9.4.0 changed the way of how rewrites work inside the experimental property of next.config.js. Therefore a major release bump to @saschazar/next-mdx-extended@^3.0.0 became necessary.

Usage

Create a next.config.js file in your project root:

// next.config.js
const withMDXExtended = require('@saschazar/next-mdx-extended')();

module.exports = withMDXExtended({
  pageExtensions: ['jsx', 'js', 'mdx', 'md'],
});

This will assume:

• your layouts are placed in ./layouts, with at least an index.jsx present, and
• your blog posts are placed in ./pages/blog.

For customization or enhancement of the above parameters, check the options section.

Options

The following options are all optional, and most of them are having default values set:

feed

object | optional | default: null

Whether to export a feed.json file containing a JSON Feed about the blog posts to ./public (e.g. for providing a feed in general, or fetching data about blog posts via the async getInitialProps() hook). Unset by default (and therefore not exported).

If provided, the object may contain values to every top-level JSON Feed key, whereas the items property is auto-generated. If some values are omitted, they automatically taken from the package.json (like title, description, homepage, etc...).

⚠️ TL/DR: Whenever activated, it creates a feed.json file in your ./public folder, which might cause unwanted side-effects in your git setup!

blogDir

string | optional | default: blog

The directory to look for blog posts for rewriting the paths for. Only filenames in this directory (incl. sub-directories) are getting parsed, whereas other .md/.mdx files are getting transformed into JavaScript as well, but will be served under their initial filename as URL.

format

string | optional | default: /blog/YYYY/[title]

The definition after how to rewrite the blog post URLs. Possible values are:

• YYYY: The full year, e.g. 2020 (parsed from file name).
• MM: The month, e.g. 01 (parsed from file name).
• DD: The date, e.g. 02 (parsed from file name).
• [title]: Any string wrapped in square brackets will be replaced by its value from the frontmatter metadata. If no such key is found in the metadata, the placeholder gets deleted from the final URL path. [title] refers to the second half of the filename primarily, after the date was parsed, but might as well be replaced by setting the according value in the frontmatter.

Example: /[author]/YYYY/MM/[title] expects an author key in the frontmatter metadata. If no title key is present in the metadata, the parsed title from the filename will be used.

extensions

array | optional | default: pageExtensions from the Next.js configuration

The expected file suffixes of the layout files in the layoutsDir directory.

layoutsDir

string | optional | default: layouts

The name of the directory (relative to the project root) for where to find the React components, which should later be wrapped around the .md/.mdx files.

Other options

As this project acts as a superior Next.js plugin wrapper for both @mdx-js/loader and @saschazar/mdx-extended-loader, the options object also takes specific options for those projects.

Please see both repository pages for additional options documentations, (e.g. mdPlugins, hastPlugins).

Credits

Without MDX, @next/mdx and next-mdx-enhanced, none of this would have happened, or at least in a very different way.

Also, I got inspired a lot by @mxstbr's website respository concerning the exportPathMap functionality.

License

Licensed under the MIT license.

Copyright ©️ 2020 Sascha Zarhuber