devpage features

Four kinds of document

A YAML document file's kind says what a folder of Markdown is: a site of pages with a sidebar, a doc of chapters read as one page — like this one — or a deck of slides. The fourth kind, a design, needs no document file: a .design file is the whole document.

kind: doc
title: devpage features
chapters: [kinds.md, designs.md, markdown.md, widgets.md]

Teaches it: Writing a document.

Designs

A UI an agent writes as code: one .design file per design, in JSX syntax over Figma's node model, composed by import with props. devpage draws it on a canvas at its own size — on the GPU — and a reader clicks through it as a prototype. GET checkout.design.png hands the agent the same drawing as a PNG, so it can look at its work before anyone else does.

// button.design
// A button: one line of text on a filled, rounded box.
<Frame props={{ label: "Button", fill: "#2563eb" }}
       layout="row" padding={[12, 20]} radius={8} fill={fill}
       justify="center" shadow={{ y: 2, blur: 6, color: "#1e3a8a33" }}>
  <Text size={16} weight={600} color="#ffffff">{label}</Text>
</Frame>

Teaches it: Designs.

Markdown and diagrams

GitHub-flavoured Markdown with raw HTML and highlighted code, and mermaid fences drawn as diagrams whose boxes are links.

Kind Like
site a docs website
doc a Word document
  • tables, task lists, footnotes
flowchart LR
  md["Markdown"] --> page["A page"]
  click page href "/docs/boxes/viewer/diagrams/README.md" "Diagrams"

Teaches it: Markdown that works, Diagrams.

Widgets

React components written as tags in Markdown. devpage ships Callout, Tabs, Example, FileTree, Terminal, Keys, Steps, Cards and Diagram; a project adds its own as one .tsx file each, with no build step.

Its content is Markdown.

Teaches it: Widgets.

Live updates

Save a file — by hand or by an agent — and every open page swaps in the new version, in place, without a reload.

flowchart LR
  save["Save"] --> devpage["devpage"]
  devpage -->|"change"| pages["Every open page"]
  click devpage href "/docs/boxes/viewer/live-updates/README.md" "Live updates"

Teaches it: Live updates.

Comments

Turn on comment mode with the speech-bubble button by the theme toggle, then select text or hover a paragraph to comment. Each thread is a file in a .devpage/ folder git ignores, so an agent can read it and resolve it by deleting the file. Serve a public site with --no-comments to turn them off.

  • .devpage/
    • comments/
      • docs/design.md/
        • 20261025T181502Z-7f3a.yml — one thread

Teaches it: Comments.

Checked links

Every link, image, heading anchor and diagram target is checked: broken ones are marked on the page while you write, and devpage check fails on them.

$ devpage check docs
docs/README.md:3: broken link design.md — no such file

Teaches it: Checking links.

PDF

devpage pdf has Chrome print a doc or a deck exactly as the browser shows it: a doc on A4 with its header and footer — this catalog prints that way — and a deck one 16:9 slide per page.

$ devpage pdf docs/features
devpage features.pdf

Teaches it: Printing to PDF.

Notes and slide images

A slide carries its script in a <Notes> tag — the words said while it is up, never shown on it — with a delivery, how the slide should feel; a deck says who its audience is, its goal and its tone. Every slide is also a PNG at <deck file>/<n>.png, so an agent writing the notes can look at the slide it is writing for.

# Why devpage

<Notes>
Every team writes docs, and every team's docs drift from the code.
</Notes>

$ curl -o slide-3.png localhost:3030/talks/launch/devpage.yml/3.png

Teaches it: Making slides.

Video

devpage video records a deck to mp4: GPT-Live reads each slide's notes word for word, for the deck's audience and in its tone, while Chrome shows the slides — 1920 × 1080, no silence longer than a second.

$ DEVPAGE_OPENAI_API_KEY=sk-... devpage video talks/launch
slide 1/6
...
Launch.mp4

Teaches it: Making a video.

Deploying

Run devpage for a team behind the auth proxy you already have: it names each reader in a header, and comments are kept on a volume. A public site runs with --no-comments.

$ devpage docs --host 0.0.0.0 --port 3030

Teaches it: Deploying devpage.