The zeroth² element is sacrosanct to our creed; for in the beginning there was nothing.

If you're using WordPress's JetPack, it uses an ancient version of Markdown Extra. You can either monkeypatch this, or install a separate Markdown plugin.

I've patched my fork of it in two specific places.

Firstly, I set $this->footnote_counter = 0; in the initial config of the footnotes.

Secondly, I changed the display so that the ordered list began from zero: <ol start="0">

Wait… should that be zerothly and firstly?

There's no way to change footnote links to symbols like * or ♪. Perhaps I'll add that next^3😉?

Anyway, I enjoy hacking around on my theme.

To that end, I'm writing a patch for PHP Markdown which will display the first ~200 characters of a footnote in the pop-up title text. Hover over the superscript number and you'll get a preview of the footnote⁰.

Dealing with all sorts of weird HTML & Markdown edge-cases is tricky. So, if you'd like to help, please contribute to this discussion. And if you spot any bugs, please let me know.

The test... Begins!

These footnotes support HTML¹.

And they cope with Markdown².

Footnotes with an image³ have the img replaced with its alt text.

They don't choke on entities⁴.

And plain quote marks are fine⁵.

Nested elements should work⁶.

Very long footnotes are truncated⁷.

Fully multilingual⁸.

Also Emoji⁹ compatible.

Although some may be split if they use ZWJ¹⁰.

Every Element

These are the HTML elements which display textual content - and some notes on where unusual things might happen.

• <a>¹¹ works, but doesn't show the destination of the link.

• <abbr>¹² The title text doesn't show.

• <address>¹³

• <area> / <map>¹⁴ alt text shows.

• <article>¹⁵

• <aside>¹⁶

• <audio>¹⁷

• <b>¹⁸

• <bdi>¹⁹ The BDI algorithm isn't implemented.

• <bdo>²⁰ The override isn't implemented.

• <blockquote>²¹

• <br>²² changed to newlines - which works.

• <button>²³

• <cite>²⁴

• <code>²⁵

• <data>²⁶ Doesn't show the value.

• <del>²⁷

• <details><summary>²⁸

• <dfn>²⁹

• <dialog>³⁰

• <div>³¹

• <dl><dt><dd>³²

• <em>³³

• <fieldset><legend>³⁴

• <figure><figcaption>³⁵

• <footer>³⁶

• <form>³⁷

• <h1>³⁸

• <header>³⁹

• <hgroup>⁴⁰

• <i>⁴¹

• <img>³

• <ins>⁴² datetime isn't shown.

• <kbd>⁴³

• <label>⁴⁴

• <mark>⁴⁵

• <menu><li>⁴⁶

• <meter>⁴⁷

• <nav>⁴⁸

• <ol><li>⁴⁹

• <optgroup>⁵⁰

• <option>⁵¹

• <output>⁵²

• <p>⁵³

• <picture><source>⁵⁴

• <pre>⁵⁵

• <progress>⁵⁶

• <q>⁵⁷

• <ruby><rp><rt>⁵⁸

• <s>⁵⁹ It isn't possible to show a strikethrough in a tooltip.

• <samp>⁶⁰

• <section>⁶¹

• <select>⁶²

• <small>⁶³

• <span>⁶⁴

• <strong>⁶⁵

• <sub>⁶⁶ Subscript formatting isn't available in title text

• <sup>⁶⁷ Neither is superscript

• <table><thead><tr><th><tbody><td><tfoot><caption><colgroup><col>⁶⁸

• <textarea>⁶⁹

• <time>⁷⁰ datetime isn't displayed

• <u>⁷¹

• <ul>⁷² If there is no space between the elements, the tooltip may look odd. Here, the HTML is

• <var>⁷³

• <video>⁷⁴

• <wbr>⁷⁵

Get involved

If you'd like to peruse my code or offer a suggestion, take a look at this GitHub issue.

The Problem

Using WordPress's JetPack, markdown footnotes are rendered as:

Some text <sup id="fnref-1234-1"><a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fn-1234-1" class="jetpack-footnote">1</a></sup>
...
<li id="fn-1234-1">The footnotes. <a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fnref-1234-1">↩</a></li>

There are two main problems with this:

