@metalsmith/markdown

A Metalsmith plugin to render markdown files to HTML, using Marked.

Installation

NPM:

npm install @metalsmith/markdown

Yarn:

yarn add @metalsmith/markdown

Usage

const markdown = require('@metalsmith/markdown')

metalsmith.use(
  markdown({
    highlight: function (code) {
      return require('highlight.js').highlightAuto(code).value
    },
    pedantic: false,
    gfm: true,
    tables: true,
    breaks: false,
    sanitize: false,
    smartLists: true,
    smartypants: false,
    xhtml: false
  })
)

Options

@metalsmith/markdown is powered by Marked, and you can pass any of the Marked options to it, including the 'pro' options: renderer, tokenizer, walkTokens and extensions.

You can render markdown to HTML in file metadata keys by specifying the keys option.
The keys option also supports dot-delimited key-paths.

metalsmith.use(
  markdown({
    keys: ['html_desc', 'nested.data']
  })
)

You can even render all keys at a certain path by setting the wildcard option and using a globstar * in the keypaths.
This is especially useful for arrays like the faq below:

metalsmith.use(
  markdown({
    wildcard: true,
    keys: ['html_desc', 'nested.data', 'faq.*.*']
  })
)

A file page.md with front-matter:

---
html_desc: A **markdown-enabled** _description_
nested:
  data: '#metalsmith'
faq:
  - q: '**Question1?**'
    a: _answer1_
  - q: '**Question2?**'
    a: _answer2_
---

would be transformed into:

{
  "html_desc": "A <strong>markdown-enabled</strong> <em>description</em>\n",
  "nested": {
    "data": "<h1 id=\"metalsmith\">metalsmith</h1>\n"
  },
  "faq": [
    { "q": "<p><strong>Question1?</strong></p>\n", "a": "<p><em>answer1</em></p>\n"},
    { "q": "<p><strong>Question2?</strong></p>\n", "a": "<p><em>answer2</em></p>\n"}
  ],

Notes about the wildcard

• It acts like the single bash globstar. If you specify * this would only match the properties at the first level of the metadata.
• If a wildcard keypath matches a key whose value is not a string, it will be ignored.
• It is set to false by default because it can incur some overhead if it is applied too broadly.

Custom markdown rendering

You can use a custom renderer by using marked.Renderer()

const markdown = require('@metalsmith/markdown')
const marked = require('marked')
const markdownRenderer = new marked.Renderer()

markdownRenderer.image = function (href, title, text) {
  return `
  <figure>
    <img src="${href}" alt="${title}" title="${title}" />
    <figcaption>
      <p>${text}</p>
    </figcaption>
  </figure>`
}

metalsmith.use(
  markdown({
    renderer: markdownRenderer,
    pedantic: false,
    gfm: true,
    tables: true,
    breaks: false,
    sanitize: false,
    smartLists: true,
    smartypants: false,
    xhtml: false
  })
)

CLI Usage

Add @metalsmith/markdown key to your metalsmith.json plugins key

{
  "plugins": {
    "@metalsmith/markdown": {
      "pedantic": false,
      "gfm": true,
      "tables": true,
      "breaks": false,
      "sanitize": false,
      "smartLists": true,
      "smartypants": false,
      "xhtml": false
    }
  }
}

License

MIT