Skip to content
A Metalsmith plugin to convert markdown files. – This plugin is up for adoption.
JavaScript Makefile
Branch: master
Clone or download
This branch is 51 commits ahead, 46 commits behind segmentio:master.

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


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

Build Status


A Metalsmith plugin to convert markdown files using markdown-it library.

This plugin is not one to one replacement for metalsmith-markdown. There are slight differences in how the underlying libraries behave, but I find I get better results with markdown-it. Markdown-it, however, does not support all GFM features.


$ npm install metalsmith-markdownit

CLI Usage

Install via npm and then add the metalsmith-markdownit key to your metalsmith.json plugins with any markdown-it options you want, like so:

  "plugins": {
    "metalsmith-markdownit": {
      "typographer": true,
      "html": true

Javascript Usage

Pass options to the markdown plugin and pass it to Metalsmith with the use method:

var markdown = require('metalsmith-markdownit');

  typographer: true,
  html: true

You can also pass a markdown-it preset to the plugin:

var markdown = require('metalsmith-markdownit');

metalsmith.use(markdown('default', {
  typographer: true,
  html: true

If you want to control plugin behaviour, you can set options under the plugin key of the options object (these options are not passed to Markdown It):

metalsmith.use(markdown('default', {
  typographer: true,
  html: true,
  plugin: {
    // options.plugin.pattern (string) - glob pattern. Defaults to '**/*@(md|markdown)'
    pattern: '**/*.html',  
    // options.plugin.fields (string|Array) - field or list of fields to parse with Markdown-It. Defaults to 'contents'
    fields: ['contents', 'excerpt']  
    // options.plugin.extension (string) - the file extension for parsed files. Defaults to 'html'
    extension: 'htm'

If you need access to markdown-it directly to enable features or use plugins, you can access the parser directly:

var markdown = require('metalsmith-markdownit');

var md = markdown('zero', { html: true });
md.parser.enable(['emphasis', 'html_block', 'html_tag']);


The parser's enable, disable, use and set methods are proxied on the metalsmith plugin, so you may access them like so:

var markdown = require('metalsmith-markdownit');

metalsmith.use(markdown('zero', {html: true}).enable('emphasis', 'html_block', 'html_tag'))

You may provide a function to set the parser & renderer's environment on a per-page basis, should you need to:

var markdown = require('metalsmith-markdownit');

metalsmith.use(markdown('default').env(function(page){ return page; }))



You can’t perform that action at this time.