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):

import eleventyPluginMarkdown from "@jgarber/eleventy-plugin-markdown";

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

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.

export default 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	{}

From v2.0.0, this package exports these options as defaultMarkdownOptions.

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.

import eleventyPluginMarkdown from "@jgarber/eleventy-plugin-markdown";

import markdownItFootnote from "markdown-it-footnote";
import markdownItHandle from "markdown-it-handle";

export default async function(eleventyConfig) {
  eleventyConfig.addPlugin(eleventyPluginMarkdown, {
    plugins: [
      markdownItFootnote,
      [markdownItHandle, { 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.

import eleventyPluginMarkdown from "@jgarber/eleventy-plugin-markdown";

import markdownItFootnote from "markdown-it-footnote";

export default async function(eleventyConfig) {
  eleventyConfig.addPlugin(eleventyPluginMarkdown, {
    plugins: [markdownItFootnote],
    rules: {
      footnote_block_open: () => `<h2>Footnotes</h2>\n<ol class="footnotes">\n`,
      footnote_block_close: () => '</ol>\n'
    }
  });
}

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.