readm3.com, built by the reader it documents

readm3 is our terminal markdown reader. File browser on the left, rendered document on the right, nothing else in the way. It has been on npm since the end of August. It now has a website, and the interesting part is how the website is built.

Every rendered document on readm3.com went through renderMarkdown, the same function the reader calls when you open a file. Nothing was reimplemented for the web, and there is no screenshot anywhere on the page. The docs page is the project README, parsed at build time by the version of the parser that shipped with the release. If the parser breaks, the page breaks, and CI runs the site build on every pull request so that failure lands in the PR instead of the deploy.

That was possible because of a decision made early in the codebase. renderMarkdown returns lines of spans that carry a semantic role (h1, code, link, quote) rather than a color. A theme turns roles into colors at the very end. In the terminal that is what lets --theme nord re-color a document without re-parsing it.

On the web the same property falls out for free. The build emits each span with its role as a class, then generates one CSS variable block per HQTUI theme by reading the real theme objects. The nine buttons on the page set data-theme, the variables swap, and the document re-colors. No JavaScript touches the text. It is the terminal behavior, running in a browser, for about thirty lines of CSS.

Some numbers from the build. The whole site is 96K of static output. It has no dependencies beyond HQTUI, which the package already depended on. The build script is one file. The server is another, sixty lines of Bun serving files.

The site runs on Railway behind a Dockerfile, apex and www at Porkbun. Both certificates issued within a minute of the DNS going in, which happens when you remember that Railway wants a _railway-verify TXT record per domain and that www gets its own token. Forgetting that is how a domain sits in validation for an hour with perfectly correct CNAMEs.

Install it:

bun add -g @profullstack/readm3
npm install -g @profullstack/readm3

Then run readm3 in any directory with markdown in it, or readm3 --print FILE to use it as a cat for markdown in a pipe.

Site: https://readm3.com
Source: https://github.com/profullstack/readm3

This post was drafted with AI assistance.