mdv — preview Markdown files from your terminal

mdv renders a Markdown file the way it should look — headings, tables, code, Mermaid diagrams — and opens it in your browser. One command, no account, no configuration.

uv tool install mdview-cli    # or: pipx install mdview-cli, pip install mdview-cli
mdv notes.md

Homebrew users:

brew install gogainda/tap/mdview-cli

That's the whole workflow: mdv FILE.md publishes the file to mdview.io, opens the rendered page, and prints a link you can send to anyone. Anonymous previews last 30 days and take files up to 2 MB.

Two ways to preview

Shareable preview (default). mdv FILE.md is shorthand for mdv preview FILE.md. The title comes from the first # heading, or pass your own:

mdv notes.md
mdv preview notes.md --title "Design notes"
mdv preview notes.md --json     # print the share URLs as JSON, don't open a browser

Local-only preview. mdv open uploads nothing: it packs the file into the URL itself and rendering happens entirely in your browser. Use it for drafts that shouldn't leave your machine.

mdv open notes.md

Common use cases

mdv notes.md                       # preview and share a one-off Markdown file
mdv open notes.md                  # preview locally without uploading
mdv verify notes.md                 # check rendering, then delete the remote copy
mdv fix notes.md --local           # repair broken Mermaid in the local file
mdv sync notes.md                  # update a private document and auto-repair it
mdv share notes.md                 # publish the synced document at a stable URL
mdv pdf notes.md                   # create notes.pdf

For a quick renderability check, mdv verify FILE exits 0 when the document renders cleanly and 1 when it does not. It never modifies the local file. It requires a token, uploads the current contents to a temporary private document, and deletes that document after the check.

Iterating on one document

Previews are throwaway: every run mints a new link. When you keep working on the same file — a spec, an architecture doc, a report — you want the opposite: one stable URL whose content follows your edits, and a check that every revision still renders cleanly.

Set up a free mdview.io CLI token once, then it's one command per iteration:

mdv keys set          # once (or set MDVIEW_TOKEN in CI)
mdv sync spec.md      # publish this revision, verify it, auto-repair broken diagrams

While you iterate, the document lives at its private /p/ page — only you, signed in, can see it, and the URL stays the same forever. Every sync shows the fixed, renderable version there. Broken Mermaid diagrams are repaired automatically and the fix is written back into your file (the original is kept as a timestamped backup); only documents that can't be repaired exit 1.

When — and only when — you decide to publish, make it public; and grab a PDF at any point:

mdv share spec.md               # mint the public /s/ link (from then on it follows your syncs)
mdv share spec.md --slug my-doc # …or with a custom /s/my-doc slug
mdv pdf spec.md                 # render the current revision to spec.pdf

Or do both steps at once — sync, auto-repair, and share in one call:

mdv publish spec.md --slug my-doc   # sync + repair + share, atomically

Useful around the loop:

mdv sync spec.md --no-fix     # fast sync: skip auto-repair, just report failures
mdv pdf spec.md --no-sync     # PDF of the last synced revision; local edits stay private
mdv list                      # all saved documents with their URLs
mdv status spec.md            # document ID, public state, last sync, local edits pending?
mdv unlink spec.md            # forget the file↔document link; the document stays online

Nothing is public until you run mdv share. After that, the public page serves the last synced revision — mid-edit local changes still stay private until you sync. mdv fix FILE --local repairs a file in place without creating a saved document (free accounts share the daily Quick Fix limit; Pro is unlimited).

Example session

A real session, working on a doc whose Mermaid diagrams start out broken:

$ mdv sync spec.md                 # iterate — the broken flowchart is auto-repaired (~30s)
Document: 8be0be9198400443
Private: https://mdview.io/p/8be0be9198400443
Renderable: yes (1 diagrams, 0 tables)

$ vim spec.md                      # …add two sections, each with a (broken) diagram…
$ mdv sync spec.md                 # same doc, all three diagrams repaired and verified
Document: 8be0be9198400443
Private: https://mdview.io/p/8be0be9198400443
Renderable: yes (3 diagrams, 0 tables)

$ mdv share spec.md                # happy with it — make it public
https://mdview.io/s/9a2b8fb1

$ mdv pdf spec.md                  # …and hand over a PDF
PDF: spec.pdf

Two commands did all the work: mdv sync after every editing round, and mdv share once at the end. The fixes were written back into spec.md (originals in timestamped backups, so you can review what the repair changed — worth a glance before sharing, since a repair is guaranteed to render but not to read your mind), the private URL never changed, and the public link didn't exist until it was asked for.

When this flow fits: a document that lives longer than one paste — specs, architecture docs, reports, runbooks, agent-written docs you refine over hours or days. Use it when reviewers follow one link that must always show the latest good revision, or when a PDF has to be producible at any moment. In CI, use mdv verify FILE as a docs gate; it exits 1 on broken diagrams, leaves the file untouched, and removes its temporary remote document afterward. For a one-off snapshot, mdv preview is enough; for reading a local file without uploading it, use mdv open.

Reference

Exit codes: 0 success, 1 document doesn't render cleanly, 2 usage error, 3 mdview.io error.

Environment: MDVIEW_TOKEN supplies the token without storing it (ideal for CI); MDVIEW_BASE_URL points the CLI at another server.