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 and CommonJS support:
  • ESM: import MDN from 'metalsmith-mdn'
  • CommonJS: const MDN = require('metalsmith-mdn')
• 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

Usage

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

Metalsmith(__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 |

Example

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": {}
    }
  ]
}

Test Coverage

This project maintains high statement and line coverage for the source code. Coverage is verified during the release process using the c8 coverage tool.

Author

[email protected]

License

MIT