This post summarises the current state of the discussion in this ticket and the plans to implement (original report at the bottom):

Motivation

Comments are useful in many situation. They allow adding information that directly relates to parts of the document without adding it directly to the document content.

Comments can be particularly helpful when drafting documents and during a review process.

Scope of comments

In a first iteration, we add support for point anchor comments, not range anchor comments. This means that each comment has an anchor point in the document, the anchor cannot span over a range of document content. If people want to comment on a range, they can use a comment in combination with the text highlight feature we already have. One reason to only support point anchor comments is that comments spawning a range would need a custom Markdown syntax, see below.

Each comment is attributed to a user (or guest with a name) and has a timestamp.

We support stacked comments (i.e. replies to comments), so that a comment anchor can reference a discussion of comments. Nested comments (i.e. comments on a specific comment) will not be supported.

It will be possible to edit all comments, also those from other users. This will be possible by editing the Markdown file anyway, so we don't hide this in the user interface. For reference, this is possible in Collabora Online as well.

User interface

A small chat icon button as anchor in the text will highlight the position of the comment.

The comments are displayed in popover boxes that spawn from the right side of the editor (where the table of contents outline lives). One bubble contains all comments on that anchor and has an input field at the bottom to allow adding additional comments.

When enough whitespace is available, the comments popover will be displayed open per default. On narrow screens without enough whitespace and on mobile, the popover can be opened by clicking a comments icon on the right side of the screen or by clicking the comments icon at the position of the comment.

We'll use Notion as reference for how comment boxes behave regarding responsive design and alignment:

Adding new comments is possible via toolbar button and via keyboard shortcut (to be decided).

When the document contains comments, it's possible to hide all comments in the editor toolbar to allow distraction-free reading.

Markdown representation

Comments will be persisted to Markdown using the footnote syntax that is defined in several Markdown extensions. See MultiMarkdown and Markdown Guide for details:

The major advantage over a custom syntax is that existing Markdown editors with footnote support (e.g. Obsidian and Ghostwriter) render footnote comments and make them accessible.

In order to allow adding footnote support to Text later, we extend the footnote syntax and let each footnote comment start with [comment]. To allow discussions of comments within one comment anchor, we use a bullet list.

This is how the Markdown syntax will look like:

The quick[^comment-1] brown fox.

[^comment-1]:
    - @[jane](mention://user/jane)*(2026-05-21T10:30Z)*
      Is "quick" the right word here?
    - @[bob](mention://user/bob)*(2026-05-21T12:45Z)*
      I think "fast" is more accurate.
    - @[jane](mention://user/jane)*(2026-05-21T16:12Z)*
      Or how about "swift"?