Review Markdown like a doc — keep the feedback in git.
Comment on rendered Markdown (and any file) with inline bubbles and replies.
Every comment is saved to a plain-text .mb sidecar that lives next to the
file and diffs cleanly in your pull requests.
Why Markback
You're reviewing a README, an RFC, a design doc, or a spec. Your options today:
- PR review comments — disappear when the branch merges.
- A Google Doc — not in your repo, not in git, not diffable.
- A scratch note — lost by next week.
Markback keeps the feedback next to the work, in plain text, in git:
- 💬 Comment on the rendered Markdown preview — select text, click the bubble, type. No need to hunt for the right line in raw source.
- 🧵 Threads and replies — click a 💬 badge to open the thread inline and reply.
- 📄 Saved to a
.mbsidecar —essay.md→essay.md.mb, right beside the file. Commit it; it diffs cleanly in PRs and survives merge. - ✍️ Works in any file too — highlight text in the editor, right-click →
Markback: Comment on Selection (or
Cmd/Ctrl+Shift+M). - 🔌 Portable format — the same
.mbfiles work with the Markback CLI, Python, Node, and a browser editor. No server, no account, no lock-in.
Quick start
- Install Markback from the Marketplace.
- Open a Markdown file and open its preview (
Cmd/Ctrl+Shift+V). - Select some text in the preview → click 💬 Comment → type your feedback.
- A sidecar
<filename>.mbappears next to the file. Commit it — the feedback now diffs in your PRs. - Reopen the file later: the 💬 badges are still there. Click one to read the
thread, reply, or Resolve it (resolved threads are marked, and can be
Reopened). Each comment's created/resolved/reopened actions are timestamped
in the
.mb.
Prefer the editor? Select text in any file → right-click → Comment on Selection
(or Cmd/Ctrl+Shift+M).
What a .mb file looks like
The sidecar is plain, human-readable text — hand-editable and lintable:
%markback 2
@id a1b2-c3d4
@by [email protected]
@file ./essay.md:3:5-3:18 <<< awkward phrasing
When the commented selection is small enough to be manageable, the quoted source
text is embedded inline under @file so the comment is self-contained:
@id e5f6-a7b8
@by [email protected]
@file ./essay.md:3:5-3:18
the quick brown fox
<<< awkward phrasing
That's the whole format: <<< introduces a comment. Records
lint with mb --lint and round-trip with the
browser editor.
Settings
| Setting | Description |
|---|---|
markback.author |
Identifier written as @by on every comment. If empty, falls back to git config user.email, then to no @by header. |
markback.inlineExcerpt.enabled |
Embed the literal selected source text inline in the .mb record when the selection is small enough. Default true; set false for compact, range-only records. |
markback.inlineExcerpt.maxLines |
Max lines a selection may span to be embedded inline (default 10). |
markback.inlineExcerpt.maxChars |
Max characters a selection may contain to be embedded inline (default 600). |
Selections larger than the thresholds — or whose text would break .mb
round-trip (e.g. a line that is exactly ---, or one starting with <<<) — are
recorded range-only. The Markback output channel logs the reason an excerpt was
omitted.
Restricted Mode: preview commenting uses VS Code command links, which are disabled in untrusted workspaces. Trust the workspace to enable it — the preview shows a banner when it's blocked.
Current limitations
Honest about where it's at today:
- No gutter
+icon yet — use the preview bubble, the right-click menu, or the keybinding. - No visual stale-range indicator — if a source file is edited past a recorded range, the comment still renders at its recorded position; a warning logs to the Markback output channel (View → Output → Markback).
Feedback & contributing
Markback is open source (MIT). Issues, ideas, and PRs are welcome:
- 🐛 Bugs / ideas: github.com/dandriscoll/markback/issues
- 📖 Format & docs: markback.org
- 🧪 Try the format in your browser: markback.org/try-it
If Markback saves you a round-trip, telling a teammate is the best thanks.