Sidenotes In Web Design

In typography/design, ‘sidenotes’ place footnotes/endnotes in the margins for easier reading. I discuss design choices, HTML implementations and their pros/cons.
bibliography, technology, design, CSS, JS
2020-08-062020-12-05 finished certainty: certain importance: 2


Sidenotes/margin notes are a ty­po­graphic con­ven­tion which im­proves on foot­notes & end­notes by in­stead putting the notes in the page mar­gin to let the reader in­stantly read them with­out need­ing to re­fer back and forth to the end of the doc­u­ment (end­notes) or suc­ces­sive pages (foot­notes spilling over).

They are par­tic­u­larly use­ful for web pages, where ‘foot­notes’ are de facto end­notes, and click­ing back and forth to end­notes is a pain for read­ers. (Foot­note vari­ants, like “float­ing foot­notes” which pop up on mouse hov­er, re­duce the read­er’s effort but don’t elim­i­nate it.)

How­ev­er, they are not com­monly used, per­haps be­cause web browsers un­til rel­a­tively re­cently made it hard to im­ple­ment side­notes eas­ily & re­li­ably. Tufte-CSS has pop­u­lar­ized the idea and since then, there has been a pro­lif­er­a­tion of slightly vari­ant ap­proach­es. I re­view some of the avail­able im­ple­men­ta­tions.

For gen­eral users, I rec­om­mend Tufte-CSS: it is fast & sim­ple (us­ing only com­pile-time gen­er­a­tion of side­notes, ren­dered by sta­tic HTML/CSS), pop­u­lar, and easy to in­te­grate into most web­site work­flows. For heavy foot­note users or users who want a drop-in, run­time Javascrip­t-based so­lu­tions like sidenotes.js may be more use­ful.

Side­notes and mar­gin notes (some­times also called “asides”) are an al­ter­na­tive to in de­sign. Where foot­notes put ad­di­tional ma­te­r­ial in small sec­tions at the bot­tom of the page, or­ga­nized by num­ber, and end­notes stuff them at the end of the doc­u­ment, side­notes in­stead use the large un­used left/right mar­gin of the page.

Be­cause it’s un­com­fort­able to read sen­tences which wrap from edge to edge, par­tic­u­larly for large widths, re­quir­ing many doc­u­ments wind up look­ing like a nar­row river of text flow­ing down a vast blank map. This river of text may be stud­ded with the oc­ca­sional foot­note or end­note, in­clud­ing an­cil­lary ma­te­r­ial like ci­ta­tions or di­gres­sions or ex­tended dis­cus­sion of tricky points or an­tic­i­pa­tion of ob­jec­tions or just the au­thor be­ing wit­ty, which re­quire con­stant back and forth from the place in the text where they make sense and where they can ac­tu­ally be read. As a re­sult, who ever reads end­notes in a phys­i­cal book? Only the most dili­gent will keep a thumb in the back to ac­tu­ally look up end­notes, and so they are ei­ther un­read or tend to be rel­e­gated to the most util­i­tar­ian uses like raw ci­ta­tions.

The sit­u­a­tion is even worse on the In­ter­net, be­cause while foot­notes in a book aren’t too bad (as long as they stay on the same page), web pages don’t re­ally have ‘pages’ and ‘foot­notes’ wind up de­grad­ing to sim­ply end­notes.1

Why do we use end­notes? For the most part, we use them for ci­ta­tion meta­data, abbreviations/definitions, and more ex­tended dis­cus­sions (often hu­mor­ous). But none of these are served well on­line by end­notes: ci­ta­tion meta­data is bet­ter pro­vided as hy­per­links to full­text, de­fi­n­i­tions/ab­bre­vi­a­tions have na­tive HTML sup­port as tooltips/popups—leaving only the ex­tended dis­cus­sions use-case.

com­ments on the pros/cons (, 2004):

Foot­notes are the very em­blem of fussi­ness, but they have their us­es. If they are short and in­fre­quent, they can be made eco­nom­i­cal of space, easy to find when wanted and, when not want­ed, easy to ig­nore. Long foot­notes are in­evitably a dis­trac­tion: te­dious to read and weary­ing to look at. Foot­notes that ex­tend to a sec­ond page (as some long foot­notes are bound to do) are an ab­ject fail­ure of de­sign.

End­notes can be just as eco­nom­i­cal of space, less trou­ble to de­sign and less ex­pen­sive to set, and they can com­fort­ably run to any length. They also leave the text page clean ex­cept for a pep­per­ing of su­per­scripts. They do, how­ev­er, re­quire the se­ri­ous reader to use two book­marks and to read with both hands as well as both eyes, swap­ping back and forth be­tween the pop­u­lar and the per­snick­ety parts of the text.

Side­notes give more life and va­ri­ety to the page and are the eas­i­est of all to find and read. If care­fully de­signed, they need not en­large ei­ther the page or the cost of print­ing it. Foot­notes rarely need to be larger than 8 or 9 point. End­notes are typ­i­cally set in small text sizes: 9 or 10 point. Side­notes can be set in any­thing up to the same size as the main text, de­pend­ing on their fre­quency and im­por­tance, and on the over­all for­mat of the page. If they are not too fre­quent, side­notes can be set with no su­per­scripts at all (as in this book), or with the same sym­bol (nor­mally an as­ter­isk) con­stantly reused, even when sev­eral notes ap­pear on a sin­gle page.

Our ex­tended dis­cus­sions ought to be made easy to read in con­text and not hid­den away at the end of the page. Side­notes let us reuse some of that un­used mar­gin, in a way which is com­fort­able to read, and which is com­pat­i­ble with ex­ist­ing doc­u­ments & work­flows us­ing end­notes: sim­ply move those end­notes into the mar­gin of the text they re­fer to. The user can com­fort­ably sac­cade over to a side­note in­stantly to skim it and back, the in­for­ma­tion den­sity of the lay­out in­creas­es, it re­quires no ex­otic tech­nolo­gies or rewrites or user ed­u­ca­tion, it has a long re­spectable his­to­ry, and it’s just gen­er­ally a good idea.