1. The <sup>1</sup> doesn't announce the destination of the link.
2. The ↩ may be read out as "leftwards arrow with hook"

Ideally, it would be useful to have something like:

<a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fn-1234-1" aria-label="Read footnote 1" ...

and

<a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fnref-1234-1" aria-label="Return to main content">↩</a>

Or similar.

The Solution

The issue occurs in jetpack/_inc/lib/markdown/extra.php

@define( 'MARKDOWN_FN_LINK_TITLE',     "" );
@define( 'MARKDOWN_FN_BACKLINK_TITLE', "" );

The link and backlink titles are used later in the same file to set the title.

if ($this->fn_backlink_title != "") {
    $title = $this->fn_backlink_title;
    $title = $this->encodeAttribute($title);
    $attr .= " title=\"$title\"";
}

But, because they're never set, the code doesn't run.

It's pretty easy to hotfix this. Replace the above definitions with:

@define( 'MARKDOWN_FN_LINK_TITLE',     __( 'Read footnote.', 'jetpack' ) );
@define( 'MARKDOWN_FN_BACKLINK_TITLE', __( 'Return to main content.', 'jetpack' ) );

I've raised this as an issue on GitHub.

Problems with the solution.

• It will be overwritten when JetPack updates. You can also add the new @defines to your theme if you want them to survive updates.
• I'm not sure if title is the right element. Although it seems has the same precedence as aria-label in the Accessible Name and Description Computation algorithm
• It is in English only. Because those strings don't exit in the translation file, it will only work for monolingual installs.
• The title text shows as a pop-up on certain browsers.
• No metadata. It might be nice to have the title say "Read footnote 23."
• Some footnote plugins put the footnote text in the title. That may be useful.

If you'd like to see this in the default JetPack experience - please leave a comment on GitHub.

So this is my horrible and hacky way to display inline footnotes in pure HTML and CSS. No Javascript.

Here's how it works:

The most cited work in history, for example, is a 1951 paper
   <details>
      <summary>1</summary> 
      Lowry, O. H., Rosebrough, N. J., Farr, A. L. Randall, R. J. J. Biol. Chem. 193, 265–275 (1951).
   </details>
describing an assay to determine the amount of protein in a solution.

I've use <details> and <summary> to make a collapsible element.

The problem here is that <details> is a block level element. By default, starting a <details> element will display on a new line.

It also doesn't look much like a footnote yet.

Luckily, I bodged some CSS together to make it inline:

details, summary {
  display: inline;
  vertical-align: super;
  font-size: 0.75em;
}
summary {
  cursor: pointer;
}
details[open] {
  display: contents;
}
details[open]::before {
  content: " [";
}
details[open]::after {
  content: "]";
}

• Using display:inline; turns these into inline elements - so a newline isn't started.
• The alignment and font size make it look like a normal footnote.
• The cursor: pointer; just makes it slightly easier for mouse users to see that the element is interactive.
• When the <details> is in the open state, the content will be displayed as a direct descendant of the parent element.
• Add some square brackets to make it more obvious where the footnote begins and ends.

I could have used the <sup> element to make the whole note superscript. But that produces invalid HTML.

The <details> element can contain any HTML. So I can add a fully semantic citation.

Problems

The "normal" way of doing footnotes in an ePub is to place them at the end of a section. Footnote links like ^fn1 are just hyperlinks. They take the reader to that section of the document. So eReaders will display the footnote's contents on the same page as the footnote's link:

That makes it easy for a reader to search through them all, or just read them in order.

Because my style are inline, that makes it hard to see or search for them.

And because my style are interactive elements, they place a physical burden on the user to interact with them.

The main problem is with the rendering engines used by eReaders. I tried a few, but none of them displayed <details> as an interactive element.

I'd love to know how it renders on Kindle, Kobo, and other eReaders. Here's the HTML of the test if you'd like to experiment with it and send me a screenshot.

details, summary {
  display: inline;
  vertical-align: super;
  font-size: 0.75em;
}
summary {
  cursor: pointer;
}
details[open] {
  display: contents;
}
details[open]::before {
  content: " [";
}
details[open]::after {
  content: "]";
}

