mdopen

Render a Markdown file to a self-contained, styled HTML page, open it in the browser, and annotate it — then copy the annotations back out as markdown you can paste straight into a coding agent.

Built for the loop where an agent writes a doc, you read it, and you need to tell it what's wrong — without tedious back-and-forth in a terminal.

md architecture.md

• One self-contained HTML file. No server, no build step, no browser extension. CSS, JS, and images are all inlined into the page.
• Works in any browser — including the ones embedded in terminals like cmux, or an IDE preview pane. It's just an HTML file; if something can render HTML, it works.
• Output built for agents. Notes are quote-anchored, never line-numbered, so the agent can still find every one after it rewrites the doc.
• Agent-agnostic. The feedback is plain markdown on your clipboard — paste it into Claude Code, Codex, or whatever you drive your codebase with.

• Select any text → a Comment pill appears, or press ⌘K.
• ⌘K with nothing selected leaves a general note on the whole doc.
• ⌘↵ saves, Esc cancels.
• Notes collect in a side panel, sorted into document order. Hover a card to edit (✎) or delete (×) it.
• Copy for Claude puts the whole set on your clipboard:

Feedback on docs/architecture.md (2 notes)

1. § Database schema
   > "a single users table with a tenant_id column"
   Won't work — tenants need physical isolation for the SOC2 story.

2. General
   Too much detail on schema, not enough on failure modes.

Each note carries its section heading and the quoted passage, so the agent can find every one even after it rewrites the doc. Notes on table cells also name the cell, since a bare "42%" could be anywhere:

   > "42%" — in table row "Enterprise", column "Renewal rate"

The header names the file by its path relative to where you ran md, so the agent knows exactly which file to act on.

Notes are saved to localStorage, keyed by a hash of the markdown source rather than the file path. So:

• Reload, tab discard, or browser restart → notes come back.
• Re-running md on an unchanged file → notes come back (the temp path is irrelevant).
• The doc gets edited → notes do not come back, because they're stale.

Keying on content is what keeps this simple: restore only ever runs against a byte-identical document, so there's no fuzzy re-anchoring and no orphaned-note UI. Anchors are character offsets into the document text, which stay valid regardless of how many highlights are already applied.

Entries older than 30 days are pruned automatically.

Follows prefers-color-scheme.

Local images referenced by the markdown are inlined into the HTML as data: URIs, so the page stays self-contained even though it lives in a temp dir. Remote (http(s)) images are left as-is. Missing files get a warning on stderr and keep their original path.

md page.html opens the page as-is with the annotation layer injected — same notes, same panel, same copy format. Useful when an agent hands you an HTML artifact instead of markdown.

• The page's own styling is untouched, and the annotation UI carries its own palette (following prefers-color-scheme independently of the page's theme).
• Relative images and stylesheets keep working: a <base> pointing at the original directory is injected, and in-page #links are patched to compensate.
• With --no-annotate there is nothing to inject, so the original file is opened directly.

md <file.md|file.html> [--no-open] [--no-annotate] [--out <path>]

• --no-open — print the generated path instead of opening a browser
• --no-annotate — plain rendered HTML, no annotation layer
• --out <path> — write to a specific path instead of a temp dir

annotate.mjs writes its client code as a real function and stringifies it on export, which keeps it readable and free of template-literal escaping.

npm install -g @dahbiahmed/mdopen

You get two commands, md and mdopen, both doing the same thing. (The name must be scoped — there is no unscoped mdopen on npm.)

oh-my-zsh users: it aliases md to mkdir -p, and the alias wins over the command. Use mdopen, or put unalias md in your ~/.zshrc.

Or run straight from a checkout — edits are live, no install step:

git clone https://github.com/dahbiahmed/mdopen && cd mdopen
npm install   # or: bun install
ln -s "$PWD/render.mjs" ~/.local/bin/md

The rendered page executes any raw HTML the markdown contains — that's how markdown works. Fine for docs you or your agent wrote; think twice before running md on markdown from someone you don't trust.

MIT