What are PDF annotations?

PDF annotations are marks stored in a layer above the page content: highlights, underlines, freehand ink, text boxes, sticky notes, stamps, shapes and links. They are separate objects in the file, which is why they can be moved or deleted after the fact, and also why a mark that shows in one reader may be invisible in another. This viewer lets you add them in the browser and saves them into a new PDF with pdf-lib.

The main annotation types

ISO 32000 defines about 28 annotation subtypes. The ones ordinary users meet are:

If you want to try them, the annotate PDF tool opens a file with the full toolbar; Eraser removes any mark you added, and Ctrl+Z undoes.

How annotations are stored in the file

Each page in a PDF file has an optional Annots array that lists annotation objects. An annotation object records its subtype, a rectangle on the page, a color, an author and date, optional contents text, and, for most types, an appearance stream: a small piece of drawing code that says exactly how the mark should look.

The page content underneath is untouched. That is the key difference between an annotation and page content: a highlight annotation lies over the text, while a yellow rectangle drawn into the content stream is part of the page forever. Annotations can be hidden, locked, listed in a comments panel, exported as an FDF or XFDF file, and deleted without disturbing the page.

Text markup annotations also store QuadPoints, the coordinates of the words they cover, which is why a highlight follows the line of text rather than being a free rectangle. Ink annotations store the stroke paths; FreeText stores the string, font and size.

Why some readers show annotations and some do not

Three things commonly go wrong:

• Missing appearance stream. The spec allows a producer to omit it and let the reader generate the look from the annotation's properties. Acrobat does that; many lightweight readers, browsers and print drivers do not, so the mark exists but is invisible. This is the classic "my comments disappeared" problem.
• Unsupported subtype. A reader may ignore types it does not know, for example 3D, RichMedia, or custom stamps from a specific app.
• Hidden or NoView flags. Annotations can be flagged hidden, or marked to print but not display. Preview on Mac, for instance, has a setting to hide markup.

Mobile apps are the most frequent offenders, and printing is another: some drivers rasterize only the content layer. When a document must look the same everywhere, including on paper, the answer is flattening.

Flattening annotations

Flattening draws each annotation's appearance into the page content stream and then deletes the annotation object. The result is a page where the highlight, the signature or the whiteout box are ordinary graphics: visible in every reader, impossible to move or remove by clicking, and no longer listed as comments.

Flattening is also what turns a visual cover-up into something closer to real redaction. A whiteout box that remains an annotation can be deleted by anyone, exposing the text; a whiteout box flattened into the page is permanent, although the original text objects still exist underneath unless they are removed by a redaction tool. The distinction is spelled out in how to redact a PDF.

Tools that flatten: Adobe Acrobat (Print to PDF with "comments and forms" set to document and markups, or Preflight), Apple Preview (Export), and command-line pdftk or qpdf with the flatten option. The browser's Print, Save as PDF also flattens what is rendered on screen.

How this viewer saves annotations

While you work, your marks live in the browser tab; nothing is sent anywhere. When you click Download, the viewer uses pdf-lib, an open-source JavaScript library, to write a new PDF with the highlights, drawings, text, images, signature, stickers and whiteout boxes embedded, together with any page rotation, deletion or reordering and any OCR text layer. Text you typed in Cyrillic, Arabic or other non-Latin scripts is embedded with fontkit so it displays correctly on other machines.

What the viewer does not do: it cannot change the words of the original text (use whiteout plus Add text on top), it cannot remove the underlying text behind a whiteout box, and its signature is a drawn image, not a certificate-based digital signature. It also does not import or export comment files (FDF/XFDF). For a quick start, how to highlight text in a PDF and draw on PDF show the two most-used tools.

Frequently asked questions