GitHub - gogainda/mdview-cli · GitHub
/" data-turbo-transient="true" />
Skip to content
Search/
Sign in<br>Sign upAppearance settings
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
gogainda
mdview-cli
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>11 Commits<br>11 Commits
.github/workflows
.github/workflows
src/mdview_cli
src/mdview_cli
tests
tests
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
pyproject.toml
pyproject.toml
View all files
Repository files navigation
mdv — preview Markdown files from your terminal
mdv renders a Markdown file the way it should look — headings, tables, code,<br>Mermaid diagrams — and opens it in your browser. One command, no account, no<br>configuration.
uv tool install mdview-cli # or: pipx install mdview-cli, pip install mdview-cli<br>mdv notes.md
Homebrew users:
brew install gogainda/tap/mdview-cli
That's the whole workflow: mdv FILE.md publishes the file to<br>mdview.io, opens the rendered page, and prints a link you<br>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<br>mdv preview notes.md --title "Design notes"<br>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<br>URL itself and rendering happens entirely in your browser. Use it for drafts<br>that shouldn't leave your machine.
mdv open notes.md
Common use cases
mdv notes.md # preview and share a one-off Markdown file<br>mdv open notes.md # preview locally without uploading<br>mdv verify notes.md # check rendering, then delete the remote copy<br>mdv fix notes.md --local # repair broken Mermaid in the local file<br>mdv sync notes.md # update a private document and auto-repair it<br>mdv share notes.md # publish the synced document at a stable URL<br>mdv pdf notes.md # create notes.pdf
For a quick renderability check, mdv verify FILE exits 0 when the document<br>renders cleanly and 1 when it does not. It never modifies the local file. It<br>requires a token, uploads the current contents to a temporary private document,<br>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<br>the same file — a spec, an architecture doc, a report — you want the opposite:<br>one stable URL whose content follows your edits, and a check that every<br>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)<br>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<br>you, signed in, can see it, and the URL stays the same forever. Every sync<br>shows the fixed, renderable version there. Broken Mermaid diagrams are<br>repaired automatically and the fix is written back into your file (the<br>original is kept as a timestamped backup); only documents that can't be<br>repaired exit 1.
When — and only when — you decide to publish, make it public; and grab a PDF<br>at any point:
mdv share spec.md # mint the public /s/ link (from then on it follows your syncs)<br>mdv share spec.md --slug my-doc # …or with a custom /s/my-doc slug<br>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<br>mdv pdf spec.md --no-sync # PDF of the last synced revision; local edits stay private<br>mdv list # all saved documents with their URLs<br>mdv status spec.md # document ID, public state, last sync, local edits pending?<br>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<br>serves the last synced revision — mid-edit local changes still stay private<br>until you sync. mdv fix FILE --local repairs a file in place without<br>creating a saved document (free accounts share the daily Quick Fix limit;<br>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)<br>Document: 8be0be9198400443<br>Private: https://mdview.io/p/8be0be9198400443<br>Renderable: yes (1 diagrams, 0 tables)
$ vim spec.md # …add...