How can I insert and display markdown footnotes with eleventy?

[thisisgonnatakeawhile]

Hi folks,

I'm new to 11ty so please excuse if this question is very dumb. I'm trying to find a solution to having my markdown footnotes recognised as such by eleventy (I'm using nunjucks for my layouts), but by using the default standard markdown nomenclature this doesn't seem possible, and I'm having an issue with the eleventy-plugin-footnotes plugin.

Following the instructions on the plugin's github page, I've installed it via npm install eleventy-plugin-footnotes, and updated my .eleventy.js file with the provided code:

const footnotes = require('eleventy-plugin-footnotes')
module.exports = eleventyConfig => {
  eleventyConfig.addPlugin(footnotes, { /* … */ })
}

But, I'm getting this error *ParseError: tag footnoteref not found, line:4 when I copy the example provided into one of my markdown pages and save the file. Here's the example:

Something about {% footnoteref "css-counters" "CSS counters are, in essence, variables maintained by CSS whose values may be incremented by CSS rules to track how many times they’re used." %}CSS counters{% endfootnoteref %} that deserves a footnote explaining
what they are.
{% footnotes %}

The footnote doesn't appear in the website page once loaded and I know I must be doing something very obvious very wrong, but I can't wrap my head around it nor find any solution on the internet. So this is basically me trying to vanquish my shame and letting you all know you're my last hope. Thanks a lot for reading and trying to help out a fellow eleventy user.

[pdehaan]

@thisisgonnatakeawhile This worked for me (tested in LiquidJS and Nunjucks): https://github.com/pdehaan/11ty-2343

[thisisgonnatakeawhile]

Thanks heaps for taking the time to lend a hand @pdehaan .

Maybe I'm guessing incorrectly but, would it be possible that the footnotes aren't working on my end because my source files are markdown and my layout is nunjucks and not liquid? I've studied the files you provided, tried to replicate them, but still I'm getting a ParseError: tag footnoteref not found error message when inserting the lines from your liquid file, and * ParseError: tag set not found when doing so with the ones from the nunjucks one. I imagine this is to be expected since your config line layouts/base.liquid wouldn't apply to my nunjucks layout file. Is there a way to make the plugin work with .md files and a nunjucks layout?

I've replicated your repository structure and uploaded my files here (I suspect the nunjucks lines in the markdown post shouldn't be there, but I've left them there nonetheless): https://github.com/thisisgonnatakeawhile/footnotes

Thanks again for any kind reply this ignorant inquiry might get!

[pdehaan]

@thisisgonnatakeawhile If you can put your repo up on GitHub (or a simple test repo w/ errors), I can clone it and take a look.
I'm doubtful that it's a Nunjucks/Liquid-vs-Markdown issue because by default .md files should render using the liquid engine.

But, looking at my repo, that might be a thing...
https://github.com/pdehaan/11ty-2343/blob/810c8b916ce8c86b679ae309edff0f4a885b2a1c/src/nunjucks.njk#L5-L6 Is the Nunjucks version and uses {% set foo = "bar" %}.
https://github.com/pdehaan/11ty-2343/blob/810c8b916ce8c86b679ae309edff0f4a885b2a1c/src/liquid.liquid#L5-L6 is the LiquidJS version and uses {% assign foo = "bar" %}.

So if your .md files are using the default liquid rendering engine, I think you'd need to use {% assign %} tag instead of {% set %}; which might explain your error of:

ParseError: tag set not found

[pdehaan]

OK, thanks for the repo. It's actually two small-ish issues.

First, since you're using .md files (with default liquid engine), you need to use the {% assign %} tag instead of the Nunjucks {% set %} tag.

-{%- set eleventy_footnote = "[Eleventy](https://11ty.dev/) is pretty neat. Try it out today!" | markdown -%}
-{%- set zachleat_footnote = "[Zach on Twitter](https://twitter.com/zachleat)" | markdown -%}
+{%- assign eleventy_footnote = "[Eleventy](https://11ty.dev/) is pretty neat. Try it out today!" | markdown -%}
+{%- assign zachleat_footnote = "[Zach on Twitter](https://twitter.com/zachleat)" | markdown -%}

Second, your .eleventy.js was slightly inaccurate as you had two [conflicting] module.exports = (eleventyConfig) => { ... }; blocks

diff --git a/.eleventy.js b/.eleventy.js
index be6fc9b..5486293 100644
--- a/.eleventy.js
+++ b/.eleventy.js
@@ -5,18 +5,16 @@ const md = markdownIt({
     html: true,
     linkify: true,
   });
-module.exports = eleventyConfig => {
-    eleventyConfig.addLayoutAlias("base", "layouts/base.liquid");
-    eleventyConfig.addGlobalData("layout", "base");
+
+module.exports = function (eleventyConfig){
     eleventyConfig.addPlugin(footnotes, { /* … */ });
     eleventyConfig.addFilter("markdown", function (markup) {
       return md.renderInline(markup);
     });
-};
-module.exports = function (eleventyConfig){
+
     eleventyConfig.addPassthroughCopy('./src/css/');
     eleventyConfig.addPassthroughCopy('./src/js/');
-    eleventyConfig.addPassthroughCopy('./src/assets');
+    // eleventyConfig.addPassthroughCopy('./src/assets');
     eleventyConfig.addCollection("orderedPost", function (collection) {
         return collection.getFilteredByTag("post").sort((a, b) => {
           return a.data.order - b.data.order;

Or, since that's a not very clear diff, this is what your .eleventy.js file should look like:

const { DateTime } = require("luxon");
const footnotes = require('eleventy-plugin-footnotes');
const markdownIt = require("markdown-it");

const md = markdownIt({
    html: true,
    linkify: true,
  });

module.exports = function (eleventyConfig){
    eleventyConfig.addPlugin(footnotes, { /* … */ });
    eleventyConfig.addFilter("markdown", function (markup) {
      return md.renderInline(markup);
    });

    eleventyConfig.addPassthroughCopy('./src/css/');
    eleventyConfig.addPassthroughCopy('./src/js/');
    // eleventyConfig.addPassthroughCopy('./src/assets');
    eleventyConfig.addCollection("orderedPost", function (collection) {
        return collection.getFilteredByTag("post").sort((a, b) => {
          return a.data.order - b.data.order;
        });
    });
    eleventyConfig.addFilter("postDate", (dateObj) => {
        return DateTime.fromJSDate(dateObj).toLocaleString(DateTime.DATE_FULL);
    });
    return{
        dir:{
            input: "src",
            output: "public",
        }
    };
}

If you have two module.exports = function (eleventyConfig){ blocks, the second one will overwrite the first, which means your footnotes plugin wouldn't be recognized, and same with your custom markdown filter.

[thisisgonnatakeawhile]

Omg, you're a godsend @pdehaan. Thanks for taking the time to investigate, point out the issues with my file, and post a valid solution. I wouldn't have figured it out after a million headaches. Thank you so much!!!!

[thiagomgd]

I think the source files can be markdown, as long as your layout file is liquid. With that being said, if you use markdown and you (probably) use markdown-it for rendering it, you can just add markdown-it-footnote. Do npm install and then customize the config. This is mine, with some extra plugins removed:

const markdownLibrary = markdownIt({
    html: true,
    breaks: true,
    linkify: true
  }).use(markdownItFootnote);

[thiagomgd]

If you use markdown-it-footnote, the footnotes are going to work in any template/layout, because they are part of the article. The footer section will be part of the html that's generated by markdown-it for your markdown file.

What you need to do is basically:
Install the markdown-it-footnotes plugin (https://github.com/markdown-it/markdown-it-footnote)
Add .use(require('markdown-it-footnote')) to your markdownIt config:

const md = markdownIt({
    html: true,
    linkify: true,
  })
.use(require('markdown-it-footnote'));

On your articles, use markdown notation (pandoc flavor) to have it working, either separate or inline:

Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

or

Here is an inline note.^[Inlines notes are easier to write, since you don't have to pick an identifier and move down to type the note.]

[thisisgonnatakeawhile]

Thanks for the reply @thiagomgd ,

I wish I could make the markdownIt method work because it'd be much more convenient for me, but I'm still unable to do so after installing the plugin and adding the lines of code you mentioned.

I might be glossing over a very crucial and easy to spot detail but unfortunately, I haven't been able to figure it out so far. I've updated the repository I previously linked (https://github.com/thisisgonnatakeawhile/footnotes) with the lines with which I was trying to make it work, just in case you want to check them out and help me figure out the extent of my ignorance. I'm definitely interested in learning what would my issue be here but since a solution has already been provided, I think that that might be imposing on your altruism a tad too much. Still, thanks for taking the time to reply and trying to help out!

[pdehaan]

@thisisgonnatakeawhile Ah, I think you're creating your custom markdown-it instance, but not setting it in your eleventy config. Try this:

const { DateTime } = require("luxon");
const markdownIt = require("markdown-it");


module.exports = function (eleventyConfig) {
  // 1. Create our custom markdown-it instance.
  const md = markdownIt({
    html: true,
    linkify: true,
  }).use(require("markdown-it-footnote"));

  // 2. Overwrite the built-in Markdown library with our custom instance.
  eleventyConfig.setLibrary("md", md);

  eleventyConfig.addPassthroughCopy("./src/css/");
  eleventyConfig.addPassthroughCopy("./src/js/");

  eleventyConfig.addCollection("orderedPost", function (collection) {
    return collection
      .getFilteredByTag("post")
      .sort((a, b) => {
        return a.data.order - b.data.order;
      })
      .filter((post) => !Boolean(post.data.featured));
  });

  eleventyConfig.addFilter("postDate", (dateObj) => {
    return DateTime.fromJSDate(dateObj).toLocaleString(DateTime.DATE_FULL);
  });

  return {
    dir: {
      input: "src",
      output: "public",
    },
  };
};

And my generated HMTL looked something like this:

<h2>title here</h2>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
<p>Here is a footnote reference,<sup class="footnote-ref"><a href="#fn1" id="fnref1">[1]</a></sup> and another.<sup class="footnote-ref"><a href="#fn2" id="fnref2">[2]</a></sup></p>
<hr class="footnotes-sep">

<section class="footnotes">
<ol class="footnotes-list">
  <li id="fn1" class="footnote-item"><p>Here is the footnote. <a href="#fnref1" class="footnote-backref">↩︎</a></p></li>
  <li id="fn2" class="footnote-item"><p>Here's one with multiple blocks. <a href="#fnref2" class="footnote-backref">↩︎</a></p></li>
</ol>
</section>

[thisisgonnatakeawhile]

Ohhh, I can see now why the code I had didn't work, thank you yet again @pdehaan ! The two solutions you provided are awesome but I think this one is more convenient for me. This is great, thanks again for your help and kindness.

[pdehaan]

All credit to @thiagomgd for the excellent suggestion! 👏
I agree that in this case using the markdown-it plugin directly might be a bit easier than the Eleventy plugin.

[glow12121]

I am new to Eleventy. How does one add footnotes functionality in version 3.0? I am trying to follow older instructions but there is no such file as eleventy.config.js in my setup.

Also, since footnotes are intrinsic part of Markdown formatting, it would maybe make sense to include this functionality in Eleventy engine by default. Imagine one would need separate (also third-party) plugins to display headlines or text in bold.

[Ryuno-Ki]

Eleventy is looking at a handful of config filenames -- maybe you're using another one?

[glow12121]

Why are there multiple configuration files? It is very confusing for a newbie and non-programmer.

[Ryuno-Ki]

ESM support only appeared two years ago. Initially it was only .eleventy.js.
ecae808

Then the idea came up to also support .eleventy.cjs in #1028 to explicitly support CommonJS format.
That got replaced by #1029 in ecae808 (part of #2464 ?) and here we are.

[glow12121]

I appreciate the explanation.

The program is promoted as a "simple" site generator. But as a newbie willing to migrate to Eleventy I have immediately faced these issues:

• No Markdown footnotes supports, third-party plugin needed
• No image support - as if there were many websites with no images these days
• Parts of documentation outdated or missing. No search within documentation (at least I cannot find the search icon)
• Existing documentation does not state where exactly config files and certain critical folders must be created - why not generate empty files and folders by default?
• Multiple config files confusion - why not just one?
• Why can the site source be placed both in / and /src?

Not sure if this is of any interest to anyone here, but these are issues I cannot resolve.

It would have been way easier if a tiny functioning site was generated at start.

[Ryuno-Ki]

The search is linked from the top (no icon, but the word).

That's not to diminish the feedback.