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-08-09 finished certainty: certain importance: 2


Sidenotes/margin notes are a typo­graphic con­ven­tion which improves on foot­notes & end­notes by instead putting the notes in the page mar­gin to let the reader instantly read them with­out need­ing to refer 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, reduce the read­er’s effort but don’t elim­i­nate it.)

How­ev­er, they are not com­monly used, per­haps because web browsers until rel­a­tively recently made it hard to imple­ment side­notes eas­ily & reli­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 approach­es. I review some of the avail­able imple­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 inte­grate into most web­site work­flows. For heavy foot­note users or users who want a drop-in, run­time Javascrip­t-based solu­tions like sidenotes.js may be more use­ful.

Side­notes and mar­gin notes (some­times also called “asides”) are an alter­na­tive to in design. Where foot­notes put addi­tional mate­r­ial in small sec­tions at the bot­tom of the page, orga­nized by num­ber, and end­notes stuff them at the end of the doc­u­ment, side­notes instead use the large unused left/right mar­gin of the page.

Because it’s uncom­fort­able to read sen­tences which wrap from edge to edge, par­tic­u­larly for large widths, requir­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 occa­sional foot­note or end­note, includ­ing ancil­lary mate­r­ial like cita­tions or digres­sions or extended dis­cus­sion of tricky points or antic­i­pa­tion of objec­tions or just the author being wit­ty, which require con­stant back and forth from the place in the text where they make sense and where they can actu­ally be read. As a result, who ever reads end­notes in a phys­i­cal book? Only the most dili­gent will keep a thumb in the back to actu­ally look up end­notes, and so they are either unread or tend to be rel­e­gated to the most util­i­tar­ian uses like raw cita­tions.

The sit­u­a­tion is even worse on the Inter­net, because while foot­notes in a book aren’t too bad (as long as they stay on the same page), web pages don’t really have ‘pages’ and ‘foot­notes’ wind up degrad­ing to sim­ply end­notes.1

Why do we use end­notes? For the most part, we use them for cita­tion meta­data, abbreviations/definitions, and more extended dis­cus­sions (often humor­ous). But none of these are served well online by end­notes: cita­tion meta­data is bet­ter pro­vided as hyper­links to full­text, defi­n­i­tions/abbre­vi­a­tions have native HTML sup­port as tooltips/popups—leaving only the extended dis­cus­sions use-case.

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

Foot­notes are the very emblem of fussi­ness, but they have their uses. If they are short and infre­quent, they can be made eco­nom­i­cal of space, easy to find when wanted and, when not want­ed, easy to ignore. Long foot­notes are inevitably a dis­trac­tion: tedious to read and weary­ing to look at. Foot­notes that extend to a sec­ond page (as some long foot­notes are bound to do) are an abject fail­ure of design.

End­notes can be just as eco­nom­i­cal of space, less trou­ble to design and less expen­sive to set, and they can com­fort­ably run to any length. They also leave the text page clean except for a pep­per­ing of super­scripts. They do, how­ev­er, require the seri­ous reader to use two book­marks and to read with both hands as well as both eyes, swap­ping back and forth between the pop­u­lar and the per­snick­ety parts of the text.

Side­notes give more life and vari­ety to the page and are the eas­i­est of all to find and read. If care­fully designed, they need not enlarge either 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, depend­ing on their fre­quency and impor­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 super­scripts at all (as in this book), or with the same sym­bol (nor­mally an aster­isk) con­stantly reused, even when sev­eral notes appear on a sin­gle page.

Our extended 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 unused mar­gin, in a way which is com­fort­able to read, and which is com­pat­i­ble with exist­ing doc­u­ments & work­flows using end­notes: sim­ply move those end­notes into the mar­gin of the text they refer to. The user can com­fort­ably sac­cade over to a side­note instantly to skim it and back, the infor­ma­tion den­sity of the lay­out increas­es, it requires no exotic tech­nolo­gies or rewrites or user edu­ca­tion, it has a long respectable his­to­ry, and it’s just gen­er­ally a good idea.

Examples

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

Bringhurst 2004 exam­ple of side­notes & mar­gin notes (in this case, it repeats the sec­tion head­ing)

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

, demon­strat­ing recur­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 :

