Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Stable
2.0.1
Toggle Menu
Eleventy 1.93s
Gatsby 29.05s

Markdown

Contents

Eleventy Short Name File Extension npm Package
md .md markdown-it
  • Related languages: MDX
INFO:
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

Default Options

  • html: true (markdown-it default is false)

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

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

eleventy.config.js
import markdownIt from "markdown-it";

export default function (eleventyConfig) {
let options = {
html: true,
breaks: true,
linkify: true,
};

eleventyConfig.setLibrary("md", markdownIt(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 Added in v2.0.0

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

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.
const markdownItEmoji = require("markdown-it-emoji");

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

Indented Code Blocks

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)

After listening to community feedback, starting with Eleventy 2.0.0 Indented Code Blocks are disabled for both the default Markdown library instance and any set via setLibrary.

Want to re-enable Indented Code Blocks?
WARNING:
Careful! This feature is (almost) universally disliked.

To re-enable Indented Code Blocks in Eleventy 2.0 (or newer), use the amendLibrary approach. Make sure you read through the warning documented below to understand the ramifications.

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

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.
`
;
});
Want to disable Indented Code Blocks on Eleventy v1 or older?
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?

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