Markdown
Template Languages:
Eleventy Short Name | File Extension | NPM Package |
---|---|---|
md |
.md |
markdown-it |
Markdown Options Jump to heading
Default Options Jump to heading
html: true
(markdown-it
default isfalse
)
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).
- Find your own
markdown-it
plugin on NPM npm install
the plugin.
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
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
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!
// 🛑 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.
`;
});
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
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 %}
- Method A returns:
My really *important* content.
which is successfully transformed as markdown intoMy really <em>important</em> content
. - 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.