- Stable
3.0.0
Toggle Menu
5.81s
43.36s
Markdown
Contents
Eleventy Short Name | File Extension | npm Package |
---|---|---|
md |
.md |
markdown-it |
- Related languages: MDX
Markdown Options
Default Options
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
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).
- Find your own
markdown-it
plugin on NPM 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?
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!
// 🛑 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.
`;
});
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?
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.