mdcomments — Native Comments for Markdown

How It Works

Inline [^c-id] markers anchor comments to text. Threads are defined at the bottom using footnote syntax with @author (date): and blockquoted messages:

The ==monthly revenue grew by 15%==[^c-rev1] last quarter.

[^c-rev1]:
    @alice (2026-02-10):
    > Is this YoY?

    @bob (2026-02-11):
    > Yes. Added a clarifying note.

Wrap text in ==...== for range anchoring; an anchor: metadata line provides a fallback for parsers without highlight syntax. For large documents, threads can live in a companion document.comments.md file. The full grammar and validation rules are defined in the formal specification. In any standard renderer, comments degrade gracefully to ordinary footnotes.

Design Goals

Anchored

Comments attach to specific text, not just float in the file.

Attributed

Each comment carries an author and timestamp.

Threaded

Replies form a conversation, not a flat list.

Graceful Degradation

In any renderer, comments appear as sensible footnotes — nothing breaks.

Portable

Works in any standard Markdown parser without a plugin.

Survives Round-tripping

Comments aren't stripped on export or import.

Why Footnotes?

Already standardized — supported by GFM, Pandoc, Hugo, Obsidian, and most CommonMark extensions.
Graceful degradation — comments appear as numbered references; raw [^c-id] is unintrusive where unsupported.
Separation of concerns — tiny inline marker, longer definition elsewhere keeps prose clean.
No new syntax — combines footnotes, blockquotes, and @-mentions.
Convention over specification — c- prefix and @author (date): are conventions on valid Markdown.

Comparison with Alternatives

Approach	Anchored	Author	Threaded	Hidden / Graceful	Portable	Survives Export	Notes
HTML `<!-- -->`	✗	✗	✗	✓ Hidden	✓	✓	Universal but no anchoring, author, or threading.
Ref-link hack	✗	✗	✗	✓ Hidden	✓	✓	No structure. A clever trick, not a foundation.
Obsidian `%%`	✗	✗	✗	✓ Hidden	✗	✓	Non-standard, Obsidian-only.
CriticMarkup	✓	✗	✗	✗ Visible	⚠ Pandoc	✓	Inline and anchored but lacks threading; `{}` collides with attributes.
kramdown `{::}`	✗	✗	✗	✓ Hidden	✗	✓	kramdown-only. No anchoring or structure.
MDX `{/* */}`	✗	✗	✗	✓ Hidden	✗	✓	React/JSX ecosystem only. Not portable Markdown.
Pandoc `^[]`	✓	✗	✗	✗ Visible	⚠ Pandoc	✓	Render visibly, lack identity or threading.
Marker/PyMdown	✓	✗	✗	✗ Visible	⚠ Limited	✓	Visual anchoring but same structural shortcomings as CriticMarkup.
Sidecar JSON	✓	✗	✗	✓ Hidden	✗	⚠	Comments lost if sidecar is missing. Fragile and non-portable.
Platform DB	✓	✓	✓	✓ Hidden	✗	✗ Lost	Great UX, zero portability. Comments vanish on export.
mdcomments	✓	✓	✓	✓ Graceful	✓	✓	Structured, portable, graceful degradation.

VS Code Extension

The repository includes vscode-mdcomments, a Visual Studio Code extension for writing and reviewing mdcomments directly in the editor.

Interactive Preview: Side-by-side preview with highlighted anchors, threaded cards, and reply actions.
Add Comment Command: Select text and run mdcomments: Add Comment to insert a new anchored thread.
Reply Command: Use mdcomments: Reply to Comment to append replies to existing threads.
Default Author Setting: Configure mdcomments.defaultAuthor for faster comment creation.

See vscode-mdcomments/README.html for installation and development details.