README

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

Additionally, you can render markdown to HTML in file metadata keys by specifying the keys option:

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

A file article.md with front-matter:

---
html_desc: A **markdown-enabled** _description_
---

would transform html_desc to A <b>markdown-enabled</b> <i>description</i>.

Custom markdown rendering

You can use a custom renderer by of 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

Usage no npm install needed!