Comments that live in your file

The <!--wymark: tighten this prose-->quick brown fox jumps<!--wymark-end--> over the lazy dog.

The <!--wymark: {"author":"Jane Doe"}@@Tighten this--><!--wymark-reply: {"author":"Claude"}@@Reworded, better?-->quick brown fox<!--wymark-end--> jumps over the lazy dog.

# Comments that live in your file

Select some text and press Cmd+Alt+M: a comment card appears in the gutter, anchored to your selection. So far, exactly like Word or Google Docs.

The difference is where the comment goes. Wymark does not keep comments in a database or a sidecar file. The comment is written **into your markdown file**, as a pair of HTML comment markers around the anchored text:

```markdown
The <!--wymark: tighten this prose-->quick brown fox jumps<!--wymark-end--> over the lazy dog.
```

HTML comments are invisible in every spec-correct markdown renderer -- GitHub, VS Code preview, pandoc, Obsidian's reading view all show the sentence without a trace of the marker. But the comment travels with the file: share it, sync it, commit it, hand it to an AI -- the comment is right there <!--wymark: {"author":"John Doe"}@@Hello from inside the documentation. This sentence is wrapped in a real comment marker -- flip this page to Source to see it in the source.-->in the text<!--wymark-end-->.

(That last sentence is not hypothetical: flip this page to **Source** with the toggle above and find the `<!--wymark:` marker in this paragraph.)

## Anchored, authored, threaded

A comment can carry an author and a timestamp, and replies stack into a thread:

```markdown
The <!--wymark: {"author":"Jane Doe"}@@Tighten this--><!--wymark-reply: {"author":"Claude"}@@Reworded, better?-->quick brown fox<!--wymark-end--> jumps over the lazy dog.
```

In the editor you see a familiar comment thread in the gutter: author names, times, a reply box. Your reviewer name is set once in Settings and stamped on every comment you make. In the file, it is all just the marker syntax above -- documented precisely in the [marker reference](/docs/how-it-works/markers).

**Resolving a comment deletes its markers.** The checkmark on a card removes the whole thread from the file and leaves the anchored prose untouched. No archive, no tombstone -- if you resolve too early, undo brings it back, and every saved version still contains the comments it had when you saved it.

The Source view shows the markers by default, because that is what the file says. If the syntax gets in the way while you work there, click the `</>` icon on the comments row of the status chip at the foot of the comment cards, press `⇧⌘M`, or right-click and untick **Show Comment Markers**. The markers collapse out of the text and the cards stay. They are still in the file; you just stop seeing the syntax. The **Comments** button in the ribbon shows or hides the cards themselves (`⇧⌘C`), and Source view remembers your marker choice when you hide the cards and bring them back.

:::persona word
Anchored ranges, authors, timestamps, threads, resolve -- the model is deliberately Word's. Two differences: resolving removes the comment entirely (your version history is the archive), and authorship is self-declared, like Word's, not authenticated. The payoff for markdown files is that comments survive *any* route the file takes -- mail it, sync it, or open it in another editor, and nothing is stripped, because the comments are just text in the file.
:::

:::persona markdown
Your files stay portable. A commented file is still a plain markdown file: Obsidian, GitHub, and any CommonMark renderer show clean prose, and your other tools keep working. The markers are visible if you open the raw text elsewhere -- that is the honest cost of having no database -- but they are human-readable, and removing one by hand *is* resolving it. Nothing about your file is held hostage to Wymark.
:::

:::persona git
Comments are content, so they version like content: they travel through commits, branches, and PRs with the file. A `git diff` shows marker insertions textually (Wymark's own diff strips markers when showing you prose changes, so comment activity does not masquerade as writing). GitHub renders the file clean. There is no sync with GitHub's PR comments -- these are in-file annotations, a different layer than review threads on a forge.
:::

## Why in the file?

Any tool can read a comment by reading the file, every saved version keeps the comments it had, and nothing locks you in. The cost is that the markers are visible when the raw file is opened in other tools. The reasoning is in the design note [Why comments live in the file](/docs/how-it-works/comments).

## The sidecar pointer

One line in the marker namespace is Wymark's own: while a document's [AI sidecar](/docs/guide/ai-sidecar) is enabled, the file's first line after any front matter is a `<!--wymark-sidecar ... -->` comment that points a tool at the review sidecar. It is not a comment thread, it never appears as a card, and Wymark removes it when the sidecar is turned off or the document closes.

## Current limitations

- Comments cannot overlap or nest.
- Mentions (`@name`) are plain text for now, with no special behavior.