Comparisons

Table columns:

1. Name: name/creator

2. Active: whether appeared actively maintained when last checked (usually ~2020)

3. Layout: whether it puts notes in the left, right, or both margins

4. Margin Notes: whether it appears to support margin notes (sidenotes without a number & anchor inside the text, just free-floating text)

5. Element: which HTML element/tag is used to denote the sidenote in the HTML source (eg. Markdown puts in a <a> linking to a definition in the footer)

6. Non-JS: whether Javascript required (which is bad if it can be done without JS)

7. No Click: whether the reader has to effortfully click on a note to see it (rather than visible by default or easily seen with hover)

8. Mobile/Narrow: how it handles mobile browsers and/or narrow screens (often the same)

9. Long Collapse: how it handles long notes which would threaten to overload the margin and push notes ‘off-screen’

10. FLOSS: whether OSI-approved copyright license

11. Pros/Cons: miscellaneous comments.

Tufte-CSS

Experiments in using CSS3 for sidenotes date back to at least 2003_21ya, but by far the most popular implementation, and the primary inspiration for most sidenotes users, is the c. 2014 Tufte-CSS (Github). Tufte-CSS is outdated in respects, but does sidenotes sensibly:

A Tufte-CSS-formatted sidenote 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 desktop), the notes are floated right into the margin; no measures are taken to avoid collisions or overlaps (presumably if you have that problem, you ought to just rewrite your page or fix it yourself). On narrow windows & mobile, a media-query overrides the regular CSS, so the margin notes are not floated, simply indented, and toggled. 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;
        }
}

Margin notes are implemented similarly to sidenotes because a margin note can just be a sidenote whose number is hidden (at the possibility of some user confusion at the ‘missing’ endnote/sidenote, fixable with further CSS tweaks using number counters).

One thing to note about Tufte-CSS is that, like books, it displays sidenotes by default. Many websites experimenting with note variations throw away the greatest advantage—the effortlessness of reading sidenotes by simply saccading left/right—in favor of hassling the user and forcing them to do quite as much work by clicking various UI elements to expand/collapse notes, defeating much of the point compared to a normal hyperlinked endnote.

Tufte-CSS requires no JavaScript and is pure HTML/CSS, delegating layout to the browser. It is simple, fast, supports mobile well, and widely-used—it is definitely the most popular of HTML sidenote implementations. Its disadvantages are it will not handle gracefully many complex³ or lengthy sidenotes (which will overlap), and Tufte-CSS-style notes are not generated by default by many systems (so some sort of rewrite step is necessary to integrate Tufte-CSS into however one actually creates one’s website).

Because Tufte-CSS sidenotes/margin notes are located inline, rather than put at the end of the text like most document systems implement it (eg. Pandoc), one needs either to use JS to rewrite endnotes at runtime or to rewrite them at compile-time. Many projects generate Tufte-CSS sidenote spans directly or rewrite standard Markdown <a> endnotes to spans, such as the R packages “tufte” & “Tint Is Not Tufte: An implementation in R Markdown”. For Pandoc, pandoc-sidenote is a Haskell Pandoc filter which rewrites Pandoc’s endnotes in Tufte-CSS-style spans, and can be used with Pandoc-based site builders like Hakyll or Jekyll (for the latter, see tufte-pandoc-jekyll & tufte-jekyll); Guillaume Paumier & Matt Palmer have Lua versions.

Tufte-CSS user examples: Nicolas J. Duquette, David Schmudde, in Hebrew, Robin Schroer, Dan Pittman, Jason Merrill, Andrew Zuckerman, Taeer Bar-Yam, Eric Marsden (Risk Engineering), Tom Critchlow, Phil Crissman.

Similar approaches (some of these are more limited than Tufte-CSS; typically, authors fail to handle narrow/mobile):

• “How can we develop transformative tools for thought?”, Andy Matuschak & Michael Nielsen 2019 (mobile: floating footnotes)

• Arxiv Vanity (mobile: floating footnotes)

• Nintil (mobile: pop-in, expanded)

• Danila Fedorin’s sidenotes (mobile: pop-in, collapsed) are inspired by Koos Looijesteijn’s approach, Fedorin’s implementation removes the JS but at the cost of guaranteeing accessibility and inheriting Tufte-CSS’s limitations on block elements/Markdown in sidenotes

• “What does BERT dream of?” (mobile: pop-in, expanded)

• Increment (mobile: pop-in, expanded)

