Cloudflare Pages Deploys

How this docs site (and any future static site) builds and deploys — Astro project structure, the GitHub repo, Cloudflare Pages auto-deploy, and how Leif edits content.

How a static site gets from a Markdown edit to a live page. This docs site is the reference implementation: Astro project in GitHub, Cloudflare Pages watching main, Leif making the edits. The same shape applies to any future static site.

The short version

1. Leif edits Markdown under src/content/docs/ via github_* tools
2. The change lands as a commit on main in superhitech/leif-docs
3. Cloudflare Pages sees the push and runs the Astro build
4. dist/ is published to docs.leif.super-ht.com

No manual build step, no FTP, no server to log into. Push to main and the page is live a minute or two later.

Project structure

This site is Astro with the @astrojs/mdx integration. The pieces that matter:

Path	Purpose
`src/content/docs/`	All page content — Markdown / MDX, grouped by section folder
`astro.config.mjs`	Astro config — `site` URL and the `mdx()` integration
`package.json`	Scripts and pinned dependency versions
`dist/`	Build output (generated; not committed)

Each page is a Markdown file with frontmatter (title, description, order). Section folders (overview/, infrastructure/, patterns/, …) map to URL paths.

The repo

Field	Value
GitHub repo	`superhitech/leif-docs`
Production branch	`main`
Production URL	`docs.leif.super-ht.com`
Host	Cloudflare Pages

Cloudflare Pages is connected to the GitHub repo. A push to main triggers a production deploy; pushes to other branches produce preview deploys.

Build command and output

Standard Astro build — nothing custom:

Setting	Value
Install	`npm install`
Build command	`npm run build` (i.e. `astro build`)
Output directory	`dist/`
Local dev	`npm run dev` → `http://localhost:4321`

Cloudflare runs the install + build in its own CI environment and publishes the contents of dist/. You don’t run the build yourself for a deploy — that’s the point.

How Leif edits content

Most edits to this site happen through Leif rather than a local clone. The flow:

Wayne asks Leif to change or add a page
Leif reads the relevant files with github_get_file (and github_search_code to find them when the path isn’t known)
Leif writes the change with github_create_or_update_file, or moves / renames files with github_batch_move_files
The commit lands on main; Cloudflare Pages rebuilds and republishes

For larger drafting passes, content can be authored locally with create_file / write_file and then committed up — but the deploy trigger is always the same: a commit on main.

Because the build runs in CI, a bad edit doesn’t break anything until it’s pushed — and even then it only affects the docs site, not Leif itself.

Applying this to a new static site

To stand up another static site on the same pattern:

Create the repo under superhitech/ and scaffold the static generator (Astro or otherwise). Keep content in a predictable directory so Leif can find and edit it.
Pin dependencies to known-good versions. Match this repo’s discipline — reproducible CI builds beat latest-and-greatest.
Connect Cloudflare Pages to the repo: set the production branch (main), the build command, and the output directory for the chosen generator.
Point DNS — add the custom hostname in Cloudflare Pages and let it manage the record.
Wire Leif in by using the same github_* edit flow. Once Pages is watching the branch, every committed edit auto-deploys.

The reusable idea is: content in Git, build in CI, deploy on push. Leif only ever touches the repo; Cloudflare does the rest.

Architecture — where this site sits relative to Leif
Hosts — public hostnames including docs.leif.super-ht.com
Workflow Patterns — the rest of the repeatable workflows