Markdown Commenter

Markdown annotation for VS Code and Copilot CLI.

Features

• AI-Powered Review: Copilot identifies reviewable items in your markdown documents
• Interactive Workflow: Walk through each item, make decisions with Accept/Reject/Skip/Question verdicts
• Structured Annotations: Verdicts recorded as GitHub-style > [!COMMENT] callout blocks
• Dual Distribution: Works in VS Code (extension) and terminal (Copilot CLI)
• Resume Support: Pick up where you left off — already-annotated items are skipped

VS Code UI Components

The extension provides rich UI for manual annotation without AI:

• Quick-pick Command (Ctrl+Shift+A / Cmd+Shift+A) — Select text, choose status, add optional comment
• Hover UI — Select text and hover to see clickable status buttons (✓ Accept, ✗ Reject, etc.)
• CodeLens — Status indicators appear above each annotation block; click to navigate
• Sidebar Panel — Lists all annotations in the current file; click to jump to location
• Status Bar — Shows annotation count; click to reveal sidebar panel
• Context Menu — Right-click selected text → "Add Annotation"

Installation

VS Code Extension

Install from the VS Code Marketplace:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "Markdown Commenter"
4. Click Install

Or install via command line:

code --install-extension erdem-tuna.markdown-commenter

Copilot CLI

For terminal users with GitHub Copilot CLI:

npx @erdemtuna/markdown-commenter install copilot

This installs the annotation agent and skill to ~/.copilot/.

Quick Start

VS Code

1. Open a markdown file containing findings or recommendations
2. Open Copilot Chat (Ctrl+Shift+I or click the Copilot icon)
3. Say: "Annotate this document" or "@annotate help"
4. Follow the interactive workflow to review each item

Copilot CLI

1. In your terminal, start the annotation:

   @annotate path/to/document.md
   

2. Review each item as presented
3. Enter your verdict: Accept, Reject, Skip, or Question

Annotation Format

Annotations are written as GitHub-style callout blocks:

> [!COMMENT]
> **ID**: abc12345
> **Status**: Accept
> **Re**: "key finding text..." (optional)
>
> Your comment explaining the verdict.

Verdict Types

Configuration

VS Code Settings

Platform defaults:

• Linux: ~/.config/Code/User/prompts/
• macOS: ~/Library/Application Support/Code/User/prompts/
• Windows: %APPDATA%/Code/User/prompts/

Use Cases

• Document Reviews: Annotate audit reports, technical assessments, compliance documents
• Feedback Sessions: Review proposals, specs, or design documents with structured comments
• Meeting Notes: Process action items and decisions with clear verdicts
• Research Papers: Annotate findings and recommendations for later reference

Troubleshooting

Agent not appearing in Copilot Chat

1. Reload VS Code window (Ctrl+Shift+P → "Reload Window")
2. Check output channel: View → Output → "Markdown Commenter"
3. Verify agent is installed: Check ~/.config/Code/User/prompts/ (Linux)

CLI installation issues

1. Verify Node.js 18+: node --version
2. Check installation: npx @erdemtuna/markdown-commenter list
3. Reinstall: npx @erdemtuna/markdown-commenter uninstall && npx @erdemtuna/markdown-commenter install copilot

Development

Build from source

git clone https://github.com/erdem-tuna/markdown-commenter
cd markdown-commenter
npm install
npm run compile

Run tests

npm test                   # Extension tests
cd cli && npm test         # CLI tests

Lint agent files

npm run lint:agent:all     # Lint agents and skills for token limits

Package extension

npm run package

Release process

Releases are automated via GitHub Actions:

• Extension: Push a v* tag (e.g., git tag v1.0.0 && git push origin v1.0.0)
• CLI: Push a cli-v* tag (e.g., git tag cli-v1.0.0 && git push origin cli-v1.0.0)

See CONTRIBUTING.md for maintainer setup (secrets, first-time publish, etc.).

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

See the Code of Conduct for community guidelines.

License

MIT

Related

• GitHub Copilot
• VS Code Language Model API