wiki-reader

A terminal wiki reader for markdown collections. It browses like a documentation site (side nav, breadcrumbs, working links, back/forward, prev/next), sized to live in a herdr pane next to your work.

 Worked Example Wiki                                                      ◫  ✕ 
┌────────────────────────┐┌─────────────┬─────────────┬────────────────────────┐
│ / Search…              ││ README.md × │ tokens.md × │                        │
├────────────────────────┤├─────────────┴─────────────┴────────────────────────┤
│▌ Worked Example Wiki   ││▌── frontmatter ▸ ──────────────────────────────────│
│  ▸ architecture        ││                                                    │
│  ▸ decisions           ││ Worked Example Wiki                                │
│                        ││ ────────────────────────────────────────           │
│                        ││                                                    │
│                        ││ A tiny markdown collection used as the default     │
│                        ││ smoke-test root.                                   │
│                        ││                                                    │
│                        ││ Start at Architecture Overview, follow Token       │
│                        ││ Projection, then return via back when history      │
│                        ││ exists. Enter a picture for Tab carousel / a fit.  │
│                        │├────────────┬─────────────┬─────────────────────────┤
│                        ││ ‹ Overview │             │ Architecture Overview › │
└────────────────────────┘└────────────┴─────────────┴─────────────────────────┘
  VIEW  · README.md · L1:C1 9% · 2026-09-28 · draft · 29w · 1m            ?  ⚙ 

Help (?), search (/) and options (, or c) are popups over the same layout. Click ? / ⚙ at the full-width layout footer's bottom right, below both panes, for Help / Options; the header retains ◫ / ✕ for nav / quit.

Nav rows show page titles by default (nav.labels = "filename" switches to filenames); folders always show the folder name. Press ? in the app for every key. In the image / diagram viewer: Tab / Shift+Tab step through pictures on the page, a toggles fit / actual size, v cycles a diagram's image / text / source view.

Existing terminal markdown tools behave like editors or file browsers: opening a page spawns a tab, links are inert, and search lives in a modal. wiki-reader uses a browser/wiki navigation model. Every way of reaching a page replaces the current view and records history, and tabs are an opt-in secondary feature. See ADR-0005.

wiki-reader exists because of markdown-reader by leboiko (MIT), and we are grateful for it. It was the first thing tried for browsing a wiki in a terminal and the best of its kind. Much of what wiki-reader does for a page started as something markdown-reader showed was possible: the tree beside a rendered page, tables, code blocks and a frontmatter box that read well, Mermaid diagrams in the terminal, live reload, and a settings window, whose grouped radio-button layout wiki-reader's options window borrows.

wiki-reader also depends directly on mermaid-text, markdown-reader's author's crate, for its text-mode diagrams. The rest of the page rendering is written fresh for wiki-reader's navigation model.

Other tools that shaped it, and what each contributed, are listed in Prior art and libraries: treemd, md-tui, Frogmouth, Glow and others. If you want an editor-style markdown browser rather than a wiki reader, markdown-reader is the one to use.

Phase 2 is done (closed 2026-10-06). Phase 3 alpha polish is shipped through v0.1.11 (lite build, viewers, audit fixes, linear wrap for long tokens, orphaned-reader exit); the exit decision was recorded on 2026-10-06. See the roadmap and the dogfood log. Releases and binaries are on GitHub Releases.

From crates.io:

cargo install --locked wiki-reader-tui

Or the latest main from git:

cargo install --locked --git https://github.com/luckgrid/wiki-reader wiki-reader-tui

Lite build (no images, SVG or Mermaid pictures; diagrams stay text, source or a placeholder; smaller binary, faster build; see ADR-0023). It is a cargo feature only; there is no -lite release download:

cargo install --locked --no-default-features wiki-reader-tui

The package is named wiki-reader-tui (the command it installs is still wiki-reader), because the name wiki-reader is taken on crates.io. Releases up to and including v0.1.10 use the old package name: pin one with cargo install --locked --git https://github.com/luckgrid/wiki-reader --tag v0.1.10 wiki-reader. If you installed wiki-reader before the rename, run cargo uninstall wiki-reader first (or add --force), because cargo will not let a second package overwrite the same command.

Release binaries (macOS arm64 / x86_64, Linux x86_64) ship on v* tags under GitHub Releases. Download the matching .tar.gz, verify the checksum, and put wiki-reader on your PATH:

shasum -a 256 -c wiki-reader-vX.Y.Z-<platform>.tar.gz.sha256
tar xf wiki-reader-vX.Y.Z-<platform>.tar.gz

Binaries are unsigned and not notarized. Browser downloads on macOS may be quarantined; clear with xattr -d com.apple.quarantine path/to/wiki-reader if Gatekeeper blocks them (curl downloads usually skip quarantine). The Linux binary is built on ubuntu-latest and links that runner's glibc, so older distros may need to build from source or use cargo install.

The crates are published on crates.io: wiki-reader-tui (the binary) with the library crates wiki-reader-core, wiki-reader-media and wiki-reader-render.

Check your version with wiki-reader --version and which wiki-reader. Upgrade the same way you installed (mixing paths leaves two binaries; whichever is first on PATH wins).

# cargo install → ~/.cargo/bin (--force replaces it; a --tag before the rename needs the old name, see Install)
cargo install --locked --force wiki-reader-tui

# release tarball → usually ~/.local/bin (verify and unpack as above, then overwrite)
install -m 0755 wiki-reader-vX.Y.Z-<platform>/wiki-reader ~/.local/bin/wiki-reader

If which wiki-reader and the install target disagree, remove the extra copy or put the intended directory earlier on PATH. Quit any running instance first. Your config and saved sessions are kept. Rolling back, uninstalling, resetting sessions, and replacing a published release are covered in Releasing and upgrading.

cargo run -p wiki-reader-tui -- fixtures/worked-example
# q to quit, ? for help

Or after install:

wiki-reader fixtures/worked-example
# q to quit, ? for help

wiki-reader exits by itself when its terminal goes away (the window closes, or the shell that owns the terminal session exits); it never keeps running in the background. An escape hatch, WIKI_READER_NO_WATCHDOG=1, is in the configuration guide.

integrations/herdr/ is a herdr plugin: bind a key to its wiki-reader.open action to open the reader in a new split pane in the focused pane's directory. (Images need an ordinary pane, which that action uses; herdr 0.9.x plugin panes such as overlays and popups show text only.)

./scripts/check.sh          # default and lite builds; `default` or `lite` runs one half

That runs cargo fmt --check, clippy and tests for both feature sets, link-check, rumdl and the dependency-tree guards.

Cargo workspace with wiki-reader-core (terminal-free), wiki-reader-render, wiki-reader-media (image decode and Mermaid/SVG rasterisation), the wiki-reader TUI binary, and wiki-reader-tools (repo tooling; not published). Docs live in wiki/. See guides/development.md.

Copyright © 2026 LUCKGRID. Dual-licensed under MIT or Apache-2.0, at your option. The two licenses are alternatives: users need to comply with only the one they choose. The NOTICE file names the copyright holder (the Apache-2.0 text is kept verbatim, as the licence requires). Release binaries also contain third-party packages and the embedded Noto Sans font (SIL OFL 1.1); their notices are in THIRD-PARTY-LICENSES and in every release tarball.