The most cited work in history, for example, is a 1951 paper<details><summary>1</summary> Lowry, O. H., Rosebrough, N. J., Farr, A. L. and Randall, R. J. J. Biol. Chem. 193, 265–275 (1951).</details> describing an assay to determine the amount of protein in a solution.
<br><br>
Sunlight poured like molten gold<details><summary>2</summary> Not precisely, of course. Trees didn’t burst into flame, people didn’t suddenly become very rich and extremely dead, and the seas didn’t flash into steam. A better simile, in fact, would be ‘not like molten gold.’</details> across the sleeping landscape.
<br><br>
My blog was recently featured in an academic paper
<details>
  <summary>3</summary>
  <span itemscope itemtype="http://schema.org/ScholarlyArticle">
     <span itemprop="citation">
       <span itemprop="author" itemscope itemtype="http://schema.org/Person">
         <span itemprop="name">
           <span itemprop="familyName">Eishita</span>
           <span>, </span>
           <span itemprop="givenName">Farjana Z.</span>
         </span>
       </span>
     <span> and </span>
     <span itemprop="author" itemscope itemtype="http://schema.org/Person">
       <span itemprop="name">
         <span itemprop="familyName">Stanley</span>
         <span>, </span>
         <span itemprop="givenName">Kevin G.</span>
       </span>
     </span>
     <span> and </span>
     <span itemprop="author" itemscope itemtype="http://schema.org/Person">
       <span itemprop="name">
         <span itemprop="familyName">Esquivel</span>
         <span>, </span>
         <span itemprop="givenName">Alain</span>
       </span>
     </span> 
     <q>
       <cite itemprop="headline">Quantifying the differential impact of sensor noise in augmented reality gaming input</cite>
     </q> 
     <span>(</span>
     <time itemprop="datePublished" datetime="2015">2015</time>
     <span>)</span> 
     <span itemprop="publisher" itemscope itemtype="http://schema.org/Organization">
       <span itemprop="name">Institute of Electrical and Electronics Engineers (IEEE)</span>
     </span>
     <span>.</span> DOI: <a itemprop="url" href="https://doi.org/10.1109/gem.2015.7377202">https://doi.org/10.1109/gem.2015.7377202</a></span>
  </span>
</details> which pleased me greatly.

There are a few things that really annoy me from a usability point of view. Some of these are the fault of the author, some the publisher, some the eBook format¹, and some the reader app.

Firstly, what's the point of a footnote? This is a rough and untested bit of user-storying...

• As a reader, I want to look up a reference to a quoted work. So that I can see if the author is being accurate.
• As a reader, I want to know a little more about the subject being discussed. Because I'm interested in this specific topic
• As a reader, I want to understand what a newly introduced term means. So that I can understand the rest of the book.

But, there's also another user, who often takes precedence:

• As an author, I want to show that I have done my research. So that critics can't use that to question my credibility.
• As an author, I want to add more details which don't fit in the main body of the text. Because I hate deleting text and my editor told me to take it out.
• As an author, I want to add an explanation for some jargon or terminology. So that readers unfamiliar with the subject don't feel excluded.

(This isn't a thorough bit of user research. It's just me noodling around. Feel free to add your own, well-researched, stories.)

Types of footnotes

In my experience, there are four types of footnote:

1. A citation. Anything from something a bit useless like "(Smith 1984.)" to a fully semantic "Baucherel, Kate, Blockchain Hurricane. Business Expert Press. 2020".
2. A long note. A diversion which, while interesting, is not relevant to the main argument. Think of it a bit like a Director's Commentary on a DVD.
3. A short note. Usually an explanation of an TLA² or technical term.
4. A comedy footnote³.

Here's my problem / User Need - how does a user know which type of footnote they are encountering?

In the wild

Let's take an example. I'm currently reading "Race After Technology" by Ruha Benjamin". It's an excellent book. But I am unsure how I am supposed to read it⁴. (This criticism applies to most books I've read, but this is what I'm currently reading.)

In this example, I click on ¹³ and my ebook reader - KOReader displays a little pop-up at the bottom of the screen.

Before I tap the link - I've no idea what's behind it. And, that's assuming that I know that reference numbers are tappable, and that the tap-target is large enough that I don't accidentally interact with the book in some other way.

