Getting started

The few ideas you need to reason about devpage — documents and their kinds, the folder they are served from, live pages, diagrams, widgets and comments. It sits under the devpage landing page; the viewer explains each part in depth, and Your first site, doc and deck walks all of it end to end.

Six ideas

A document is one of four kinds — A site, doc or deck is Markdown plus a small YAML file whose kind names it; a lone Markdown file is a doc on its own. A design is one .design file, with no document file, drawn on a canvas.
A folder is what is served — Usually the top of your repository; addresses are file paths, so links work as on disk.
A site's sidebar is its Topics — Each page lists its children in ## Topics; a doc has an outline, a deck its keys.
The page you see is the file on disk — No build step; a save swaps every open page in place.
Fences become diagrams, tags become widgets — Mermaid drawn in the page's theme; capitalized tags are React widgets.
Comments are notes, not docs — One file per thread in .devpage/, which git ignores; resolving deletes it.

How they fit

flowchart LR
  yml["Document file<br/>kind"] --> pages["Markdown files"]
  pages --> view["Site, doc or deck<br/>in the browser"]
  save["A save"] -.->|"live update"| view
  view <--> comments["Comments<br/>.devpage/"]
  design[".design file"] --> canvas["Design on its<br/>canvas page"]
  design -->|"embedded"| view
  save -.->|"patch"| canvas
  click yml href "./boxes/viewer/writing-a-document/README.md#the-document-file" "The document file"
  click pages href "./boxes/viewer/writing-a-document/markdown-that-works/README.md" "Markdown that works"
  click view href "./boxes/viewer/README.md" "The viewer"
  click save href "./boxes/viewer/live-updates/README.md" "How open pages stay current"
  click comments href "./boxes/viewer/comments/README.md" "Comments"
  click design href "./boxes/viewer/designs/README.md" "Designs"
  click canvas href "./boxes/viewer/designs/README.md#viewing-a-design" "Viewing a design"

Where next

Documenting another repository — Giving a real project's docs a devpage.yml.
Writing a document — the four kinds, the document file, the served folder, links, and the Markdown that works.
Writing a doc and Making slides — chapters, slides and paper.
Designs — a UI an agent writes as code, clicked through as a prototype, embedded in a page, and fetched as a PNG.
Comments — commenting, and the files threads are kept in.
Organizing navigation — how Topics sections shape the sidebar and the reading order.
Diagrams and Themes — Mermaid diagrams, and the light and dark themes.
Configuration reference — every field of each kind, and the command line, exactly.

Topics

Your first site, doc and deck — from an empty folder to pages that update while you edit them.