Examples

Some ex­am­ples of side­notes in books; Bringhurst uses side­notes him­self, of course:

Bringhurst 2004 ex­am­ple of side­notes & mar­gin notes (in this case, it re­peats the sec­tion head­ing)

Side­notes ex­ten­sively used in me­dieval man­u­scripts and early mod­ern books such as the (first 2 pages) (see also ), or Bayle’s awe-in­spir­ingly am­bi­tious use of (re­cur­sive) margin/side notes:

, demon­strat­ing re­cur­sive footnotes/sidenotes (1737, vol­ume 4, pg901; source: Google Books)

Side­notes have been less used in more con­tem­po­rary books; the best-known pop­u­lar­izer is :

Ex­am­ple of Tufte’s use of side­notes & mar­gin notes: they pro­vide ad­di­tional ex­am­ples, com­men­tary, and ci­ta­tion meta­data for the reader in con­text, with­out forc­ing in­scrutable lookups buried deep at the end of the chap­ter (or worse, book) which few read­ers will ever bother with. (From pg61, “Lay­er­ing & Sep­a­ra­tion”, En­vi­sion­ing In­for­ma­tion, Tufte 1990)

in uses mar­gin notes as a kind of in­dex, list­ing key­words in the mar­gin. The den­sity of key­words can make the mar­gins in­ter­est­ing to read on their own; an ex­am­ple from TAOCP: pre-fas­ci­cle 4B: “A Draft of Sec­tion 7.2.1.7: His­tory of Com­bi­na­to­r­ial Gen­er­a­tion”:

Mar­gin notes show­ing key­words for dis­cus­sion of Chinese/Indian al­go­rith­mic his­tory in Knuth.

Implementations

So, side­notes are great. They are also easy in LaTeX PDFs.2 But how do we use them on­line for HTML?

Al­though side­notes are ‘just’ snip­pets of text to the left or right of the main text and it might seem hard to screw it up, as al­ways, there are a lot of ways to ac­com­plish that goal, and many ways we can en­hance (or screw up) them.

Do we put them on the left, right, or both sides? What of the sev­eral pos­si­ble HTML el­e­ments are our side­notes de­lim­ited as (<span>, <a>, <div>, <aside>, <small>, or even <table>)? Do we use Javascript, ac­cept­ing that it’ll ‘flash’ an in­cor­rectly ren­dered page as the JS loads & runs, and out­right break for users with JS turned off (as is in­creas­ingly sen­si­ble on an ever-more-hos­tile In­ter­net)? Does the user have to click or do any­thing to make side­notes vis­i­ble? If not, what about on mo­bile or tiny screens, which don’t have any mar­gins worth speak­ing of—do they get side­notes in any form, and if so, do they ren­der ‘in­line’ as sim­ply part of their para­graph, or do we dis­play them as sep­a­rate blocks (‘pop-in’) and by de­fault or after a user click? How are many side­notes laid out, do they bump each other down the page or just over­lap—it would seem that JS is nec­es­sary to avoid over­laps in most ap­proach­es, but is that too great a price? How does one add side­notes sup­port to an ex­ist­ing body of doc­u­ments (typ­i­cally Mark­down)? And so on.

Over­all, I would say that good side­notes should: ren­der on ei­ther both sides or the right (but not the left), use spans or links where pos­si­ble, use sta­tic HTML/CSS, dis­play by de­fault (any user effort de­feats the point!) but col­lapse to pop-ins (be­cause mo­bile users don’t have screen real es­tate to spare for op­tional ma­te­r­ial al­though many au­thors choose ex­pand­ed) with in­line be­ing an op­tion for mar­gin notes de­pend­ing on how the writer uses them, with side­notes over­lap­ping as a trade­off for not re­quir­ing JS (the au­thor will just have to rewrite such ex­ces­sive side­note us­age to avoid over­lap­ping bugs), and end­notes in ex­ist­ing cor­puses can be rewrit­ten by what­ever tool com­piles the HTML into the ap­pro­pri­ate span en­cod­ing.

Be­low I com­pare im­ple­men­ta­tions I have found, and com­pile a ta­ble of what seems to me to be the key parts of the side­notes tax­on­o­my.

My rec­om­men­da­tion is that for new or light­ly-noted writ­ings, one use Tufte-CSS-style side­notes. For heavy side­note use, a JS so­lu­tion like sidenotes.js is prob­a­bly nec­es­sary.

Comparisons

