eleventy-plugin-markdown

An Eleventy plugin for processing Markdown files with markdown-it.

Usage

First, add the plugin as a development dependency to your project's package.json file:

npm install --save-dev @jgarber/eleventy-plugin-markdown

Next, add the plugin to your project's Eleventy configuration file (e.g. eleventy.config.js):

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(require('@jgarber/eleventy-plugin-markdown'));
};

Filters

With no additional configuration, eleventy-plugin-markdown will configure markdown-it and add a markdown filter for use in your Eleventy project's templates.

In a JavaScript template (e.g. post.11ty.js), you might use the markdown filter to process a post's title to properly render typographic quotes. The optional second argument, 'inline', instructs the filter to use MarkdownIt.renderInline which will not wrap the output in a <p> element.

module.exports = class {
  render({ collections }) {
    const post = collections.post[0];

    return JSON.stringify({
      title: this.markdown(post.data.title, 'inline')
    });
  }
};

Or, in a Liquid template (e.g. post.liquid):

<title>{{ post.data.title | markdown: "inline" }}</title>

[!TIP] Omit the inline argument/option to wrap the processed output in <p> elements. Using the examples above: this.markdown(post.data.title) and {{ post.data.title | markdown }}.

Options

| Name | Type(s) | Default | |:----------|:---------|:--------------------------------------------------| | preset | String | default | | options | Object | { breaks: true, html: true, typographer: true } | | plugins | Array | [] | | rules | Object | {} |

See the MarkdownIt.new documentation for details on additional preset and options values.

Plugins

The plugins option accepts an Array whose elements may be plugin functions or an Array of a plugin function and an Object of options. Each element in the plugins Array is passed directly to MarkdownIt.use.

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(require('@jgarber/eleventy-plugin-markdown'), {
    plugins: [
      require('markdown-it-footnote'),
      [require('markdown-it-handle'), { attributes: false }]
    ]
  });
};

Renderer Rules

The rules option accepts an Object whose keys are tokens and values are functions conforming to markdown-it's Renderer#rules interface. Various plugins (like markdown-it-footnote) support this kind of customization.

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(require('@jgarber/eleventy-plugin-markdown'), {
    plugins: [require('markdown-it-footnote')],
    rules: {
      footnote_block_open: () => `<h2>Footnotes</h2>\n<ol class="footnotes">\n`,
      footnote_block_close: () => '</ol>\n'
    }
  });
};

ESM Support

Eleventy v3.0.0 added bundler-free ESM support. This plugin works with either ESM or CommonJS projects!

import markdownPlugin from '@jgarber/eleventy-plugin-markdown';

export default async function(eleventyConfig) {
  eleventyConfig.addPlugin(markdownPlugin);
}

Acknowledgments

First and foremost, eleventy-plugin-markdown wouldn't be possible without Zach Leatherman's incredible work creating Eleventy and his stewardship of its community.

eleventy-plugin-markdown is written and maintained by Jason Garber.