• Matt Wilcox, with an unusual use of margin notes for paragraph/section summaries, similar to my use (mobile: pop-in, expanded)

• “Dictionary of Numbers”, Glen Chiacchieri (mobile: ❌)

• Roman Gornitsky (The Temporary State) (mobile: ❌)

• Richard Rutter (mobile: pop-in, expanded)

• “Singular: Possible futures of the singularity”, James Yu & GPT-3 (mobile: click-to-expand as a sticky pop-up)

• “The Problem of Detecting Polygenic Selection from Temporal Data”, Vince Buffalo (mobile: pop-in, expanded)

• “How to do sidenotes in HTML documents using CSS and Javascript”, Frans de Jonge 2005_19ya (an early example, with consideration of cross-browser compatibility for the era)

• Omar Rizwan (Hugo)

• Darius Kazemi/Emma Winston (‘margin notes’, no apparent use of numbering to support ‘sidenotes’; nice retro theme; <aside>; pop-in, expanded; no truncation/wrapping; absolute positioning offset based on div around associated paragraph, so can’t handle overlaps which leads to bugs as can be seen in that page; apparently extraneous use of grid?)

• Vale (notable for strange handling of mobile: the sidenotes are hidden and their footnote numbers left in place, by being moved to the end of a section and grouped in a single list while being collapsed; clicking or tapping the footnote jumps to the end-block but does not expand them, and they must be clicked on to expand them all.)

• Tyler Vigen: pop-in-only; tooltips used for ‘hover’, which is a bad idea⁴

• examples with no mobile (❌) support:

  • Hoefler&Co.

  • Michael Petralia

  • The Morning After WordPress template’s “asides” (example)

  • Francesco (overloads <section> & manually overrides list markers for numbering for one section per sidenote, with fragile grid default positioning; mobile is just desktop but made microscopic)

  • xkqr

sidenotes.js

sidenotes.js was developed by Said Achmiz in 2019 for use on Gwern.net after looking at Tufte-CSS and deciding that Tufte-CSS’s simple approach (while appropriate for most users) would fail on particularly-heavily endnoted pages:

The advantage over Tufte-css is that sidenotes.js ‘manually’ lays out sidenotes at runtime to minimize overlap while trying to keep sidenotes within the same window as the anchor, enabling it to handle almost arbitrarily many long endnotes without rendering any unreadable. Sidenotes/endnotes can be arbitrarily long and contain most block elements like code blocks, blockquotes, lists, images, tables, etc. While it’s at it, sidenotes are highlighted & their matching anchors highlighted on hover, too-long sidenotes are partially collapsed (the user clicks to expand them). Further, it supports a custom “margin note” feature: any HTML spans of text with the class marginnote will be popped out of the text into the margin if there is room, or it will be left in place & italicized. (I place margin notes at the beginning of paragraphs as summaries, letting users more easily skim.)

The disadvantage compared to pure static HTML/CSS approaches is that the JS needs to load and copy the endnotes into sidenotes, reflow as necessary over the whole page, which is user-visible & distracting; this is noticeable even putting the load in the HEAD to speed it up. It can also interact with other complicated features and while it will handle heavy note loads much better than most static approaches (most of which don’t even try to avoid errors like overlaps), it still has the occasional subtle bug.

For narrow windows, other approaches can be used. On Gwern.net, I use floating footnotes which ‘pop up’ when the user hovers over a footnote anchor⁵, which avoids the need to navigate to the end of the page & back.