Com­par­i­son of side­notes im­ple­men­ta­tions for web pages.
Name Date Ac­tive? Lay­out Mar­gin? El­e­ment Non-JS? No click? Mo­bile Fall­back Nar­row Long Col­lapse? FLOSS Pros/Cons
Tufte-CSS, Dave Liep­mann 2014 <span> Pop-in (de­fault: col­lapsed) Pop-in Sta­t­ic, sim­ple, pop­u­lar; buggy block el­e­ments, end­note-in­com­pat­i­ble, lim­ited num­ber sup­ported
sidenotes.js, Said Achmiz 2019 ↔︎ <a> End­notes (“pop-in” planned) End­notes (eg on hov­er) MIT Scales to many, Pan­doc-com­pat­i­ble; slow, bug­gy.
side­bar, Said Achmiz 2020 <div> Pop-in ? Sta­t­ic; not in­tended for foot­notes, one-sided only (cur­rent­ly).
Ink & Switch 2016 <aside> Pop-in Pop-in Sta­t­ic; non-Free, no side­notes.
Robert Ny­s­trom 2014 <aside> In­line In­line Offers in­line fall­back; cus­tom, non-Free, re­quires JS.
Matthew But­t­er­ick 2013 <aside> In­line In­line Sta­t­ic, sim­ple, offers in­line fall­back; cus­tom, non-Free, no num­ber­ing.
Koos Looi­jesteijn 2019 <span>/<small> Pop-in (col­lapsed) Pop-in (col­lapsed) ❌? App/screen-reader-compatible, search­able; rel­a­tively com­plex, re­quires JS, non-Free.
Har­vard Law Re­view 2016? ↔︎ ❌? <span> Pop-in Pop-in ✅ (but too short! ☹) Uses both mar­gins; cus­tom, non-Free, re­quires clicks & JS.
Yale Law Jour­nal 2017? ❌? <div> ✅ (but too short! ☹) Float­ing foot­note fall­back; cus­tom, non-Free, re­quires clicks & JS, en­tire site un­us­able on mo­bile.
Knight In­sti­tute ? ❌? <span> Pop-in (col­lapsed) Pop-in (col­lapsed) ✅ (but too short! ☹) Some­what more read­able than Har­vard/Yale; cus­tom, non-Free, re­quires clicks & JS.
New York ? ❌? <span> Float­ing foot­note Float­ing foot­note MIT? Float­ing foot­note fall­back; left mar­gin, re­quires clicks for every­thing, re­quires JS, un­clear li­cense.
jQuery.side­notes, Clark 2013 <a> End­notes Pop-in (ex­pand­ed) MIT Fea­ture­ful; slow, un­main­tained, lim­ited num­ber, only on the left?
Side­notes.js, Cor­reia 2015 ↔︎ ❌? data Slide-in Slide-in MIT Unique ‘slide-in’ ap­proach; every­thing else.
The In­dia Fo­rum ? <a> Slide-in End­notes Im­proved slide-in shows all foot­notes; every­thing else.
HTML ta­bles NA NA ↔︎ <table> Sta­t­ic, sim­ple; no mobile/narrow com­pat­i­bil­i­ty, rigid, no fea­tures, hard to write or mod­i­fy.

Tufte-CSS

Ex­per­i­ments in us­ing CSS3 for side­notes date back to at least 2003, but by far the most pop­u­lar im­ple­men­ta­tion, and the pri­mary in­spi­ra­tion for most side­notes users, is the c. 2014 (Github). Tufte-CSS is out­dated in re­spects, but does side­notes sen­si­bly:

Tufte-CSS’s sec­tion on sidenotes/margin notes, demon­strat­ing sidenotes/margin notes (de­fault desk­top ap­pear­ance).
Tufte-CSS “pop-in” side­notes, col­lapsed vs un­col­lapsed (on a nar­row win­dow or mo­bile)

A Tufte-CSS-formatted side­note looks like this:

<label for="sn-extensive-use-of-sidenotes" class="margin-toggle sidenote-number"></label>

<input type="checkbox" id="sn-extensive-use-of-sidenotes" class="margin-toggle"/>

<span class="sidenote">This is a sidenote.</span>

By de­fault (on desk­top), the notes are floated right into the mar­gin; no mea­sures are taken to avoid col­li­sions or over­laps (pre­sum­ably if you have that prob­lem, you ought to just rewrite your page or fix it your­self). On nar­row win­dows & mo­bile, a me­di­a-query over­rides the reg­u­lar CSS, so the mar­gin notes are not float­ed, sim­ply in­dent­ed, and tog­gled. The CSS looks like:

.sidenote,
.marginnote {
    float: right;
    clear: right;
    margin-right: -60%;
    width: 50%;
    margin-top: 0.3rem;
    margin-bottom: 0;
    font-size: 1.1rem;
    line-height: 1.3;
    vertical-align: baseline;
    position: relative;
}

...
label.sidenote-number {
    display: inline;
}

label.margin-toggle:not(.sidenote-number) {
    display: none;
}

...
/* The mobile fallback: */
@media (max-width: 760px) {
    .sidenote,
        .marginnote {
            display: none;
        }
        .margin-toggle:checked + .sidenote,
        .margin-toggle:checked + .marginnote {
            display: block;
            float: left;
            left: 1rem;
            clear: both;
            width: 95%;
            margin: 1rem 2.5%;
            vertical-align: baseline;
            position: relative;
        }
}

Mar­gin notes are im­ple­mented sim­i­larly to side­notes be­cause a mar­gin note can just be a side­note whose num­ber is hid­den (at the pos­si­bil­ity of some user con­fu­sion at the ‘miss­ing’ endnote/sidenote, fix­able with fur­ther CSS tweaks us­ing num­ber coun­ter­s).

One thing to note about Tufte-CSS is that, like books, it dis­plays side­notes by de­fault. Many web­sites ex­per­i­ment­ing with note vari­a­tions throw away the great­est ad­van­tage—the effort­less­ness of read­ing side­notes by sim­ply sac­cad­ing left/right—in fa­vor of has­sling the user and forc­ing them to do quite as much work by click­ing var­i­ous UI el­e­ments to expand/collapse notes, de­feat­ing much of the point com­pared to a nor­mal hy­per­linked end­note.

Tufte-CSS re­quires no JavaScript and is pure HTML/CSS, del­e­gat­ing lay­out to the brows­er. It is sim­ple, fast, sup­ports mo­bile well, and wide­ly-used—it is defi­nitely the most pop­u­lar of HTML side­note im­ple­men­ta­tions. Its dis­ad­van­tages are it will not han­dle grace­fully many com­plex3 or lengthy side­notes (which will over­lap), and Tufte-CSS-style notes are not gen­er­ated by de­fault by many sys­tems (so some sort of rewrite step is nec­es­sary to in­te­grate Tufte-CSS into how­ever one ac­tu­ally cre­ates one’s web­site).

