termdoc

what it looks like

Release notes

A universal document viewer for the terminal, 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.

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

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

# Homebrew, AUR, Scoop, static binaries — planned

Requires a Rust toolchain (rustup.rs). Prebuilt binaries and a Homebrew tap are on the backlog. Runs on Linux, macOS and Windows — all three are covered by CI.

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.