Comments and suggestions

There are two ways to respond to a document without simply overwriting it: a comment, which is a note attached to some text, and a suggestion, which is a tracked edit that someone accepts or rejects. This page covers adding comments, reviewing suggestions, and what blocks publishing.

Before you start: commenting needs the commenter, editor or owner role. Making, accepting and rejecting suggestions need the editor or owner role. Viewers can only read. See Roles and permissions.

Add a comment

Select the text you want to comment on.
In the selection bubble, select Comment.
Type your comment in the comment box that appears.
Select Comment, or press ⌘↵.

The comment is anchored to the text you selected and stays attached to it as the document changes around it.

To mention a colleague, write or reply in the Comments tab, where the comment box accepts @ mentions. Anyone you mention gets a notification with a link straight to the thread. See Notifications.

Reply to and resolve comments

Threads are listed in the Comments tab of the Edit panel: select Edit panel, then the speech bubble icon. If you opened the document as a guest through a share link, select Comments in the toolbar instead.

To reply, select Reply on a comment, type, and select Reply.
When a thread is dealt with, select Resolve. Resolved threads are hidden from the list but not deleted.
To see resolved threads again, tick Resolved at the top of the Comments tab. Select Reopen to bring a thread back.

Suggest a change

To propose an edit instead of making it, switch to Suggesting mode: select Edit panel, then set Mode to Suggesting. Your insertions and deletions are recorded as tracked changes with your name on them, and none of them is applied until someone accepts it. Formatting, new paragraphs and list changes are not tracked. Commenters cannot suggest.

For the full steps, see How to suggest edits.

Review suggestions

When a document has suggestions, editors see a review list at the top of the document with the number of changes and who made them.

One at a time: select Accept (✓) or Reject (✗) beside a change.
Step through: use the arrows beside the count to jump from change to change.
All at once: select Accept all or Reject all.

The review list scrolls with the document, so scroll to the top to find it.

Suggestions from Workover AI

Some AI actions also arrive as suggestions. When Workover AI proposes a revision, the review list names the source, and you can select Accept all, Dismiss, or Ask Workover AI to discuss it. See Iterating on a draft.

Not every AI action works this way. Improve, Shorten, Expand and Fix grammar in the selection bubble replace your text directly, even in Suggesting mode. Tools connected through the CLI or MCP server can also be given permission to edit a document directly. See The CLI and MCP server.

Publishing with unresolved suggestions

You cannot publish a document that still has suggestions. The push controls on the Edit panel’s WP tab are disabled and explain why: publishing would put the tracked changes, including the text marked for removal, on your live site. Accept or reject every suggestion first.