Comments and mentions

Comments are a server feature. They exist on the DocuCommit server (read-only web app), and nowhere else: the DocuCommit editor (desktop app) has no comment UI, does not fetch comments, and will never show you one. If your team discusses pages, that discussion happens in the browser.

Reading never requires signing in. Commenting does — anyone with an account on your server can comment, and there is no separate reviewer role.

Commenting on a block

Every top-level block of a rendered page — a paragraph, a heading, a list, a table, a code fence, a callout — is a comment anchor. Hovering a block shows two small controls:

Control	Appears when	Does
💬 with a number	the block already has comments	opens the thread
＋ (Add a comment)	you are signed in	opens an empty thread

Either opens a popover on the block. The box is labelled Add a comment… for the first comment and Reply… after that, and the button below it is Comment. If you are not signed in the popover says Log in to comment. instead of showing the form.

A comment is plain text, up to 10 000 characters. Markdown in the body is not rendered.

The comments drawer

The 💬 button in the bottom corner (Open comments / Close comments) carries a count of unresolved threads and opens a Comments panel with two sections:

• General — comments about the page as a whole rather than any one block. This is the only place to post one; the form reads Comment on this page…, and an empty page says No general comments yet.
• On this page — one row per block thread, in document order, showing the author, the reply count, and a resolved or outdated tag. Clicking a row scrolls to the block, flashes it, and opens the thread.

Threads and resolving

A block holds one thread. The first comment is the root; everything posted afterwards on the same block is a reply to it, shown indented under it. Threads are one level deep — you cannot reply to a reply, and comments in the General section are a flat list with no replies at all.

Every root comment shows author · time and a Resolve button, which flips to Reopen. Resolving does not hide anything: the thread stays on the page, tagged · resolved, and stops counting towards the drawer badge. Any signed-in user can resolve or reopen any thread, not only the person who wrote it.

Comments are attributed to your account’s display name. Your email address is used on the server to route notifications and is never sent to the browser — the API returns the name only.

@mentions

Type @ at the start of a line or after a space and a suggestion list appears, showing each person’s name next to their handle. Arrow keys move, Enter or Tab picks, Escape closes. A handle is the person’s display name with the spaces removed, so Anna Lindqvist is @AnnaLindqvist. Handles may contain letters, digits, ., _, and -, up to 64 characters.

You can type a handle without using the menu. The server resolves it against registered email addresses first, then against display names with spaces removed, ignoring case. A handle that matches nobody is simply skipped — the comment posts, and no one is told.

@ inside a code span, a fenced or indented code block, or raw HTML is ignored, so @Override in a Java sample never mails anyone.

A resolved mention sends that person an email, whether or not they follow the page. See Follows and notifications for what arrives and when.

Where comments live

Comments are not in your Git repository. Each document’s thread lives in one JSON file in the server’s working directory:

<workdir>/.comments/<library>/<project>/<section…>/<document>.json

Two consequences follow, and both matter:

• A git clone of your repository contains no comments. Nothing about them travels with the content, to the editor or anywhere else.
• Backing them up means backing up the server volume, not the repository. See Backup and restore.

The path is configurable with docucommit.comments.store — see Configuration.

How a comment stays attached

A comment does not store a line number. It stores an anchor: the first 16 hex characters of the SHA-256 of that block’s Markdown source, with the ends trimmed and every run of whitespace collapsed to a single space. When two blocks in a document are byte-identical after that normalisation, the second gets -2 appended, the third -3, and so on.

In plain words: a comment sticks to its paragraph, not to its position. Rewrite the section above it, add ten pages before it, move the paragraph to the end of the document — the anchor is unchanged and the comment follows the text. Re-wrapping the same sentence across different line lengths does not disturb it either, because the whitespace is normalised away.

Edit the commented paragraph itself and the anchor changes, which means the comment no longer matches any block on the page. It is not deleted. It is shown, at the end of the document, under a heading:

Outdated comments The text these referred to has changed.

The drawer marks the same threads · outdated and disables the jump, since there is nothing left to jump to. An outdated thread cannot be resolved or replied to — it is a read-only record of a discussion about text that no longer exists. The same thing happens to the later of two identical paragraphs if you delete the earlier one, because the ordinal suffixes shift.

[!TIP] If a comment still applies after you have rewritten the paragraph, post it again on the new text. There is no way to re-anchor the old one.

When documents move

At startup and after every sync, the server reconciles the comment files against the current content:

What happened to the document	What happens to its comments
Renamed or moved to another section	The file is re-homed to the new path, matched by the document’s uuid
Deleted from the repository	The file is deleted
Unchanged	Nothing

This is why the editor maintains a uuid in frontmatter that you are told to leave alone. It is the identity a comment file follows across a move.

What comments do not do

• They are invisible in the editor. A writer working in the desktop app sees no indication that a paragraph is being discussed. Comments are a server-side conversation about published content.
• They are not live. The page loads its comments once, with the document. A comment someone else posts while you are reading appears when you reload.
• They cannot be edited or deleted. The server exposes exactly two actions — post a comment, and set a thread resolved or unresolved. There is no edit endpoint and no delete endpoint, in the UI or the API. Correcting yourself means posting a reply.
• They are not moderated. Any account can comment, and any account can resolve any thread.
• They do not survive the loss of the server volume. Nothing in Git will bring them back.

Both write endpoints (POST /api/projects/{project}/comments and POST /api/projects/{project}/comments/{id}/resolve) require an authenticated session and a CSRF token. The browser handles both; a script would have to sign in first.