Be­cause Tufte-CSS sidenotes/margin notes are lo­cated in­line, rather than put at the end of the text like most doc­u­ment sys­tems im­ple­ment it (eg Pan­doc), one needs ei­ther to use JS to rewrite end­notes at run­time or to rewrite them at com­pile-time. Many projects gen­er­ate Tufte-CSS side­note spans di­rectly or rewrite stan­dard Mark­down <a> end­notes to spans, such as the R pack­ages “tufte” & “Tint Is Not Tufte: An im­ple­men­ta­tion in R Mark­down”. For Pan­doc, pan­doc-si­de­note is a Haskell Pan­doc fil­ter which rewrites Pan­doc’s end­notes in Tufte-CSS-style spans, and can be used with Pan­doc-based site builders like Hakyll or Jekyll (for the lat­ter, see tufte-pan­doc-jekyll & tufte-jekyll); Guil­laume Pau­mier & Matt Palmer have Lua ver­sions.

Tufte-CSS user ex­am­ples: Nico­las J. Du­quette, David Schmudde, in He­brew, Robin Schroer, Dan Pittman, Ja­son Mer­rill, An­drew Zuck­er­man, Taeer Bar-Yam, Eric Mars­den (Risk En­gi­neer­ing), Tom Critchlow.

Sim­i­lar ap­proaches (some of these are more lim­ited than Tufte-CSS; typ­i­cal­ly, au­thors fail to han­dle narrow/mobile):

sidenotes.js

sidenotes.js was de­vel­oped by Said Achmiz in 2019 for use on Gw­ern.net after look­ing at Tufte-CSS and de­cid­ing that Tufte-CSS’s sim­ple ap­proach (while ap­pro­pri­ate for most users) would fail on par­tic­u­lar­ly-heav­ily end­noted pages:

Demon­stra­tion of sidenotes.js han­dling mul­ti­ple large dense end­note an­no­ta­tions on .

The ad­van­tage over Tufte-css is that sidenotes.js ‘man­u­ally’ lays out side­notes at run­time to min­i­mize over­lap while try­ing to keep side­notes within the same win­dow as the an­chor, en­abling it to han­dle al­most ar­bi­trar­ily many long end­notes with­out ren­der­ing any un­read­able. Sidenotes/endnotes can be ar­bi­trar­ily long and con­tain most block el­e­ments like code blocks, block­quotes, lists, im­ages, ta­bles, etc. While it’s at it, side­notes are high­lighted & their match­ing an­chors high­lighted on hov­er, too-long side­notes are par­tially col­lapsed (the user clicks to ex­pand them). Fur­ther, it sup­ports a cus­tom “mar­gin note” fea­ture: any HTML spans of text with the class marginnote will be popped out of the text into the mar­gin if there is room, or it will be left in place & ital­i­cized. (I place mar­gin notes at the be­gin­ning of para­graphs as sum­maries, let­ting users more eas­ily skim.)

The dis­ad­van­tage com­pared to pure sta­tic HTML/CSS ap­proaches is that the JS needs to load and copy the end­notes into side­notes, re­flow as nec­es­sary over the whole page, which is user-vis­i­ble & dis­tract­ing; this is no­tice­able even putting the load in the HEAD to speed it up. It can also in­ter­act with other com­pli­cated fea­tures and while it will han­dle heavy note loads much bet­ter than most sta­tic ap­proaches (most of which don’t even try to avoid er­rors like over­lap­s), it still has sub­tle bugs.4 Fur­ther, mo­bile sup­port has not been im­ple­ment­ed, leav­ing the reg­u­lar end­note func­tion­al­ity as a fall­back. (Ach­miz in­tends to im­ple­ment mo­bile side­notes as “pop-ins” like Tufte-CSS.)

For nar­row win­dows, other ap­proaches can be used. On Gw­ern.net, I use float­ing foot­notes which ‘pop up’ when the user hov­ers over a foot­note an­chor5, which avoids the need to nav­i­gate to the end of the page & back.

sidenotes.js as­sumes that the doc­u­ment has been gen­er­ated from Pan­doc Mark­down and has nor­mal Pan­doc end­notes (of the form <a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> for the an­chor, and <li id="fn1" role="doc-endnote"><p>Example</p></li> for the end­note body at the end of the doc­u­men­t). Hence, im­ple­ment­ing side­notes with it re­quires lit­tle more than a JS im­port like <script src="/static/js/sidenotes.js" async></script>. (This has some ad­van­tages: for ex­am­ple, footnotes/sidenotes re­main link­able—one can link to #fn1 or #sn1 as de­sired. Al­though ar­guably if any­one needs to link a spe­cific foot­note it may be time to rewrite that foot­note into some­thing like a sec­tion or ap­pen­dix, as Pan­doc foot­note num­bers are un­sta­ble and adding/removing a foot­note be­fore a linked foot­note will break links to it, it is con­ve­nient to be able to do so.)

Users or sim­i­lar im­ple­men­ta­tions:

Ink & Switch

Ink & Switch’s pages like ’s 2016 sta­tic mar­gin notes fea­ture looks much like Tufte-CSS in us­ing HTML/CSS to cre­ate right-aligned side­notes, al­though Ink & Switch es­chews ex­plicit foot­note num­ber­ing and its pop-ins are un­col­lapsed by de­fault.

Ink & Switch, “Lo­cal-first soft­ware” mar­gin notes
Ink & Switch, “Lo­cal-first soft­ware” mar­gin notes, mo­bile (pop-in, de­fault ex­pand­ed)

Im­ple­men­ta­tion-wise, it takes a no­tice­ably differ­ent tack in which CSS fea­tures it us­es. The HTML it­self is just an <aside> el­e­ment:

<aside><p><a href="https://ourincrediblejourney.tumblr.com/">Our incredible journey</a>
    is a blog that documents startup products getting shut down after an acquisition.</p></aside>

But their CSS uses calc() ex­ten­sively to cre­ate po­si­tion­ing & read­just over­laps with­out JS:

article aside, figcaption, header>#byline {
  --aside-offset: 1rem;
  --aside-offset-lineheight: 1.5rem;
  box-sizing: border-box;
  margin-bottom: calc(var(--padding) * 2);
  padding: var(--padding);
  position: absolute;
  right: 0;
  width: var(--aside-width);
}