Here's another, from the same page: Here the author provides a citation and some explanatory text. How does an author decide what goes in the body and what goes in the notes? How does the user know whether the footnote is a citation or is explanatory?

Finally, again from the same page, there's this: This footnote is so long that the UI pop-up isn't big enough to contain it and displays a scrollbar.

Again, this isn't a criticism of this specific author. This happens on lots of books. The publishing industry seems to have a complete disregard for the user's need.

How do users read? Do they want to click on every footnote link they encounter? Do they expect to read them at the end? Does having a mixture of notes and citations confuse them?

Specification

The ePub specification talks about how to handle footnotes. One of the great things about ePub is that it is based on HTML5. The footnote markup is pretty simple:

<p>
   In that year<a href="https://shkspr.mobi/blog/2020/07/usability-of-footnotes/#ft2f" role="doc-noteref" epub:type="noteref">2</a> there were 67 mills engaged in the manufacture of cotton goods …
</p>

<aside id="ft2f" role="doc-footnote" epub:type="footnote">
   <p>
     2 The manufacturing statistics for 1900 which follow are not those given in the Twelfth Census, but are taken from the <em>Census of Manufactures</em> …
   </p>
</aside>

Most eBook publishers also include a back-link, so that users can easily return to the main text.

The specification doesn't say whether citations should be displayed differently to footnotes.

I guess it would be easy to add class="citation" and have the CSS .citation::before {content="cite ";}

That would allow users to differentiate between ^{cite 2} and ^{note 2}.

Usability

There are some "technical" usability issues here. How the user interacts with links, whether the note appears as a pop-up or inline, and the process of returning to the main text.

But I want to talk about the cognitive issues at play. When footnotes can contain anything from a citation to essential background information, the user is forced to break from the flow⁵ of reading - often in the middle of a sentence. This is a problem in both paper books and electronic books.

I'm still stuck on the user needs. It seems to me that most footnotes are for the author's benefit. If the text is that important, it should be in the main body. If it isn't, leave it out.

Abbreviations can be dealt with inline using the <abbr> element. You should be able to to tap on the TLA to get the definition.

As for citations? Isn't that what HTML links are for? Just link directly to the document in question as part of the running text.

Would it make life easier for reader to include a fully semantic citation inline? Take this scrap of imaginary text:

There are many websites about Shakespeare. As is discussed in Eric M. Johnson's Opening Shakespeare from the Margins (2017), 187-205 Springer International Publishing The Shakespeare User the use of open source software has seen...

Which can be represented by the HTML code:

<span itemscope itemtype="http://schema.org/ScholarlyArticle">
   <span itemprop="citation">
      <span itemprop="author" itemscope itemtype="http://schema.org/Person">
         <span itemprop="name">
            <span itemprop="familyName">Johnson</span>, 
            <span itemprop="givenName">Eric M.</span>
         </span>
      </span> 
      <q>
         <a itemprop="url" href="https://doi.org/10.1007/978-3-319-61015-3_10">
            <cite itemprop="headline">Opening Shakespeare from the Margins</cite>
         </a>
      </q> 
      (<time itemprop="datePublished" datetime="2017">2017</time>)  
      page: <span itemprop="pagination">187-205</span>. 
      <span itemprop="publisher" itemscope itemtype="http://schema.org/Organization">
         <span itemprop="name">Springer International Publishing</span>
      </span>. 
      <span itemprop="publication">The Shakespeare User</span>.
   </span>
</span>

CSS could be used to show / hide various parts of the citation until interacted with. A reader familiar with hypertext should know that visiting a link will take them to an external site. No need for footnotes at all!

Obviously, I haven't done any proper usability studies. Nor have I spoken to any users other than myself.

But surely we need a better way of making footnotes and citations better for readers?

What's next

There have been many attempts to get a <footnote> element into HTML. I think there's some value in adding semantic information to a document. But I probably think that the <aside> element and <cite> element are good enough.

Perhaps the W3C Publishing Group needs to fund some user research to see if ePub notes and citations work well for most users.

Perhaps authors need to realise that linear text is a relic of paper-based publishing and that hypertext affords new ways for a reader to journey through a text.

Or, perhaps, I need to learn how to read without getting distracted.