Book-Style Marginalia System

A detailed exploration of the refined marginalia system that brings book-like note presentation to technical documentation.

Evolution of Our Marginalia System

The Heartbred Journal’s marginalia system has evolved from a basic three-column prototype to a refined, book-like reading experience. This log explores the key design decisions and technical implementation that make the system feel more organic and less like traditional web components.

Design decisions were guided by the principle that marginalia should feel like handwritten notes in the margin of a book, not like HTML boxes floating on a page.

Design Philosophy

The refined marginalia system embraces intentional imperfection and readability while removing unnecessary UI elements. By eliminating borders, boxes, and other “web component” styling cues, the notes integrate seamlessly with the page, resembling notes in the margin of a physical book.

From our design language documentation: “Perfection is suspicious. Our design embraces controlled chaos and deliberate roughness to signal authenticity and humanity.”

The marginalia system exemplifies this principle through subtle spacing, minimal backgrounds, and organic typography choices.

Key Features

Sequential Numbering

Rather than using decorative markers, we’ve implemented simple, sequential numbering for all marginalia notes. This approach matches how footnotes work in academic papers and books, making the system immediately familiar to readers.

// Single global counter for all note types
counter: 0,

// Get next sequential number regardless of type
getNextNumber() {
  this.counter++;
  return this.counter;
}

The marginalia store maintains a single counter and ID map for consistent numbering across the document.

Visual Focus

When hovering over a reference or note, the system fades all other elements to create immediate visual connection between the reference and its corresponding note. This subtle interaction enhances readability without disrupting the flow of content.

The fade effect applies to both pins and notes simultaneously, allowing readers to instantly see which note corresponds to which reference.

This approach is particularly helpful in content with many notes, as it reduces visual noise and helps maintain context.

Type Differentiation

The system supports three distinct note types, each with subtle styling differences rather than heavy visual treatments:

Standard notes - General commentary and explanations
Code notes - Technical details and code examples in monospace
Handwritten notes - Personal observations in a handwriting-style font

I love how the handwritten notes use Kalam font to create a more personal feel!

The subtle styling differences (monospace for code, handwriting for personal notes) provide just enough visual hierarchy without overwhelming the design.

These distinctions help readers quickly understand the nature of each note.

Both the Table of Contents and marginalia column remain visible as you scroll through the document. This ensures that context is always available regardless of where you are in the content.

The sticky positioning is achieved with CSS:

.toc, .marginalia-inner {
  position: sticky;
  top: 60px;
  max-height: calc(100vh - 60px);
  overflow-y: auto;
  z-index: 10;
}

This approach keeps both the TOC and notes visible and scrollable independently of the main content as you scroll down the page.

Technical Implementation

The system is implemented using Alpine.js for state management and Astro components. This combination allows for reactive behavior while maintaining excellent performance.

// Data attributes provide clean separation between 
// Astro templating and Alpine expressions
x-data="{ active: false, noteNumber: 0 }"
x-init="noteNumber = $el.dataset.numberOverride 
        ? parseInt($el.dataset.numberOverride) 
        : (Alpine.store('marginalia')
          ? Alpine.store('marginalia')
              .getNumberForId($el.dataset.noteId)
          : 1)"

Using data attributes to pass values from Astro to Alpine avoids template syntax conflicts.

Auto-Numbering

The system automatically assigns sequential numbers to notes based on their order in the document . Authors can also override the auto-numbering with explicit values when needed.

Auto-numbering makes authoring content significantly easier:

<InlinePin noteId="example">reference</InlinePin>
<MarginaliaNote noteId="example">Note content</MarginaliaNote>

Authors only need to ensure matching noteId values, and the system handles numbering automatically.

Usage Examples

Basic Note

<InlinePin noteId="basic">A reference</InlinePin>

<MarginaliaNote noteId="basic">
  This is a basic margin note.
</MarginaliaNote>

Code Note

<InlinePin noteId="code-example" pinType="code">
  Code reference
</InlinePin>

<MarginaliaNote noteId="code-example" noteType="code">
  js
  // Example code
  function hello() {
    console.log("Hello world");
  }
</MarginaliaNote>

Handwritten Note

<InlinePin noteId="personal" pinType="handwritten">
  Personal comment
</InlinePin>

<MarginaliaNote noteId="personal" noteType="handwritten">
  This appears in a handwriting style font to indicate
  personal commentary.
</MarginaliaNote>

Future Enhancements

We’re considering several enhancements to the marginalia system:

Local storage to persist pin/note states between page views
Ability to toggle all notes on/off
Note filtering by type
Print-optimized layout

I’m particularly excited about the print-optimized layout!

It would be great to have notes correctly positioned at the bottom of pages when printing, similar to how academic papers handle footnotes in print.

The toggle feature would also help for readers who want to focus solely on the main content before exploring the notes.

Conclusion

The refined marginalia system strikes a balance between digital interactivity and book-like familiarity . By removing unnecessary UI elements and focusing on subtle interactions, we’ve created a reading experience that feels natural and enhances comprehension without distracting from the main content.

This approach aligns perfectly with our broader design philosophy: embracing the tension between technical authenticity and polished intentionality.

The marginalia system doesn’t try to hide that it’s digital, but it draws inspiration from centuries of print design to create a more human reading experience.