Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


A Metalsmith plugin to render markdown files to HTML, using Marked (by default).

metalsmith: core plugin npm: version ci: build code coverage license: MIT


  • Compiles .md and .markdown files in metalsmith.source() to HTML.
  • Enables rendering file metadata keys to HTML through the keys option
  • Define a dictionary of markdown globalRefs (for links, images) available to all render targets
  • Supports using the markdown library of your choice through the render option



npm install @metalsmith/markdown


yarn add @metalsmith/markdown


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

import markdown from '@metalsmith/markdown'
import hljs from 'highlight.js'

// use defaults

// use explicit defaults
  wildcard: false,
  keys: [],
  engineOptions: {}

// custom
    engineOptions: {
      highlight: function (code) {
        return hljs.highlightAuto(code).value
      pedantic: false,
      gfm: true,
      tables: true,
      breaks: false,
      sanitize: false,
      smartLists: true,
      smartypants: false,
      xhtml: false

@metalsmith/markdown provides the following options:

  • keys: Key names of file metadata to render to HTML in addition to its contents - can be nested key paths
  • wildcard (default: false) - Expand * wildcards in keys option keypaths
  • globalRefs - An object of { refname: 'link' } pairs that will be available for all markdown files and keys, or a metalsmith.metadata() keypath containing such object
  • render - Specify a custom render function with the signature (source, engineOptions, context) => string. context is an object with the signature { path:string, key:string } where the path key contains the current file path, and key contains the target metadata key.
  • engineOptions Options to pass to the markdown engine (default marked)

Rendering file metadata

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

    keys: ['html_desc', '']

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:

    wildcard: true,
    keys: ['html_desc', '', 'faq.*.*']

A file with front-matter:

html_desc: A **markdown-enabled** _description_
  data: '#metalsmith'
  - 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.

Defining a dictionary of markdown globalRefs

Markdown allows users to define links in reference style ([]:).
In a Metalsmith build it may be especially desirable to be able to refer to some links globally. The globalRefs options allows this:

    globalRefs: {
      twitter_link: '',
      github_link: '',
      photo: '/assets/img/me.png'

Now contents of any file or metadata key processed by @metalsmith/markdown will be able to refer to these links as [My Twitter][twitter_link] or ![Me][photo]. You can also store the globalRefs object of the previous example in a metalsmith.metadata() key and pass its keypath as globalRefs option instead.

This enables a flow where you can load the refs into global metadata from a source file with @metalsmith/metadata, and use them both in markdown and templating plugins like @metalsmith/layouts:

    global: {
      links: {
        twitter: '',
        github: ''
  // eg in a markdown file: [My Twitter profile][twitter]
  .use(markdown({ globalRefs: 'global.links' }))
  // eg in a handlebars layout: {{ global.links.twitter }}

Custom markdown rendering

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

import markdown from '@metalsmith/markdown'
import { marked } from 'marked'
const markdownRenderer = new marked.Renderer()

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

    engineOptions: {
      renderer: markdownRenderer,
      pedantic: false,
      gfm: true,
      tables: true,
      breaks: false,
      sanitize: false,
      smartLists: true,
      smartypants: false,
      xhtml: false

Using another markdown library

If you don't want to use marked, you can use another markdown rendering library through the render option. For example, this is how you could use markdown-it instead:

import MarkdownIt from 'markdown-it'

let markdownIt
  render(source, opts, context) {
    if (!markdownIt) markdownIt = new MarkdownIt(opts)
    if (context.key == 'contents') return mdIt.render(source)
    return markdownIt.renderInline(source)
  // specify markdownIt options here
  engineOptions: { ... }


To enable debug logs, set the DEBUG environment variable to @metalsmith/markdown*:

metalsmith.env('DEBUG', '@metalsmith/markdown*')

CLI Usage

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

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