An Eleventy plugin for processing Markdown files with markdown-it.
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'));
};
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 }}
.
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.
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 }]
]
});
};
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'
}
});
};
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);
}
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.