README.md

July 21, 2026 · View on GitHub

Metalsmith

Metalsmith MDN

MDN is a Metalsmith plugin that lets you use Nunjucks in your markdown content. It enables the re-use of section components, the same components that you use in your page section templates can now be used in long text pages. Simply add the component props to the frontmatter of your markdown file and use the mdn tag to include the component in your markdown content.

If you are new to the concept of section components, you can read more about it on the Metalsmith Components Website and in this blog post.

Features

Process Nunjucks templates within Markdown content
Support for custom Nunjucks filters
ESM-only, requires Node >= 22. CommonJS consumers can require() it via Node 22's require(esm) support.
High Performance Parallel Processing:
- Processes multiple files simultaneously
- Renders multiple MDN tags concurrently within each file
- Non-blocking template rendering for optimal performance
100% test coverage with comprehensive test suite
Detailed error messaging for easier debugging

Installation

npm install metalsmith-mdn

This package is ESM-only and requires Node >= 22. CommonJS projects on Node 22 can still consume it with require('metalsmith-mdn') thanks to Node's require(esm) support.

Usage

Note: This plugin must be run immediately before the markdown plugin.

import Metalsmith from 'metalsmith';
import MDN from 'metalsmith-mdn';
import markdown from '@metalsmith/markdown';

Metalsmith(import.meta.dirname)
  // ...
  .use(
    MDN({
      templatesDir: 'layouts',
      customFilters: 'nunjucks-filters.js'
    })
  )
  .use(markdown());
// ...

Options

Option	Default	Description
`templatesDir`	`layouts`	The directory where your Nunjucks templates are stored, relative to the Metalsmith root
`customFilters`	`nunjucks-filters.js`	The filename of a custom Nunjucks filter file, located in the Metalsmith root directory

Examples

To add a section component to your markdown content, use the mdn tag and pass unique tag name and props as arguments.

Here is an example of a markdown file with a section component. This example uses the setup that is shown in the Usage section above.

`index.md`

---
layout: simple.njk
bodyClass: 'home'

seo:
  title: My Awesome Metalsmith Website
  description: 'Fusce Aenean Ridiculus Tristique'

mySectionComponent:
  layout: sections/intro.njk
  text:
    title: Important Information
    header: 'h2'
    subTitle: ''
    prose: |-
      Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
---

# Home page title

Donec id elit non mi porta gravida at eget metus. Donec sed odio dui. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.

{#mdn "mySectionComponent" #}

Curabitur blandit tempus porttitor. Nullam id dolor id nibh ultricies vehicula ut id elit. Vestibulum id ligula porta felis euismod semper.

In addition to page related props, the mySectionComponent tag is used to include the intro section component. The intro section component is located in the layouts/sections directory and is defined in the intro.njk file. Note that the intro section component imports the text macro.

`layouts/sections/intro.njk`

{% from "../partials/text.njk" import text %}

<section class="section-intro>
  <div class="content">
    {% set info = params %}
    {{ text(info.text) }}
  </div>
</section>

`layouts/partials/text.njk`

{% macro text(info) %}

  {% if info.title %}
    {% if info.header === "h1" %}
      <h1>{{ info.title }}</h1>
    {% elif info.header === "h2" %}
      <h2>{{ info.title }}</h2>
    {% else %}
      <h3>{{ info.title }}</h3>
    {% endif %}
  {% endif %}

  {% if info.subTitle %}
    <p class="sub-title">{{ info.subTitle }}</p>
  {% endif %}

  {% if info.prose %}
    <div>{{ info.prose | mdToHTML | safe }}</div>
  {% endif %}

{% endmacro %}

`index.html`

index.html below shows the transformed end result of the file. The intro section component, populated with the props from the frontmatter is included in the markdown content.

<h1>Home page title</h1>
<p>
  Donec id elit non mi porta gravida at eget metus. Donec sed odio dui. Morbi leo risus, porta ac consectetur ac,
  vestibulum at eros.
</p>

<section class="section-intro  ">
  <div class="content">
    <h2>Important Information</h2>
    <div>
      <p>Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
    </div>
  </div>
</section>

<p>
  Curabitur blandit tempus porttitor. Nullam id dolor id nibh ultricies vehicula ut id elit. Vestibulum id ligula porta
  felis euismod semper.
</p>

Debug

To enable debug logs, set the DEBUG environment variable to metalsmith-mdn*:

metalsmith.env('DEBUG', 'metalsmith-mdn*');

Alternatively, you can use the DEBUG environment variable directly:

DEBUG=metalsmith-mdn* node build.js

CLI usage

To use this plugin with the Metalsmith CLI, add metalsmith-mdn to the plugins key in your metalsmith.json file:

{
  "plugins": [
    {
      "metalsmith-mdn": {}
    }
  ]
}