Comment on a page — Commentware

Leave a comment on anything on a page, then mention, attach, reply, edit and resolve.

Leave a comment on anything on a page, then answer, edit and resolve the thread it starts. Learn more about comments, threads and pins.

Prerequisites

The extension installed and connected to a server. See Install a server.

Open the comment overlay

Press the keyboard shortcut — Alt+C, or ⌥C on a Mac.

The overlay opens over the page, with its toolbar. Drag the toolbar anywhere on the page and it stays where you put it. Being open belongs to the tab, not to the page: follow a link with the overlay open and it is still open on the next page.

Escape closes the nearest thing that is open, such as a menu or a running microphone, before a comment you are writing or a thread you opened, and the overlay itself last. Escape on a new comment drops it and what you typed. An Escape you press in one of the page’s own fields stays with the page, except while the crosshair is armed, when any Escape puts it away.

Chrome owns the shortcut, and you can change or clear it at . Every place in the extension that names the shortcut asks Chrome what it actually is, so if you rebind it the extension follows. The extension’s toolbar icon opens the side panel instead, a different surface holding the same threads. See Find a comment.

Say where the comment goes, in one of two ways:
- Select the toolbar’s first button, which arms a crosshair, then click the thing on the page the comment is about.
- Right-click it and choose “Leave a Commentware comment”. When text is selected, the item is inside a “Commentware” submenu, beside “Live edit”. On a Mac, right-clicking a word selects it, so there it is in the submenu too.
Type the comment in the composer that opens on the spot.
Press Enter to send it. Shift+Enter starts a new line.

In a frame the page fills in itself instead of loading it from an address, such as one the page has written content into or one it builds from data it made, right-clicking its text shows the “Commentware” submenu, holding “Leave a Commentware comment” and “Live edit (experimental)”, whether or not text is selected.

The page is photographed as you saw it the moment you placed the pin. To stop that for a site, see Settings.

Right-clicking on one of Commentware’s own pins, or inside an iframe that Commentware cannot reach, gives you the crosshair instead — neither of those can say which element on the page you meant.

Comments are Markdown. Headings, lists, code, emphasis and links are all drawn as you would expect. Links open in a new tab, and only http, https and mailto links are clickable; anything else stays as readable text.

Try a wording with live edit

Live edit is experimental. It shows how new wording fits the page before you suggest it.

Select some text, right-click, and choose “Live edit (experimental)”. The text becomes editable where it is.
Change it.
Press ✓ or Ctrl+Enter (⌘+Enter on a Mac) to post it, or ✕ or Escape to put the page back and post nothing.

The page goes back to how it was, and a comment is left on that spot. It holds the old text and the new one, and a screenshot of the page with your edit in it. Its card opens so you can add more.

If the page reloads while you are editing — you reload it, or a development server does — the edit comes back on the same text, with what you typed and the cursor where it was. If the reload changed that text, the edit still comes back, and a message headed “Live edit · experimental” says the comment will quote the text you started from, not the new text. If the text is no longer on the page, a new comment opens holding your edit, with no screenshot, and a message says why. Select Comment to post it, or Cancel to drop it. If the edit is too long for one comment, the message says it could not come back. A reload that lands on a different address, or on a site whose screenshots are now turned off, drops the edit.

Live edit works on the page, in frames loaded from the page’s own address (the same scheme, host and port), and in frames the page fills in itself instead of loading them from an address. In a frame from another site or subdomain, or in one the page isolates with a sandbox attribute that does not include allow-same-origin, a message says the text is inside a frame live edit cannot reach. For text the page already lets you edit, or on a site whose screenshots are turned off, a message says why live edit cannot start. If you choose “Live edit (experimental)” in a frame the page fills in itself with no text selected there, the message says “Select some text on the page first, then choose Live edit.” A comment from live edit quotes the page and includes a screenshot, which a site with screenshots turned off refuses.

Mention somebody

Type @.
Pick a person from the list that opens. A name typed by hand instead is not a mention: it looks addressed to somebody and notifies nobody, with no error to tell you. Learn more about how mentions are kept.

The name becomes one piece: it is highlighted, a backspace beside it takes the whole name, and deleting the word deletes the mention. A mention is what sends that person a notification.

Attach a file

Select the paperclip on the composer.
Choose the file.

Pictures are shown inline in the comment rather than as a link. Anything that is not a picture is served as a download. If your server does not speak attachments the button is not there, and the sentence beside it says which side has to update, before you choose a file.

Open an attached picture and you get the same drawing tools the screenshot gets. What you mark up comes back as a reply with the edited copy attached, rather than replacing the original: a comment says what it said, so the marked-up version becomes a new one underneath it.

Reply, edit, resolve

The thread card is the same in the overlay and in the side panel, so every one of these works in either place.

Reply in the box at the bottom of the thread.
Edit your own comment from its menu. It stays in place.
Delete a comment or a whole thread. Only a key holding can_admin may delete anything; every other key is refused. See Manage users and access keys.
Resolve a thread when it is finished. A resolved thread’s pin shows a tick rather than a count, and the side panel files it under its own heading instead of in the open list. Nothing is deleted.

Resolved threads are eventually purged — after 30 days by default, and the person running the server sets that. Learn more about the retention purge.

Reply without telling the whole thread by turning off the bell beside Reply before you send. Only the people the reply mentions are told; everybody else sees it as unread on the pin. An agent does this for its “Looking into it.” when it starts on something you asked for. The bell is on again for the next reply.

Mark a comment unread

A thread remembers how far you have read, as a position rather than a set of ticks. Opening a thread marks it read up to the newest comment that was on your screen when you opened it, and a line marks where the new comments start.

Open the comment’s menu on the page, or find the control on its row in the side panel.
Choose Mark unread from here.

That comment and everything after it is unread again, and the pin shows that something in it is unread. A card left open in a tab you are not watching goes on collecting unread comments below the line.

Filter the comments drawn

The third control on the overlay’s toolbar chooses which comments are drawn, and it is remembered across pages:

All comments — the default, which hides nothing.
Open comments — what is still outstanding.
Resolved comments — what a review actually concluded, and nothing else.

Nothing is ever deleted by resolving, so a page somebody has worked through for a month draws thirty ticked pins over four live ones. That is what this is for. The control wears the active mode’s own icon, so a filter can never be in effect without being on screen.

Preview the live edits on a page

The same control holds a switch that shows every unresolved live edit in the page, with its new text in place of the text it is about.

On the overlay’s toolbar, open the third control, the one that filters comments.
Select Preview live edits. The line under it begins “Experimental.” and says how many edits are shown and why the rest are not, for example “2 of 3 edits shown. 1 on text that has changed.”
To turn it off, select Preview live edits again.

Where two live edits touch the same text, the newest one is shown. A live edit whose first comment was edited or deleted is not shown, and which comments the filter draws does not change what the preview shows. The preview belongs to the tab: it stays on when you close the overlay or follow a link in the same tab, and goes when you turn it off or close the tab. Nothing on the page says it is on while the overlay is closed. If the page keeps writing over the text, the preview leaves that edit, and the line under the switch says so.

Note: Only your browser shows the preview. A new comment, its screenshot and a live edit you start all use the page as it is served.

Check that it worked

A pin marks the spot, and opening it shows your comment in its thread. A mention is highlighted as one piece, and a resolved thread’s pin shows a tick.

Next steps

Find a comment: find a thread on a page you are not on.
Move a pin and edit its screenshot: put an unstuck pin back, and mark up what it shows.