ada

The fastest terminal markdown viewer, for one file or a whole vault of notes.

First in 80 of 84 measurements against five other terminal viewers, on time, CPU and memory.

Follow links and come back to where you were, see what git says changed, read wide tables at any width, and look at the pictures.

Download ada

Binaries for Linux and macOS, or build it with cargo.

Ada, a fluffy grey mixed-breed cat, lying on a shelf and looking at the camera — Named after Ada, regal matriarch, at her behest.

ada index.md

ada jumping to a heading from the outline, searching, following a link from the link list, picking a theme in the settings, sorting the second of two tables by how long things take, going back, and following a link to a mermaid sequence diagram whose cast stays on top as it scrolls

Tables you can work with #

Sorting knows its units: 350 µs, 12 ms, 1.2 s, 1m 30s and 6 days sort as the durations they are, 1,440 as a number and €420 as money. In a long table, the header row stays on screen as it scrolls.

s sort by a column C-← C-→ another table t auto, grid, records

a table of durations in µs, ms, s, minutes and days, sorted ascending, then descending, then back to the source order — Ascending, descending, and back to the source order.

a long table scrolling with its header row kept at the top — A month of the feeder's log; the header stays.

At any width #

Prose rewraps and tables re-lay out the moment the terminal changes size. A table too wide to fit turns into records, a card per row; widen the terminal and the grid comes back.

a seven-column table re-laid out as the terminal narrows, turning into records, then back into a grid — A real resize: ada in a tmux pane, the border moving.

Links you can walk #

Relative paths, [[wiki links]], anchors and src/main.rs#L42. Back returns to the same spot, with the same link focused.

Links that survive moves: a wiki link is found by name anywhere in the vault, as in Obsidian. An Obsidian vault needs no setup; any other folder of notes, one line in config.toml.

Tab focus Enter follow BS back L forward o outline l links

following a wiki link to a heading in another note, and coming back — `[[shenanigans#Unsolved]]`, there and back.

A git gutter #

