A margin note aligned to the paragraph it belongs to

Why this block is harder than it looks

A margin note is the most useful alternative to a footnote and it needs two things a normal layout does not provide: a margin wide enough to hold it, and vertical alignment with a specific paragraph rather than with the flow. The alignment is where it goes wrong, because a note positioned absolutely against the page drifts away from its paragraph as soon as anything above changes, and a note in the flow pushes the paragraph down. It also has to swap sides on a double-sided document, so the note is always in the outer margin rather than in the gutter.

The decisions that make it work

Reasons rather than a description of the code. Each of these is a choice that has a wrong answer, and the wrong answer is usually the default.

• Widen the outer page margin deliberately to hold the notes, rather than trying to fit them into a margin sized for white space.
• Position each note relative to its own paragraph, not to the page, so it moves when the text moves.
• Mirror the side on left and right pages using the page pseudo-classes, so the note is always in the outer margin and never in the binding.
• Set it small, around 7.5 to 8 point, with a tighter line height than the body, so a three-line note occupies less height than the paragraph it sits beside.
• Keep notes short enough to fit beside their paragraph. A note taller than its paragraph collides with the next one and there is no automatic mechanism to stop it.
• Never put essential information in a margin note. It is the first thing lost when a document is reformatted or read aloud.

The fragment

Markup and the CSS it needs, and nothing else. It expects a document that already has a page rule and a base stylesheet, so paste it into one rather than opening it on its own.

<p class="has-note">
  The survey was carried out under dry conditions with full access to the
  ground floor.
  <span class="note">Access to the rear elevation was arranged separately.</span>
</p>

<style>
  @page {
    size: A4;
    margin: 22mm 20mm 26mm 20mm;
  }
  @page :left  { margin-left: 48mm; }     /* wide outer margin, mirrored */
  @page :right { margin-right: 48mm; }

  .has-note { position: relative; }       /* the note is anchored to the text */
  .has-note .note {
    position: absolute;
    top: 0;
    width: 34mm;
    font-size: 7.5pt;
    line-height: 1.3;
    color: #555;
  }
  /* outer margin on both sides */
  @page :left  { .has-note .note { left: -40mm; } }
  @page :right { .has-note .note { right: -40mm; } }
</style>

What breaks when it is built the obvious way

Positioning the note against the page rather than against its paragraph. It sits correctly in the draft and drifts the moment a sentence is added above it, and nothing about the output shows that the note is now beside the wrong paragraph.

How to prove it survived pagination

Add a paragraph above a noted paragraph and render again. The note should have moved with its paragraph. Then check a left page and a right page and confirm the note is in the outer margin on both.

Where it sits in a finished document

This page is one block. The document it belongs to has a page rule, a base stylesheet, a header and everything else around it, and repeating all of that here would make thirty pages that say the same thing. The multi-page report template is a complete file with this block already in it, so take that and change the fragment rather than assembling one from parts. The property doing most of the work here is covered on its own page, with the support caveats that belong there rather than here.

Frequently asked

Other parts of a document

The blocks that sit next to this one, and one from the next group along so you are not sealed inside a single kind of problem.