{
  "$type": "site.standard.document",
  "canonicalUrl": "https://rednafi.com/zephyr/footnotes-for-the-win/",
  "description": "Why footnote-style reference links create cleaner Markdown documents and improve the writing experience over inline links.",
  "path": "/zephyr/footnotes-for-the-win/",
  "publishedAt": "2023-10-07T00:00:00.000Z",
  "site": "at://did:plc:fgtm2c26vfcj74rfmeggbyqj/site.standard.publication/3mnl6f7ob462z",
  "tags": [
    "Essay"
  ],
  "textContent": "There are a few ways you can add URLs to your Markdown documents:\n\n- Inline links\n\n    \n\n    This will render as inline link.\n\n- Reference links\n\n    \n\n    Define the link destination elsewhere in the document like this:\n\n    \n\n    This will render the same way as before, [reference link].\n\n- Footnote style reference links\n\n    \n\n    Define the link destination using a footnote reference:\n\n    \n\n    This will render a bit differently with a clickable number beside the origin text that\n    refers to the backref at the bottom of the document. Like this: footnote style reference\n    link (see [example link]).\n\n    Try clicking on the number within the square brackets and see how the page scrolls down\n    to the corresponding backref link that lives with other backrefs at the tail of the\n    page.\n\nThe inline link approach is the most prevalent one as it's also the easiest one to write.\nBut it suffers from a few issues:\n\n- Links scattered throughout your documents can make updates cumbersome.\n- Reusing a link elsewhere requires multiple copy-pastes.\n- Placing several [links][reference link] [side][reference link] by [side][reference link]\n  can feel awkward, and URL stylings like blue highlighting or underlining make things\n  noisy.\n- To add a reference section, you'll have to create a separate segment, usually at the\n  bottom of your page, and duplicate the URLs.\n- On mobile devices, accidentally fat-fingering a URL can promptly redirect readers away\n  from your content, potentially against their intention.\n- Enforcing a line width limit can be challenging due to lengthy inlined URLs.\n\nThe reference link approach solves some of these issues since you won't have to scatter the\nURLs across your document or repeat them multiple times for multiple usage. This also allows\nyou to use a Markdown formatter to enforce a maximum line width. I use [prettier] to cap the\nline width at 92 characters and the formatter works better when it doesn't have to shimmy\naround multiple long inline URLs.\n\nThis is certainly better than using inline links, but it still suffers from all the other\nissues that plague the former approach. Creating a reference section still requires some\nrepetition, and juxtaposing multiple links remains awkward. Also, accidental misclicks that\ntake you to a different page remains an issue.\n\nThe footnote-style reference link comes to the rescue. It keeps the document clean by moving\nall URLs to the bottom in a dedicated reference section. The small superscript numbers don't\ndistract the reader as much but provide an easy way to navigate to the corresponding links\nif needed. Accidental clicks are no longer an issue since clicking on a reference\nsuperscript will bring the user down to the footnote section where they can click on the\nconcomitant URL or jump back to the origin by tapping on the backref (↩︎) symbol. The\nreference section also allows you to provide more context on each link, like a title or\ndescription.\n\nMoreover, adding multiple links to the same origin is straightforward since you simply add\nthe footnote numbers like this (see [footnotes with extra texts] and [multiple footnotes]).\nPlus, you don't have to manually create a separate reference section; it automatically gets\ncreated for you as you start adding footnotes. See the reference section in this post and\nclick on the backref links to go back to the origin. Most parsers like [GitHub flavored\nMarkdown] now support footnotes out of the box.\n\nRecently, I've spent an entire evening converting almost all of the inline links on this\nsite into footnote style references in a semi-automated manner. I still use reference links\nhere and there but mostly prefer footnotes since they allow me to avoid repetition and\nsubjectively look less distracting compared to underlined or highlighted URLs. And suddenly,\n[prettier]'s job has become easier too!\n\nFurther reading\n\n- [Checkout the raw Markdown file of this post]\n\n\n\n\n[example link]:\n    https://example.com\n\n[prettier]:\n    https://prettier.io/\n\n[footnotes with extra texts]:\n    https://rednafi.com\n\n[multiple footnotes]:\n    https://rednafi.com/index\n\n[github flavored markdown]:\n    https://github.github.com/gfm/\n\n[checkout the raw markdown file of this post]:\n    https://github.com/rednafi/rednafi.com/blob/main/content/zephyr/footnotes_for_the_win.md\n\n[reference link]:\n    https://example.com",
  "title": "Footnotes for the win"
}