Start here

What this is

The exact, working recipe behind nci-notes.pages.dev — reverse-engineered from the two live projects, not invented.

Read this if

You are an agent (or a human) who has been asked to "make a page like the NCI one" — a private, good-looking, multi-page HTML site, hosted on a *.pages.dev URL, rebuilt from Markdown or notes in a repo, deployable with one command, and optionally locked to a handful of e-mail addresses.

This guide is the real recipe, taken from two sites that are live right now:

Site	Project on disk	Pattern
`nci-notes.pages.dev` (e.g. `/interview-prep`)	`~/Documents/claude_projects/NCI`	Python generator → `site/` → staged `deploy/` bundle → wrangler
`nvidia-prep-dashboard.pages.dev`	`~/Documents/claude_projects/NVIDIA_JOB`	Hand-written `index.html` dashboard + `md2html.py` siblings → deploy the folder in place

Both sit on the same Cloudflare account and are deployed by the same command shape. Pick whichever pattern fits: the NVIDIA one if your content is already HTML/Markdown in a folder, the NCI one if pages must be generated from structured notes.

The whole thing in five lines

mkdir -p mysite && echo '<h1>hello</h1>' > mysite/index.html
npx wrangler@3 pages project create my-project --production-branch=main
npx wrangler@3 pages deploy mysite --project-name=my-project --branch=main --commit-dirty=true
curl -sI https://my-project.pages.dev/ | head -1     # expect: HTTP/2 200
# → live at https://my-project.pages.dev

Everything else in this guide is detail around those five lines: how to generate mysite/, how to gate it, how to move the credentials to another machine, and which four things reliably go wrong.

Prerequisites

Node + npx. Wrangler is never installed globally here — every command is npx wrangler@3 …, which pins v3 (3.114.17 at the time of writing) and avoids a v4 migration surprise mid-deploy.
A logged-in wrangler session. Check with npx wrangler@3 whoami. On this Mac mini it reports the account Theo.veyron.ai@gmail.com's Account, id 67fb71fdc571c92a35e2c0f24114dc71, and the token carries the pages (write) scope — that scope is the one that matters. If it is not logged in: npx wrangler@3 login (opens a browser), or carry the session over from another device using Move your keys between devices.
Python 3 only if you use the generator pattern. No third-party packages are required — both reference projects hand-roll their Markdown→HTML rather than depend on markdown.
No wrangler.toml is needed. Neither reference project has one. Pages deployments take all their configuration from command-line flags. Do not add one "for tidiness" — it changes how wrangler resolves the project and is a common way to break a working deploy.

The rule that shapes everything

Deliverables are hosted, not local. A file on disk that nobody can open from their phone has
not been delivered.

That is why every one of these projects ends in a pages.dev URL, and why the deploy step is a committed script in the repo rather than something a human remembers how to type.

Next: the recipe.

The recipe →