aside, figcaption, figure img, figure video {
  border-radius: calc(var(--padding)/4);
  max-width: 100%;
}

aside, aside>*, #byline, #byline li, figcaption, figcaption>*, blockquote footer {
  font-size: 0.8125rem;
  font-weight: 400;
  -ms-hyphens: none;
  -webkit-hyphens: none;
  hyphens: none;
  line-height: 1.25rem;
  margin-bottom: 0.5rem;
  text-align: left;
}

...
/* aside and figcaption nudge ---------------- */

/* using these can cause overlapping of elements. if you apply to one aside, you may
    need to apply and adjust other that precede clearing the blocks figcaption or section */

.move-up-1 {
  margin-top: calc((var(--aside-offset) + (var(--aside-offset-lineheight)*1))/-1);
}

.move-up-2 {
  margin-top: calc((var(--aside-offset) + (var(--aside-offset-lineheight)*2))/-1);
}
...
.move-up-25 {
  margin-top: calc((var(--aside-offset) + (var(--aside-offset-lineheight)*25))/-1);
}

One down­side is that there is no sup­port for num­ber­ing I can see, so they’re all mar­gin notes. The CSS is con­sid­er­ably more com­plex and I’m not sure what the com­plex­ity gains one com­pared to Tufte-CSS—correctness?

Robert Nystrom

Game pro­gram­mer Robert Ny­s­trom’s 2014 book Game Pro­gram­ming Pat­terns, makes heavy use of side­notes im­ple­mented in HTML/CSS/JS, mostly sim­i­lar to Tufte-CSS.

Game Pro­gram­ming Pat­terns, desk­top side­notes
Game Pro­gram­ming Pat­terns, mo­bile (in­line, ex­panded by de­fault)

He takes a differ­ent ap­proach: side­notes are writ­ten us­ing the HTML <aside> el­e­ment, and a <span> with each aside’s ID spec­i­fies their place­ment in the text; the JS then moves the aside into the mar­gin. He de­signed it to han­dle re­siz­ing be­low <800px not by pop-in foot­notes in a block, but by me­di­a-queries sim­ply shift­ing the aside into the text, in­line. (With no JS, the fall­back is also in­clud­ing it in­line.)

<p>Let&#8217;s say we want a happy face to appear on screen. Our program starts looping
through the framebuffer, coloring pixels. What we don&#8217;t realize is that the
video driver is pulling from the framebuffer right as we&#8217;re writing to it. As it
scans across the pixels we&#8217;ve written, our face starts to appear, but then it
outpaces us and moves into pixels we haven&#8217;t written yet. The result is
<em>tearing</em>, a hideous visual bug where you see half of something drawn on screen.</p>
<p><span name="tearing"></span></p>
<p><img src="images/double-buffer-tearing.png" alt="A series of images of an in-progress frame
    being rendered. A pointer writes pixels while another reads them. The reader outpaces the writer
    until it starts reading pixels that haven't been rendered yet." /></p>
<aside name="tearing">

