termdoc

what it looks like

Release notes

A fast, terminal-native document viewer, with inline code and
a link[1].

Formats

• Markdown, plain text and logs
• Detection for JSON, YAML, TOML, XML, CSV
  ◦ and the Office/ZIP family
• PDF and EPUB are on the roadmap

┌──────────┬──────────┬───────────┐
│ Format   │  Status  │ Milestone │
├──────────┼──────────┼───────────┤
│ Markdown │  ready   │ M0        │
│ CSV      │ detected │ M1        │
│ PDF      │ pending  │ M3        │
└──────────┴──────────┴───────────┘

fn main() {
    println!("hello");
}

│ Streaming by default: a 488 MB log costs 1.4 MB of memory.

[1] https://termdoc.app

Not a mock-up. That block is generated by running termdoc over a Markdown file and translating the ANSI it emits — the colours, the wrapping and the box-drawing are the renderer’s own.

formats

● works today · ◐ reader in development, shown as plain text with a warning on stderr · ✕ recognised, but this build refuses to display it rather than dumping bytes at your terminal.

The middle row is the honest one. A recognised text format still gets shown, because mid-roadmap that beats refusing to open the file — and --strict turns that warning into a non-zero exit if a script would rather stop. Run termdoc --formats to see what the binary you actually installed can read.

graceful degradation

┌──────────┬──────────┬─────┐
│ Format   │  Status  │ M   │
├──────────┼──────────┼─────┤
│ Markdown │  ready   │ M0  │
│ CSV      │ detected │ M1  │
│ PDF      │ pending  │ M3  │
└──────────┴──────────┴─────┘

+----------+----------+-----+
| Format   |  Status  | M   |
+----------+----------+-----+
| Markdown |  ready   | M0  |
| CSV      | detected | M1  |
| PDF      | pending  | M3  |
+----------+----------+-----+

Format	Status	M
Markdown	ready	M0
CSV	detected	M1
PDF	pending	M3

One table, three rungs down. Each gives up something the rung above it could afford, and the last one gives up the frame entirely: below a certain width a bordered table can only fit by truncating cells, so it stops being a table and becomes tab-separated values — output for cut and awk rather than for reading. Losing the borders is recoverable; losing the data is not.

Degradation is an input to the layout, not a chain of special cases bolted onto it. The terminal’s real capabilities are detected once, and every ladder — colour truecolor → 256 → 16 → none, hyperlinks, headings — reads from that same value. With colour off, not one escape byte is emitted.

features

• Streaming by design — the document is an event stream borrowing from an mmap, never a materialised tree. A 488 MB log costs 1.4 MB of memory
• Behaves like a system utility — termdoc huge.log | head -5 dies with signal 13 like cat does, instead of panicking. In a pipe, stdout carries only the document
• Unicode-aware layout — grapheme clusters, CJK widths, combining marks and ZWJ sequences. No line exceeds the width in display cells, and none ends in trailing spaces
• Layered detection — magic bytes, extension, structure and delimiter sniffing each propose a format with a confidence and a reason. termdoc --explain prints every opinion, including the losing ones
• Encoding resolved once — BOM, then UTF-8 validation, then statistical detection. A latin-1 file renders with its accents, and no reader ever decides how bytes become text
• Tables that fit — width allocated across columns, degrading box-drawing → ASCII → TSV rather than truncating data
• Architecture enforced by the compiler — a reader cannot see a backend, because Cargo’s dependency graph does not contain that edge. A test reads the manifests and fails if one appears
• MIT OR Apache-2.0 — no telemetry, no network calls, no lock-in

install

# from crates.io
$ cargo install termdoc

# or a prebuilt binary — macOS · Linux · Windows
$ github.com/marturojt/termdoc/releases/latest

# then point it at anything
$ termdoc README.md
$ termdoc --explain odd.dat
$ cat README.md | termdoc

# Homebrew, AUR, Scoop — planned

Prebuilt binaries for macOS (universal), Linux (x86_64 and aarch64) and Windows are attached to every release, with SHA256SUMS.txt covering each archive — and CI unpacks and runs every one of them before the release is drafted. Building from source needs a Rust toolchain (rustup.rs). A Homebrew formula is still on the backlog.

what termdoc is not

• Not an editor — it never writes to the document
• Not a converter, though a Markdown backend is planned for piping
• Not an IDE, and not a syntax-highlighting playground
• It never shells out to an external application to display a file
• No telemetry, no analytics, no network calls of any kind

status

• M0██████████Markdown, plain text, logs — complete
• M1███░░░░░░░data and code: detection and encoding landed, readers next
• M2░░░░░░░░░░the interactive pager
• M3░░░░░░░░░░HTML, DOCX, ODT, RTF, EPUB, PDF, images
• M4░░░░░░░░░░plugin host and SDK
• M5░░░░░░░░░░PPTX, XLSX, Jupyter, SVG, math

Readers exist for Markdown, plain text and logs. Detection recognises considerably more — JSON, YAML, TOML, XML, HTML, CSV, source code, PDF and the Office/ZIP family — and until each dedicated reader lands, a recognised-but-unreadable text format is shown as plain text with a warning on stderr. --strict turns that warning into an error.