Sidemark

A .NET library for the Markdown Review Sidecar Format (MRSF) v1.0 — portable, version-controlled review comments for Markdown documents.

Overview

Sidemark implements the MRSF v1.0 specification, providing a complete .NET library for parsing, validating, and serializing review sidecar files (.review.yaml / .review.json).

MRSF stores review comments in sidecar files next to Markdown documents, keeping the source clean while enabling durable anchoring, threaded review comments, and Git-friendly history.

Features

  • Model — Strongly-typed MrsfDocument and MrsfComment classes covering all required and optional fields
  • Parser — Read .review.yaml and .review.json sidecar files with auto-format detection
  • Serializer — Write to YAML or JSON, omitting null optional fields
  • Validator — Full MRSF v1.0 conformance checking with error/warning diagnostics
  • Discovery — Sidecar file location via co-location or .mrsf.yaml sidecar_root configuration

Installation

dotnet add package Sidemark

Quick Start

Parse a sidecar file

using Sidemark;

// Auto-detects YAML vs JSON by file extension
var doc = MrsfParser.ParseFile("docs/architecture.md.review.yaml");

foreach (var comment in doc.Comments.Where(c => !c.Resolved))
    Console.WriteLine($"[{comment.Author}] {comment.Text}");

Validate a document

var result = MrsfValidator.Validate(doc);

if (!result.IsValid)
    foreach (var error in result.Errors)
        Console.WriteLine($"ERROR: {error.Message}");

foreach (var warning in result.Warnings)
    Console.WriteLine($"WARN: {warning.Message}");

Discover sidecar files

// Find the sidecar for a Markdown file (checks .mrsf.yaml config first)
var sidecarPath = MrsfDiscovery.DiscoverSidecar(
    "docs/architecture.md", workspaceRoot: ".");

// Find all sidecars in a directory tree
var allSidecars = MrsfDiscovery.DiscoverAll("docs/", workspaceRoot: ".");

Create and write a sidecar

var doc = new MrsfDocument
{
    MrsfVersion = "1.0",
    Document = "docs/readme.md",
    Comments = new()
    {
        new MrsfComment
        {
            Id = Guid.NewGuid().ToString("N")[..8],
            Author = "Jane Doe (janedoe)",
            Timestamp = DateTimeOffset.UtcNow.ToString("o"),
            Text = "This section needs more detail.",
            Resolved = false,
            Line = 12,
            SelectedText = "The gateway component"
        }
    }
};

// Write as YAML (recommended) or JSON
MrsfSerializer.WriteFile(doc, "docs/readme.md.review.yaml");

Specification Compliance

This library implements the following sections of the MRSF v1.0 specification:

Section Topic Status
§3 File Naming and Discovery ✅ Full
§4 Top-Level Structure ✅ Full
§5 Versioning ✅ Full
§6 Comment Fields (Required + Optional) ✅ Full
§7 Targeting and Anchoring ✅ Model + Validation
§9 Lifecycle ✅ Full
§10 Conformance and Error Handling ✅ Full
Edit this page