devpage

devpage renders the documents a software project lives by — a site of system docs, a design doc or PRD, a slide deck — from Markdown files in the repository, and designs of its UI from .design files, live: point it at a document, open the address it prints, and every page you have open updates the moment its file is saved — by you or by an agent. These pages are devpage's own documentation, served by devpage.

What devpage does

Extended Markdown — GitHub-flavoured Markdown with raw HTML allowed, highlighted code, and mermaid fences drawn as diagrams whose nodes link to other pages.
Light and dark — A light and a dark theme the reader can switch between.
Widgets — React components used as HTML tags in Markdown: callouts, tabs, file trees, examples, terminals, keycaps, steps and cards ship with devpage; a project adds its own as .tsx files.
Designs — A UI an agent writes as code, a .design file in JSX syntax over Figma's node model: drawn on a canvas, clicked through as a prototype, embedded in any page, and fetched as a PNG so the agent can see its work.
Live updates — A file's change refreshes every open page in place, without a reload.
Comments — Turn on comment mode, then select text or hover a paragraph; threads are files in a .devpage/ folder git ignores, so an agent can read and resolve them.
Checked links — Broken links show on the page while you write, and devpage check fails a test on them.
PDF — devpage pdf prints a doc or a deck exactly as the browser shows it.
Video — devpage video records a deck to mp4, each slide's notes read aloud by GPT-Live.
Local or deployed — On your machine, or for a team behind the auth proxy you already have.

flowchart LR
  md["Markdown files"] --> devpage
  designs[".design files"] --> devpage
  devpage --> browser["Browser"]
  md -. "a save" .-> browser
  browser <-->|"comments"| store[".devpage/"]
  devpage --> pdf["PDF"]
  click md href "./boxes/viewer/writing-a-document/README.md" "Writing a document"
  click designs href "./boxes/viewer/designs/README.md" "Designs"
  click devpage href "./boxes/viewer/README.md" "The viewer"
  click store href "./boxes/viewer/comments/README.md" "Comments"
  click pdf href "./boxes/viewer/pdf/README.md" "Printing to PDF"

What devpage may become beyond this is on the vision: ideas, not commitments. How these docs are laid out is on the system catalog.

Contributors

Andrei Puni — author.
Radu Marias — clickable Mermaid diagrams: nodes that act as links, highlighted on hover.

Topics

Start here

Vision — what devpage is for and where it is going. Ideas, not commitments.
Installing devpage — cargo install devpage, what PDF printing needs, and running it.
Getting started — the mental model, and a first site, doc and deck run end to end.

The system

System catalog — how devpage works, one subject per folder.
General constraints — the rules every change is reviewed against.