Bring rich inline commenting to Markdown files directly inside VS Code, Cursor, or Antigravity, powered by GitHub as the primary backend.

All comments, replies, and reactions are stored directly on GitHub (in dedicated orphan git references refs/md-comments/data), requiring zero commits, zero branches, and zero PR overhead in your workspace codebase. For offline or non-GitHub repositories, comments seamlessly fall back to local companion <filename>.comments.yml files.

Key Features

Inline Highlights & Comments: Leave comments on specific text selections or paragraphs.
GitHub Backend with Local Fallback: Comments auto-save live to GitHub (refs/md-comments/data), with graceful local fallback to <filename>.comments.yml when working offline.
Fuzzy Anchoring Cascade: Comments are robustly anchored using a cascade matching strategy:
1. Paragraph Hash: Exact match of the normalized FNV-1a hash of the text.
2. Fuzzy Text Match: Selection-based substring search to identify the text even if slightly edited.
3. Heading + Paragraph Index: Contextual paragraph offset within the closest heading.
Threaded Conversations: Support for nested replies, emoji reactions, and thread status (Open / Resolved) for page-level and text-selection comments.
Git/GitHub Integration: Resolves local Git/GitHub configuration to display actual GitHub display names and avatars. Mentions using @username link to GitHub profiles.
Code Lens Integration: See comment counts directly inline above your Markdown paragraphs. Click the lens to open the comments panel.
Orphan Detection: Detect and manage comments whose anchors are lost due to drastic document changes.

Installation

From VS Code Marketplace / Open VSX

Search for MD-Comments in the VS Code Extensions view and click install.

From VSIX

Download the latest .vsix from GitHub Releases, then install from the UI:

Open the Extensions view (Cmd+Shift+X or Ctrl+Shift+X).
Click the ⋯ (Views and More Actions) menu at the top-right.
Select Install from VSIX… and choose the downloaded file.

Alternatively, install via CLI:

code --install-extension md-comments-<version>.vsix
# or in Cursor:
cursor --install-extension md-comments-<version>.vsix

Usage

Open any Markdown (.md) file.
Click the Comment Icon (💬) in the editor title menu (top-right), or open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and search for Markdown Comments: Open Comment Preview.
Select any text in the editor, click the Add comment button in the sidebar (or use editor hover actions) to start a new discussion.
Replies and emoji reactions can be managed directly in the preview sidebar.
Comments auto-save live to the GitHub backend in real time (or fall back to a companion <filename>.comments.yml file when offline).
If paragraphs are drastically edited, comments might become "orphaned". You can scan for them by running Markdown Comments: Scan for Orphaned Comments from the Command Palette.

Commands

The extension registers the following commands:

mdComments.openCommentPreview (Markdown Comments: Open Comment Preview): Opens the comments panel next to your active Markdown editor.
mdComments.scanOrphans (Markdown Comments: Scan for Orphaned Comments): Scans the active document for comments whose anchors no longer match the text and marks them as orphaned.
mdComments.refreshPreview: Refreshes the comment preview panel.

Settings

Customize the extension's behavior in your VS Code settings:

mdComments.sidebarWidth: Default width of the comments side panel in pixels (default: 340, min: 260, max: 600).
mdComments.reactionEmojis: List of emoji options for comment reactions (default: ["👍", "👀", "❤️", "🎉", "❓"]).