Exam­ple of Tufte’s use of side­notes & mar­gin notes: they pro­vide addi­tional exam­ples, com­men­tary, and cita­tion meta­data for the reader in con­text, with­out forc­ing inscrutable 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”, Envi­sion­ing Infor­ma­tion, Tufte 1990)

in uses mar­gin notes as a kind of index, list­ing key­words in the mar­gin. The den­sity of key­words can make the mar­gins inter­est­ing to read on their own; an exam­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 algo­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 online for HTML?

Although 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 always, there are a lot of ways to accom­plish that goal, and many ways we can enhance (or screw up) them.

Do we put them on the left, right, or both sides? What of the sev­eral pos­si­ble HTML ele­ments are our side­notes delim­ited as (<span>, <a>, <div>, <aside>, <small>, or even <table>)? Do we use Javascript, accept­ing that it’ll ‘flash’ an incor­rectly ren­dered page as the JS loads & runs, and out­right break for users with JS turned off (as is increas­ingly sen­si­ble on an ever-more-hos­tile Inter­net)? Does the user have to click or do any­thing to make side­notes vis­i­ble? If not, what about on mobile 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 ‘inline’ as sim­ply part of their para­graph, or do we dis­play them as sep­a­rate blocks (‘pop-in’) and by default 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 approach­es, but is that too great a price? How does one add side­notes sup­port to an exist­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 either 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 default (any user effort defeats the point!) but col­lapse to pop-ins (be­cause mobile users don’t have screen real estate to spare for optional mate­r­ial although many authors choose expand­ed) with inline being an option for mar­gin notes depend­ing on how the writer uses them, with side­notes over­lap­ping as a trade­off for not requir­ing JS (the author will just have to rewrite such exces­sive side­note usage to avoid over­lap­ping bugs), and end­notes in exist­ing cor­puses can be rewrit­ten by what­ever tool com­piles the HTML into the appro­pri­ate span encod­ing.

Below I com­pare imple­men­ta­tions I have found, and com­pile a table 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 solu­tion like sidenotes.js is prob­a­bly nec­es­sary.

Comparisons

Com­par­i­son of side­notes imple­men­ta­tions for web pages.
Name Date Active? Lay­out Mar­gin? Ele­ment Non-JS? No click? Mobile 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 ele­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.
Ink & Switch 2016 <aside> Pop-in Pop-in Sta­t­ic; non-Free, no side­notes.
Robert Nys­trom 2014 <aside> Inline Inline Offers inline fall­back; cus­tom, non-Free, requires JS.
Matthew But­t­er­ick 2013 <aside> Inline Inline Sta­t­ic, sim­ple, offers inline 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, requires JS, non-Free.
Har­vard Law Review 2016? ↔︎ ❌? <span> Pop-in Pop-in ✅ (but too short! ☹) Uses both mar­gins; cus­tom, non-Free, requires clicks & JS.
Yale Law Jour­nal 2017? ❌? <div> ✅ (but too short! ☹) Float­ing foot­note fall­back; cus­tom, non-Free, requires clicks & JS, entire site unus­able on mobile.
Knight Insti­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, requires clicks & JS.
New York ? ❌? <span> Float­ing foot­note Float­ing foot­note MIT? Float­ing foot­note fall­back; left mar­gin, requires clicks for every­thing, requires JS, unclear license.
jQuery.side­notes, Clark 2013 <a> End­notes Pop-in (ex­pand­ed) MIT Fea­ture­ful; slow, unmain­tained, lim­ited num­ber, only on the left?
Side­notes.js, Cor­reia 2015 ↔︎ ❌? data Slide-in Slide-in MIT Unique ‘slide-in’ approach; every­thing else.
The India Forum ? <a> Slide-in End­notes Improved slide-in shows all foot­notes; every­thing else.
HTML tables 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

Exper­i­ments in using CSS3 for side­notes date back to at least 2003, but by far the most pop­u­lar imple­men­ta­tion, and the pri­mary inspi­ra­tion for most side­notes users, is the c. 2014 (Github). Tufte-CSS is out­dated in respects, 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 appear­ance).
Tufte-CSS “pop-in” side­notes, col­lapsed vs uncol­lapsed (on a nar­row win­dow or mobile)

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 default (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 & mobile, a medi­a-query over­rides the reg­u­lar CSS, so the mar­gin notes are not float­ed, sim­ply indent­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 imple­mented sim­i­larly to side­notes because 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 using num­ber coun­ter­s).

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

