The website

How the public landing page and these docs are built into one static site, checked locally, refreshed and deployed with Cloudflare Workers Builds.

The public site is one directory of static files: a hand-written landing page and this docs bundle rendered under /docs/. Everything lives in site/, and nothing is deployed from this repository by a command. Publishing is the owner's decision.

Path What it is
site/index.html, site/404.html The landing page and the not-found page, plain HTML with no inline script or style
site/assets/ The stylesheet, the theme switch and tour scripts, the self-hosted fonts, the screenshots and the Open Graph image
site/docs-theme/ The okf-wiki theme for /docs/: the app's colours and faces, and a link back to the landing page
site/_headers Response headers, including the content security policies; the build fills in the docs' script hashes
site/wrangler.jsonc The Cloudflare Worker nocturne: static assets only, serving site/dist/, with the empty previews block pull request builds need
site/toolchain.sh Builds the docs renderer from source for a host with no container runtime
site/brand/ The sources of the social card and the touch icon; not deployed
site/scripts/ The build, a local server that applies _headers, the checks, the screenshot capture and the brand images

Build

make site                                  # writes site/dist/
make site SITE_URL=https://example.org     # the origin for the canonical and Open Graph links

SITE_URL defaults to https://nocturne.is. make site renders docs/ with okf-wiki, then copies the landing page and its assets into site/dist/, fills in the site origin and the pinned Lemonade version from lemonade.lock, and writes site/dist/_headers.

Two renderers give the same output:

Renderer Used when
The pinned container image (OKF_WIKI_IMAGE, okf-wiki v1.2.0, run with podman and no network) podman is installed
The binary in site/.toolchain/ podman is missing, which is the case on a Cloudflare build image

site/toolchain.sh fills site/.toolchain/ (git-ignored). It downloads the okf-wiki v1.2.0 release archive for the host (the release the image carries), checks it against the sha256 values committed in site/okf-wiki.sha256, and unpacks the binary and the Mermaid bundle the docs' diagrams need. It needs only curl. make site runs the script by itself when podman is absent and the binary is not there yet, so the build command on Cloudflare is just make site. OKF_WIKI and OKF_WIKI_VENDOR name a different binary and Mermaid bundle. To move the pin, change VERSION in toolchain.sh, replace okf-wiki.sha256 with that release's checksums.txt, and move OKF_WIKI_IMAGE to match.

Check

make site/serve                            # http://127.0.0.1:4180 with the headers applied
make -C site check                         # axe, policy errors, 360 px, keyboard, screenshots

The check runs axe on the landing page and on docs pages in both themes at 1440 and 390 px, fails on any console or policy error and on sideways scrolling, tabs to the theme buttons, and confirms the theme chosen on the landing page carries into the docs. A few findings come from markup the renderer writes itself (linked section titles in the sidebar, wide tables, the search button); they are reported as warnings because the theme cannot change them.

Screenshots

The screenshots are the app's own screens on its demo data. The desktop pictures crop to the column where the page changes, so the reader does not have to spot the difference between two full windows. The capture writes only the pictures the pages use. To refresh them, run the mock interface, and for the phone picture the phone app's scripted build, and capture again:

cd ui && npx vite --mode mock --port 4173  # in another terminal
cd ui && VITE_ENGINE=phone-mock PHONE_OUT_DIR=/tmp/phone npx vite build --config vite.phone.config.ts
python3 -m http.server -d /tmp/phone --bind 127.0.0.1 4174   # in another terminal
make -C site shots PHONE=http://127.0.0.1:4174   # writes site/assets/img/*.webp in both themes

make shots prints where the highlighted part of each tour picture sits. When a recapture moves it, copy the numbers into that step's data-mark in site/index.html.

On wide screens, when the reader has not asked for reduced motion, assets/js/tour.js turns the Keep, Ask and morning page steps into one still frame beside the text: as each step reaches the middle of the screen only the page in the frame cross-fades, and a short highlighter pass shows where to look. Without the script, with reduced motion or on narrow screens, each step keeps its own picture.

Brand images

The mark is the app icon, a half moon on a dark tile, and site/favicon.svg draws it. Every other brand image derives from it or from the morning page screenshot, and make -C site brand renders them all again with a headless browser:

Image Source Used by
docs/assets/social-preview.png, 1280 x 640 site/brand/card.html The repository's social preview
site/assets/img/og.png, 1200 x 630 site/brand/card.html The link preview of the landing page, the install page and every docs page
docs/assets/logo.svg and logo.png, 512 x 512 A copy of site/favicon.svg The README header
site/apple-touch-icon.png, 180 x 180 site/brand/touch-icon.svg, the icon without rounded corners Phones and tablets, which round it themselves
site/favicon-32.png site/favicon.svg Browsers that cannot show an SVG favicon

The card sets the landing page's headline and its one-line description on the dark theme, beside the light morning page with demo data, in the faces the site ships. Its words, its mark and its address stay inside the central 1100 x 540, clear of the edges GitHub crops on some pages. Change the card when the landing page's headline changes, and render it again after make shots refreshes the morning page.

GitHub does not read the social preview from the repository: after a change, upload docs/assets/social-preview.png under the repository's Settings, General, Social preview. The docs theme adds the Open Graph image through its head slot (site/docs-theme/head.html), and the build fills in the site origin there as it does on the landing page.

Deploy

The site is the Worker nocturne, static assets only, built by Cloudflare Workers Builds from this repository. The Worker's name in the dashboard must match name in site/wrangler.jsonc. Under the Worker's Settings, Build:

Setting Value
Production branch main
Root directory site
Build command make site
Deploy command npx wrangler deploy
Preview command npx wrangler preview

The root directory is site because it is where the build command runs and where the deploy command finds wrangler.jsonc. The output path is not a dashboard field: the deploy command takes it from assets.directory, so the build only has to finish writing dist/ first. The build image has curl and make but no container runtime, which is why it renders with the binary from toolchain.sh.

Pull request builds run npx wrangler preview, which serves the branch at a preview address and never touches production. It reads its own previews block and refuses to run without one; every setting here is top level, so the block is empty.

nocturne.is is attached under the Worker's Domains and Routes. flatpak.nocturne.is is not part of this Worker: it is a separate proxied CNAME record that points at GitHub Pages, which serves the Flatpak repository (see The Flatpak).

A local deploy is make site and then npx wrangler deploy from site/, after wrangler login.

What the page may say

The landing page claims only what the app does today. When a feature, a platform or a release changes, change the page with it: no download button until a release exists.

Connections

Local graph

Linked from