Writing a document

How to write a devpage document: the four kinds and when to use each, the document file that describes one, and the folder devpage serves from. How pages link to each other and which Markdown renders are on their own pages, below. It is a task article under the viewer; read Getting started first for the mental model.

Four kinds

A system's documentation is a site. A design doc, a PRD or a proposal is a doc. A talk is slides. A screen or a flow an agent proposes is a design. The first three are Markdown files on disk, render the same Markdown, take comments and are checked for broken links; a doc and a deck also print to PDF. A design is not Markdown and has no document file: its .design file is the whole document, and a page embeds it with ![Name](name.design) — see Designs.

The document file

A site, a doc or a deck is described by one YAML file. Its kind says which of the three it is, and the rest of its fields follow from that:

kind: site              # a site of pages
title: devpage          # its name, shown in the sidebar and the tab
root: README.md         # the page it opens on

kind: doc
title: Sync design
chapters: [context.md, design.md, rollout.md]

kind: slides
title: Launch
slides: [intro.md, problem.md, demo.md]

The file can have any name. devpage.yml is the one devpage looks for when it is given a folder, so name it that unless a folder holds several documents. Paths in it are relative to its folder. A change to a document file takes effect on the next request; there is nothing to restart. Every field, its type and its errors are in the configuration reference; a doc's chapters and PDF settings are on Writing a doc, a deck's slides on Making slides.

A single Markdown file needs no document file. devpage design.md serves it as a doc of one chapter, titled by its # heading, with the default PDF settings. Give it a document file when it grows chapters or needs a header or footer on paper.

The served folder

devpage serves from the served folder: the folder you start it from, or the one --root names. Start it from the top of the repository and the whole repository is served, whichever document you open:

cd my-project && devpage docs              # serves my-project/
devpage --root ~/code/my-project ~/code/my-project/docs

The document you start devpage with must be inside the served folder. A file's address is its path from the top of the served folder: docs/boxes/viewer/README.md is served at /docs/boxes/viewer/README.md, and / leads to the document devpage was started with. A folder has no address of its own; link to a file in it instead.

A page's title — shown in the browser tab — is its first line that starts with # ; a page without one is titled with its file name. Start every page with # Title so the tab reads well.

Documenting another repository

devpage serves any repository's Markdown, not only its own. Give the other repository a document file — usually docs/devpage.yml with kind: site — and start devpage from that repository's top:

cd ../my-project && devpage docs                  # the folder holding devpage.yml
devpage --root ~/code/my-project ~/code/my-project/docs/devpage.yml

Pages can link anywhere in the served folder, so the docs can stay in docs/ and still link to the top-level README.md or to images beside the code.

Several at once. Each devpage process serves one folder and takes the first free port from 3030 up. Read the port from the line each one prints:

$ devpage docs
devpage → http://localhost:3030
$ devpage ../my-project/docs
My project → http://localhost:3031

How a request becomes a page is explained in Serving pages.

Topics

• Links between pages and documents — what a link to a page, a document file or a heading opens.
• Markdown that works — the GitHub-flavoured features, code blocks, images and other files.