Markdown

• Related languages: MDX

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.

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.

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

// 🛑 Bad, don’t do this
eleventyConfig.addShortcode("badShortcode", function () {
	return `
    This is a code block in a markdown file!
`;
});

// ✅ This will return expected output
eleventyConfig.addShortcode("goodShortcode", function () {
	return `
This will not be a code block in a markdown file.
`;
});

// ✅ This is also acceptable
eleventyConfig.addShortcode("alsoGoodShortcode", function () {
	return outdent`
    This will not be a code block in a markdown file.
`;
});

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?

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.

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

	// Method B: ⚠️ Careful when wrapping with HTML
	return `<div>${content}</div>`;
});

{% 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:

• HTML
• Markdown
  • MDX
• WebC
• JavaScript
  • JSX
  • TypeScript
• Nunjucks
• Liquid
• Handlebars
• Mustache
• EJS
• HAML
• Pug
• Custom

Related Docs

• Default Template Engine for Markdown Files