Eleventy The possum is Eleventy’s mascot

Eleventy Documentation

This is an older version of Eleventy. Go to the newest Eleventy docs (current path: /docs/languages/markdown/) or the full release history.
Menu

Markdown

Template Languages:

Eleventy Short NameFile ExtensionNPM Package
md.mdmarkdown-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 #

Default Options #

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

Optional: Set your own library instance New in v0.3.0 #

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

module.exports = function(eleventyConfig) {
let markdownIt = require("markdown-it");
let options = {
html: true,
breaks: true,
linkify: true
};

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

Add your own plugins New in v0.3.0 #

Pass in your own markdown-it plugins using the setLibrary Configuration API method (building on the method described in “Using your own options”).

  1. Find your own markdown-it plugin on NPM
  2. npm install the plugin.
module.exports = function(eleventyConfig) {
let markdownIt = require("markdown-it");
let markdownItEmoji = require("markdown-it-emoji");
let options = {
html: true
};
let markdownLib = markdownIt(options).use(markdownItEmoji);

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

There are extra <pre> and <code> in my output #

This is a Common Pitfall.

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)

That means 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.
`
;
});

If your content indentation is still irregular and you do need to disable indented code blocks, you can do so by configuring your markdown-it instance to disable the code rule (following the "Set your own library instance" procedure above).

let markdownLib = markdownIt(options).disable('code');

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

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