From 7402983bcf71fb927a418df8962579ed18b5102b Mon Sep 17 00:00:00 2001
From: Helen Chong <119173961+helenclx@users.noreply.github.com>
Date: Tue, 6 Aug 2024 17:02:53 +0800
Subject: [PATCH] Add how-to article about accessible footnotes
---
.../myarticles/accessible-footnotes.md | 228 ++++++++++++++++++
1 file changed, 228 insertions(+)
create mode 100644 src/articles/myarticles/accessible-footnotes.md
diff --git a/src/articles/myarticles/accessible-footnotes.md b/src/articles/myarticles/accessible-footnotes.md
new file mode 100644
index 00000000..cadf86c9
--- /dev/null
+++ b/src/articles/myarticles/accessible-footnotes.md
@@ -0,0 +1,228 @@
+---
+articleTitle: How I (Tried to) Implement Accessible Footnotes
+date: 2024-08-06
+desc: "How I implement accessible footnotes, at least to the best of my ability. Written for 32-Bit Cafe's Community Code Jam #5."
+categories: ["32-bit cafe", "accessibility", "html", "css", "eleventy", "markdown-it"]
+toc: true
+---
+
+[32-Bit Cafe](https://32bit.cafe/) is holding its fifth community code jam, titled ["Back to School"](https://32bit.cafe/~xandra/events/codejam5/), from 4 to 17 August 2024. I have been looking forward to participating in 32-Bit Cafe's community code jam for the first time, so I am excited. This motivates me to finally write a how-to article I have been meaning to do for a while: how to implement accessible footnotes on Leilukin's Hub, or at least, I tried to do so to the best of my abilities.
+
+On [32-Bit Cafe's Discourse forum](https://discourse.32bit.cafe/), I made a [post on 28 June 2024](https://discourse.32bit.cafe/t/handling-citations-and-or-footnotes/1061/2?u=leilukin) in response to [solaria](https://solaria.neocities.org/)'s thread ["Handling Citations and/or Footnotes"](https://discourse.32bit.cafe/t/handling-citations-and-or-footnotes/1061) to share my methods of adding footnotes on my website. Now, I am writing an extended version of that post of mine in the form of this article, so I could share what I learned about web page footnotes on my website as well.
+
+(Note: This article assumes a foundational familiarity with HTML and CSS)
+
+## About Footnotes
+
+Plagiarism.org [defines footnotes](https://www.plagiarism.org/article/what-are-footnotes) as notes placed at the bottom of a page, and what footnotes do is to cite references or comment on a designated part of the text above it.
+
+My use case of footnotes is citing sources of information, particularly citing the same source multiple times on the same page when information from the same source is spread across my page. As of this writing, my website pages that use footnotes include the [trivia page of my {% cite "A Summer’s End — Hong Kong 1986" %} shrine 1](https://leilukin.com/shrines/asummersend/trivia/) and the [facts page of my {% cite "Cassette Beasts" %} shrine](https://leilukin.com/shrines/cassettebeasts/facts/). You are free to look at the HTML and CSS for reference, including when you are reading this article as I am explaining how I implement the footnotes.
+
+Footnotes are used both on print and on the web. However, maintaining footnotes on the web can be tedious, especially if you want to update a web page to add or remove them, since you will need to change the number references of existing footnotes.
+
+## Attempted to Use CSS Counters
+
+When I was searching for how to implement accessible footnotes, I discovered [Kitty Giraudel](https://kittygiraudel.com/)'s article, ["Accessible Footnotes with CSS"](https://www.sitepoint.com/accessible-footnotes-css/) which teaches the method of using the combination of HTML [`aria-describedby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) attribute and [CSS counters](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_counter_styles/Using_CSS_counters) to add numbered references, to reduce the hassle of manually re-numbering all existing footnotes in case you want to update or reorder the references.
+
+Her article also teaches adding a highlight background colour when heading to a footnote from a reference, as well as providing back links to head back to a reference from a footnote, by using the combination of the backlink Unicode icon (↩) and the HTML `aria-label` attribute with a value of “Back to content”. The uses of ARIA labels make footnotes more screen reader-friendly.
+
+Furthermore, Kitty created the [eleventy-plugin-footnotes plugin](https://github.com/KittyGiraudel/eleventy-plugin-footnotes)tor the static site generator [Eleventy](https://www.11ty.dev/), and wrote a blog post about it, ["Footnotes in 11ty"](https://kittygiraudel.com/2020/12/02/footnotes-in-11ty/). Since I already had begun to [use Eleventy to build my website](/blog/posts/2024-04-21-april-2024-leilukins-hub-overhaul-with-eleventy), I tried Kitty's plugin.
+
+Unfortunately, a known limitation of using CSS counter method to generate footnotes is [not being able to reference the same footnote multiple times](https://github.com/KittyGiraudel/eleventy-plugin-footnotes/issues/83). As I want to be able to reference the same footnote more than once when I am citing sources on my shrine pages, I had to give up the plugin and look for an alternative.
+
+## Starting with markdown-it-footnote Plugin's Default Footnote Markup
+
+Kitty Giraudel's blog post about creating footnotes in Eleventy mentioned [markdown-it-footnote](https://github.com/markdown-it/markdown-it-footnote), the footnotes plugin for [markdown-it](https://github.com/markdown-it/markdown-it) Markdown parser, which is integrated in Eleventy by default to convert Markdown to HTML. Kitty commented on the accessibility shortcomings of markdown-it-footnote in the blog post:
+
+> [...]it’s not super accessible (let alone by default), even considering all the customisation options. That’s because the footnote references end up being numbers (e.g. [1]) which are meaningless when listed or tabbed through because devoid of their surrounding context.
+
+That said, since the plugin is customisable, I still wanted to give it a shot to see if I could make configurations to improve its accessibility, so I installed markdown-it-footnote and looked into the plugin's default HTML markup output.
+
+Here is a sample of what the HTML markup output of markdown-it-footnote looks like:
+
+```html
+This is a paragraph with the first footnote reference.
+
+Here is the second paragraph with the second footnote reference.
+
+This the third paragraph, but with a foootnote reference that points to the first footnote.
+
+
+
+```
+
+What this HTML markup does:
+- Adding a footnote reference as a superscript by using the [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup) tag with numbers as the content.
+- Using a `
` horizontal line element to separate the main body of the page and the footnote section;
+- Using the `` tag to render the footnotes as a numbered list;
+- Each footnote list item has an `id` attribute
+- If a footnote is referenced more than once, the additional footnote references are labelled with colons.
+
+(Note: the class names were added by markdown-it-footnote, but if you do not use it, you can rename the class name to whatever you want, and even if you use markdown-it-footnote, you can still change the class names if you want to go deep into it)
+
+Next step is trying to improve this HTML markup by making it accessible.
+
+## Make markdown-it-footnote's Markup More Accessible
+
+### Clarify Footnote Reference Labels
+
+As pointed out by Kitty Giraudel, labelling the footnote reference as mere numbers like [1] is an accessibility shortcoming, because these reference links become meaningless when being focused on by tabbing through the links, as these reference links would be devoid of context.
+
+What I did to tackle this was changing the reference labels by adding a word "Footnote" to clarify that these links are for footnotes. For example, [1] becomes [Footnote #1], so when screen readers focus on a footnote reference link, it will be read out as "Footnote number one link".
+```html
+
+```
+
+Optionally, if you want your footnote labels to still display only numbers on screen, you can use a CSS class to [visually hide](https://www.a11yproject.com/posts/how-to-hide-content/) the extra characters in the footnote label. This `.visually-hidden` utility class is a useful tool in your arsenal for accessible web design, as it is often used to hide a content that you do not mean to show on screen, but you still want it to be read by assistive technology.
+
+```css
+.visually-hidden {
+ clip: rect(0 0 0 0);
+ clip-path: inset(50%);
+ height: 1px;
+ overflow: hidden;
+ position: absolute;
+ white-space: nowrap;
+ width: 1px;
+}
+```
+
+To make my footnote reference labels display only a number on screen, I use a `span` tag with `visually-hidden` as the value of the `class` attribute to wrap around "Footnote #", so on screen, [Footnote #1] is changed to [1].
+
+```html
+
+```
+
+### Add ARIA Label to Footnote Back Links
+
+Next step is adding an ARIA label to the footnote backlinks, by adding an `aria-label` attribute with "Back to reference #[Insert reference number]" as its value. For example:
+
+```html
+
+```
+
+When a footnote back link is focused on via tabbing, screen readers will read it out as "Back to reference number one link".
+
+### Add Heading to Footnote Section
+
+To make it clear that the section is for footnotes, I add a HTML heading before the list of footnotes, such as:
+```html
+Footnotes
+```
+
+## Final HTML Markup for Accessible Footnotes
+
+Here is my final HTML markup sample to create accessible footnotes:
+
+```html
+This is a paragraph with the first footnote reference.
+
+Here is the second paragraph with the second footnote reference.
+
+This the third paragraph, but with a foootnote reference that points to the first footnote.
+
+
+
+```
+
+As for the CSS, in addition to using the `.visually-hidden` utility class, I refer to Kitty Giraudel's ["Accessible Footnotes with CSS"](https://www.sitepoint.com/accessible-footnotes-css/) article to style the highlight background color when heading to a footnote from a reference.
+
+## Configure My Markup in Eleventy's Configurations
+
+(If you do not use Eleventy, you may skip this section)
+
+My final step was to configure the markdown-it-footnote plugin, by editing Eleventy's configuration file (I named mine `eleventy.config.js`), so the plugin would render my accessible footnote HTML markup.
+
+```js
+// markdown-it plugins
+const markdownIt = require("markdown-it");
+const markdownItFootnote = require("markdown-it-footnote");
+let markdownLibrary;
+
+module.exports = function (eleventyConfig) {
+ /* Markdown Overrides */
+ markdownLibrary = markdownIt({
+ html: true,
+ }).use(markdownItFootnote);
+
+ // Configure markdown-it-footnote
+ markdownLibrary.renderer.rules.footnote_block_open = () => (
+ '\n' +
+ '