The gutter marks what git says changed in the rendered note: added and modified lines, staged and unstaged, each in its own color.

]c [c next, previous change

a note with change marks in the left gutter beside a staged new task, an unstaged edited task and an unstaged new task

Search that sees through markup #

A regex matches the text as you read it, across bold, italic and plain, as you type. Link targets match too, and it's smart-case.

/ search n N next, previous

typing a search that matches across bold, italic and plain text

Mermaid, drawn as text #

Sequence diagrams, flowcharts, state and class diagrams in a ```mermaid block are drawn in the note, in your theme's colors, in any terminal and in --print. A sequence diagram's cast stays on top as you scroll. A 120-node flowchart draws in 5.7 ms, where md-tui's renderer takes 17 s.

← → scroll a wide diagram

scrolling through a sequence diagram whose participants stay on top, then a flowchart with a subgraph and a state diagram with a composite state

Mermaid gantt charts #

A gantt chart in a ```mermaid block draws its tasks as bars on a date axis that fits the width, colored by their tags: done, active, critical, milestones. after, durations and excluded days work as in Mermaid.

a gantt chart of a cat's week in two sections, with done, active and critical tasks and a milestone

a note with a photo of Ada shown inline, in kitty — In kitty.

Images #

png, jpeg and gif (its first frame), right in the note, over kitty, sixel or iTerm2, with half-blocks as the fallback, and inside tmux. A link to an image opens it full screen.

Piped straight in: ada tells an image by its first bytes, so curl -s …/cat.png | ada --print draws it right in the terminal, no format to name.

One previewer for fzf #

One tool in place of bat and kitten icat. ada --print fills the pane at its size: notes rendered, tables and all, code, logs and JSON highlighted, and images, in kitty's graphics protocol in kitty and Ghostty and in half-blocks elsewhere.

A preview stops 2,000 rows in, so an 80 MB log previews as fast as a small file: 4.0 ms, where bat takes a second.

fzf --preview 'ada --print {}'
# from rg matches: the matched line lands mid-pane
rg -n . | fzf -d : --preview-window '+{2}-/2' \
  --preview 'ada --print --line {2} {1}'

fzf with ada as its previewer, moving from a note with two tables to one with a seven-column table, then a Rust file and a highlighted log — Two notes with tables, the feeder's code, and its log.

Fourteen themes, and yours #

The ten dark ones are below; the light ones are gruvbox-light, catppuccin-latte, tokyonight-day and rose-pine-dawn. T previews each as you move through the list, and C-← C-→ switch between dark and light. Your own start from any of them and change only what they need.

gruvbox-dark
catppuccin-mocha
catppuccin-macchiato
catppuccin-frappe
dracula
tokyonight-night
tokyonight-storm
tokyonight-moon
rose-pine
rose-pine-moon

Also #

Not only markdown #
Code, config and other text files open whole and highlighted, in some 200 languages, and logs and JSON through parsers of ada's own (JSON colored however long its lines); main.rs#L24 lands on line 24. w wraps code or scrolls it sideways, # shows line numbers.
Callouts, footnotes, task lists #
GitHub's five callout kinds, footnotes you can follow, and checkboxes.
Live reload #
Reads the file again the moment it changes, keeping its place, or with live_reload = "notify" marks the change until r. e opens $EDITOR at the line on screen.
From a pipe #
ada tells markdown, code, JSON, YAML, diffs and logs apart by what they hold: journalctl -b | ada. -l json names the language when the guess is wrong.
Your keys #
Remap any action, including two-key sequences like "g g", in config.toml.
Record and replay #
--record a session and --replay it to the same frames: a bug report that reproduces.

No crashes, on any input #

ada is fuzzed as whole sessions, not one function at a time: a document, then up to 64 things a reader, the file system, git or the terminal can do, in any order.

45.8 M

fuzzed sessions

whole scripted sessions, plus 1.5 B runs of the printer, scanners, highlighting lexers, image codecs, terminal probe, link lookup and diagrams; over 43 h in eighteen runs

bugs found, all fixed

an overflow on an impossible git hunk; five frame bugs with wide glyphs or a popup over an image; a parser blow-up and a highlighter loop, now bounded; three malformed images that took it down; a wiki link that lost its folder

crashes, hangs or OOMs

in every run since the fixes

unsafe blocks

two set glibc's malloc arena count, before the threads that use it start; two give back the binary's read-only pages once the syntax set has loaded; one reads a row of screen cells as bytes, to compare rows in wide loads; three find a document's newlines with AVX2 on x86_64, once the CPU is known to have it. Plus 17 for Windows interop, in the Windows build only: calls into the Win32 console, file-watch and shell APIs

Any document
Markdown, code, config, plain text and images, built from random bytes and a dictionary of the parts markdown parsers find hardest. Other targets fuzz --print, whole and streamed (which must match byte for byte), the log and JSON scanners, the Makefile and shell lexers (checked against syntect line for line), image decoding, mermaid diagrams at any width, the sixel encoder, and the terminal's replies to ada's probe.
Any input
Every action, through the real keymap or directly: scrolling, links, search, sorting, the outline, themes, the settings popup, saving the config, the mouse (wheel, clicks, selecting text by dragging or double and triple clicks), and resizes at any size.
A world that answers badly
Links to missing or corrupt files, wiki links looked up by name in trees whose names collide by case and folder, fuzzed git hunks, images that report zero or huge sizes, and results that arrive late, out of order, or after their document is gone.
Every frame checked
Each step paints through ada's real diff and encoder into a vt100 terminal emulator, which must show exactly what ada meant to draw, cell by cell: glyphs, colors, attributes, and the numbering of kitty image cells. So must the screen ada leaves in the terminal when it quits.

Every interaction is a message, so a recorded session replays to identical frames: --record makes a bug report that reproduces. A deterministic stand-in for the fuzzer runs with every cargo test.

Install #

Binaries for Linux (x86_64 and aarch64: gnu for glibc 2.34 or newer, musl static for any Linux, Alpine included, printing large files in up to 1.4× the time) and macOS (Apple silicon and Intel) are on the releases page: unpack one and put ada on your PATH. The macOS binaries aren't signed, so if the archive came through a browser, run xattr -d com.apple.quarantine ada first. Or build it from crates.io:

cargo install --locked ada-md

or the latest from git: cargo install --locked --git https://github.com/junkdog/ada-md ada-md.

The release binaries are linked with the code a typical run needs first, so a run takes up to about 1 MiB less memory on Linux, and less than half that on macOS. That takes two links, which cargo install can't do. To build ada the way the releases are, on Linux (x86_64 and aarch64) and macOS, from a clone:

cargo ordered --locked   # target/release/ada, as released

Rust 1.88 or newer, and a C compiler: highlighting runs on Oniguruma, built from source. For a pure-Rust build, add --no-default-features. Git integration runs the git command.

Windows is mostly untested: ada builds and runs there but doesn't follow Windows' conventions yet. The README lists what's missing; support is planned for 1.1.

# read a note
ada notes/today.md

# from a pipe: ada tells markdown, code, JSON, YAML, diffs and logs apart
git show HEAD~3:README.md | ada
journalctl -b -u sshd | ada

# code, config and images too
ada src/main.rs
ada plot.png

# as an fzf preview
fzf --preview 'ada --print {}'

Press ? in ada for the keys. The README has every key and option.

ada

Tables you can work with #

At any width #

Links you can walk #

A git gutter #

Search that sees through markup #

Mermaid, drawn as text #

Mermaid gantt charts #

Images #

One previewer for fzf #

Fourteen themes, and yours #

Also #

Not only markdown #

Callouts, footnotes, task lists #

Live reload #

From a pipe #

Your keys #

Record and replay #

Fast, and lean #

In a 120×40 terminal

Printing, `--print` and the other printers

In a 120×40 terminal

Printing, `--print` and the other printers

In a 120×40 terminal

Printing, `--print` and the other printers

In a 120×40 terminal

Printing, `--print` and the other printers

As a previewer: code, logs and JSON #

Image previews #

Mermaid diagrams #

No crashes, on any input #

Any document

Any input

A world that answers badly

Every frame checked

Install #

ada

Tables you can work with #

At any width #

Links you can walk #

A git gutter #

Search that sees through markup #

Mermaid, drawn as text #

Mermaid gantt charts #

Images #

One previewer for fzf #

Fourteen themes, and yours #

Also #

Not only markdown #

Callouts, footnotes, task lists #

Live reload #

From a pipe #

Your keys #

Record and replay #

Fast, and lean #

In a 120×40 terminal

Printing, --print and the other printers

In a 120×40 terminal

Printing, --print and the other printers

In a 120×40 terminal

Printing, --print and the other printers

In a 120×40 terminal

Printing, --print and the other printers

As a previewer: code, logs and JSON #

Image previews #

Mermaid diagrams #

No crashes, on any input #

Any document

Any input

A world that answers badly

Every frame checked

Install #

Printing, `--print` and the other printers

Printing, `--print` and the other printers

Printing, `--print` and the other printers

Printing, `--print` and the other printers