@saschazar/next-mdx-extended
v4.0.0
Published
Easily wrap MDX pages in React components
Downloads
5
Readme
📦 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 anindex.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