{Werner Glinka}

Introducing Metalsmith MDN

Enhancing Markdown with embedded Nunjucks Components

Markdown is an important tool for developers and writers, prized for its simplicity and efficiency in writing web content. However, its inherent limitations in handling long-form content, particularly in incorporating reusable Page Sections, have posed challenges. Enter MDN, a brand new Metalsmith plugin inspired by MDX, creating the way of embedding reusable Section Components within Metalsmith markdown content.

Leveraging the robust capabilities of Nunjucks templating, MDN empowers creators to overcome markdown's traditional limitations, enabling unprecedented flexibility in Metalsmith content creation.

Introduction to Section Components

For those unfamiliar, Section Components are reusable blocks of code that can define a portion of a webpage, like a header, footer, or a specific content section. They promote efficiency and consistency across web pages. MDN allows you to reuse these components directly in your markdown files, bridging the gap between simple markdown content and dynamic template features. This is particularly useful for long text pages where you want to maintain a consistent look and feel with the rest of your site.

Getting Started with MDN

Installation

npm install metalsmith-mdn

Usage

Once installed, you can incorporate MDN into your Metalsmith build process. MDN should be used immediately before the markdown plugin to ensure proper processing of your content. Here's a quick setup example:

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

Metalsmith(__dirname)
  ...
  .use(MDN({
    templatesDir: "layouts",
    customFilters: "nunjucks-filters.js",
  }))
  .use(markdown())
  ...

This setup tells Metalsmith to use MDN with specified options for template directory and custom Nunjucks filters, followed by the markdown plugin to process the markdown files.

Configuration Options

  • templatesDir: This option specifies the directory where your Nunjucks templates are stored, relative to the Metalsmith root. The default is "layouts" if not specified.
  • customFilters: If you have custom Nunjucks filters, you can specify the filename here. The file should be in the Metalsmith root directory, defaulting to "nunjucks-filters.js" if not set.

Implementing Section Components in Markdown

To use a section component in your markdown, simply include it using the mdn tag within your markdown file. Here's how:

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 this example, the mySectionComponent defined in the frontmatter is included in the markdown content using the {#mdn "mySectionComponent" #} tag. This component is defined in the sections/intro.njk file and uses a text macro from another template for processing its content.

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 %}

The Result

After processing, the markdown content along with the included section component is transformed into HTML. The section component's content is rendered according to the props defined in the markdown file's frontmatter, seamlessly integrating with the markdown content.

index.html

<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>

By adopting MDN in your Metalsmith projects, you can significantly enhance your markdown files, making them more dynamic and reusable. This approach not only improves the efficiency of content creation but also ensures consistency across your website, providing a richer experience for both developers and end-users.

The plugin is available on GitHub and can be installed via npm. Give it a try and see how MDN can revolutionize your Metalsmith content creation process!

Scroll to top