Markdown Review Sidecar Format (MRSF) — Draft

Markdown Review Sidecar Format (MRSF), also known as Sidemark, is a portable, version-controlled, and machine-actionable way to store review comments outside Markdown files.

🌐 sidemark.org · 💻 VS Code Extension

This makes:

• Markdown docs clean and uncluttered
• Review history persist across edits
• Automated review tools and AI agents/skills able to reason about comments reliably

🧠 What Problem This Solves

Markdown workflows today struggle with durable, context-aware review comments:

• Inline comments can’t move with the text
• GitHub/GitLab reviews vanish with edits
• Automated agents (LLMs, bots) have no structured API for feedback

MRSF solves this with sidecar files that hold review metadata separate from content and a CLI/MCP interface for tooling.

🚀 Features

• Standardized sidecar format for Markdown reviews
• Anchors with line/span + fallback matching (selected_text)
• Re-anchoring after edits using configurable strategies
• JSON Schema for validation
• CLI tools for validation, re-anchoring, status checks
• MCP server for integrations with LLMs and assistant clients
• Python CLI & SDK (pip install mrsf) — 1:1 port of the Node.js CLI
• Rendering plugins for Marp, Marked, markdown-it, and rehype/unified ecosystems
• Interactive editor integrations for VS Code, Monaco, Milkdown/Crepe, and experimental Tiptap hosts

📄 Specification

The full specification is available in MRSF-v1.0.md.

🔧 Quick Start

Install

# Node.js
npm install -g @mrsf/cli

# Python
pip install mrsf

Typical workflow

# create a sidecar for a Markdown file
mrsf init docs/architecture.md

# add a comment anchored at line 12
mrsf add docs/architecture.md -l 12 "Add more detail about this architecture."

# check for issues
mrsf validate

# after the document changes
mrsf reanchor

# see comment health
mrsf status

You can also attach tool-specific extension fields when creating comments. The public SDKs and MCP server accept these as key/value maps, and they are stored on disk as flat x_* fields:

mrsf add docs/architecture.md \
  --author "review-bot" \
  --text "Needs a second pass" \
  --line 12 \
  --ext x_source=review-bot \
  --ext x_score=0.91 \
  --ext 'x_labels=["needs-review","docs"]'

See the full CLI documentation in cli/README.md, or run mrsf --help.

📦 Examples

Minimal sidecar (.review.yaml) next to the Markdown):

mrsf_version: "1.0"
document: docs/architecture.md
comments:
- id: abc123
  author: Jane Doe
  timestamp: '2026-03-02T18:22:59Z'
  text: "Can you clarify this section?"
  resolved: false
  line: 9

Advanced example with exact span:

- id: def456
  author: Jane Doe
  timestamp: '2026-03-02T18:24:51Z'
  text: "Is this phrasing accurate?"
  type: question
  resolved: false
  line: 12
  end_line: 12
  start_column: 42
  end_column: 73
  selected_text: "While many concepts are represented"

More examples: see the examples folder.

🛠 MCP Server

You can run MRSF as an MCP (Model Context Protocol) server for LLM/assistant integrations.

Install:

npm install -g @mrsf/mcp

Example (Claude Desktop config):

{
  "mcpServers": {
    "mrsf": {
      "command": "npx",
      "args": ["-y", "@mrsf/mcp"]
    }
  }
}

Servers expose resources like:

• mrsf://sidecar/{path}
• mrsf://comment/{path}/{id}
• mrsf://anchors/{path}

See the full MCP server documentation in mcp/README.md.

💻 VS Code Extension

Sidemark for VS Code brings MRSF review comments directly into your editor — gutter icons, inline previews, hover cards, a sidebar panel, and automatic reanchoring on save.

Install from the Visual Studio Marketplace or search for "Sidemark" in the VS Code Extensions view.

🧪 Monorepo Tests

All TypeScript/Vitest packages can now be run from the repository root:

npm install
npm test

For watch mode or coverage from the root:

npm run test:watch
npm run test:coverage

The root Vitest project aggregates:

• cli/
• mcp/
• plugins/shared/
• plugins/markdown-it/
• plugins/monaco/
• plugins/rehype/
• vscode/

🐍 Python CLI & SDK

A full Python port of the CLI and library, installable via pip:

pip install mrsf

Same 9 commands, same library API, same 134 tests:

import mrsf

doc = mrsf.parse_sidecar("README.md.review.yaml")
for comment in doc.comments:
    print(f"{comment.author}: {comment.text}")