sidenotes.js assumes that the document has been generated from Pandoc Markdown and has normal Pandoc endnotes (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 endnote body at the end of the document). Hence, implementing sidenotes with it requires little more than a JS import like <script src="/static/js/sidenotes.js" async></script>. (This has some advantages: for example, footnotes/sidenotes remain linkable—one can link to #fn1 or #sn1 as desired.⁶)

Users or similar implementations:

• Fantastic Anachronism

• Leo Gao (eg. 1, 2) designed his site inspired a little by Gwern.net, and uses sidenotes similarly; his approach seems to be simpler. (mobile: endnotes)

• OpenAI (eg. 1) (mobile: endnotes)

• Marshall (Vandegrift) Bockrath, from pre-2012! (mobile: ❌)

Ink & Switch

Ink & Switch’s pages like “Local-first software: You own your data, in spite of the cloud”’s 2016 static margin notes feature looks much like Tufte-CSS in using HTML/CSS to create right-aligned sidenotes, although Ink & Switch eschews explicit footnote numbering and its pop-ins are uncollapsed by default.

Implementation-wise, it takes a noticeably different tack in which CSS features it uses. The HTML itself is just an <aside> element:

<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() extensively to create positioning & readjust overlaps without 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 downside is that there is no support for numbering I can see, so they’re all margin notes. The CSS is considerably more complex and I’m not sure what the complexity gains one compared to Tufte-CSS—correctness?

Robert Nystrom

Game programmer Robert Nystrom’s2014 book Game Programming Patterns, makes heavy use of sidenotes implemented in HTML/CSS/JS, mostly similar to Tufte-CSS.

He takes a different approach: sidenotes are written using the HTML <aside> element, and a <span> with each aside’s ID specifies their placement in the text; the JS then moves the aside into the margin. He designed it to handle resizing below <800px not by pop-in footnotes in a block, but by media-queries simply shifting the aside into the text, inline. (With no JS, the fallback is also including 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 necessary, or whether inline is the best fallback for sidenotes. The use of <aside> is also a complication, as few formats include any native support for that.

Nystrom’s books are an interesting read for programmers, and also have some other interesting design aspects: see “Zero to 95,688: How I wrote Game Programming Patterns”/“Crafting Crafting Interpreters” on the build system & literate programming & his hand-drawn illustration workflow; & “Zero to 353 Pages: Bringing My Web Book to Print and eBook” on working with EPUB & typesetting the print book.

Matthew Butterick

Matthew Butterick’s 2013_11ya ebook/website Practical Typography uses margin notes, but in a sidenotes way, on the left:

They fallback to pop-ins defaulted to expanded on narrow/mobile windows:

The approach is HTML/CSS, but using <aside> elements, 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;
    }
}

Presumably Butterick used his Racket-based Pollen document system with custom tags, since the base system doesn’t cover notes; Sancho McCann & Jonas Hietala has documented Pollen sidenotes.

Koos Looijesteijn

Koos Looijesteijn’s loosely Tufte-CSS-like sidenotes are right-aligned, symbol rather than number incremented, and narrow/mobile collapsed pop-ins:

In “Semantic sidenotes for the web” 2019, he discusses his approach, intended to satisfy additional requirements:

• The span that the sidenote refers to should have a proper semantic HTML element (no abuse of elements made for other purposes)

• The content of the sidenote should have a similarly valid HTML tag. Additionally:

  • The sidenote content may contain span elements such as <a> and <em>.

  • The sidenote content may contain clickable elements that can receive keyboard focus.

  • The sidenote content must be stylable.

• The elements should not cause auto closing of their parent <p> tag.

• Reader modes and apps like Pocket and RSS readers should show sidenote content in a typographically acceptable way. That means at the very least that I can’t rely on website’s CSS to place and style the elements correctly.

• The sidenote content should be read by screen readers, in a flow that makes sense. That likely means the two parts should be placed together.

He came up with something initially like Tufte-CSS, but rejected pure <span>, <aside> as being not quite the right semantics, purely static as breaking reader mode/apps, and settled on JS-enhanced <span>/<small> combination.

Harvard Law Review

The Harvard Law Review’s website has, since at least 2016, employed sidenotes, as is particularly appropriate for legal writing, which notoriously overuses footnotes for citations, precedents, and digressions. From “The Potential-Use Test and the Northwest Passage” (HLR editors 2020):

HLR’s proprietary are bidirectional, JS-based, and collapsed 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</em><i class="close-txt">&times;</em></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 wonder why the JS is necessary, but checking with NoScript, one sees that without the JS, the sidenotes are all piled up on the left margin, overlapping badly, so the JS does the ‘alternating’. (Is it possible to use CSS to do this alternation automatically, removing the need for JS to do bidirectional sidenotes?)

More distressingly, HLR’s sidenotes are also on default collapsed on desktop, trimmed at a shockingly short length—typically not even half a sentence! While collapsing long footnotes is a good idea, it’s puzzling to collapse at such a short length that literally every sidenote will be collapsed, since this again defeats the point of having sidenotes, and making it hard to see if a sidenote is worth clicking on since only the first few words are exposed so one cannot even see if the sidenote is short (merely a bit of citation) or long (a more in-depth discussion).

Yale Law Journal

The Yale Law Journal, like HLR, uses sidenotes in online articles like “Amazon’s Antitrust Paradox” (Khan2017), since at least 2016. Like HLR, all sidenotes are aggressively collapsed to near-unreadability, requiring a click to expand, whereupon they turn into floating footnotes.

