@profullstack/readm3

readm3

A terminal markdown reader. File browser on the left, the rendered document on the right, and nothing else in the way.

Built on HQTUI — truecolor, mouse, and a terminal that gets restored no matter how the process dies.

╭─  readm3  ──────────── 6 ─╮╭─  README.md  ────────────────────────────────────── 24% ─╮
│ ▾ docs                    ││ readm3                                                   │
│     usage.md              ││ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│   README.md               ││                                                          │
│   CHANGELOG.md            ││ A terminal markdown reader. File browser on the left, the │
│                           ││ rendered document on the right.                          │
│                           ││                                                          │
│                           ││ Install                                                  │
│                           ││ ─────────                                                │
│                           ││                                                          │
│                           ││ ┌─ bash ────────────────────────────────────────────────  │
│                           ││ │ bun add -g @profullstack/readm3                        │
│                           ││ └────────────────────────────────────────────────────────  │
╰───────────────────────────╯╰──────────────────────────────────────────────────────────╯
 ↑↓ move  ↵ open  ←→ fold  / find  tab reader  ? keys  q quit              docs  dark

Install

bun add -g @profullstack/readm3     # Bun is the default runtime
npm  install -g @profullstack/readm3 # Node 22.6+ works too

Or run it without installing:

bunx @profullstack/readm3
npx  @profullstack/readm3

Use

readm3                  # browse markdown under the current directory
readm3 ./docs           # browse a directory
readm3 CHANGELOG.md     # open a file, browse its directory
readm3 --theme nord     # pick a palette

The browser only shows markdown. Directories with nothing beneath them are pruned, node_modules and friends are never walked, and README sorts first.

Keys

↑ ↓ j k	move or scroll	tab	switch pane
→ ← l h	expand or collapse	/	filter files
enter	open the file	esc	clear the filter
space b	page down / up	r	rescan and reload
g G	top / bottom	[ ]	sidebar width
?	help	q ctrl+c	quit

The mouse works too: the wheel scrolls whichever pane it is over, and a click opens a file.

What it renders

Headings, bold, italic, inline code, links, fenced and indented code blocks with a language label, ordered and unordered lists, nested lists, task lists, blockquotes, tables with per-column alignment, horizontal rules, images as labelled placeholders, and YAML front matter — shown rather than hidden, because it is usually what you opened the file for.

The HTML that real READMEs are full of is folded back into markdown rather than printed as tags, and inline code is held out of that, so Array<string> survives.

Options

-t, --theme <name>   dark, dracula, nord, tokyo-night, gruvbox, matrix,
                     monochrome, high-contrast, light
-w, --width <n>      sidebar width in columns (default: 28% of the terminal)
-a, --all            include dot-directories and dotfiles
-M, --no-mouse       disable mouse tracking
-v, --version
-h, --help

As a library

The renderer and the file tree are pure and need no terminal, so they can be reused on their own:

import { renderMarkdown, toText, scan, files } from "@profullstack/readm3";

const lines = renderMarkdown("# Hello\n\nSome **text**.", 60);
console.log(toText(lines));
// [ 'Hello', '━━━…', '', 'Some text.' ]

for (const file of files(scan("./docs"))) console.log(file.path);

renderMarkdown returns lines of spans carrying a semantic role — h1, code, link, quote and so on — rather than colors, so the same document can be re-themed without re-parsing.

Runtimes

Bun is the default. Node 22.6+ runs the same code. Tested on Linux, macOS and Windows Terminal.

Develop

bun install
bun src/cli.ts .     # run it against its own repo
bun test test/       # 48 tests, no TTY needed
bun run typecheck
bun run build

License

MIT.