Landing site

Building the exocomp.dev landing page together with the rendered docs bundle, with podman or with a CI toolchain, and the Cloudflare build that publishes them.

site/ holds the landing page and renders this bundle into a wiki that is served beside it under /docs/. One build produces both halves, and the result is what gets published.

What the build produces

dist/ is build output: it is untracked, regenerated whole on every build, and never hand-edited. The render copies the pinned mermaid runtime into dist/docs/vendor/, because this bundle has diagrams and a render that would fall back to a public CDN is an error rather than a quiet downgrade.

Two renderers, one output

site/build.sh renders with whichever of these is available:

site/toolchain.sh produces the second renderer for a host that has neither podman nor a published binary: go install for github.com/abn/okf-wiki/cmd/okf-wiki into site/.toolchain/bin/, then the same pinned mermaid bundle the image bakes, built with npm and esbuild from that module's source. It needs Go 1.25 or newer and Node with npm, and it writes only to site/.toolchain/, which is untracked. build.sh runs it on its own when neither renderer is present, so a CI build command is just the build script.

make site/build     # renders and assembles site/dist/
make site/serve     # builds, then serves site/dist on :8788 (SITE_PORT=)
site/toolchain.sh   # only to install the renderer ahead of a build

site/serve runs wrangler dev, which reads the same config the deployment does. A plain file server would ignore _headers and _redirects, and a preview that ignores them is not a preview of the deployment; on a host with no Node, python3 -m http.server -d site/dist is enough to read the pages.

Publishing to Cloudflare

The site is the Worker exocomp, serving exocomp.dev as static assets with no script. site/wrangler.toml names the build output — [assets] directory = "./dist" — and wrangler deploy uploads that tree, _headers and _redirects included. The Worker's name in the dashboard must match the config's name.

cd site && npx wrangler deploy   # local deploy; needs `wrangler login`

The Git-connected build lives under the Worker's Settings → Build:

The root directory has to be site and not the repository root: it is both where the build command runs and where the deploy command reads this config from. Set GO_VERSION as well — the build image defaults to Go 1.24.3 and the renderer's module asks for 1.25, so without it every build spends a minute downloading a newer toolchain first. exocomp.dev is added under the Worker's Domains & Routes.

A Workers Builds run is two commands in one environment: the build command in the root directory, then the deploy command, each on a fresh Ubuntu 24.04 sandbox per push. That sandbox has Go and npm but no container runtime, which is why the build renders with a standalone binary and installs its toolchain itself. The output path is not a dashboard field: the deploy command takes it from [assets] directory, so the build command only has to finish writing dist/ before the deploy command starts.