A small, self-contained CLI that serves a live-reloading browser preview of a Markdown file, including mermaid diagrams, or of a Typst document. Built to replace an editor plugin (for example nvim's markdown-preview) with an external process, so it works with any editor that can run a shell command, such as Helix.
With cargo-binstall, which fetches the prebuilt binary for your platform instead of compiling:
cargo binstall mdpreviewerOr build and install from crates.io:
cargo install mdpreviewerBinaries are published for macOS arm64 (aarch64-apple-darwin) and Linux x86_64
(x86_64-unknown-linux-gnu); cargo install covers everything else. The
archives are also on the
releases page with a
.sha256 beside each one, if you would rather unpack one yourself.
Either way, mdpreviewer has to land on the PATH your editor inherits. See
Building from source to install from a clone instead.
mdpreviewer [--line N] [--no-open] path/to/file.md # open a preview (or reuse one)
mdpreviewer --sync [--line N] path/to/file.md # update a running preview only
mdpreviewer --restart [--line N] path/to/file.md # stop any running server, then open
mdpreviewer --quit # stop the running server
mdpreviewer --help # list the options
mdpreviewer --version # print the versionThe first run binds a random local port, opens your default browser at that URL, and renders the file. Saving the file reloads the content in place. On Unix the server detaches from its launcher, so it can be run from an editor command without blocking, and it shuts itself down shortly after the last browser tab closes.
Only one preview server runs per user. Later runs hand their file to it over a
Unix socket ($XDG_RUNTIME_DIR/mdpreviewer.sock) instead of starting another, so
the open tab switches to the new file. A new tab opens only if none is open.
--line Nscrolls the preview to source lineN, centering and briefly highlighting that block.--synconly talks to a running server. It never starts one, never opens a tab and never prints anything, so it is cheap enough to run on every save.- Every mode that takes a file ignores anything that is not
.md,.markdownor.typ, so a preview binding is inert in a source buffer. A leading~in the path is expanded. --quitstops the running server and its browser tabs stop updating. It takes no file, and exits 0 whether or not a server was running.--restartis--quitfollowed by a normal open. Browser assets are compiled into the binary, so after a rebuild this is how you get a running server to serve the new ones.--no-openprints the URL instead of opening a browser.--helpand--versionanswer and exit without starting or contacting a server. They are also accepted as-hand-V, and--helpis honoured even when the rest of the command line is wrong.
Click a mermaid diagram, an image, a table or a code block to blow it up to fill the window. In the overlay:
| Input | Effect |
|---|---|
| scroll wheel | zoom in or out around the pointer |
| drag | pan |
0 |
fit to the window again |
+ / - |
zoom from the centre |
| double-click | toggle between fitting the window and the document's scale |
f |
true browser fullscreen |
esc, the ×, or a click outside |
close |
Links are left alone, so a linked image follows its link, and clicking after selecting text does not zoom. The overlay follows live reloads: saving the file re-renders what it is showing and keeps your zoom, and it closes if the block is gone.
The preview follows the document's relative references the way GitHub does.
Clicking a link to another Markdown file, such as [setup](docs/setup.md) or
[back](../README.md), switches the preview to that file, and relative images
such as  load from beside the document and reload when
the image file is replaced. A link to a file
that is missing, or is not Markdown, shows a notice at the top of the window
instead. The preview shows one document at a time, so a ctrl- or middle-click
on such a link switches the preview too, rather than opening a new tab. Only
image files are served that way, and relative links to anything
other than Markdown are left to the browser. Saving in the editor switches the preview back to the
file being edited, since C-s tells the server which file that is.
A .typ file is compiled in-process, with the typst compiler built into the
binary, and shown as its pages, the way the PDF would look. Saving the document,
or any file it reads (#include, #import, images, data), reloads the preview.
While a save does not compile, the last pages that did stay up under the error
list.
The document's directory is the project root, as with typst compile. System
fonts are used, with typst's own fonts as a fallback. @preview packages come
from the same cache as the typst CLI and are downloaded on first use.
--line N and C-s scroll to the text a line produced. A line that produces no
text of its own (a #set rule, an image, an equation) scrolls to the nearest
text before it, and lines inside an #included file do not scroll.
Helix has no plugin system, so the preview is an ordinary command bound to a
key. :sh runs in Helix's working directory and %{buffer_name} is relative to
it (Helix has no absolute-path variable), so the two line up.
[editor]
# Save shortly after edits, so the preview follows typing, not just C-s.
auto-save = { focus-lost = true, after-delay.enable = true, after-delay.timeout = 300 }
[keys.normal]
# Save, then scroll a running preview to the cursor. A silent no-op otherwise.
"C-s" = [":w", ':sh mdpreviewer --sync --line %{cursor_line} "%{buffer_name}"']
[keys.insert]
"C-s" = ["normal_mode", ":w", ':sh mdpreviewer --sync --line %{cursor_line} "%{buffer_name}"']
# A "Markdown" submenu. This assumes `\` is your leader key; any free key works.
[keys.normal.\\.m]
label = "Markdown"
m = { command = [":w", ':sh mdpreviewer --line %{cursor_line} "%{buffer_name}"'], label = "Preview (save, start or switch)" }
r = { command = [":w", ':sh mdpreviewer --restart --line %{cursor_line} "%{buffer_name}"'], label = "Restart preview server" }
q = { command = ":sh mdpreviewer --quit", label = "Quit preview server" }| Key | Does |
|---|---|
C-s |
Save, then scroll the preview to the cursor. Runs on every save. |
\mm |
Save, then start the preview or point the running one at this file |
\mr |
Save, then restart the server and open this file |
\mq |
Stop the server |
Helix has no per-filetype keymaps, so these run in every buffer. mdpreviewer
only acts on .md, .markdown and .typ files; anywhere else it refuses
with not a Markdown or Typst file: <name>, which Helix shows in its shell popup. That also
covers [scratch] buffers, where :w fails first but Helix runs the rest of
the list anyway.
Success is silent. mdpreviewer prints the URL only when stdout is a terminal,
so a binding does not pop one up on every keypress, but failures always print.
Helix reports a file outside its working directory as ~/..., and the binding
quotes it so the shell cannot expand it. mdpreviewer expands a leading ~
itself.
Bindings like these need mdpreviewer on the PATH Helix inherits;
mise run install symlinks it into ~/.local/bin.
Use \mr after rebuilding. The browser assets are compiled into the binary, so
a server started from an older build keeps serving the assets it was built with,
no matter how many times you press \mm. --restart replaces the process, so
it picks up both new assets and new server code. It binds a new port, so any tab
from the previous server stops updating; close it.
This repo uses mise for tasks:
mise run build # cargo build --release
mise run install # build + symlink target/release/mdpreviewer into ~/.local/bin
mise run update-vendor # refresh the vendored browser assetsThe Rust toolchain is pinned in rust-toolchain.toml, which rustup reads, so a
plain cargo in the repo uses it too:
cargo build --releasehk drives every linter and formatter, so CI and a local run do the same work:
mise run lint # hk check --all
mise run format # hk check --fix --all (alias: fix)hk.pkl lists the steps: rustfmt and clippy for Rust, oxfmt for the browser
JavaScript, CSS and HTML, typstyle for Typst, shfmt and shellcheck for shell
scripts, yamlfmt and actionlint and zizmor for the workflows, pinact to pin the
workflows' actions to commit SHAs, taplo for TOML,
pkl format for hk.pkl itself, and rumdl for Markdown. Shell indentation
comes from .editorconfig. examples/ is excluded from Markdown formatting because
those files are fixtures whose odd formatting is the point, and
assets/vendor/ is excluded everywhere because it is pinned upstream code.
hk can install git hooks with hk install, but this repo is developed with
Jujutsu, which does not run git hooks, so run the tasks directly.
release-plz runs on every push to main. It keeps a
pull request open that bumps the version and writes CHANGELOG.md from the
Conventional Commit messages. Merging that PR publishes the crate to crates.io,
tags the commit, creates the GitHub release, and attaches macOS arm64 and Linux
x86_64 binaries.
Publishing needs a CARGO_REGISTRY_TOKEN repository secret holding a crates.io
token with the publish-new and publish-update scopes.
Release immutability has to stay off in the repository settings. release-plz
publishes the release first and the binaries job attaches the archives to it
a minute later, which an immutable release rejects with
HTTP 422: Cannot upload assets to an immutable release. Turning the setting
off only affects later releases; one already sealed stays sealed.
Before pushing, rehearse locally:
mise run release:check # lint, test, and package the crate
mise run release:preview # show the version bump and changelog
mise run release:publish-dry-run # rehearse the publish, changing nothingThe browser assets are vendored under assets/vendor/ so the tool works
offline and pins known-good versions:
mermaid.min.js(mermaid, default 11.17.2)github-markdown.css(github-markdown-css dark, default 5.8.1)
Refresh them with mise run update-vendor (or sh scripts/update-vendor.sh).
Override versions via MERMAID_VERSION / GH_MD_CSS_VERSION.
render.rsrenders Markdown to HTML with comrak (GFM extensions; raw HTML passed through for fidelity;data-sourceposon blocks for scroll sync). Fencedmermaidblocks are left as code blocks and turned into diagrams by the client.typeset.rscompiles Typst documents with the embedded compiler, renders each page as an SVG, and lays invisibledata-sourceposmarkers over each page so scroll sync works as it does for Markdown.https.rsdownloads@previewpackages over rustls.watch.rswatches the file's parent directory (to survive editor atomic-rename saves) and emits debounced reload events.server.rsserves the shell page, the rendered fragment (/content), an SSE stream ofreloadandscrollevents (/events), and the embedded assets. It switches documents when asked over the control socket or when a relative link to a document is clicked (/open), and serves relative images (/file).assets/app.jsrenders the fragment, turns mermaid fences into diagrams, reloads on SSE events, scrolls to the cursor line, and provides the click-to-zoom overlay.control.rsis the control socket: its location, a one-line protocol, the client used by later runs, and the server-side listener.main.rsparses the CLI, reuses a running server when there is one, and otherwise binds the port and socket before forking and runs the server in the detached child.