result = mrsf.validate(doc)

Python uses the same explicit extension-map contract when adding comments:

opts = mrsf.AddCommentOptions(
  author="review-bot",
  text="Needs a second pass",
  line=12,
  extensions={
    "x_source": "review-bot",
    "x_score": 0.91,
    "x_labels": ["needs-review", "docs"],
  },
)

See python/README.md for the full SDK reference.

🎨 Rendering Plugins

Render MRSF review comments directly in Markdown output as badges, highlights, and tooltips.

markdown-it Plugin

For VitePress, markdown-it, and any markdown-it-based renderer:

npm install @mrsf/markdown-it-mrsf

import MarkdownIt from "markdown-it";
import { mrsfPlugin } from "@mrsf/markdown-it-mrsf";

const md = new MarkdownIt();
md.use(mrsfPlugin, { sidecarPath: "doc.md.review.yaml" });

See plugins/markdown-it/README.md.

Marp Plugin

For Marpit and Marp presentation pipelines:

npm install @mrsf/marp-mrsf

import { Marpit } from "@marp-team/marpit";
import { mrsfPlugin } from "@mrsf/marp-mrsf";

const marpit = new Marpit();
marpit.use(mrsfPlugin, { comments: sidecarData, interactive: true });

The plugin adds data-mrsf-page metadata to rendered page containers and also accepts vendor-only x_page comment hints when a presentation-level anchor is more useful than a line anchor.

See plugins/marp/README.md.

Marked Plugin

For Marked-based renderers in Node.js or the browser:

npm install marked @mrsf/marked-mrsf

import { Marked } from "marked";
import { markedMrsf } from "@mrsf/marked-mrsf";

const parser = new Marked();
parser.use(markedMrsf({ sidecarPath: "doc.md.review.yaml" }));

See plugins/marked/README.md.

rehype Plugin

For Astro, Next.js MDX, Docusaurus, and the unified ecosystem:

npm install @mrsf/rehype-mrsf

import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { rehypeMrsf } from "@mrsf/rehype-mrsf";
import rehypeStringify from "rehype-stringify";

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeMrsf, { sidecarPath: "doc.md.review.yaml" })
  .use(rehypeStringify)
  .process(markdown);

See plugins/rehype/README.md.

✍️ Interactive Editor Integrations

MRSF also ships editor-native integrations when you want the review workflow inside a live editing surface instead of rendered HTML.

Monaco Plugin

For Monaco-based editors in browser and desktop apps:

npm install @mrsf/monaco-mrsf monaco-editor

See plugins/monaco/README.md.

Tiptap Plugin (Experimental)

For browser-hosted Tiptap editors with inline highlights, gutters, and an explicit-save review workflow:

npm install @mrsf/tiptap-mrsf @tiptap/core @tiptap/starter-kit

See plugins/tiptap/README.md.

Milkdown + Crepe Plugin

The @mrsf/milkdown-mrsf package runs the same MRSF review controller in both direct Milkdown editors and the higher-level Crepe shell. It covers sidecar load/save/reload/reanchor flows, inline anchors, gutter overlays, thread tooltips, and selection-based comment actions through a browser host adapter.

Try the demo:

cd examples
npm install
npm run demo:milkdown

Then open the printed local Vite URL and navigate to / to switch between direct Milkdown and Crepe while they share the same review runtime.

See plugins/milkdown/README.md.

Stability & Versioning

The MRSF specification is currently v1.0 Draft. Published packages follow Semantic Versioning; while packages remain pre-1.0, minor releases may include breaking changes and consumers should read package changelogs before upgrading.

Package changelogs:

• @mrsf/cli
• @mrsf/mcp
• @mrsf/markdown-it-mrsf
• @mrsf/rehype-mrsf

Tools target mrsf_version "1.0". Consumers SHOULD tolerate unknown future minor versions and unknown x_-prefixed extension fields by preserving them when reading and writing sidecars. Consumers SHOULD warn, rather than silently proceed, when they encounter an unknown major version.

🧪 Status

Draft: this specification and tooling are open for feedback and improvement.

File issues or pull requests with suggestions.

❤️ Contributing

We welcome:

• review of the spec
• implementation feedback on the CLI/MCP/Python SDK
• integration examples with editors, renderers, and bots

See CONTRIBUTING.md

Disclaimer MRSF is a personal open‑source project. It is not affiliated with, endorsed by, or an official standard of Microsoft. Any internal experimentation does not imply product adoption.

📄 License

MIT