Tufte-CSS requires no JavaScript and is pure HTML/CSS, del­e­gat­ing lay­out to the brows­er. It is sim­ple, fast, sup­ports mobile well, and wide­ly-used—it is defi­nitely the most pop­u­lar of HTML side­note imple­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 default by many sys­tems (so some sort of rewrite step is nec­es­sary to inte­grate Tufte-CSS into how­ever one actu­ally cre­ates one’s web­site).

Because Tufte-CSS sidenotes/margin notes are located inline, rather than put at the end of the text like most doc­u­ment sys­tems imple­ment it (eg Pan­doc), one needs either 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 directly or rewrite stan­dard Mark­down <a> end­notes to spans, such as the R pack­ages “tufte” & “Tint Is Not Tufte: An imple­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 exam­ples: Nico­las J. Duquette, David Schmudde, in Hebrew, Robin Schroer, Dan Pittman, Jason Mer­rill, Andrew Zuck­er­man, Taeer Bar-Yam, Eric Mars­den (Risk Engi­neer­ing), Tom Critchlow.

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

sidenotes.js

sidenotes.js was devel­oped by Said Achmiz in 2019 for use on Gwern.net after look­ing at Tufte-CSS and decid­ing that Tufte-CSS’s sim­ple approach (while appro­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 anno­ta­tions on .

The advan­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 anchor, enabling it to han­dle almost arbi­trar­ily many long end­notes with­out ren­der­ing any unread­able. Sidenotes/endnotes can be arbi­trar­ily long and con­tain most block ele­ments like code blocks, block­quotes, lists, images, tables, etc. While it’s at it, side­notes are high­lighted & their match­ing anchors high­lighted on hov­er, too-long side­notes are par­tially col­lapsed (the user clicks to expand 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 begin­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 approaches is that the JS needs to load and copy the end­notes into side­notes, reflow as nec­es­sary over the whole page, which is user-vis­i­ble & dis­tract­ing; this is notice­able even putting the load in the HEAD to speed it up. It can also inter­act with other com­pli­cated fea­tures and while it will han­dle heavy note loads much bet­ter than most sta­tic approaches (most of which don’t even try to avoid errors like over­lap­s), it still has sub­tle bugs.4 Fur­ther, mobile sup­port has not been imple­ment­ed, leav­ing the reg­u­lar end­note func­tion­al­ity as a fall­back. (Ach­miz intends to imple­ment mobile side­notes as “pop-ins” like Tufte-CSS.)

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

sidenotes.js assumes 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 anchor, 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, imple­ment­ing side­notes with it requires lit­tle more than a JS import like <script src="/static/js/sidenotes.js" async></script>. (This has some advan­tages: for exam­ple, footnotes/sidenotes remain link­able—one can link to #fn1 or #sn1 as desired. Although arguably 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 appen­dix, as Pan­doc foot­note num­bers are unsta­ble and adding/removing a foot­note before 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 imple­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 using HTML/CSS to cre­ate right-aligned side­notes, although Ink & Switch eschews explicit foot­note num­ber­ing and its pop-ins are uncol­lapsed by default.

Ink & Switch, “Local-first soft­ware” mar­gin notes
Ink & Switch, “Local-first soft­ware” mar­gin notes, mobile (pop-in, default expand­ed)

Imple­men­ta­tion-wise, it takes a notice­ably differ­ent tack in which CSS fea­tures it uses. The HTML itself is just an <aside> ele­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() exten­sively to cre­ate posi­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 Nys­trom’s 2014 book Game Pro­gram­ming Pat­terns, makes heavy use of side­notes imple­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, mobile (in­line, expanded by default)

He takes a differ­ent approach: side­notes are writ­ten using the HTML <aside> ele­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 designed it to han­dle resiz­ing below <800px not by pop-in foot­notes in a block, but by medi­a-queries sim­ply shift­ing the aside into the text, inline. (With no JS, the fall­back is also includ­ing it inline.)

<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 unclear to me whether the JS is actu­ally nec­es­sary, or whether inline is the best fall­back for side­notes. The use of <aside> is also a com­pli­ca­tion, as few for­mats include any native sup­port for that.

Nys­trom’s books are an inter­est­ing read for pro­gram­mers, and also have some other inter­est­ing design aspects: see “Zero to 95,688: How I wrote Game Pro­gram­ming Pat­terns/“Craft­ing Craft­ing Inter­preters on the build sys­tem & lit­er­ate pro­gram­ming & his hand-drawn illus­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 Typog­ra­phy uses mar­gin notes, but in a side­notes way, on the left:

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

They fall­back to pop-ins defaulted to expanded on narrow/mobile win­dows:

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

The approach is HTML/CSS, but using <aside> ele­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 McCann & Jonas Hietala 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 incre­ment­ed, and narrow/mobile col­lapsed pop-ins:

KL, desk­top
KL, mobile (pop-in clicked)

In “Seman­tic side­notes for the web” 2019, he dis­cusses his approach, intended to sat­isfy addi­tional require­ments:

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

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

    • The side­note con­tent may con­tain span ele­ments such as <a> and <em>.
    • The side­note con­tent may con­tain click­able ele­ments that can receive key­board focus.
    • The side­note con­tent must be sty­lable.
  • The ele­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 typo­graph­i­cally accept­able way. That means at the very least that I can’t rely on web­site’s CSS to place and style the ele­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 togeth­er.

He came up with some­thing ini­tially like Tufte-CSS, but rejected pure <span>, <aside> as being not quite the right seman­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, employed side­notes, as is par­tic­u­larly appro­pri­ate for legal writ­ing, which noto­ri­ously overuses foot­notes for cita­tions, prece­dents, and digres­sions. From “The Poten­tial-Use Test and the North­west Pas­sage” (HLR edi­tors 2020):

HLR, desk­top; note the default collapse/fade
HLR, mobile (pop-in on click)

HLR’s pro­pri­etary are bidi­rec­tion­al, JS-based, and col­lapsed pop-in on mobile; they use <span>s which are rearranged 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 inline <span> in the usual Tufte-CSS, one might won­der why the JS is nec­es­sary, but check­ing with NoScript, 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 ‘alter­nat­ing’. (Is it pos­si­ble to use CSS to do this alter­na­tion auto­mat­i­cal­ly, remov­ing the need for JS to do bidi­rec­tional side­notes?)

More dis­tress­ing­ly, HLR’s side­notes are also on default 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 defeats 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 exposed so one can­not even see if the side­note is short (merely a bit of cita­tion) or long (a more in-depth dis­cus­sion).

Yale Law Journal

The , like HLR, uses side­notes in online arti­cles like “Ama­zon’s Antitrust Para­dox” (Khan 2017), since at least 2016. Like HLR, all side­notes are aggres­sively col­lapsed to near-un­read­abil­i­ty, requir­ing a click to expand, where­upon they turn into float­ing foot­notes.

YLJ, default desk­top
YLJ, side­notes clicked on to expand

They are JS-based, relo­cat­ing foot­notes grouped at the end of the arti­cle, but inside <div> ele­ments rather than <a> ele­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 appears to have no nar­row or mobile sup­port what­so­ev­er—the page just gets small­er. YLJ is unread­able on mobile, requir­ing zoom­ing & pan­ning.

Knight Institute

The Knight First Amend­ment Insti­tute of uses side­notes some­what like HLR/YLJ in its long­form pages (eg “The Case for Dig­i­tal Pub­lic Infra­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 Insti­tute side­notes (not expand­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 appears to have rolled its own JS, as the site.js’s imple­men­ta­tion does­n’t have any Google/Github hits.

The fad­ing, font size, and default col­laps­ing of ‘long’ side­notes are all not nearly as extreme 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 cita­tion and what actu­ally include addi­tional com­men­tary. (The use of but­tons & chevrons are also nice touches in explain­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 require hover to expose and then fall back to click­-driven float­ing foot­notes:

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

NY uses spans, but they are put at the end and then JS reveals 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 repos 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 mobile is a jus­ti­fi­able choice, the rest is not, and I do not like this side­note design at all.

jQuery.sidenotes

Andrew Clark’s 2013 jQuery.side­notes (Github) JS library imple­ments side­notes to the left, pars­ing Mark­down end­notes; for nar­row win­dows, it does inlined ‘pop-in’ but expanded by default; and for mobile it is just end­notes. Unusu­al­ly, Clark’s demo puts side­notes on the left mar­gin (there does­n’t seem to be an option for plac­ing on the right, or both), and includes some key­bind­ings.

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

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

The imple­men­ta­tion seems to take the expected approach of pop­ping match­ing ele­ments out into the mar­gin with media queries con­trol­ling width-re­lated behav­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 being weighed down by jQuery/NPM infra­struc­ture. One fur­ther caveat: I think the expected format/classes of end­notes has long since changed and the library has not been updated since 2013, at least for Pan­doc, so jQuery.side­notes’s defaults will prob­a­bly break for recent 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 entirely differ­ent approach to both pre­sen­ta­tion & encod­ing of side­notes. Instead of reusing the exist­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 anno­tated link (desk­top)

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

The anno­ta­tions are them­selves writ­ten as cus­tom data attrib­utes on ele­ments such as links (by default, 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 approach entirely unlike the oth­ers and an inter­est­ing exper­i­ment, but I do not rec­om­mend it for side­notes.

The India Forum

The India Forum uses jQuery for a slide-in approach but improves 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” Kor­pela, ~2007, demon­strates a com­pletely differ­ent approach using HTML tables: define two columns with differ­ent sizes/style, and put the side­notes in the sec­ond col­umn.

There are many pos­si­ble approaches to includ­ing side­notes on web pages. Hav­ing stud­ied alter­nate meth­ods like CSS posi­tion­ing and float­ing, I have come to the con­clu­sion that the sim­plest method gives the best results. This method con­sists of a two-col­umn table, with the main text in one column, the side­notes in the oth­er. Using the CSS meth­ods, it becomes awk­ward to con­trol the heights of pieces of text so that each side­note starts at the same ver­ti­cal posi­tion as the main text that it relates to.

Easy:

Side­notes via 2-col­umn HTML tables.

This has the usual advantages/disadvantages of using tables for web design: it is fast, avoids Javascript & (most) CSS com­plex­i­ties, and is straight­for­ward; but it is rigid, degrades on smaller screens, diffi­cult to write (eg no num­ber­ing in Kor­pela’s exam­ples, mak­ing them mar­gin notes, unless the author man­u­ally adds super­scripts or oth­er­wise com­pli­cates it).

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

Miscellaneous

Some imple­men­ta­tions are just bad ideas or not worth dis­cussing in detail with screen­shots:

  • ILoveTy­pog­ra­phy.­com uses image 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 inside an empty <figure> with no images!

    This is invalid HTML, fails badly in some cases (eg in the linked exam­ple, one mar­gin note is almost unread­able because it over­laps with a giant pul­l-quote illus­tra­tion), has no advan­tage over a <span> that I can find; it does at least degrade grace­fully into pop-in (de­fault expand­ed) block ele­ments on narrow/mobile.

  • BLDBLOG gen­er­ally avoids com­plex lay­out and foot­notes entire­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 absolute posi­tion­ing. The near­est posi­tioned ances­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 posi­tion is left unspec­i­fied, rely­ing on the way browsers imple­ment absolute posi­tion­ing (i.e., to place an ele­ment where it would be placed if posi­tion were static) to put it in the right place. Frag­ile, unse­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, reserved for foot­notes, and JS inserts 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 designs with explicit 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 entirely sep­a­rate pages? No: this only adds to the read­er’s bur­den, and it’s even more work for the author. (The ded­i­cated might embrace hyper­tex­tu­al­ity and cre­ate an enor­mous web of small nuggets of text which include and go beyond end­notes, but for peo­ple writ­ing online, 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, refind­ing, and nav­i­gat­ing them.)↩︎

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

  3. Tufte-CSS side­notes do not cor­rectly sup­port block ele­ments like lists or para­graphs, because spans are inline and those are block ele­ments; but this is fix­able.↩︎

  4. For exam­ple, as of 2020-08-09, mar­gin notes do not quite inter­act right, and occa­sion­ally over­lap with side­notes; an exam­ple of this error 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 anno­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, despite ample mar­gin. Com­pare Atlantic’s web ren­der­ing using pop-ins with the orig­i­nal Wal­lace 2005 print arti­cle which used elab­o­rate recur­sive side­notes inte­grated in unusual geome­tries.↩︎