undocumented

The reader as static files, for any static host: the pages prose . serves, written out by the same renderRoute (server.ts), not a second site. It publishes one commit, HEAD, as the public repository shows it: git archive exports the committed, tracked files into a temporary folder and the pages are rendered from there, so no untracked scratch file, no .env and no ignored output can reach the site, and uncommitted edits don’t either (it warns about them). The live parts drop out, and the bar says which commit it is. The same commit always gives the same bytes.

The command: serve a repository and open it in the browser (spec §4); as prose build, write the same pages for a static host (build.ts); as prose publish, commit them to a branch a host deploys from (publish.ts). No config, and only the few flags a person would reach for: a port, not opening the browser, where a build goes, and a published site’s branch and domain.

Code is highlighted on the server with shiki, through shiki/core and only the languages a repository here is likely to hold, not the full bundle of every grammar. The theme is shiki’s CSS-variables theme: each token’s colour is a variable, set in style.ts for light and for dark, so code and page share one palette and follow the reader’s setting without a second render. The highlighter is created on first use and kept for the life of the server.

The package’s library surface. The commands are prose [dir], prose build and prose publish (cli.ts, spec §4); the same server, build, publish, parser and tree walk are exported for anyone who wants that view of a repository in code.

undocumented

The names a chunk of JS or TS declares at its top level, which is what a chunk’s anchor is made from (spec §3.2): export function addTodo anchors as #addTodo. The names come from oxc-parser’s AST, not a regex: the regex versions this replaced each missed the next shape a real file used (imports, then destructuring), which is the predictable failure of matching text instead of parsing it (docs/lessons.md).

undocumented

Turns one source file’s text into its file prose, preamble and chunks (spec §3.2): find the @prose comments (each language its own way, §3.1), then slice the code between consecutive comments into chunks. Each chunk keeps its comment’s byte span, so a renderer can lay the file out in source order with the prose where the comment was.

undocumented

prose build, committed to a branch a host deploys from: prose by default, an orphan branch holding only the site. It never checks the branch out or touches the working tree, the index or HEAD: the pages go through a temporary index into git write-tree, git commit-tree puts the tree on the branch’s last commit, and git update-ref moves the branch, only if it’s still where it was read. It doesn’t push; git push origin prose is a separate step, so nothing leaves the machine unasked. A build is byte-identical for the same commit, so a publish commit holds only the pages that changed, and a publish that changes nothing makes no commit.

The rail on the left of every page: the repository’s folders and files, as an editor’s explorer shows them, folders first. It’s built from the walk’s file list alone, with no file read, so it costs nothing per page beyond its HTML. Each folder is a <details>, open when the current page is inside it, so the tree works without script; the page’s script remembers which folders a reader opened, and where the rail was scrolled, across pages (render.ts).

Turns the tree’s nodes into the renderer’s pages (spec §4.1): a folder, a Markdown file, a source file read as one document, or a plain text file. Every function returns a complete HTML string; nothing runs in the browser but the few lines in page. Markdown goes through markz, the same parser in files and in prose blocks, and code through highlight.ts.

undocumented

A small read-only HTTP server on a repository (spec §4). It renders each page when it’s requested, from the files on disk, and caches nothing but the highlighter, so what it shows is always the working tree. It binds to loopback, serves only files the walk lists, and writes nothing.

The file tree on the left, then one readable column, light and dark from the reader’s setting. Prose is the page and code is the aside: code sits folded in a quieter panel, so a file reads as its prose first. Every page shares one centre line: prose keeps the reading measure, and code runs widen to 100 columns, oxfmt’s print width, equally on both sides, so code wraps only on a narrow window and prose never moves between a doc and a source file. Below 52rem the tree hides behind the Files button, over the page, and the editor link goes.

undocumented

Walks a repository into a tree of folders and files (spec §4), each with its summary: a folder’s from its README.md, a Markdown file’s from its first paragraph, a source file’s from its file prose. A source file also carries its text and its blocks, so a renderer can lay it out as one document. docs/ is an ordinary folder here (spec §3.4).