Highlights and reviews

Reading in preview

Document preview includes Marked-style reading navigation. A left border marks the current block and stays in a reading band about one-third of the way down the screen as you move through the text.

Your place is saved in this browser and restored when you reopen the document. Reading position is never added to share links — it is local to your browser only.

The Aa menu at the right of the toolbar sets the typography you read in. It applies to the document you are on, and Use this style everywhere at the bottom of that menu makes it your default for every document you open. See reading styles for the five styles and how a reader’s choice relates to the author’s.

Press ? on a document page to see the shortcuts. The main keys are:

Navigation steps through paragraphs, headings, code blocks, and other top-level blocks. Items in a list count as separate stops. The h shortcut toggles a block highlight — it creates a real highlight when the block is clear, or removes it when the whole block is already highlighted. Press c to comment on that highlight, or at the beginning of the current block when it is not fully highlighted.

Highlighting a document

Anyone who can read a document can highlight it — an account is not required. Select some text in the document body and a small toolbar appears next to your selection with two actions:

• Highlight marks the passage. Selecting an existing highlight offers to remove it again.
• Comment opens a note field attached to that passage.

Turn on Highlight as I select in the toolbar’s Highlights menu to skip the confirmation step: every selection becomes a highlight as you make it. That preference is remembered in your browser.

Highlights and notes save on their own; the toolbar shows Saving… and then Saved. There is no separate save button.

Notes and the comments sidebar

A highlight with a note gets an anchor in the margin, and the speech-bubble button in the toolbar opens a sidebar listing every note alongside the document. Clicking a note jumps to its passage. The sidebar can be dragged wider, and Show highlights in the Highlights menu hides the marks entirely when you want to read the text clean.

Signing your highlights

The Signature field in the Highlights menu takes a short label — usually initials — and applies it to every new highlight you create. It is worth setting before you review someone else's draft: the author sees that label next to your review, which matters when several people annotate the same document and none of them are signed in.

Starting over

Clear highlights, in the Highlights menu, removes all of your highlights on that document. Your next highlight starts a fresh set with a new share link, so links you already handed out stop resolving to your annotations.

How highlight sets work

Your highlights on a document are stored together as a highlight set. A document can have many sets — one per reader — and they never overwrite each other.

Opening a document normally shows your own highlights and nobody else's. Other people's sets appear when you open their link, or in the Reviews panel described below.

Sharing your highlights

Copy highlight link, in the toolbar’s Highlights menu, copies the document URL with your set attached as a ?hl= parameter. Anyone who opens that link sees the document with your highlights and notes rendered on it, whether or not they have an account.

https://markedb.in/x7k2m?hl=abc123

The TextBundle link on the document page follows whichever set you are viewing, so downloading while a ?hl= link is open gives you the Markdown, its images, and a highlights.json in Marked's format. That is how an annotated draft gets back onto your Mac.

Collecting reviews on your own document

Publish a draft as unlisted or public, send the link to the people whose feedback you want, and ask them to highlight it. Each reviewer's annotations become their own set on your document.

On a document you can edit, a Reviews panel sits above the text and lists every set that has highlights in it, newest first. Each row shows who made it, how many highlights and notes it contains, when it last changed, and — if it was forked from another set — where it came from.

Reviewers are labelled by account display name when they were signed in, by the signature they typed when they were not, and as Anonymous reviewer when there is neither.

Importing a review

Import copies a reviewer's highlights and notes into your own set, so one pass through the document shows feedback from several people at once. Identical passages are merged rather than stacked, and the reviewer's own set is left exactly as it was — importing is a copy, not a move. Import as many reviews as you like, then export one TextBundle with everything on it.

Who can do what

Applications can list and fetch reviews too — see the highlight set endpoints in the API reference.