BBS-MD

What This Is

A retro-styled terminal markdown viewer that renders a vault of interconnected markdown files as browsable pages in a ratatui TUI. It acts like a BBS — the binary is set as a user's login shell so when someone SSHs in, they land directly in the markdown browser. Multiple users can connect and browse simultaneously.

Core Value

Users can connect via SSH and seamlessly browse a vault of linked markdown documents with retro BBS aesthetics — no shell, no commands, just content navigation.

Requirements

Validated

✓ Rust binary with ratatui dependency — existing
✓ Cargo project scaffolded (edition 2024) — existing

Active

Render markdown files as styled terminal pages (headers, bold, lists, code blocks, tables)
Support [[wiki-links]] and standard [markdown](links) between documents
Web-like navigation: follow links, go back, history
Landing page via index.md as entry point
Filesystem watching for live content updates
Multi-user read-only access (concurrent sessions)
Retro BBS aesthetic (ANSI art, box-drawing characters)
Show [IMAGE: alt text] placeholders for images
Vault-relative link resolution (links resolve to .md files in vault)

Out of Scope

Embedded SSH/telnet server — the OS SSH daemon handles connections, this is just a terminal app
Write/edit capabilities — read-only viewer
User authentication or identity — the SSH daemon handles auth
Mobile or web frontend — terminal only
Image rendering beyond placeholders — no sixel/kitty graphics

Context

Existing Rust project with ratatui 0.30.0, crossterm backend, anyhow for errors
Early stage — currently just scaffolding with hello world
The binary will be configured as a user's default shell in /etc/passwd or sshd config
Multiple SSH connections = multiple independent processes, each running the same binary against the same vault directory
Vault is a directory of .md files, structure defined by the content creator
Filesystem watching means the app picks up new/changed files without restart

Constraints

Runtime: Rust with ratatui — already chosen and scaffolded
Transport: Pure terminal app, no networking code needed
Rendering: Must work in standard VT100-compatible terminals
Concurrency: Read-only access, so no file locking needed between sessions
Entry point: Must handle being launched as a login shell gracefully

Key Decisions

Decision	Rationale	Outcome
No embedded SSH server	App is a login shell, SSH daemon handles transport	— Pending
Both wiki-links and markdown links	Maximum compatibility with existing vaults	— Pending
Filesystem watching over manual reload	Content should feel "live" like a web server	— Pending
index.md as landing page	Familiar convention, vault author controls the experience	— Pending
Read-only, no auth	Simplicity — SSH daemon handles access control	— Pending

Last updated: 2026-02-28 after initialization

3.1 KiB Raw Blame History