Add, answer, and resolve [!comment] callouts in Obsidian markdown files. Use when leaving editorial comments on a draft, replying to existing comment threads, resolving addressed feedback, flagging claims that need sources, or reviewing writing with annotations instead of direct edits. Defines the callout format: author, date, text reference, type tags ([edit], [question], [flag]), threading, and resolution.
This defines how to use [!comment] callouts in Obsidian markdown files. These are visible, structured editorial annotations — like Google Docs comments, but in plain markdown.
Use this convention whenever:
> [!comment]- **@author** · YYYY-MM-DD · re: "referenced text"
> The comment body goes here.
| Part | Purpose |
|---|---|
[!comment]- |
Callout type, collapsed by default (-) |
**@author** | Who left the comment |
YYYY-MM-DD | Date |
re: "..." | Short excerpt (5-15 words) from the passage being discussed, or a section heading |
| Body | The actual comment — concise and actionable |
Add a tag before the author to categorize:
> [!comment]- [edit] **@author** · YYYY-MM-DD · re: "referenced text"
> The comment body.
| Tag | When to use |
|---|---|
| (none) | General annotation or note |
[edit] | Suggesting a text change (rephrase, cut, rewrite) |
[question] | Asking for clarification or more information |
[flag] | Marking something that needs attention (missing source, factual concern, etc.) |
**@claude** (or the appropriate model name)When a comment has been addressed, apply strikethrough to the title and body, and add a resolution line:
> [!comment]- ~~[flag] **@claude** · 2026-03-25 · re: "performance claims"~~
> ~~This needs a source or benchmark reference.~~
> **Resolved** by @chekos · 2026-03-25
Nest replies inside the parent comment using a second blockquote level. Replies use [!comment] (no -) since they're already inside a collapsed parent:
> [!comment]- **@claude** · 2026-03-25 · re: "metrics summary"
> Which metrics are these? Be specific.
>> [!comment] **@chekos** · 2026-03-25
>> Clarified to "monthly active users and retention rate."
Read the document. For each issue you find, insert a comment at the relevant location using the appropriate type. After all comments are placed, summarize what you added:
Added 4 comments to
essay.md:
[edit]on "intro paragraph" — tighten opening[question]on "methodology" — missing citation[flag]on "results" — unsubstantiated claim- General on "conclusion" — strong ending, consider expanding
Read through the document looking for existing [!comment] callouts. For each one:
Find all [!comment] callouts in the document. For each one, apply the resolution format (strikethrough + resolved-by line). Only resolve comments that have actually been addressed — if the underlying issue hasn't been fixed, leave the comment open and flag it.
The structured format (@author · date · re: "text") is a convention, not a rigid requirement. A quick > [!comment] fix this is perfectly valid. Use the full format when context and attribution matter (reviews, collaboration); use the short form for quick personal notes.