<p>We start drawing pixels just as the video driver starts reading from the
framebuffer (Fig. 1). The video driver eventually catches up to the renderer and
then races past it to pixels we haven&#8217;t written yet (Fig. 2). We finish drawing
(Fig. 3), but the driver doesn&#8217;t catch those new pixels.</p>
<p>The result (Fig. 4) is that the user sees half of the drawing. The name
&#8220;tearing&#8221; comes from the fact that it looks like the bottom half was torn off.</p>
</aside>
@media only screen and (min-width: 800px) {
  .page {
    padding-right: 300px; }

  aside {
    position: absolute;
    width: 240px;
    right: 30px;
    padding: 0;
    background: none;
    border: none;
    padding-left: 22px;
    border-radius: 0;
    border-left: solid 8px #f0e9db; }
  aside p, aside li {
      font: 14px/20px "Source Sans Pro", "Lucida Grande", "Lucida Sans Unicode", Verdana, sans-serif; } }

It’s un­clear to me whether the JS is ac­tu­ally nec­es­sary, or whether in­line is the best fall­back for side­notes. The use of <aside> is also a com­pli­ca­tion, as few for­mats in­clude any na­tive sup­port for that.

Ny­s­trom’s books are an in­ter­est­ing read for pro­gram­mers, and also have some other in­ter­est­ing de­sign as­pects: see “Zero to 95,688: How I wrote Game Pro­gram­ming Pat­terns/“Craft­ing Craft­ing In­ter­preters on the build sys­tem & lit­er­ate pro­gram­ming & his hand-drawn il­lus­tra­tion work­flow; & “Zero to 353 Pages: Bring­ing My Web Book to Print and eBook” on work­ing with EPUB & type­set­ting the print book.

Matthew Butterick

Matthew But­t­er­ick’s 2013 ebook/website Prac­ti­cal Ty­pog­ra­phy uses mar­gin notes, but in a side­notes way, on the left:

Mar­gin note left in Prac­ti­cal Ty­pog­ra­phy.

They fall­back to pop-ins de­faulted to ex­panded on narrow/mobile win­dows:

The same mar­gin note, on a nar­row win­dow: it now ap­pears as a pop-in block el­e­ment, but ex­panded with­out the user need­ing to click (as they would in Tufte-CSS).

The ap­proach is HTML/CSS, but us­ing <aside> el­e­ments, which are styled in CSS:

title-block, aside {
    display: block;
    float: left;
    position: absolute;
    margin-left: 0;
    left: 2.5rem;
    width: calc(2.5rem * 3);
    text-align: right;
    list-style-type: none;
    clear:both; margin-bottom: 1rem;
    font-variant-numeric: normal;
}

@media all and (min-width:1200px) {
    aside {
        left : 0;
        width: calc(2.5rem * 4);
    }
}

@media all and (max-width:520px) {
    title-block, aside { float: inherit;
    position: inherit;
    width: 100%;
    text-align: left;}

    aside {
        background: #fefefe;
        padding: 0.3rem 0.5rem;
        width: 90%;
        border: 1px solid #ccc;
        border-left: 3px solid #ccc;
    }

    aside > p:last-child {
        margin-bottom: 0;
    }
}

Pre­sum­ably But­t­er­ick used his Rack­et-based Pollen doc­u­ment sys­tem with cus­tom tags, since the base sys­tem does­n’t cover notes; San­cho Mc­Cann & Jonas Hi­etala has doc­u­mented Pollen side­notes.

Koos Looijesteijn

Koos Looi­jesteijn’s loosely Tufte-CSS-like side­notes are right-aligned, sym­bol rather than num­ber in­cre­ment­ed, and narrow/mobile col­lapsed pop-ins:

KL, desk­top
KL, mo­bile (pop-in clicked)

In “Se­man­tic side­notes for the web” 2019, he dis­cusses his ap­proach, in­tended to sat­isfy ad­di­tional re­quire­ments:

  • The span that the side­note refers to should have a proper se­man­tic HTML el­e­ment (no abuse of el­e­ments made for other pur­pos­es)

  • The con­tent of the side­note should have a sim­i­larly valid HTML tag. Ad­di­tion­al­ly:

    • The side­note con­tent may con­tain span el­e­ments such as <a> and <em>.
    • The side­note con­tent may con­tain click­able el­e­ments that can re­ceive key­board fo­cus.
    • The side­note con­tent must be sty­lable.
  • The el­e­ments should not cause auto clos­ing of their par­ent <p> tag.

  • Reader modes and apps like Pocket and RSS read­ers should show side­note con­tent in a ty­po­graph­i­cally ac­cept­able way. That means at the very least that I can’t rely on web­site’s CSS to place and style the el­e­ments cor­rect­ly.

  • The side­note con­tent should be read by screen read­ers, in a flow that makes sense. That likely means the two parts should be placed to­geth­er.

He came up with some­thing ini­tially like Tufte-CSS, but re­jected pure <span>, <aside> as be­ing not quite the right se­man­tics, purely sta­tic as break­ing reader mode/apps, and set­tled on JS-en­hanced <span>/<small> com­bi­na­tion.

Harvard Law Review

The web­site has, since at least 2016, em­ployed side­notes, as is par­tic­u­larly ap­pro­pri­ate for le­gal writ­ing, which no­to­ri­ously overuses foot­notes for ci­ta­tions, prece­dents, and di­gres­sions. From “The Po­ten­tial-Use Test and the North­west Pas­sage” (HLR ed­i­tors 2020):

HLR, desk­top; note the de­fault collapse/fade
HLR, mo­bile (pop-in on click)

HLR’s pro­pri­etary are bidi­rec­tion­al, JS-based, and col­lapsed pop-in on mo­bile; they use <span>s which are re­arranged by the JS:

Canada, on the other hand, asserts that the Northwest Passage constitutes internal waters and does
not fall under any definition of international strait.
<sup class="footnote-ref js-article-aside-trigger "><i class="ref-txt">2</i><i class="close-txt">&times;</i></sup>
<cite class="article-aside footnote short-crop">
    <span class="article-aside-txt">
        <span class="footnote-num">2.</span>
        <em>See</em> Territorial Sea Geographical Coordinates (Area 7) Order, SOR/1985-872 (Can.) (detailing Canada’s
        claims to land and waters that include the Northwest Passage); Note from the Canadian Embassy, Washington, D.C.,
        to the U.S. Department of State (June 11, 1985), <em>reprinted in</em> 2 <span class="small-caps">Marion Nash (Leich),
        Dep’t of State, Cumulative Digest of United States Practice in International Law 1981–1988</span>, at 2047 (1994).
    </span>
</cite>

Since it uses in­line <span> in the usual Tufte-CSS, one might won­der why the JS is nec­es­sary, but check­ing with No­Script, one sees that with­out the JS, the side­notes are all piled up on the left mar­gin, over­lap­ping bad­ly, so the JS does the ‘al­ter­nat­ing’. (Is it pos­si­ble to use CSS to do this al­ter­na­tion au­to­mat­i­cal­ly, re­mov­ing the need for JS to do bidi­rec­tional side­notes?)

More dis­tress­ing­ly, HLR’s side­notes are also on de­fault col­lapsed on desk­top, trimmed at a shock­ingly short length­—­typ­i­cally not even half a sen­tence! While col­laps­ing long foot­notes is a good idea, it’s puz­zling to col­lapse at such a short length that lit­er­ally every side­note will be col­lapsed, since this again de­feats the point of hav­ing side­notes, and mak­ing it hard to see if a side­note is worth click­ing on since only the first few words are ex­posed so one can­not even see if the side­note is short (merely a bit of ci­ta­tion) or long (a more in­-depth dis­cus­sion).

Yale Law Journal

The , like HLR, uses side­notes in on­line ar­ti­cles like “Ama­zon’s An­titrust Para­dox” (Khan 2017), since at least 2016. Like HLR, all side­notes are ag­gres­sively col­lapsed to near-un­read­abil­i­ty, re­quir­ing a click to ex­pand, where­upon they turn into float­ing foot­notes.

YLJ, de­fault desk­top
YLJ, side­notes clicked on to ex­pand

They are JS-based, re­lo­cat­ing foot­notes grouped at the end of the ar­ti­cle, but in­side <div> el­e­ments rather than <a> el­e­ments like usu­al:

<div id="footnote_wrapper" style="position:relative;">
    <div id="footnote_1" style="display:none;" class="footnote_truncated">
        <div class="truncated_footnote_number">1</div>
        <div class="truncated_footnote_inner"><span> </span>David <span class="SpellE">Streitfeld</span>,
            <i>As Competition Wanes, Amazon Cuts Back Discounts</i>,
            <span class="forced_sans_reg">N.Y. Times</span> (July 4, 2013), http&hellip;
            </div>
    </div>
...</div>

Worse, YLJ ap­pears to have no nar­row or mo­bile sup­port what­so­ev­er—the page just gets small­er. YLJ is un­read­able on mo­bile, re­quir­ing zoom­ing & pan­ning.

Knight Institute

The Knight First Amend­ment In­sti­tute of uses side­notes some­what like HLR/YLJ in its long­form pages (eg “The Case for Dig­i­tal Pub­lic In­fra­struc­ture: Har­ness­ing past suc­cesses in pub­lic broad­cast­ing to build com­mu­ni­ty-ori­ented dig­i­tal tools”, Zuck­er­man 2020):

Knight In­sti­tute side­notes (not ex­pand­ed)

They are JS-based, right-aligned, col­lapsed (but with a slightly more gen­er­ous length limit than HLR/YLJ), and fall­back to Tufte-CSS-like pop-in blocks (de­fault col­lapsed). As sim­i­lar as it seems to those, Knight ap­pears to have rolled its own JS, as the site.js’s im­ple­men­ta­tion does­n’t have any Google/Github hits.

The fad­ing, font size, and de­fault col­laps­ing of ‘long’ side­notes are all not nearly as ex­treme as HLR/YLJ, so the Knight side­notes are sub­stan­tially more pleas­ant to read, as it’s much eas­ier to see what side­notes are merely a brief ci­ta­tion and what ac­tu­ally in­clude ad­di­tional com­men­tary. (The use of but­tons & chevrons are also nice touches in ex­plain­ing the func­tion­al­ity to the read­er.)

New York

’s web­site CMS Clay/Kiln (used on NYmag.com/Vulture/the Cut/Grub Street/Slate) pro­vide JS-based left side­notes which re­quire hover to ex­pose and then fall back to click­-driven float­ing foot­notes:

Vul­ture, desk­top (on hov­er)
Vul­ture, mo­bile (after click­ing)

NY uses spans, but they are put at the end and then JS re­veals them when the user hov­ers:

<span class="clay-annotated kiln-phrase" aria-describedby="annotation-1" tabindex="0">Virgin Airlines first-class lounge</span>
...
<div data-uri="www.vulture.com/_components/annotations/instances/cjg2jwsso00c23k62pm0yv0qg@published"
     class="annotations" data-editable="content">
    <span role="tooltip" id="annotation-1" data-uri="www.vulture.com/_components/annotation/instances/cjg2jx3el00c73k62em8v15xy@published"
       class="annotation" data-editable="text">
       Offers spa treatments, “expert mixologists,” and, at Heathrow, a “lodge and viewing deck” with an “après-ski vibe.”
   </span>
</div>

I could­n’t find men­tion of side­notes in the var­i­ous Clay/Kiln Github re­pos but there are enough of them and it’s all com­pli­cated enough I may have missed them, so I don’t know if the rel­e­vant JS/CSS is MIT-licensed like the Clay/Kiln ecosys­tem gen­er­ally seems to be.

While float­ing foot­notes on mo­bile is a jus­ti­fi­able choice, the rest is not, and I do not like this side­note de­sign at all.

jQuery.sidenotes

An­drew Clark’s 2013 jQuery.side­notes (Github) JS li­brary im­ple­ments side­notes to the left, pars­ing Mark­down end­notes; for nar­row win­dows, it does in­lined ‘pop-in’ but ex­panded by de­fault; and for mo­bile it is just end­notes. Un­usu­al­ly, Clark’s demo puts side­notes on the left mar­gin (there does­n’t seem to be an op­tion for plac­ing on the right, or both), and in­cludes some key­bind­ings.

jQuery.side­notes (de­fault desk­top ap­pear­ance)

The pop-in ap­pear­ance looks like Tufte-CSS’s.

The im­ple­men­ta­tion seems to take the ex­pected ap­proach of pop­ping match­ing el­e­ments out into the mar­gin with me­dia queries con­trol­ling width-re­lated be­hav­ior.

Clark’s jQuery.side­notes offers more fea­tures than usu­al, but I’m not sure how use­ful they are. It’s also quite ‘heavy­weight’ in be­ing weighed down by jQuery/NPM in­fra­struc­ture. One fur­ther caveat: I think the ex­pected format/classes of end­notes has long since changed and the li­brary has not been up­dated since 2013, at least for Pan­doc, so jQuery.side­notes’s de­faults will prob­a­bly break for re­cent Mark­down doc­u­ments.

Sidenotes.js, Correia

Bruno Cor­reia’s 2015 Side­notes.js (Github), not to be con­fused with Said Achmiz’s sidenotes.js, takes an en­tirely differ­ent ap­proach to both pre­sen­ta­tion & en­cod­ing of side­notes. In­stead of reusing the ex­ist­ing mar­gin, Side­notes.js cre­ates a new view by slid­ing a stick­y-ele­ment ‘tab’ into view with the side­note con­tents, hid­ing the orig­i­nal page:

Side­notes.js, before/after click­ing on an an­no­tated link (desk­top)

On nar­row or mo­bile, the slid-in new page just takes up the whole screen.

The an­no­ta­tions are them­selves writ­ten as cus­tom data at­trib­utes on el­e­ments such as links (by de­fault, oth­ers are sup­port­ed):

<p>While the two headsmen were engaged in making fast cords to his flukes,
and in other ways getting the mass in readiness for towing,
some <a
    href="#"
    data-sidenote="&gt;strong&lt;Conversation:&gt;/strong&lt; the informal exchange of ideas by spoken words:
                   'the two men were deep in conversation'.">
    conversation</a>
ensued between them.</p>

This is a unique ap­proach en­tirely un­like the oth­ers and an in­ter­est­ing ex­per­i­ment, but I do not rec­om­mend it for side­notes.

The India Forum

The In­dia Fo­rum uses jQuery for a slide-in ap­proach but im­proves over Cor­reia’s by show­ing all the side­notes in a pane after click­ing:

TIF, after click­ing on foot­notes

Tables

Jukka “Yucca” Ko­r­pela, ~2007, demon­strates a com­pletely differ­ent ap­proach us­ing HTML ta­bles: de­fine two columns with differ­ent sizes/style, and put the side­notes in the sec­ond col­umn.

There are many pos­si­ble ap­proaches to in­clud­ing side­notes on web pages. Hav­ing stud­ied al­ter­nate meth­ods like CSS po­si­tion­ing and float­ing, I have come to the con­clu­sion that the sim­plest method gives the best re­sults. This method con­sists of a two-col­umn table, with the main text in one column, the side­notes in the oth­er. Us­ing the CSS meth­ods, it be­comes awk­ward to con­trol the heights of pieces of text so that each side­note starts at the same ver­ti­cal po­si­tion as the main text that it re­lates to.

Easy:

Side­notes via 2-col­umn HTML ta­bles.

This has the usual advantages/disadvantages of us­ing ta­bles for web de­sign: it is fast, avoids Javascript & (most) CSS com­plex­i­ties, and is straight­for­ward; but it is rigid, de­grades on smaller screens, diffi­cult to write (eg no num­ber­ing in Ko­r­pela’s ex­am­ples, mak­ing them mar­gin notes, un­less the au­thor man­u­ally adds su­per­scripts or oth­er­wise com­pli­cates it).

I in­clude this for its his­tor­i­cal in­ter­est—while this strat­egy may have made sense in 2007, the trade­offs now are highly un­fa­vor­able given that Tufte-CSS etc work, and I’m not sure any­one should use it.

Miscellaneous

Some im­ple­men­ta­tions are just bad ideas or not worth dis­cussing in de­tail with screen­shots:

  • ILoveTy­pog­ra­phy.­com uses im­age cap­tions & mar­gin notes which, like Tufte-CSS, are floated/outdented right, but bizarrely, it uses fig­ure cap­tions—just <figcaption> with a spe­cial class in­side an empty <figure> with no im­ages!

    This is in­valid HTML, fails badly in some cases (eg in the linked ex­am­ple, one mar­gin note is al­most un­read­able be­cause it over­laps with a gi­ant pul­l-quote il­lus­tra­tion), has no ad­van­tage over a <span> that I can find; it does at least de­grade grace­fully into pop-in (de­fault ex­pand­ed) block el­e­ments on narrow/mobile.

  • BLDBLOG gen­er­ally avoids com­plex lay­out and foot­notes en­tire­ly, and does­n’t have much mar­gin to put side­notes in, so I was sur­prised while read­ing the archives to find one post which has a left mar­gin note, and even more sur­prised to check the HTML source and see that the ‘mar­gin note’ is in fact a header: a <h6>.

    Huh‽ It turns out that the header is floated left with some grue­some CSS. Said Achmiz sum­maries how the Rube Gold­berg con­trap­tion works:

    The CSS uses ab­solute po­si­tion­ing. The near­est po­si­tioned an­ces­tor is <article>, not .entry-content. Within <article>, .entry-content is right-floated and has a fixed width. This cre­ates a vari­able-width space on the left (de­ter­mined by how much hor­i­zon­tal space is left within <article> after that fixed width is sub­tract­ed). The side­note <h6> is then set with position:absolute and left:0. Ver­ti­cal po­si­tion is left un­spec­i­fied, re­ly­ing on the way browsers im­ple­ment ab­solute po­si­tion­ing (i.e., to place an el­e­ment where it would be placed if po­si­tion were static) to put it in the right place. Frag­ile, un­se­man­tic, & hacky.

See Also


  1. You can imag­ine web pages with true foot­notes: where a sticky bot­tom mar­gin is cre­at­ed, re­served for foot­notes, and JS in­serts the rel­e­vant foot­notes into that as the user scrolls, but I’m not sure I’ve ever seen this out­side of book skeuo­morph web de­signs with ex­plicit pag­i­na­tion, and screens are small enough that users would chafe at the loss of ver­ti­cal pix­els.

    Then should we put our notes on en­tirely sep­a­rate pages? No: this only adds to the read­er’s bur­den, and it’s even more work for the au­thor. (The ded­i­cated might em­brace hy­per­tex­tu­al­ity and cre­ate an enor­mous web of small nuggets of text which in­clude and go be­yond end­notes, but for peo­ple writ­ing on­line, URLs/pages tend to be “heavy­weight”, and a com­mit­ment, often cor­re­spond­ing to a sin­gle file on disk; cre­at­ing hun­dreds of end­note-sized URLs also cre­ates its own prob­lems like nam­ing, re­find­ing, and nav­i­gat­ing them.)↩︎

  2. You can use the sidenotes/marginnote (where the na­tive \marginpar{} com­mand fails) pack­ages.↩︎

  3. Tufte-CSS side­notes do not cor­rectly sup­port block el­e­ments like lists or para­graphs, be­cause spans are in­line and those are block el­e­ments; but this is fix­able.↩︎

  4. For ex­am­ple, as of 2020-08-09, mar­gin notes do not quite in­ter­act right, and oc­ca­sion­ally over­lap with side­notes; an ex­am­ple of this er­ror can be seen (some­times) in my .↩︎

  5. Some web­sites, like Grant­land or Strat­e­ch­ery, sup­port float­ing foot­notes… but only when the user clicks! (Bet­ter is Grant­land’s his­tory of the Gra­cies, which helps the reader keep the clan straight by pop­ping into the left mar­gin an an­no­tated fam­ily tree when­ever they click a Gra­cie name.) FiveThir­tyEight, on the other hand, does pop-in foot­notes—but not side­notes, de­spite am­ple mar­gin. Com­pare At­lantic’s web ren­der­ing us­ing pop-ins with the orig­i­nal 2005 David Fos­ter Wal­lace print es­say which used elab­o­rate re­cur­sive side­notes in­te­grated in un­usual geome­tries. (Said Achmiz offers an ex­am­ple of a less ugly re­design of that.)↩︎