Configure markdown footnotes in eleventy

Eleventy's markdown docs are an excellent resource for setting up a basic markdown configuration but don't include info on setting up footnotes in markdown.

What are footnotes and why use them?

Footnotes are:

a note printed at the bottom of a page that gives extra information about something that has been written on that page. ^[1]

Many people use footnotes for detailed comments and endnotes for citation of sources, without cluttering the body of the document.

The config

To get footnotes working in Eleventy, you need to configure the markdown-it markdown library to use a plugin called markdown-it-footnote, all set up in your .eleventy.js file, inside your exported config function:

module.exports = function (config) {
  // set markdown footnote processor
  let markdownIt = require("markdown-it");
  let markdownItFootnote = require("markdown-it-footnote");
  
  let options = {
    html: true, // Enable HTML tags in source
    breaks: true,  // Convert '\n' in paragraphs into <br>
    linkify: true // Autoconvert URL-like text to links
  };
  
  // configure the library with options
  let markdownLib =  markdownIt(options).use(markdownItFootnote);
  // set the library to process markdown files
  config.setLibrary("md", markdownLib);

  //rest of your config here...
};

What this does

First, you need to require the markdown library and plugin, setting then to variables used later in the config.

Then we set up some options - none of these are footnote specific, so in theory this could be empty, but the options are passed into markdown-it when we tell it to use the footnote plugin. See a full list of markdown-it options you can use.

Then set the markdown library to be markdownIt, and to use the footnote plugin. Set that to process any md files you may have.

Using footnotes references in markdown

in your markdown add a caret and identifier inside square brackets [^1] where you want the footnote to be. Identifiers are often numbers, but you can use words also. For the footnote itself, you use the exact same syntax, but add a colon after it followed by your footnote text [^1]: foo.

Footnotes themselves can be inserted anywhere, and will always be rendered at the bottom of your page.

Example

The footnote number should always be inserted after the punctuation. [^2]

[^2]: Like that. 

this text will be above the footnote in the output, 
which is rendered at the bottom of the page.

Output

The footnote number should always be inserted after the punctuation. ^[2]

this text will be above the footnote in the output, which is rendered at the bottom of the page.

Advanced use

Rendering unique footnotes across documents through namespacing

In most cases, footnotes are rendered in a single document, with unique footnote references.

However, if you wanted to render a long list of documents in a single view, you could end up with clashes if you used the same footnote identifier (common if you use numbers like 1).

Solution: eleventy provides a way of namespacing documents through addition of a unique docId in your YAML declaration at the top of your markdown.

Example:

docId: 'i-am-unique'

...results in the following namespaced HTML footnote link

<a href="#fn-i-am-unique-1" id="fnref-i-am-unique-1">[1]</a>