Sidemark – MRSF Review Comments for VS Code

Add, manage, and navigate Markdown Review Sidecar Format (MRSF) comments directly inside Visual Studio Code — without touching your Markdown source files.

Features

Preview Recovery Status (0.6.0 Development)

The recovery targets VS Code's Markdown Preview and Markdown Text Editor, not the hybrid Markdown Editor. Modern Preview tabs expose a document URI and can drive document-bound sidebar actions. Legacy markdown.showPreview* webviews do not expose their source URI; automatic sidebar switching between multiple legacy previews remains a release blocker. This development version does not claim full compatibility until that gap is resolved.

Development Verification

After installing and building the CLI dependency and installing the Monaco dependency, run these commands from vscode/:

npm ci
npm run lint
npm test
npm run test:host -- 1.137.0
npm run test:host -- stable
npm run package

Host tests use temporary documents and an isolated VS Code profile. They check preview-only activation, JSON hydration, external updates and both preview tab types. Playwright connects to a loopback-only debugging port to test native preview comment clicks, Enter-key activation and immediate Resolve/Unresolve hover updates without changing the cursor selection. Screenshots are saved under .vscode-test/screenshots/. Complete visual parity, all action transports, multi-document legacy tracking and rich-anchor parity remain unverified.

To run only the real-webview tooltip bounds checks (both gutters, narrow panes, long text), set MRSF_TEST_FOCUS=tooltip before npm run test:host. In PowerShell, use $env:MRSF_TEST_FOCUS = "tooltip"; remove it afterward with Remove-Item Env:MRSF_TEST_FOCUS to restore the full suite. This focused mode does not test native click transport, file watching, or comment persistence.

Gutter icons & inline highlights

Every commented line gets a color-coded gutter icon (open 💬, resolved ✅, orphaned ⚠️, multiple comments). Inline/column-span comments are highlighted directly in the editor text.

Rich hover cards

Hover over any commented line to see the full comment thread with author, timestamp, badges, and one-click action links:

• Resolve / Unresolve — toggle comment state without leaving the editor
• Reply — add a threaded reply
• Delete — remove the comment

Sidebar panel

A dedicated Sidemark activity-bar panel lists all comments for the active Markdown file:

• Sort by line number or date
• Toggle resolved comments visibility
• Navigate to any comment with a single click
• Reanchor all comments from the sidebar
• Add new comments directly

Automatic reanchoring on save

When you save a Markdown file, Sidemark silently reanchors all comments using the MRSF multi-step resolution algorithm (exact text → fuzzy match → line fallback). High-confidence results are applied automatically; uncertain results are flagged for manual review.

Interactive reanchor review

Run Sidemark: Reanchor Comments from the command palette for a guided review session. Each uncertain result is shown with old/new anchor decorations and accept/reject/skip controls.

Anchor drift detection

When you insert or delete lines, the status bar warns you that comment anchors may have drifted. Saving the file clears the warning after reanchor runs.

Staleness warnings

If any comments reference a different git commit than HEAD, the status bar shows an orange warning with the count of stale comments. Click it to reanchor.

Getting Started

1. Install the extension from the VS Code Marketplace (or install the .vsix manually).
2. Open a Markdown file that has a co-located .review.yaml sidecar — or create one:
   • Right-click a line → Sidemark: Add Line Comment
   • Select text → Sidemark: Add Comment on Selection
3. View comments in the Sidemark sidebar, or hover over commented lines.

Tip: The first time you add a comment, Sidemark will ask for your author name. It's saved globally so you only enter it once.

Commands

All commands are also available from the editor context menu (right-click) on Markdown files.

Default keyboard shortcuts

Sidemark includes default chord shortcuts for adding comments:

Press the first key combination, release it, then press the second.

Settings

All settings are under the Sidemark section in VS Code Settings.

How It Works

Sidemark stores review comments in sidecar files alongside your Markdown documents, following the MRSF v1.0 specification:

docs/
  architecture.md                    ← your document
  architecture.md.review.yaml       ← sidecar with comments

Comments are anchored to specific lines or text ranges using line, end_line, start_column, end_column, and selected_text. When the document is edited, the reanchor algorithm relocates comments using exact text matching, fuzzy matching, and positional fallback.

Sidecar format

mrsf_version: "1.0"
document: docs/architecture.md
comments:
  - id: 1d3c72b0
    author: Alice (alice)
    timestamp: "2026-03-02T18:22:59Z"
    text: "This section needs clarification."
    resolved: false
    line: 9
    selected_text: "The gateway component routes all inbound traffic."
    commit: 02eb613

See the specification for the full schema, including threading (reply_to), types, severity levels, and extension fields (x_*).

Alternate Sidecar Location

Place a .mrsf.yaml at your repository root to store sidecars in a central directory:

sidecar_root: .reviews

With this config, the sidecar for docs/architecture.md is resolved as .reviews/docs/architecture.md.review.yaml.

CLI Companion

The @mrsf/cli package provides command-line access to the same functionality — validate, add, resolve, reanchor, and list comments from the terminal or CI/CD pipelines:

npx @mrsf/cli validate --strict
npx @mrsf/cli reanchor --staged
npx @mrsf/cli list --open

Requirements

• VS Code 1.137 or later
• Git (optional — enables commit-based staleness detection and diff-based reanchoring)

Links

• sidemark.org — Official website and documentation
• MRSF v1.0 Specification — Full format specification
• @mrsf/cli on npm — CLI companion package
• GitHub Repository — Source code and issue tracker

License

MIT — Copyright (c) 2026 Wictor Wilén