A Metalsmith plugin to convert markdown files.
Last updated 2 years ago by mayo .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install metalsmith-markdownit 
SYNC missed versions from official npm registry.

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; }))



Current Tags

  • 0.5.0                                ...           latest (2 years ago)

7 Versions

  • 0.5.0                                ...           2 years ago
  • 0.4.0                                ...           4 years ago
  • 0.3.0                                ...           5 years ago
  • 0.1.3                                ...           5 years ago
  • 0.1.2                                ...           5 years ago
  • 0.1.1                                ...           6 years ago
  • 0.1.0                                ...           6 years ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 35
Dependencies (3)
Dev Dependencies (4)

Copyright 2014 - 2016 © |