Footnotes for the win

There are a few ways you can add URLs to your markdown documents:

• Inline links

  [inline link](https://example.com)
  

  This will render as inline link.

• Reference links

  [reference link]
  

  Define the link destination elsewhere in the document like this:

  [reference link]: https://example.com
  

  This will render the same way as before, reference link.

• Footnote style reference links

  footnote style reference link[^1]
  

  Define the link destination using a footnote reference:

  [^1]: https://example.com
  

  This will render a bit differently with a clickable number beside the origin text that refers to the backref at the bottom of the document. Like this: footnote style reference link¹.

  Try clicking on the number within the square brackets and see how the page scrolls down to the corresponding backref link that lives with other backrefs at the tail of the page.

The inline link approach is the most prevalent one as it’s also the easiest one to write. But it suffers from a few issues:

• Links scattered throughout your documents can make updates cumbersome.
• Reusing a link elsewhere requires multiple copy-pastes.
• Placing several links side by side can feel awkward, and URL stylings like blue highlighting or underlining make things noisy.
• To add a reference section, you’ll have to create a separate segment, usually at the bottom of your page, and duplicate the URLs.
• On mobile devices, accidentally fat-fingering a URL can promptly redirect readers away from your content, potentially against their intention.
• Enforcing a line width limit can be challenging due to lengthy inlined URLs.

The reference link approach solves some of these issues since you won’t have to scatter the URLs across your document or repeat them multiple times for multiple usage. This also allows you to use a markdown formatter to enforce a maximum line width. I use prettier² to cap the line width at 92 characters and the formatter works better when it doesn’t have to shimmy around multiple long inline URLs.

This is certainly better than using inline links, but it still suffers from all the other issues that plague the former approach. Creating a reference section still requires some repetition, and juxtaposing multiple links remains awkward. Also, accidental misclicks that take you to a different page remains an issue.

The footnote-style reference link comes to the rescue. It keeps the document clean by moving all URLs to the bottom in a dedicated reference section. The small superscript numbers don’t distract the reader as much but provide an easy way to navigate to the corresponding links if needed. Accidental clicks are no longer an issue since clicking on a reference superscript will bring the user down to the footnote section where they can click on the concomitant URL or jump back to the origin by tapping on the backref (↩︎) symbol. The reference section also allows you to provide more context on each link, like a title or description.

Moreover, adding multiple links to the same origin is straightforward since you simply add the footnote numbers like this³⁴. Plus, you don’t have to manually create a separate reference section; it automatically gets created for you as you start adding footnotes. See the reference section in this post and click on the backref links to go back to the origin. Most parsers like GitHub flavored markdown⁵ now support footnotes out of the box.

Recently, I’ve spent an entire evening converting almost all of the inline links on this site into footnote style references in a semi-automated manner. I still use reference links here and there but mostly prefer footnotes since they allow me to avoid repetition and subjectively look less distracting compared to underlined or highlighted URLs. And suddenly, prettier’s² job has become easier too!

Recent posts