They are JS-based, relocating footnotes grouped at the end of the article, but inside <div> elements rather than <a> elements like usual:

<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>,
            <em>As Competition Wanes, Amazon Cuts Back Discounts</em>,
            <span class="forced_sans_reg">N.Y. Times</span> (July 4, 2013), http&hellip;
            </div>
    </div>
...</div>

Worse, YLJ appears to have no narrow or mobile support whatsoever—the page just gets smaller. YLJ is unreadable on mobile, requiring zooming & panning.

Knight Institute

The Knight First Amendment Institute of Columbia University uses sidenotes somewhat like HLR/YLJ in its longform pages (eg. “The Case for Digital Public Infrastructure: Harnessing past successes in public broadcasting to build community-oriented digital tools”, Zuckerman2020):

They are JS-based, right-aligned, collapsed (but with a slightly more generous length limit than HLR/YLJ), and fallback to Tufte-CSS-like pop-in blocks (default collapsed). As similar as it seems to those, Knight appears to have rolled its own JS, as the site.js’s implementation doesn’t have any Google/Github hits.

The fading, font size, and default collapsing of ‘long’ sidenotes are all not nearly as extreme as HLR/YLJ, so the Knight sidenotes are substantially more pleasant to read, as it’s much easier to see what sidenotes are merely a brief citation and what actually include additional commentary. (The use of buttons & chevrons are also nice touches in explaining the functionality to the reader.)

New York

New York’s website CMS Clay/Kiln (used on NYmag.com/Vulture/the Cut/Grub Street/Slate) provide JS-based left sidenotes which require hover to expose and then fall back to click-driven floating footnotes:

NY uses spans, but they are put at the end and then JS reveals them when the user hovers:

<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 couldn’t find mention of sidenotes in the various Clay/Kiln Github repos but there are enough of them and it’s all complicated enough I may have missed them, so I don’t know if the relevant JS/CSS is MIT-licensed like the Clay/Kiln ecosystem generally seems to be.

While floating footnotes on mobile is a justifiable choice, the rest is not, and I do not like this sidenote design at all.

JQuery.sidenotes

Andrew Clark’s 2013_11ya jQuery.sidenotes (Github) JS library implements sidenotes to the left, parsing Markdown endnotes; for narrow windows, it does inlined ‘pop-in’ but expanded by default; and for mobile it is just endnotes. Unusually, Clark’s demo puts sidenotes on the left margin (there doesn’t seem to be an option for placing on the right, or both), and includes some keybindings.

The pop-in appearance looks like Tufte-CSS’s.

The implementation seems to take the expected approach of popping matching elements out into the margin with media queries controlling width-related behavior.

Clark’s jQuery.sidenotes offers more features than usual, but I’m not sure how useful they are. It’s also quite ‘heavyweight’ in being weighed down by jQuery/NPM infrastructure. One further caveat: I think the expected format/classes of endnotes has long since changed and the library has not been updated since 2013_11ya, at least for Pandoc, so jQuery.sidenotes’s defaults will probably break for recent Markdown documents.

Sidenotes.js, Correia

Bruno Correia’s2015 Sidenotes.js (Github), not to be confused with Said Achmiz’s sidenotes.js, takes an entirely different approach to both presentation & encoding of sidenotes. Instead of reusing the existing margin, Sidenotes.js creates a new view by sliding a sticky-element ‘tab’ into view with the sidenote contents, hiding the original page:

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

The annotations are themselves written as custom data attributes on elements such as links (by default, others are supported):

<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 others and an interesting experiment, but I do not recommend it for sidenotes.

The India Forum

The India Forum uses jQuery for a slide-in approach but improves over Correia’s by showing all the sidenotes in a pane after clicking:

The ‘slide-in’ approach can be contrasted with the ‘slide-up’ approach used by Wikipedia:

And some other sites, like Justin Duke:

The ‘slide-in’ from left/right can make use of margin on bigger screens, but there is usually no margin on cramped mobile screens, so one faces a fundamental choice between inserting the footnote/sidenote text ‘into’ the body, usually forcing layout shift, and ‘over’ the body, obscuring some of it. (For Gwern.net, pop-ins were the only acceptable solution as they are less modal: they let the reader continue navigating/reading the page, no matter how deep they drill into the recursively-linked pop-ins.)

