marustdown

A fast terminal markdown viewer. It renders GitHub-flavored markdown with real typography.

Features

• Pager with a cursor line, search, heading jumps and a breadcrumb of the current section.
• Task lists you can check off. Toggling a task writes [ ] ↔ [x] back to the file.
• Keyboard link following. f tags every visible link, and typing a tag opens it (in uppercase, it copies the URL instead). Tab and Shift-Tab step through links, and Enter opens the selected one. #anchors jump within the page, linked .md files open in the viewer with a back history, and everything else goes to xdg-open.
• Outline picker. Filter the headings by typing, then jump to one.
• Live reload with --watch: the view follows changes to the file, keeps your place, and stays at the end when you were there, like tail -f.
• Edit in $EDITOR at the cursor's source line, and see the result when you return.
• Copy code blocks to the system clipboard with OSC 52, which also works over SSH.
• Math: $…$ and $$…$$ LaTeX is rendered as Unicode, like x² + yᵢ, ∑ᵢ₌₁ⁿ or √(x + 1), with matrices and cases drawn over several lines.
• Mermaid diagrams: ```mermaid blocks are drawn with box-drawing characters: flowcharts, sequence, state, class, pie, gantt and more. Diagrams that fail to parse show their source.
• Horizontal scrolling: code blocks, diagrams and formulas wider than the screen scroll sideways under the cursor instead of being cut off.
• Syntax highlighting for about 220 languages, using syntect with bat's syntax definitions from two-face. Colors come from your theme, not from a separate highlighting theme.
• Clickable links (OSC 8) in terminals that support them.
• Cat mode prints the rendered document to stdout, and is used automatically when output is piped or redirected. Output is styled on a terminal and plain text otherwise.
• Fully configurable: themes, per-element styles, glyphs, layout and key bindings.
• Fast: memory-mapped input and a flat three-buffer layout with no per-line allocations. Highlighting is cached per code block, so resizing never re-highlights.

Screenshots

Syntax highlighting	Task lists
Math and diagrams	Outline

The screenshots are generated with VHS: run cargo build --release && vhs docs/demo.tape to regenerate them.

Install

Prebuilt static binaries for Linux (x86_64 and aarch64) run on any distro:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/beshralghalil/marustdown/releases/latest/download/marustdown-installer.sh | sh

Other ways:

cargo binstall marustdown        # prebuilt binary through cargo-binstall
cargo install marustdown --locked  # build from source: Rust 1.92+ and a C compiler

You can also download an archive from Releases and put mar on your PATH. Each archive also contains the man page and shell completions:

Alert icons use Nerd Font glyphs. Without one, run mar --no-icons or set icons = false.

Usage

mar README.md            # page a file
mar README.md --cat      # print the rendered document and exit
cat notes.md | mar       # read stdin (`mar -` works too)
mar doc.md > doc.txt     # redirected output is plain, readable text
mar --color always doc.md | less -R   # keep the styling when piping

Keys

Every binding except Ctrl-C can be changed, see docs/configuration.md.

Configuration

Config file: ~/.config/marustdown/config.toml (or $XDG_CONFIG_HOME/marustdown/config.toml). Every key is optional; set only what you want to change.

theme = "light"          # dark, light, ansi, or a file in ~/.config/marustdown/themes/

[layout]
width = 100

[styles.h1]
fg = "#ff8800"

[keys]
toggle = ["space"]

The full reference is in docs/configuration.md, and every default is in assets/config.toml.

Notes

• Links to local markdown files are resolved against the current file's directory, and a #fragment jumps to the matching heading using GitHub's anchor rules. External links open with xdg-open (open on macOS).
• A code block's language is looked up by the name after the fence, either a file extension (rs, py, ts) or a language name (rust, Dockerfile). Unknown languages are shown without highlighting.
• Copying needs a terminal that supports OSC 52. Under tmux, also set set -g set-clipboard on.
• Toggling a task checks that the file still has a task box at that spot before writing, so a file edited behind the viewer's back won't be corrupted.
• Input from stdin can be viewed and its tasks toggled, but those changes aren't saved.

Development

cargo test
cargo clippy --all-targets

source memory-maps the input, layout turns pulldown-cmark events into a Document (flat text, style runs and line ends, with no escape codes), and render and pager turn that into terminal output without knowing anything about markdown.

License

MIT