Markdown Review Viewer

A self-contained, single-file Markdown review app. Open markdown-reviewer.html in a browser, load a Markdown document, select rendered text, add inline review comments, manage threads, and explicitly export/import review state.

The app is implemented as plain HTML, CSS, and JavaScript in one file. It has no backend, no build step for the app artifact, no CDN/runtime dependencies, and no automatic browser persistence.

Highlights

• Runs as one standalone HTML file: no server, build step, CDN, or runtime dependency.
• Loads local .md / .markdown files with the browser File API.
• Imports and exports portable review payloads.
• Supports full self-contained exports and comments-only exports bound to a Markdown file hash.
• Supports optional browser-native gzip-compressed exports using the mr1.gz. payload format when Compression Streams are available.
• Imports legacy/uncompressed base64 JSON payloads and compressed mr1.gz. payloads.
• Supports deployed-page share URLs via a payload query parameter on http: / https: pages.
• Renders Markdown safely with a controlled vanilla JavaScript renderer.
• Supports text selection, source-offset-backed highlights, active comment navigation, and comment cards.
• Supports multiple and overlapping comments.
• Supports comment deletion, replies, and open/resolved thread status.
• Provides light and dark themes; default follows prefers-color-scheme.
• Stores nothing automatically: no local storage, session storage, IndexedDB, cookies, service workers, or backend persistence.

Quick Start

Open the app directly from disk:

xdg-open markdown-reviewer.html

Or double-click markdown-reviewer.html in a file manager.

On the start screen:

1. Enter your display name.
2. Choose one load path:
   • Markdown file to start a new review.
   • Markdown file + Include comments to import a comments-only payload for the selected file.
   • Full payload to import a self-contained exported review payload.
3. Click the load/start button.
4. Select text in the rendered document and add comments.
5. Use Export to copy a payload before closing or refreshing the page.

Export is the only persistence mechanism. Unsaved work is lost on refresh or tab close.

Reviewing Documents

After loading a document, the workspace provides:

• Rendered Markdown document view.
• Desktop comment rail and mobile comments drawer.
• Linked highlights and comment cards.
• Active-state navigation between highlights and comments.
• Theme toggle for the current in-memory session.
• Export panel for copying review payloads.

Comment threads support:

• Creating comments from selected rendered text.
• Multiple comments on the same or overlapping text ranges.
• Deleting threads after confirmation.
• Adding replies to open threads.
• Resolving and reopening threads.
• Collapsed resolved threads with resolver metadata.
• Hidden resolved highlights by default, with temporary reveal when a resolved thread is activated.

Export And Import Modes

Full Export

Full export is the default. It includes the Markdown and all review comments, replies, and resolution metadata:

{
  "version": 1,
  "mode": "full",
  "markdown": "# Example\n\nThis is a document.",
  "comments": []
}

Use this when you want a self-contained review payload that can be imported without also selecting the original Markdown file.

Comments-Only Export

The export panel includes a Comments only checkbox. When enabled, the payload excludes Markdown and includes a SHA-256 hash of the reviewed Markdown contents:

{
  "version": 1,
  "mode": "comments-only",
  "markdownHash": {
    "algorithm": "SHA-256",
    "value": "base64-encoded-sha256-digest"
  },
  "comments": []
}

To import comments-only payloads, choose Markdown file, select the matching Markdown file, enable Include comments, and paste the comments-only payload. The app computes the selected file hash and blocks import if it does not match.

Minified And Compressed Payloads

Generated JSON exports are minified before encoding. No pretty-printing or indentation is added to generated payload JSON.

When the browser supports Compression Streams, the export panel also offers Compressed payload. Compressed exports:

• Use browser-native gzip over minified JSON bytes.
• Are emitted as copyable plaintext with the prefix mr1.gz..
• Use base64url for the compressed bytes.
• Work for both full and comments-only export modes.

Uncompressed base64 JSON payloads remain fully supported for backward compatibility.

Shareable URLs

When markdown-reviewer.html is served from http: or https:, the export panel generates a share URL containing the current export payload in a payload query parameter. Local file: sessions do not offer URL sharing and should use the raw payload copy/paste workflow.

Opening a deployed URL with ?payload=... preselects the full-payload import tab and pre-fills the payload field. The user still must enter a display name and explicitly load the review.

Review Payload Data

A comment object contains source offsets and display metadata:

{
  "id": "comment_1710000000000_ab12cd",
  "start": 12,
  "end": 31,
  "highlightedText": "This is a document",
  "timestamp": "2026-06-04T12:34:56.000Z",
  "author": "Alice",
  "body": "This section needs clarification.",
  "replies": [
    {
      "id": "reply_1710000000000_ab12cd",
      "timestamp": "2026-06-04T12:40:00.000Z",
      "author": "Bob",
      "body": "I agree."
    }
  ],
  "status": "open",
  "resolvedAt": null,
  "resolvedBy": null
}

The payload intentionally excludes UI-only state such as the current theme, active comment, selection draft, source selection draft, drawer state, or export modal state.

Supported Markdown

The built-in renderer is intentionally pragmatic rather than full CommonMark. It supports:

• Headings # through ######
• Paragraphs
• Bold, italic, and inline code
• Triple-backtick code blocks
• Blockquotes
• Ordered and unordered lists
• Links with safe protocols only: http:, https:, mailto:
• Horizontal rules
• Tables

Raw HTML is rendered inertly as text, and unsafe link protocols are not emitted as clickable links.

Development

Development dependencies are managed with Node, Playwright, and mise. The final app itself remains dependency-free.

Install dependencies if needed:

npm install

Run the end-to-end suite:

mise run test:e2e

Run broader verification:

mise run verify

Alternative npm scripts:

npm run test:e2e
npm run verify

Run headed Playwright tests:

mise run test:e2e:headed

Repository Layout

markdown-reviewer.html       # final standalone application artifact
spec.md                      # technical specification
plan.md                      # implementation plan and phase checklist
designs/                     # visual design references
tests/                       # Playwright end-to-end tests
playwright.config.js         # Playwright configuration
mise.toml                    # repeatable development tasks
package.json                 # development-only test dependencies

Verification Scope

The Playwright suite covers onboarding validation, Markdown rendering and escaping, theme behavior, responsive layout, selection/comment creation, comment navigation, deletion, replies, resolution, import/export, comments-only hash validation, minified payloads, compressed payloads, share URLs, stale-range warnings, mobile behavior, accessibility/focus handling, and absence of automatic browser storage writes.

Current implementation status in plan.md: phases 1 through 15 are marked Done.

Security And Privacy Notes

• Markdown and imported payloads are treated as untrusted input.
• The app does not evaluate imported data as code.
• User content is escaped before controlled Markdown transforms are applied.
• Links are limited to safe protocols: http:, https:, and mailto:.
• No data is sent over the network by local file: sessions.
• Deployed share URLs contain the selected export payload and may expose review data through browser history, server logs, proxies, or link sharing.
• No browser persistence APIs are used for automatic saving.