Skip to content

Text Elements / References and Notes

css/modules/typography/_notes.scss

A reference mark is a <sup> holding a link to its note; the note links back. Plain ids and links do the work — no script, and the browser's own back button returns the reader to the text.1 The mark drops the link underline, and the note the reader jumped to is marked while it is the target.2

  1. Each note's id matches the mark's link, and its back link points at the mark's id. ↩
  2. The fixed header is accounted for: the page scrolls the target clear of it. ↩
<p>… the text.<sup><a href="#note-1" id="ref-1" aria-label="Note 1">1</a></sup></p>

<div class="footnote">
<ol>
    <li id="note-1">The note. <a href="#ref-1" aria-label="Back to reference 1">↩</a></li>
</ol>
</div>

The .footnote block and its top rule keep to the width of the prose. Its list starts on the block’s text edge, with the numbers in its padding. Numbered automatically, with one source of truth for the order, is a full footnote engine — that comes later. For an article with a handful of notes, numbering by hand is fine.

Sidenotes

Sidenotes are the typographic equivalent of having a knowledgeable friend lean over and whisper context while you’re reading. They provide supplementary information, references, or commentary without disrupting the main narrative flow—because nothing kills momentum quite like footnotes at the bottom of the page that make you scroll like it’s 19951.

1 You weren’t born yet then, right?

We provide two distinct elements for different annotation needs:

  • sidenote — The workhorse of our marginalia system. This is a flexible block element that can contain text, images, interactive elements, or your grandmother’s secret borscht recipe if that’s somehow relevant to your content. Built on a 9-column grid system, it ensures the main content column remains unbroken while providing unlimited creative freedom for supplementary content. Use this when you need a proper sidebar conversation.
  • aside-footer — The rebel that doesn’t follow margin rules. This element appears alongside the paragraph after the one being commented on, rather than beside it. It floats at the article’s right edge. Useful for logical asides or when the space next to the original paragraph is already occupied by another sidenote (it happens—some content is just chatty). On mobile, it reverts to following the commented paragraph directly, because we’re not complete anarchists. There it gets a thin rule above, like a stacked sidenote.

In Rare Styles, sidenotes live in the right margin of text pages, creating a visual dialogue between primary and secondary content. On mobile devices, where margins are a luxury we can’t afford, they gracefully fold into the main column immediately after the commented element. They’re styled with smaller font sizes and secondary colors to signal their supporting role—think backup dancers, not the main act.

The .sidenote is a direct child of the .sidenote-wrapper, next to the text it comments on. The wrapper places only its own children: whatever sits inside them — a chart card, a grid, a definition list — keeps its own layout, and an embedded chart keeps the color of its own links.

The row is a nine-column grid: the text takes columns 1–6, the note columns 8–9, at the article’s right edge. .lead, .highlight, .text-content-caption and .teaser-bottom take columns 1–7 and stop short of the note. In the article flow two rows are 16px apart, and a row’s last text block has no bottom margin. A table wider than the note goes in a .table-scroll inside it.

On a tablet the note stays beside the text. On a phone every row stacks: the note follows the text under a thin rule, set to the right.

A chart in a note goes in a .chart block; a RareCharts chart counts without the class. Such a row stacks as on a phone below 1024px, below 1226px when it sits directly in the article or one of its sections, and on paper. The chart keeps its own alignment. A row with a table in its note stacks on paper too: a sheet does not scroll.

A .sidenote-banner is a note set off by a 4px rule on its left, for an aside with a heading of its own, like this one. On a tablet it takes one column more, unless a wide block in the row holds it; on a phone it spans the row under the text.

The banner’s text, set small and light like any note.

To help readers quickly parse the nature of sidenote content, we provide several modifier classes that add visual cues:

  • sidenote-bookmark — Decorated with a bookmark icon, this signals editorial comments, observations, or quick asides. Perfect for “by the way” moments that deserve their own visual identity.
  • sidenote-link — For reference sidenotes and external citations. The icon treatment makes it immediately clear that this sidenote is pointing elsewhere, saving readers the cognitive overhead of discovering this mid-sentence.
  • sidenote-attach — The paperclip of the digital age. Marks sidenotes containing supplementary materials, downloads, related resources, or that PDF your colleague keeps referencing but never actually shares. Makes “additional resources” actually discoverable.
  • sidenote-bulb — The lightbulb moment carrier. Use this for helpful tips, practical insights, and those “why didn’t I think of that” ideas that make readers feel smarter. Because sometimes a good lifehack deserves more fanfare than plain text can provide.
  • sidenote — When you need that personal touch or want to simulate marginalia in a vintage textbook. Use sparingly, unless you’re writing a manifesto (we don’t judge).

The system is extensible—you can create your own sidenote types by adding custom selectors to your styles. Simply define a new class with a ::before pseudo-element and mask any icon from the shipped SVG set (or your own SVG):

.sidenote-memory::before {
content: "";
width: 1em;
height: 1em;
background-color: currentcolor;
mask: url("images/icons/cognition-200.svg") no-repeat center / contain;
}

This opens the door to domain-specific marginalia: .sidenote-warning for caveats, .sidenote-experiment for research notes, .sidenote-coffee for productivity tips that require caffeine. The only limit is your imagination — and the set you ship: any Material Symbols glyph can be added via scripts/fetch-icons.py (see the Icons page).

Memory Activation: Remember Rareism principles. Just because you can create custom sidenote types doesn’t mean you should turn your margins into an icon bazaar.

Don’t forget to add your new class to the marker list in the source: the marker then takes its place beside the note, and the top-left corner of a stacked note:

// assets/css/modules/typography/_notes.scss
$sidenote-markers: ".sidenote-bookmark, .sidenote-attach, .sidenote-link, .sidenote-bulb, .sidenote-memory, .sidenote-coffee";