Annotate

Before / afterBefore / after sliderArrows onlyMargin notesSide notesMarks

Playground

PreviewCode

Before

12

After

34

1 / 2

Hover a mark to highlight its note, or a note to highlight its mark. Click a screenshot to zoom it.

To share a screenshot, press its Copy button, or focus it and press Ctrl+C (⌘C on a Mac). You get a PNG with the marks and notes drawn in. The browser's own Copy Image gives you the same PNG once the pointer has been over the screenshot. Copying needs setup in two cases:

• An image from another origin needs CORS headers from its server.
• A page in an iframe needs allow="clipboard-write" on the frame.

A comparison shows its screenshots side by side, or one at a time on a narrow page, and zooms them as one gallery. A slider stacks the two screenshots, and you drag the divider to reveal one or the other.

Everything reads the same without a script. zoom and carousel come with the package. To page through screenshots spread across a page, or show a flow one step at a time, see the recipes.

Three blocks, each on its own page:

• screenshot is an image with marks on it.
• annotation is one mark and its note, inside a screenshot.
• compare shows two screenshots side by side, or one over the other with a slider.

An annotation goes inside a screenshot, and a compare holds two screenshots:

::screenshot{src="/after.png" alt="Filter toolbar on one row" title="After" href="https://pr42.preview.example.com/plan"}
:::annotation{x=67.9 y=34.8 w=13 h=14.2}
Extra filters collapse into **+2 filters**.
:::
::

A mark on the screenshot and its note. The content is the note. Props can be inline, in a YAML props block, or bound with :x. Notes in the list under the image are numbered. Side notes sit beside, above, or below the image and point with an arrow instead.

A side note sits level with its mark unless at moves it along its margin; its arrow then leaves the note level and sweeps into the mark, the way a hand-drawn leader does. to aims the arrow at one point instead of the middle of the mark's edge, which suits mark="none": the arrow alone points, and nothing covers the screen.

Playground

PreviewCode

AB

A

Bugs fixed fell with the duck supply.

B

The pigeons ate week 15.

Playground

PreviewCode

1A

A

r now counts the office cat.

Two screenshots side by side, titled Before and After unless they set their own title. Numbers continue from one side to the other, and the pair stacks on narrow screens. Notes with side="left" or side="right" join the numbered list under their screenshot, since beside it they'd sit against the other one and shrink their own image; notes with side="top" and side="bottom" stay above and below, and both images keep the same room for them so they stay level.

With mode="slider", the two screenshots share one frame: Before shows left of a divider and After right of it. Drag anywhere on the pair, or focus the handle and use the arrow keys, to move it; a click on the screenshots that doesn't drag zooms the pair. Use it when both screenshots show the same spot and the change is small, so the reader sees it at full width. Side notes become numbered notes in the list, since an arrow would cross the divider. Without the script, the two screenshots stack.

Playground

PreviewCode

Before

1

After

2

1 / 2

side="left", side="right", or side="top" moves a note out of the list to beside or above the image, with a hand-drawn arrow to its mark. Add mark="none" to point at something without drawing a box. Side notes have no number, because the arrow already links them to their mark.

• In a compare, only notes above the image keep their arrow.
• On narrow screens, side notes drop under the image and the arrows hide. Each note and its target get a matching letter instead.

Notes on the same side need room. The plugin reports side notes whose marks sit close together vertically, since they would likely overlap. It can't measure the text, so check the rendered page too. If two notes collide, move one to the other side or into the list.

Measure the element in the page you captured and divide by the viewport. Don't estimate from the image.

const r = element.getBoundingClientRect();
const box = {
  x: (r.x / innerWidth) * 100,
  y: (r.y / innerHeight) * 100,
  w: (r.width / innerWidth) * 100,
  h: (r.height / innerHeight) * 100,
};

For a full-page screenshot, add the scroll offset and divide by the page size instead.

Numbers place themselves. Each sits on a corner of its mark, so it reads as that mark's number and not its neighbor's. It tries top left, top right, bottom left, then bottom right, and takes the first corner clear of other numbers, marks, and arrows. If it would hang past the image's edge, it lines up with the mark's edge instead.

Set viewport on the screenshot so the plugin judges the corners against the image's real shape. If marks crowd so close that two numbers overlap at every corner, the plugin reports both annotations.

The plugin adds a problem with any block to meta.issues, as Validation describes. Each issue names its block. A screenshot goes by its src, or by its position and alt when another screenshot has the same src. An annotation goes by its position in its screenshot:

screenshot "after.png", annotation 2: the box runs past the image edge. Keep x + w and y + h within 100.

The plugin reports an unknown prop with a list of the valid ones, and a :bound prop that points at missing frontmatter. It leaves bindings to data or props to the renderer. Each kind of problem has its own rule in Doctor, with an example and its fix.

The plugin takes no options. In comarkUi(), annotate: false turns it off.

The package comes with a small CLI that knows zoom and carousel too.

• check lists every problem in one or more files, and exits with 1 if there are any.
• render writes a standalone page next to each file. Open it and take a screenshot to confirm each mark sits on its target.

npx comark-annotate check duck-audit.md pigeons.md
npx comark-annotate render duck-audit.md -o duck-audit.html

comark-ui brings comark-annotate and registers it. To use it alone, install it and pass the HTML renderers as components:

pnpm add comark @comark/html comark-annotate

import { createHtmlRenderer } from "@comark/html";
import annotate, { components } from "comark-annotate/html";

const render = createHtmlRenderer({ plugins: [annotate()], components });
const html = await render(markdown);

The renderer inlines its styles and script once per document. Annotate renders only to HTML; Renderers covers using it with other plugins, a strict Content Security Policy, and untrusted notes.

The comark-ui agent skill knows the syntax, how to measure marks from the page, and how to check the result. Agents install it with npx skills add onmax/comark-ui, and Agents covers the rest.

Screenshots and comparisons follow the page's theme through the shared tokens. The mark colors are separate from the theme, because each one means something. The rules sit in a comark CSS layer, so any plain rule of your own wins. ::diff is in comark-diff, which has its own Theme section.

Annotate reads these shared tokens:

Set them on .ca, the root of every block:

A screenshot's or compare's ink colors its annotations the same way. An annotation's color sets --ca-color, --ca-solid, and --ca-ink on its own mark and note, so it wins over .ca. Caveat comes inlined with the styles, about 32 KB once per page.

• Every block sits in a .ca: a screenshot's figure.ca-screenshot inside it, and .ca.ca-compare for a compare (plus .ca-slider with mode="slider").
• A screenshot holds .ca-heading with its title in .ca-label, then .ca-stage with the image in .ca-frame, and a figcaption with the notes in ol.ca-notes. It has .ca-left, .ca-right, or .ca-top when it has side notes there.
• A mark is a .ca-mark with its shape as a class, such as .ca-box or .ca-circle, and its number in .ca-stamp. A side note is a .ca-callout with its arrow in .ca-arrow. A mark, its arrow, and its note share a data-n.
• The Copy button is .ca-copy. A slider's divider is .ca-handle, with its knob in .ca-grip.

.ca {
  --ca-color: #0070f3;
  --ca-solid: #0070f3;
  --ca-ink: #fff;
  --ca-note-font: inherit;
}