Home

Comments

Comments

Comments let you attach discussion to specific text in a document without changing the document's main content. They are useful for review, feedback, editorial notes, and collaborative discussion.

Stencila also preserves comments during bi-directional conversion between Stencila Markdown and common authoring formats such as Microsoft Word and Google Docs. In practice, many people will receive or respond to comments through those tools rather than writing comment syntax by hand in Stencila Markdown, but this conversion makes it possible to exchange reviewed documents with collaborators while keeping comment threads intact.

This capability also provides an interface between collaborators using those formats and AI agents working in Stencila. Collaborators can leave requests as comments in Microsoft Word or Google Docs, and agents can respond in the same threads to explain changes they made, answer questions, or report what action they took.

In Stencila Markdown, comments are authored in two parts:

  • Anchors in the document text mark where a comment applies.

  • Definitions later in the document provide the comment content.

Syntax

A comment uses an identifier such as c1. You place anchor markers in the document body, then define the comment using a reference-style definition.

A paragraph with {>>c1}commented text{<<c1}.

[>>c1]: The comment text.

The opening marker {>>c1} starts the commented range and the closing marker {<<c1} ends it. The definition [>>c1]: ... supplies the actual comment content.

Range comments

The most common form is a range comment, which applies to a span of inline content:

A paragraph with {>>c1}a comment on some content{<<c1}.

[>>c1]: This is the first comment.

A range comment can also span across paragraphs and other block content. The opening and closing markers do not need to be in the same paragraph:

A paragraph that starts {>>c1}a comment spanning multiple paragraphs.

A second paragraph that is still inside the same comment.

A final paragraph that ends the comment{<<c1}.

[>>c1]: This comment covers several paragraphs.

Point comments

A comment can also be attached to a single point in the document using only a closing marker:

A paragraph with a point comment{<<c1}.

[>>c1]: This comment is attached at a single position.

This is useful when you want to comment on a location between words or at the end of a sentence, rather than on a selected range.

Overlapping comments

Comments can overlap. This allows one thread to cover a larger passage while another thread discusses a smaller part within it.

A paragraph with {>>c1}a comment on some content{<<c1} and {>>c2}an overlapping comment in it.

A paragraph that is {>>c3}within the overlapping comment{<<c2}.

A paragraph with a point comment{<<c3}.

[>>c1]: This is the first comment.

[>>c2]: This is the second comment, spanning multiple paragraphs.

    It has multiple paragraphs.

[>>c3]: A third comment.

Replies

Replies are regular comments that declare which earlier comment they reply to using a parent attribute.

A paragraph with {>>c1}commented text{<<c1}.

[>>c1]: This is the first comment.

[>>r1]{parent="c1"}: A reply to the first comment.

Nested replies work the same way: each reply points to its immediate parent comment.

A paragraph with {>>c1}commented text{<<c1}.

[>>c1]: This is the first comment.

[>>r1]{parent="c1"}: A reply to the first comment.

[>>r2]{parent="r1"}: A reply to the reply.

[>>r3]{parent="c1"}: Another reply to the original comment.

You can add multiple replies to build up a thread, with each reply using parent to indicate where it belongs.

Metadata

Comment definitions can include attributes such as the author (by), timestamp (at), and parent comment (parent):

A paragraph with a point comment{<<c1}.

[>>c1]{by="Arthur Dent", at="1978-10-12T09:00:00Z"}: I think the Heart of Gold should be introduced a little earlier in this section.

[>>r1]{by="Ford Prefect", at="1978-10-12T09:07:00Z", parent="c1"}: Agreed — readers will better understand why the Infinite Improbability Drive matters later.

[>>r2]{by="Zaphod Beeblebrox", at="1978-10-12T09:11:00Z", parent="r1"}: The ship is the important bit, baby. Move it up.

[>>r3]{by="Trillian", at="1978-10-12T09:18:00Z", parent="c1"}: If we do that, let's also mention its stolen prototype status for context.

These attributes are especially useful when comments are generated or preserved by collaborative tools.

Tips

  • Use stable, simple identifiers like c1, c2, and c3 when writing by hand.

  • Keep comment definitions near the end of the relevant section or document so they are easy to find.

  • Use replies for discussion within a thread instead of creating separate top-level comments on the same passage.

  • Use metadata when you need to preserve authorship or timing information.

Related guides

For related authoring features, see:

Schema types

For the formal Stencila Schema definitions behind these features, see:
Edit on GitHub
© 2026 Stencila