npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@saschazar/next-mdx-extended

v4.0.0

Published

Easily wrap MDX pages in React components

Downloads

5

Readme

Build Status npm version codecov

📦 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