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.