Choosing Markdown in Eleventy: Default vs. markdown‑it Plugin

Decision Context

Eleventy (11ty) ships with a built‑in Markdown processor powered by the marked library. For many sites this is sufficient – it is fast, has zero external dependencies, and works out of the box. However, if your content requires advanced Markdown features such as footnotes, definition lists, or custom syntax extensions, you’ll need a more feature‑rich parser. The @11ty/eleventy-plugin-markdown‑it plugin brings in markdown‑it and its extensive plugin ecosystem.

Key decision factors:

• Feature requirements (footnotes, definition lists, custom syntax)
• Build performance (parse time, bundle size)
• Dependency management and version compatibility
• Configuration simplicity and maintainability

Option Comparison

Feature	Default (marked)	markdown‑it plugin
Footnotes	Not supported	Supported via markdown-it-footnote
Definition lists	Not supported	Supported via markdown-it-deflist
Custom syntax highlighting	Limited – relies on markdown-it-highlightjs via marked extensions	Full control via markdown-it-highlightjs or any markdown-it plugin
Dependency overhead	None – part of Eleventy core	Adds markdown‑it and any chosen plugins
Build time impact	Fast – marked is highly optimised	Marginally slower; measurable on large sites
Ecosystem support	Limited – marked has few official plugins	Rich – dozens of community plugins available
Configuration simplicity	Minimal – no extra config needed	Requires plugin registration in .eleventy.js

Trade‑offs

• Speed vs. Features: The default parser is faster but lacks advanced syntax. The plugin adds a small performance penalty but unlocks many extensions.
• Dependency Management: Keeping the default reduces external dependencies, lowering the risk of version drift. The plugin introduces markdown‑it and any chosen extensions, so you must maintain those packages.
• Consistency: Using markdown‑it ensures that all Markdown rendering across the site follows the same rules, which is beneficial if you have a large team or many contributors.
• Future‑proofing: The markdown‑it ecosystem is actively maintained and offers plugins for emerging Markdown features, giving you more flexibility as your content evolves.

Implementation Example

Below is a minimal .eleventy.js configuration that registers the markdown‑it plugin with a couple of common extensions. The example assumes you’re using Eleventy version 0.12.0 or newer.

// .eleventy.js
const markdownItPlugin = require('@11ty/eleventy-plugin-markdown-it');

module.exports = function(eleventyConfig) {
  // Register the markdown‑it plugin with desired extensions
  eleventyConfig.addPlugin(markdownItPlugin, {
    // Enable the footnote and definition list extensions
    markdownItOptions: {
      html: true,
      linkify: true,
      typographer: true
    },
    markdownItPlugins: [
      require('markdown-it-footnote'),
      require('markdown-it-deflist'),
      // Add syntax highlighting if desired
      require('markdown-it-highlightjs')
    ]
  });

  // Optional: keep Eleventy’s default Markdown for non‑Markdown files
  eleventyConfig.setLibrary('md', require('marked'));
};

To add the plugin, run:

npm install @11ty/eleventy-plugin-markdown-it markdown-it-footnote markdown-it-deflist markdown-it-highlightjs

Validation Checklist

1. Create a test Markdown file (e.g., test.md in your source directory):

   # Test Page
   
   This is a footnote example[^1].
   
   [^1]: Footnote content.
   
   My list:
   
   - Item 1
   - Item 2
   
   Definition list:
   
   Term 1
   : Definition 1
   
   Term 2
   : Definition 2
   

2. Run the build:

   npx eleventy --serve

3. Inspect the output:
   • Navigate to the generated page (e.g., http://localhost:8080/test.html).
   • Verify that the footnote link appears and that the definition list renders as an <dl> element.
   • Check that syntax highlighting is applied to any code blocks.
4. Benchmark (optional):

   For large sites, compare build times before and after adding the plugin to ensure the performance impact is acceptable.

Limitations & Checklist

• Eleventy must be 0.12.0+ to load the plugin correctly. Older versions may throw a "cannot find module" error.
• Adding markdown‑it increases the bundle size; monitor dependency updates to avoid security regressions.
• Some markdown‑it plugins may conflict with each other or with Eleventy’s own Markdown handling. Test thoroughly when adding multiple extensions.
• If you only need a single feature (e.g., footnotes), consider using Eleventy's addPlugin with a lightweight custom renderer instead of pulling in the entire markdown‑it ecosystem.

In summary, choose the default marked parser for speed and minimal maintenance when your content is plain Markdown. Opt for the markdown‑it plugin when you need advanced syntax, a unified extension ecosystem, or consistent rendering across a large site. The decision hinges on your feature requirements, build performance tolerance, and willingness to manage additional dependencies.