OpenPress

@openpress-comment

Comment markers

Inline review markers live as MDX comments in source. The workbench renders them as numbered pins; agents resolve them with the apply-comments workflow. No external comments database.

OpenPress comments are not a separate service. Each comment is an MDX comment block written directly into the source file — the workbench reads them at render time and surfaces them as interactive pins. This means comments travel with the document in git, survive across branches, and can be resolved by any tool that edits MDX (including AI agents).

Trade-off vs. a comments DB. No accounts, no notifications, no threaded replies — by design. If you need those, host the deployed reader behind a service like Hypothes.is or roll your own annotation backend. OpenPress only owns the inline markers.

Marker format

Symbol Impl

# @openpress-comment

A standard MDX comment block whose first attribute name matches @openpress-comment. The engine parses it during MDX compilation and emits a pin in the workbench.

{/* @openpress-comment id="c-2026-05-28-abc" ts="2026-05-28T12:34:00Z" text="..." */}

Attributes

Name Type Default Description
id required string Stable identifier. The workbench generates one when you create a comment from the UI; agents should re-use existing ids when editing.
ts required ISO 8601 Creation timestamp. Surfaced in the workbench tooltip and used for sort order in the pending-comments panel.
text required encoded string The comment body. Encoded so it can survive MDX parsing — line breaks, quotes, and unicode pass through unchanged.
author string Optional. Free-form label ("Q", "reviewer", "GPT-5").
In MDX prose
The model assumes uniform demand across the network — see
chapter 3 for the relaxation under sparse-link conditions.

{/* @openpress-comment id="c-2026-05-28-uniform-demand" ts="2026-05-28T12:34:00Z" text="Is 'uniform' the right word here? Maybe 'isotropic'?" author="reviewer" */}

Multiple markers can sit next to the same content. The workbench groups them on the same block but renders separate pins so each comment stays addressable. Position in source determines visual order in the panel.

Authoring comments

From the workbench (humans)

  1. Run npm run dev, open http://127.0.0.1:5173/workspace.
  2. Toggle the inspector from the toolbar.
  3. Click a block (or the insertion bar between blocks) → Add comment.
  4. Type the comment, submit with Cmd/Ctrl + Enter.
  5. The workbench writes the marker back into the MDX source and saves the file.

From an agent (Claude / Codex / Cursor)

  1. Search the source file with open-press search . "<query>" --json to locate the block.
  2. Insert a marker line directly after the target prose. Use a fresh id (UUID-ish — convention is c-YYYY-MM-DD-<slug>) and a current ISO timestamp.
  3. Use open-press replace . "<old>" "<new>" --apply or write the file directly with the editor's MDX edit tool.

Resolving comments

Comments are inline TODOs for the document. The workflow is read → decide → edit source → remove marker. Removing a marker is a positive action that signals "this is handled" — never delete one without applying the change (or recording the decision to skip).

Find all pending markers
rg "@openpress-comment" press/ -n

Agents have a dedicated workflow for this — see the CLI Tools page and the bundled openpress-apply-comments skill. The skill's contract:

  1. List every pending marker.
  2. For each, read the surrounding prose, decide on a source edit, apply it.
  3. Delete the marker only after the edit is in place.
  4. Run npm run build to verify nothing broke.
  5. Report which markers were resolved and which (if any) were left because they needed a human decision.

Anti-patterns

  • Don't reuse ids across documents. The id is the addressing key for the workbench pin — duplicates break navigation. If you fork a chapter and need to keep a marker, regenerate the id.
  • Don't clear a marker without an action. Markers are commitments. Either apply the change, or replace the marker with a follow-up TODO comment explaining why it's being held.
  • Don't hand-write the encoded text. Use the workbench, or let the agent generate it — manual escaping of quotes / newlines is error-prone.