Stand with Ukraine 🇺🇦
Eleventy
The possum is Eleventy’s mascot

Eleventy Documentation

Menu

Markdown

Template Languages:

Eleventy Short Name File Extension NPM Package
md .md markdown-it
Markdown files are by default pre-processed as Liquid templates. You can change this default in your configuration file (or disable it altogether). To change this for a single template and not globally, read Changing a Template’s Rendering Engine.

Markdown Options Jump to heading

Default Options Jump to heading

The only listed options here are the ones that differ from the default markdown-it options. See all markdown-it options and defaults.

Starting in Eleventy 2.0, we’ve disabled the Indented Code Blocks feature by default.

Optional: Set your own library instance Jump to heading

Pass in your own instance of the Markdown library using the Configuration API. See all markdown-it options.

const markdownIt = require("markdown-it");

module.exports = function(eleventyConfig) {
let options = {
html: true,
breaks: true,
linkify: true
};

eleventyConfig.setLibrary("md", markdownIt(options));
};

Optional: Amend the Library instance Coming soon in v2.0.0 Jump to heading

Run your own callback on the provided Library instance (the default or any provided by setLibrary above).

module.exports = function(eleventyConfig) {
eleventyConfig.amendLibrary("md", mdLib => mdLib.enable("code"));
};

Add your own plugins Jump to heading

Pass in your own markdown-it plugins using the amendLibrary (Eleventy >= 2.0) or setLibrary (Eleventy <= 1.0) Configuration API methods (building on the method described in “Options” above).

  1. Find your own markdown-it plugin on NPM
  2. npm install the plugin.
Eleventy version: >= 2.0 <= 1.0
const markdownItEmoji = require("markdown-it-emoji");

module.exports = function(eleventyConfig) {
// New in 2.0
eleventyConfig.amendLibrary("md", mdLib => mdLib.use(markdownItEmoji);
};
const markdownIt = require("markdown-it");
const markdownItEmoji = require("markdown-it-emoji");

module.exports = function(eleventyConfig) {
let options = {
html: true
};
let markdownLibrary = markdownIt(options).use(markdownItEmoji);

eleventyConfig.setLibrary("md", markdownLibrary);
};

Indented Code Blocks Jump to heading

This section changed significantly in Eleventy 2.0. You may want to backtrack to Eleventy 1.0’s markdown documentation.

Markdown has a lesser known feature called Indented Code Blocks, which means any content that is indented by four or more spaces (and has a preceding line break) will be transformed into a code block.

    a simple
indented code block

is transformed into:

<pre><code>a simple
indented code block
</code></pre>

(Example borrowed from the CommonMark Specification)

Starting with Eleventy 2.0 and newer, this feature is disabled for both the default Markdown library instance and any set via setLibrary. To renable this feature in Eleventy 2.0, use the amendLibrary approach.

Want to re-enable Indented Code Blocks? Read this lengthy Common Pitfall.

There are extra <pre> and <code> in my output Jump to heading

This is a Common Pitfall.

When using Indented Code Blocks, any content that follows this four (or more) space indent may be subject to transformation. If you pre-process your markdown using Nunjucks or Liquid or another templating engine, that means the content retrieved from an include or a shortcode may also fit this formatting. Careful when you include extra whitespace in your includes or shortcodes!

Filename .eleventy.js
// 🛑 Bad, don’t do this
eleventyConfig.addShortcode("badShortcode", function() {
return `
This is a code block in a markdown file!
`
;
});
Filename .eleventy.js
// ✅ This will return expected output
eleventyConfig.addShortcode("goodShortcode", function() {
return `
This will not be a code block in a markdown file.
`
;
});

If you still wish to indent your template literals, you can use outdent to strip each line of indentation before handing it off to the renderer.

// ✅ This is also acceptable
eleventyConfig.addShortcode("alsoGoodShortcode", function() {
return outdent`
This will not be a code block in a markdown file.
`
;
});
module.exports = function(eleventyConfig) {
eleventyConfig.amendLibrary("md", mdLib => mdLib.enable("code"));
};
For Eleventy 1.x and older: Want to disable Indented Code Blocks?
const markdownIt = require("markdown-it");

module.exports = function(eleventyConfig) {
let options = {
// … truncated for brevity
};

eleventyConfig.setLibrary("md", markdownIt(options).disable("code"));
};

Why can’t I return markdown from paired shortcodes to use in a markdown file? Jump to heading

This is a Common Pitfall.

The truth is, you can return markdown inside shortcodes (as long as the file is transforming markdown, either as a .md file extension or with templateEngineOverride). However, there is one small wrinkle that might catch you off guard.

Filename .eleventy.js
eleventyConfig.addPairedShortcode("myShortcode", function(content) {
// Method A: ✅ This works fine
return content;

// Method B: ⚠️ Careful when wrapping with HTML
return `<div>${content}</div>`;
});
Syntax Liquid, Nunjucks
{% myShortcode %}My really *important* content.{% endmyShortcode %}
  1. Method A returns: My really *important* content. which is successfully transformed as markdown into My really <em>important</em> content.
  2. Method B returns: <div>My really *important* content.</div> which markdown treats as an HTML block which cannot have nested markdown inside of it. It’s transformed into <div>My really *important* content.</div>. Read more at the CommonMark specification on HTML blocks.

Other pages in Template Languages:


Related Docs