@bobfrankston/mdview
v0.1.15
Published
Render a markdown file and display it via msger or msgview
Downloads
1,759
Maintainers
bobfrankstonReadme
mdview
Render a markdown file (or stdin) and display it in a window via msger (Rust/wry, default) or msgview (Electron).
Why
msger and msgview are HTML viewers — they don't auto-render markdown. mdview is the preprocessor: it renders the .md to a self-contained HTML document (via msgcommon's renderMarkdown), injects a <base href> so relative links and images resolve against the source file's directory, and hands the HTML to whichever host you pick.
The HTML is loaded raw (-raw / rawHtml: true) — no msger/msgview template, no buttons. Just the rendered page in a window.
Install
npm install -g @bobfrankston/mdviewThis pulls msger as a dependency, so the default host works out of the box. To use the -host msgview backend you must install msgview separately:
npm install -g @bobfrankston/msgviewUsage
mdview [options] <file.md> [-- <host-flags>...]
cat foo.md | mdview -stream [options] [-- <host-flags>...]Options
Window:
| Flag | Description |
|---|---|
| -pos x,y[,s] | Window position (screen index s is optional, Windows only). |
| -size w,h | Window size in pixels. |
| -ontop | Keep window above others. |
| -zoom <percent> | Initial zoom (e.g. -zoom 150). |
Behavior:
| Flag | Description |
|---|---|
| -host msger\|msgview | Backend host. Default: msger. Persisted to ~/.mdview.json. |
| -w, -watch | Re-render and reload when the file changes on disk. Implies -nodetach. |
| -stream | Read markdown from stdin instead of a file. |
| -save <file> | Render to <file> (HTML) and exit; don't open a window. |
| -nodetach | Wait for the window to close before exiting. Default is detach (mdview returns immediately). |
| -dev | Open developer tools on startup. |
| -h, -help | Show help. |
Both -foo and --foo forms are accepted.
Host pass-through flags
Anything after -- is forwarded to the host. Needed only for flags mdview doesn't expose directly:
mdview README.md -- -resetmdview's own -pos, -size, -ontop, -zoom, -dev are translated for both hosts natively. Passthrough flags override top-level (last-write-wins) if you specify both.
Examples
# Default (msger), one-shot — shell returns immediately (detach is the default)
mdview README.md
# Switch to msgview and remember the choice
mdview -host msgview notes.md
mdview notes.md # subsequent runs use msgview until you switch back
# Pin position/size/ontop directly (no `--` needed)
mdview README.md -pos 100,100 -size 1000,800 -ontop
# Wait for the window to close (scripting)
mdview README.md -nodetach
# Watch mode — reloads on save, stays attached
mdview -w draft.md
# Render and save HTML, no window
mdview README.md -save out.html
# Pipe from stdin
cat foo.md | mdview -stream
gh pr view --json body -q .body | mdview -streamHow it works
- Read the markdown source (file or stdin)
- Render to a complete HTML document via
renderMarkdown(md, title, baseHref)from msgcommon <base href="file:///<source-dir>/">is injected into<head>— relative[link](./other.md)andresolve against the source directory- Pass HTML +
rawHtml: trueto the host:- msger: programmatic
showMessageBoxExAPI → stdin JSON to the Rust binary (no command-line length limit) - msgview:
spawn('msgview', ['-raw', '-html', html, ...])(subject to Windows cmd.exe ~8k arg limit; use msger for large docs)
- msger: programmatic
Limits
- Watch mode respawns the window — geometry resets each reload. Pin it with
-pos x,y -size w,h. - msgview + huge HTML can hit the 8k cmd.exe arg limit on Windows. Switch to msger if rendering is silently truncated.
- Cross-file
[x](other.md)links navigate to the raw.mdfile, not the rendered version. The host loads it as text. (Future: intercept.mdnavigation and re-render.) - Explicit refresh is editor-driven via watch mode —
touchthe file to force a reload without changing it.
Bind to .md files (Windows)
In Explorer, right-click any .md → Open With → Choose another app → mdview.cmd (in %APPDATA%\npm\). Tick "Always use this app".