Markdown

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.

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 #

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!

// 🛑 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.
`;
});

Related Docs

• Default Template Engine for Markdown Files