Microsoft Word / Google Docs style comments for Markdown files — stored inline,
readable, and Git-friendly.
Comments are kept inside the Markdown file in a fenced ```MarkdownComments
block placed immediately above the block they annotate. The block holds a small
YAML list of comment threads, so review conversations travel with the text and
diff cleanly in Git.
Features
- Add comments on a selection or block (Word-style threads).
- Reply, resolve, reopen, edit, and delete comments and threads.
- Inline anchoring to a quoted selection or a whole block, with a
"needs reattach" state when a quote no longer matches.
- Diagnostics for invalid YAML, duplicate ids, Git conflict markers, and
non-UTC timestamps — always non-destructive.
- Markdown Preview integration: comment fences render as comment cards
(like Mermaid diagrams), never as raw code.
- Interactive Comments Preview panel: run MarkdownComments: Open Comments
Preview (or use the editor title button) to reply, edit, resolve, reopen, and
delete comments directly from a side-by-side preview.
- Comments sidebar: an activity-bar view (Markdown Comments) shows just the
comment threads for the active Markdown file — Word-style side comments — with
the same reply/edit/resolve/reopen/delete actions. It follows whichever
Markdown file you focus (including the interactive Comments Preview panel) and
updates live as you edit. Click a comment to jump to it: if our interactive
Comments Preview panel is open for that file, the panel scrolls to the thread
and briefly highlights it; if VS Code's built-in Markdown preview is open, the
preview scrolls to the commented line and flashes it (no raw editor needed —
see below); otherwise the source Markdown opens at the anchored line. While the
sidebar is open, the built-in Markdown preview hides its inline comment cards so
comments appear in just one place.
- Hide & collapse controls: hide all comments, collapse comment bodies, hide
resolved threads, or collapse individual threads — in the panel, the sidebar,
and the built-in Markdown preview.
How it works
A pure Rust core (compiled to WebAssembly) owns the format contract: parsing,
anchoring, validation, and deterministic edit synthesis. The extension supplies
identity (Git user.name) and timestamps, applies the text edits the core
returns, and renders the VS Code Comments UI.
Running the extension (development)
Press F5 in VS Code (open either the repository root or the extension
folder). The bundled Run MarkdownComments Extension launch config runs a
build extension task first, so the Extension Development Host always starts from
a freshly built dist/. Then open a .md file in the new window.
[!IMPORTANT]
After changing extension code you must reload the running window for the change
to take effect: in the Extension Development Host run Developer: Reload Window
(Ctrl+R), or stop and press F5 again. If you
instead installed a packaged .vsix, reinstall the new build — an old install
keeps running stale code. dist/ is git-ignored, so a fresh clone has no build
until you run npm run build (F5 does this for you).
VS Code exposes no API for an extension to scroll the built-in Markdown
preview to a line. We work around this from inside the preview itself: the
extension contributes a preview script (markdown.previewScripts), and when you
click a sidebar comment it refreshes the preview so our markdown-it plugin embeds
an invisible scroll anchor next to the matching comment; the preview script then
scrolls that anchor into view and briefly flashes the line. This works even when
only the preview is open — no source editor is opened.
The fully-controllable alternative is the Comments Preview panel
(MarkdownComments: Open Comments Preview), our own webview, which scrolls to and
highlights the thread directly. When neither preview is open, clicking a comment
opens the source Markdown at the anchored line.
Versioning of builds
package.json keeps a clean base version (X.Y.Z). Packaged builds are stamped
with a local timestamp so every artifact is uniquely traceable:
X.Y.Z-YYYYMMDD-HHMMSS e.g. 0.1.0-20260605-230038
npm run package builds a .vsix whose version carries the timestamp, then
restores package.json to its clean base version (the working tree stays
clean). The stamped version is what shows in the Extensions view after install,
so you can confirm exactly which build is running.npm run version:stamp prints the stamped version without writing it.npm run version:stamp:write writes the stamped version into package.json
(useful before an F5 session if you want the Extension Development Host to
display the timestamp); npm run version:reset strips it back to the base.
Settings
markdownComments.authorName: display name for new comments (defaults to the
local Git user.name).markdownComments.showResolved: show resolved threads inline. When disabled,
resolved threads are hidden in the editor.
See docs/format.md for the full format specification.
License
MIT — see LICENSE.
