A VS Code extension that lets you add review comments directly on markdown files — just like code review on GitHub, but for any .md file, right inside VS Code (desktop & web).
Perfect for reviewing AI-generated documentation, collaborating on specs, and giving feedback on markdown content.
Features
Click on any line in a markdown file to add a review comment. Start discussions with replies.
✅ Resolve / Reopen Threads
Mark threads as resolved when feedback is addressed. Reopen if needed.
📊 Review Summary Panel
See all comments at a glance in a beautiful side panel — open threads, resolved threads, and stats.
Export all review comments as a formatted markdown document for sharing.
🎨 Visual Indicators
- Highlighted lines with open comments
- Overview ruler markers
- Status bar showing comment counts
🌐 Web Compatible
Works in VS Code for the Web (vscode.dev), GitHub Codespaces, and desktop VS Code.
How It Works
- Open any
.md file in VS Code
- Hover over a line — you'll see a
+ icon in the gutter to add a comment
- Type your comment and submit
- Reply to existing threads to discuss
- Resolve threads when the feedback is addressed
- The file owner edits the
.md file based on the comments
- Use "Show Review Summary" (toolbar button) to see all comments at a glance
Comments are stored in a sidecar JSON file next to the markdown file:
docs/
architecture.md ← the document
architecture.md.reviews.json ← review comments (auto-created)
Alternatively, configure storage in a .md-reviews/ folder at the workspace root.
Tip: Commit the .reviews.json files to your repo so collaborators can see the review comments!
Commands
| Command |
Description |
MD Review: Add Review Comment |
Add a comment to the selected line |
MD Review: Show Review Summary |
Open the review summary panel |
MD Review: Set Reviewer Name |
Set your display name for comments |
MD Review: Export Comments as Markdown |
Export all comments to a new markdown file |
MD Review: Resolve |
Mark a comment thread as resolved |
MD Review: Reopen |
Reopen a resolved thread |
MD Review: Delete Thread |
Delete an entire comment thread |
MD Review: Edit Comment |
Edit your comment |
MD Review: Delete Comment |
Delete a single comment |
Settings
| Setting |
Default |
Description |
md-review.reviewerName |
"" |
Your name for review comments (prompted on first use) |
md-review.commentFileLocation |
"sidecar" |
"sidecar" stores next to the .md file, "folder" stores in .md-reviews/ |
md-review.showResolvedComments |
true |
Whether to display resolved comments in the editor |
Getting Started
Install from Source
# Clone the repo
git clone <repo-url>
cd md-review
# Install dependencies
npm install
# Compile
npm run compile
# Press F5 in VS Code to launch the Extension Development Host
Build for Web
npm run compile-web
Package as VSIX
npx @vscode/vsce package
Review Workflow
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Reviewer │ │ .md file │ │ File Owner │
│ opens file │────▶│ + comments │────▶│ reads comments │
│ adds review │ │ .reviews.json│ │ updates .md │
│ comments │ │ │ │ resolves threads│
└─────────────┘ └──────────────┘ └─────────────────┘
- Reviewer opens the
.md file, adds line-level comments
- Comments are saved in the sidecar
.reviews.json file
- File Owner opens the same file, sees all comments inline
- Owner edits the
.md file to address feedback
- Owner resolves threads as they're addressed
- Both can use the Review Summary panel for an overview
Architecture
src/
extension.ts ← Entry point, registers commands
commentStore.ts ← Persistence layer (reads/writes .reviews.json)
commentController.ts ← VS Code CommentController API bridge
reviewSummary.ts ← Webview panel showing review summary
decorations.ts ← Line highlights & status bar
types.ts ← TypeScript interfaces
The extension uses VS Code's native Comment API (vscode.CommentController), the same API used by the GitHub Pull Request extension. This ensures a familiar, native-feeling experience.
License
MIT