Tables

Jukka “Yucca” Korpela, ~2007, demonstrates a completely different approach using HTML tables: define two columns with different sizes/style, and put the sidenotes in the second column.

There are many possible approaches to including sidenotes on web pages. Having studied alternate methods like CSS positioning and floating, I have come to the conclusion that the simplest method gives the best results. This method consists of a two-column table, with the main text in one column, the sidenotes in the other. Using the CSS methods, it becomes awkward to control the heights of pieces of text so that each sidenote starts at the same vertical position as the main text that it relates to.

Easy:

This has the usual advantages/disadvantages of using tables for web design: it is fast, avoids Javascript & (most) CSS complexities, and is straightforward; but it is rigid, degrades on smaller screens, difficult to write (eg. no numbering in Korpela’s examples, making them margin notes, unless the author manually adds superscripts or otherwise complicates it).

I include this for its historical interest—while this strategy may have made sense in 2007_17ya, the tradeoffs now are highly unfavorable given that Tufte-CSS etc work, and I’m not sure anyone should use it.

Annotate, Molly White

“Annotate” (demo) is a CSS+JS framework by Molly White, created for her “The Edited Latecomers’ Guide To Crypto”, which is a heavily-commentated (side by side) fisking of an article on cryptocurrency.

Perhaps because the commentary may be longer than the text & complex, Annotate takes a novel approach: text+commentary pairs live in <section> elements, interleaving <div>s (possibly nested or ‘grouped’), with <mark> elements to specify highlighted ranges (eg. in yellow highlighting) for which part of the text a commentary is referring to. The CSS then uses CSS grids (row-based layout) to lay them out side by side. (Javascript is used for live highlighting/focusing of ranges when clicked on, but otherwise appears optional.)

For mobile, it defaults to expanded pop-ins but does not appear to make any effort to interleave or separate pairs to ensure that the commentary for each visible highlighted range is also visible.

Miscellaneous

Some implementations are just bad ideas or not worth discussing in detail with screenshots:

• ILoveTypography.com uses image captions & margin notes which, like Tufte-CSS, are floated/outdented right, but bizarrely, it uses figure captions—just <figcaption> with a special class inside an empty <figure> with no images!

  This is invalid HTML, fails badly in some cases (eg. in the linked example, one margin note is almost unreadable because it overlaps with a giant pull-quote illustration), and has no advantage over a <span> that I can find; it does at least degrade gracefully into pop-in (default expanded) block elements on narrow/mobile.

• BLDBLOG generally avoids complex layout and footnotes entirely, and doesn’t have much margin to put sidenotes in, so I was surprised while reading the archives to find one post which has a left margin note, and even more surprised to check the HTML source and see that the ‘margin note’ is in fact a header: a <h6>.

  Huh‽ It turns out that the header is floated left with some gruesome CSS. Said Achmiz summaries how the Rube Goldberg contraption works:

  The CSS uses absolute positioning. The nearest positioned ancestor is <article>, not .entry-content. Within <article>, .entry-content is right-floated and has a fixed width. This creates a variable-width space on the left (determined by how much horizontal space is left within <article> after that fixed width is subtracted). The sidenote <h6> is then set with position:absolute and left:0. Vertical position is left unspecified, relying on the way browsers implement absolute positioning (ie. to place an element where it would be placed if position were static) to put it in the right place. Fragile, unsemantic, & hacky.

• MIT Admissions uses a footnote-sidenote hybrid:

  

  Span-annotated footnote links (with the trigger text lightly highlighted in red), on hover, trigger JS to create a single sticky/floating ‘sidenote’ which is located in the bottom-right corner; hovers on other footnotes replace it with their contents. (Layout does not take into account the sidebar or anything that may already be there, and the footnote popup box simply appears over it.)

  For mobile/narrow windows, it uses pop-in, but not as a block element, instead, inline with red-colored brackets to delimit it:

  

• Evan Ovadia (eg.): content & sidenotes are put into pairs of columns. Presumably does not handle many long sidenotes gracefully.

  For mobile/narrow, it collapses them as a row of numbered links to expand on click.

• Simon Tatham: uses a highly unusual footnote format which I can’t decide if it’s a footnote or a sidenote.

  Footnotes are duplicated in button toggles & at the bottom; footnote numbered anchors are set to the right margin, and when clicked, ‘popin’, but to the side of the text, which reflows into a left text column vs right footnote column (no JS, just CSS+HTML):