md-reviewer

Inline comments for markdown files. Select text, add comments, share via git. No database, no cloud — comments live in your files.

What it does

md-reviewer is a local tool for reviewing and annotating markdown documents. It gives you a WYSIWYG editor with the ability to select any text and attach a comment to it. Comments are stored directly inside the markdown file as a JSON block in an HTML comment — invisible to every markdown renderer, visible in source, and fully git-friendly.

When you push your files, the comments travel with them. When a collaborator pulls, they see your comments. When they add their own, each comment is stamped with the local machine username so you know who said what. No accounts, no sync service, no lock-in.

Install

npm install -g md-reviewer

Or run directly with npx:

npx md-reviewer

Usage

# Review markdown files in current directory
md-reviewer

# Review a specific directory
md-reviewer ./docs

# Custom port
md-reviewer ./book --port 4000

# Don't auto-open browser
md-reviewer --no-open

This starts a local server and opens your browser. Select any markdown file from the sidebar, then:

• Add a comment — Select text in the editor, click "+ Comment", type your note
• View comments — Highlighted text has comments; click to see them in the panel
• Resolve comments — Click "Resolve" to remove a comment
• Edit content — The editor is always live; changes auto-save after 1.5 seconds

How comments are stored

Comments are appended to the end of each markdown file as a JSON array inside an HTML comment block:

Your regular markdown content here...

<!--review_comments:
[
  {
    "anchorText": "the text that was selected",
    "comment": "This needs to be clearer",
    "author": "darryl",
    "created": "2026-02-18T05:34:50.272Z",
    "id": "mlrll9r480z5"
  }
]
-->

This format is:

• Invisible — HTML comments are ignored by every markdown renderer (GitHub, VS Code preview, static site generators)
• Portable — Comments travel with the file. Copy it, email it, push it to git
• Git-friendly — Standard text that diffs, merges, and blame-tracks normally
• Human-readable — Open the file in any editor and you can read the comments directly
• Zero-dependency — No database, no cloud service, no accounts

Features

• WYSIWYG markdown editing (Quill.js)
• Text-anchored inline comments
• Comment grouping (multiple comments on the same text appear as threads)
• Author attribution via local machine username
• Real-time orphan detection (comment turns red if you edit the anchored text)
• Dark mode
• Folder-grouped file list with persistent collapse state
• Auto-save with manual Cmd/Ctrl+S override
• Click comment to scroll to highlighted text

Collaboration workflow

You:          md-reviewer ./manuscript
              [add comments, edit text]
              git add -A && git commit -m "review ch01" && git push

Collaborator: git pull
              md-reviewer ./manuscript
              [see your comments, add their own]
              git add -A && git commit -m "respond to review" && git push

You:          git pull
              md-reviewer ./manuscript
              [see their responses, resolve comments]

Each person's comments are stamped with their machine username. No merge conflicts unless two people comment on the exact same file simultaneously (and even then, git's text merge usually handles it).

Requirements

• Node.js 16+
• A browser

License

MIT