Why comments live in the file
Wymark writes a comment into your markdown file, as a pair of HTML comment markers around the text it is about. Comments shows what that looks like and how to work with it; the marker reference has the exact format. This page is the reasoning.
This is the design decision most worth defending, so here is the reasoning:
- Any tool can read them. An agent, a script, or a colleague with a plain text editor sees the comment, the exact prose it is anchored to, who said it, and the discussion so far – by reading the file, with no API. Any of them can act on the comment and reply in place. A comments database would make every one of those steps a special integration.
- Snapshots capture comments for free. Comments are file content, so every saved version preserves its comment state. Restore a version, get its comments back.
- No lock-in. The format is documented, human-readable, and editable by hand. Any tool – or any person with a text editor – can read, write, and resolve Wymark comments.
The accepted trade-offs: markers are visible when you open the raw file in other tools (a few editors with non-spec preview behavior, notably Typora, also render them visibly), and they appear as bytes in external diffs. We think plain text that everything can read beats invisible state that only one app can.
# Why comments live in the file
Wymark writes a comment into your markdown file, as a pair of HTML comment markers around the text it is about. [Comments](/docs/concepts/comments) shows what that looks like and how to work with it; the [marker reference](/docs/how-it-works/markers) has the exact format. This page is the reasoning.
This is the design decision most worth defending, so here is the reasoning:
- **Any tool can read them.** An agent, a script, or a colleague with a plain text editor sees the comment, the exact prose it is anchored to, who said it, and the discussion so far -- by reading the file, with no API. Any of them can act on the comment and reply in place. A comments database would make every one of those steps a special integration.
- **Snapshots capture comments for free.** Comments are file content, so every saved version preserves its comment state. Restore a version, get its comments back.
- **No lock-in.** The format is documented, human-readable, and editable by hand. Any tool -- or any person with a text editor -- can read, write, and resolve Wymark comments.
The accepted trade-offs: markers are visible when you open the raw file in other tools (a few editors with non-spec preview behavior, notably Typora, also render them visibly), and they appear as bytes in external diffs. We think plain text that everything can read beats invisible state that only one app can.