SidemarkMarkdown Review Sidecar Format (MRSF)

Add portable Markdown comments and review threads without embedding comments in Markdown files.

Get Started

Read the Spec

View on GitHub

💡

"Pull Requests review changes. Sidemark reviews documents over time."

PR Reviews Aren’t Built for Living Documents

📝

Keeps Markdown Clean

Review comments live in sidecar files, not inline annotations. Your documents stay readable and diff-friendly.

🔗

Durable Anchoring

Comments anchor to lines, columns, and selected text. When the document changes, re-anchoring finds their new positions automatically.

🤖

AI & Agent Ready

Structured YAML format with MCP server support. AI assistants can read, create, and manage reviews through standard protocols.

@mrsf/mcp on npm

✅

Validation & Schema

JSON Schema and CLI validation ensure sidecars are well-formed. Integrates into CI/CD pipelines.

🔄

Git-Aware

Tracks commits, detects staleness, and uses git diffs for intelligent re-anchoring after edits.

📦

Simple Tooling

npm install -g @mrsf/cli — validate, add, resolve, reanchor, and more from the terminal.

@mrsf/cli on npm

🐍

Python CLI & SDK

pip install mrsf — validate, add, resolve, reanchor, and more from the terminal.

mrsf on PyPI

💻

VS Code Extension

Sidemark for VS Code — gutter icons, inline previews, hover cards, sidebar panel, and automatic reanchoring built right into your editor.

VS Code Marketplace

🧩

Monaco Plugin

Embed Sidemark directly into Monaco-based editors with @mrsf/monaco-mrsf — gutter annotations, inline highlights, hover summaries, and host-driven comment workflows.

@mrsf/monaco-mrsf on npm

🥛

Milkdown + Crepe Plugin

Run the same Sidemark review runtime in direct Milkdown editors and Crepe shells, with shared sidecar workflows, inline anchors, gutters, tooltips, and host-controlled save and reanchor flows.

Milkdown + Crepe guide

✍️

Tiptap Plugin (Experimental)

Bring Sidemark into Tiptap-based rich-text editors with @mrsf/tiptap-mrsf. Experimental package; help needed to harden anchor behavior, gutter parity, and editor workflows.

@mrsf/tiptap-mrsf on npm

🎨

markdown-it Plugin

Render review comments as badges, line highlights, and tooltips with @mrsf/markdown-it-mrsf — works with VitePress and any markdown-it project.

@mrsf/markdown-it-mrsf on npm

🏷️

Marked Plugin

Use @mrsf/marked-mrsf to render review comments in Marked pipelines and browser-based Markdown renderers with the same shared controller and CSS.

@mrsf/marked-mrsf on npm

🔌

rehype Plugin

Use @mrsf/rehype-mrsf to render comments in the unified ecosystem — Astro, Next.js MDX, Docusaurus, and more.

@mrsf/rehype-mrsf on npm

🎤

Marp Plugin

Render review comments in Marpit and Marp slide decks with @mrsf/marp-mrsf, including page-level vendor hints for presentation workflows.

Marp plugin guide

Markdown Comments Without Polluting Markdown

If you're searching for markdown comments, comments in Markdown, or a way to leave review feedback on Markdown documents without stuffing HTML comments into the file, Sidemark is built for that exact workflow.

Sidemark, also known as MRSF (Markdown Review Sidecar Format), stores comments in a sidecar file next to the Markdown document. That gives you durable anchors, threaded review comments, Git-friendly history, and tooling for CLIs, editors, AI agents, and rendering pipelines.

Interactive Editor Integrations

If you want comments inside a live editor instead of rendered HTML, Sidemark also includes interactive editor packages:

VS Code extension for a turnkey desktop workflow
Monaco plugin for custom Monaco-based apps
Milkdown + Crepe guide for direct Milkdown editors and Crepe hosts sharing the same runtime
Tiptap plugin for experimental rich-text editor workflows

Plugins for Rendering and Editing

Sidemark now has a dedicated plugin section for both rendering pipelines and editor integrations:

How Sidemark Handles Comments In Markdown Workflows

Traditional comments in Markdown are fragile because Markdown has no standard native comment system. Sidemark solves that by keeping review comments outside the Markdown content itself while still anchoring them to exact lines, ranges, and selected text inside the document.