Configuration reference

The exact contract of a devpage document file and of the devpage command line: every field of each kind with its type, default and validation, the commands and flags, and the errors devpage stops with. It is the reference page under the viewer.

Command line

devpage [path] [--root <folder>]
        [--host <address>] [--port <port>] [--user-header <name>] [--no-comments]
devpage check [path] [--root <folder>]
devpage pdf <path> [--root <folder>] [-o <file>]
devpage video <path> [--root <folder>] [-o <file>]
devpage --help
devpage --version

path is read the same way by every command:

Flags

Environment variables

Only devpage video reads any, and only these — never OPENAI_API_KEY (the narrator). A variable set to an empty string counts as not set.

On start, devpage checks the document is inside the served folder, watches it, binds its address and prints one line on standard output — the entry document's title and its address:

<title> → http://localhost:<port>

It then logs every request on standard error (see Serving pages) and each link problem once, as it is found. It runs until stopped. Changes to document files and pages take effect on the next request; nothing needs a restart.

Document files

A document file is a YAML mapping whose kind field says what it describes. Paths in it are relative to the file's folder and must stay inside the served folder. A field the kind doesn't have is an error, not ignored.

site

A site's pages are the Markdown files in its document file's folder and below it; a page there is shown in this site's frame. When sites are nested, a page belongs to the nearest one.

doc

In header and footer, {page} is the page's number and {pages} the count.

A .md file given instead of a document file is a doc whose one chapter is that file, titled by its first # heading (or its file name), with every pdf default.

slides

Errors

devpage stops before serving when the entry document can't be loaded. It prints Error: and what it was doing — reading <file> or in <file> — then the cause:

Loading the document

Binding the address

After it starts

Once devpage is serving, an edit that makes the entry's file invalid doesn't stop it either: / and the site's pages show the problem until the file is fixed, and the last valid version is kept meanwhile. The same problems in a document file reached by a link don't stop devpage: they are problems, shown on the pages that link to it and reported by devpage check. devpage pdf also stops with pdf prints a doc or slides, not a site when given a site, and with the error downloading chrome-headless-shell into <cache folder> when the first download of its Chrome fails, and with pdf prints a doc or slides, not a design when given a design.

devpage video stops, before it starts Chrome, with video needs GPT-Live: set DEVPAGE_OPENAI_API_KEY, or DEVPAGE_AZURE_OPENAI_ENDPOINT and DEVPAGE_AZURE_OPENAI_API_KEY when no narrator is set, DEVPAGE_AZURE_OPENAI_ENDPOINT is set but DEVPAGE_AZURE_OPENAI_API_KEY is not, DEVPAGE_AZURE_OPENAI_ENDPOINT is not an address: <endpoint>, video records slides, not a site (or a doc, a design), and every slide needs <Notes> to be narrated; these have none: <n> (<file>), …. Once running it stops with downloading chrome-for-testing into <cache folder> when the first download of its Chrome fails, connecting to GPT-Live at <address> when the session can't open (a wrong key is HTTP error: 401 Unauthorized), with the error GPT-Live sends as GPT-Live: <message>, and with the narrator said nothing for slide <n> within 60 seconds. It writes no file unless the whole deck was recorded.

A design's problems never stop devpage, even when the design is the entry: its canvas shows them over the last valid drawing, and devpage check prints each as <file>:<line>:<column>: <message> and exits 1.

Examples

devpage's own documentation, docs/devpage.yml:

# devpage's own documentation, served by devpage.
kind: site
title: devpage
root: README.md
widgets: widgets
watch:
  - "**/*.md"
  - "**/*.yml"

The feature catalog shows the doc kind and the devpage talk the slides kind; each devpage.yml is beside its chapters or slides. The checkout prototype shows the design kind, which has no document file (devpage docs/designs/checkout/checkout.design).