Sidenotes: A Progressive Enhancement for Web Annotations

A couple of weeks ago, the Unbreaking website team shipped a small but significant update to their issue pages that transforms how readers interact with annotations. What began as an exploration of footnote usability has evolved into a thoughtful implementation of sidenotes—a feature that keeps contextual information visible alongside the main text rather than forcing readers to jump between sections.

The Problem with Traditional Footnotes

The challenge was clear from the start. Unbreaking's issue explainers often contain more than 200 annotations for particularly active topics. While the default HTML footnote pattern works functionally—using superscript numbers that link to footnote IDs at the bottom of the page, with return links bringing readers back to their place—this approach creates a jarring reading experience when dealing with dense annotation structures.

As Mark Llobera, tech director and writer on the Unbreaking team, explains: "It's functional, but for a text that has a lot of footnotes, like ours does, that is a lot of jumping back and forth." This constant navigation disrupts the reading flow and can make complex topics even harder to understand.

The Sidenote Solution

The team explored two approaches during prototyping: tooltip-style notes that appear in floating text boxes, and sidenotes that display in a sidebar. After internal user testing, they chose the sidenote treatment because it "preserved the right amount of context without obscuring the main text."

[[IMAGE:2]]

Early version of a tooltip-style note.

[[IMAGE:3]]

Early version of a sidenote.

The implementation follows progressive enhancement principles, ensuring accessibility and functionality across all devices and browsing conditions. The default behavior remains the traditional jump pattern, but for users on larger devices, the experience transforms.

How It Works

The technical implementation is elegant in its simplicity. When viewing on a larger browser window, CSS hides the default footnote numbers and replaces them with sidenote buttons styled identically to maintain visual consistency. When a reader clicks a number, JavaScript creates a sidenote element positioned at the same vertical height as the button, displaying the annotation content in the right-hand gutter.

Key accessibility features include:

• Proper focus management that moves between the text and sidenote when opening and closing notes
• Keyboard navigation support
• Screen reader compatibility
• Progressive enhancement that maintains functionality when JavaScript is disabled

The Technical Details

The current code handles several important aspects:

1. Default behavior preservation: The traditional "jump" pattern remains intact for all users
2. Device detection: CSS determines when to show sidenote buttons versus traditional footnote numbers
3. Dynamic content creation: JavaScript generates sidenote elements on demand rather than pre-rendering them
4. Focus management: Browser focus shifts to the note when opened and returns to the button when closed
5. Styling consistency: Sidenote buttons match the appearance of traditional footnote numbers to avoid confusing users

Why This Matters

This implementation represents more than just a UI improvement—it's a thoughtful approach to information architecture on the web. By keeping annotations in context, readers can maintain their place in the main text while accessing supplementary information. This is particularly valuable for complex topics where understanding often depends on connecting multiple pieces of information simultaneously.

The project also demonstrates how small, focused improvements can significantly enhance user experience. What started as an exploration of footnote usability has become part of a broader pattern of thoughtful enhancements at Unbreaking, including recent work on site search and timeline date-sorting.

The Broader Context

Annotations have long been an obsession for Llobera, who notes they're "hard to do well on the web because a text can be shaped so differently across devices and browsers." This challenge is particularly acute for content-heavy sites that need to serve diverse audiences with varying needs and capabilities.

The sidenote implementation shows how web developers can balance innovation with accessibility, creating enhanced experiences for users who can benefit from them while maintaining baseline functionality for everyone else. It's a model for progressive enhancement that other content-heavy sites might consider adopting.

Looking Forward

The Unbreaking team views this as just one piece of an ongoing effort to improve how complex information is presented and understood online. The success of the sidenote feature has sparked momentum for further improvements, with site search and timeline sorting already in production.

For developers interested in similar challenges—making complex information more accessible and understandable—the Unbreaking team welcomes collaboration. Their approach demonstrates that thoughtful, user-centered development can make a real difference in how people interact with and understand important information online.

The sidenote feature may seem like a small detail, but it represents a significant step forward in web annotation design. By keeping context close to content, it helps readers maintain their mental model of complex topics while providing easy access to supplementary information. In an era of information overload, such thoughtful design choices become increasingly valuable.