Cloudflare workflow
Cloudflare Pages hosts the static reader, not the optional Node editor. Match the connected project to the repository that actually exists: full build inputs or pre-rendered output. A wrong output root can publish source files, miss assets or show an unrelated index.
This is current documentation guidance, not a change to your Cloudflare account. Inspect the existing project’s production branch, root, build command, output and domains before changing it. A repository connection alone is not authorization to release.
Repository choice
| Shape | Host work |
|---|---|
| Source project | Install, test, build selected MarkStack source |
| Rendered repository | Serve approved generated bytes; no MarkStack generation |
| Mixed, unknown | Inspect actual tree, settings before selecting |
Source shape contains builder, package, lockfile, config, content, static and templates. Its output is dist unless your reviewed build selects something else. Node 24+ is required by this pin. Explicitly select the intended supported numeric version in Pages; current build-image docs do not promise package engines detection.
Rendered shape contains only home/page HTML, 404, index, CSS/JS/fonts/media/notices and supported host files at its selected publishing root. A blank framework preset/None and exit 0 make sense for no-build static output, with the actual containing folder as output. These settings are not for a source repository that needs generation.
Revision and environment
| Item | Review |
|---|---|
| Production branch | Which commits trigger public deployment |
| Preview branches | Who can see resulting artifacts |
| Root | Actual project, build working directory |
| Node | Explicit supported numeric selection |
| Build | Fail on install, test, build errors |
| Output | Generated public artifact, never checkout, private data |
| Config | Final origin, path and effective runtime inputs |
The engine does not automatically use CF_PAGES_URL as siteUrl. A build-generated preview can retain production metadata or authored root links. Do not claim every preview address becomes its canonical address automatically.
Use selected engine/lockfile and keep asset versions coherent. A host’s successful exit 0 reports build success; it does not mean the command tested your links or content. Inspect provider logs/status and actual artifact. Do not add secrets/private runtime to a connected public source repository merely to make a build find settings.
Review before production
- Prepare a reviewed local/staging artifact and route map.
- Confirm intended branch/project/output and what a push will trigger.
- Preview the exact content/index/resources and intended audience.
- Review source/config/host-rule diffs and old-route policy.
- Release through the established approval/deployment process.
- Verify Pages deployment status, observed URL and current live bytes.
The handbook’s prescribed writing order does not change existing routes. A navigation-only reorder still changes generated shared page HTML and needs a coherent reviewed artifact. Avoid publishing a fresh index that points at pages not deployed yet, or new pages with old search/navigation left indefinitely.
Routes, 404 and redirects
| Layer | Cloudflare behavior |
|---|---|
| HTML matching | Serves matching path; normalizes HTML to extensionless route |
| Directory page | index.html can redirect to directory slash path |
| Missing route | Nearest custom 404 up the directory tree |
| No top-level 404 | SPA fallback assumption, unsuitable here |
_redirects |
Ordered host file, one rule per line |
| Functions | File redirect, header rules do not cover Function-served requests |
Keep generated top-level 404.html in the artifact. Test status/content rather than using a blanket 200 home rewrite. Current reader generates ordinary directory pages and search targets, not a client-side SPA route handler.
Host redirect rules belong in reviewed static/_redirects so the builder copies them to output root, or in pre-rendered output before approved publication. Format is source, destination, optional status; default is 302. Use explicit 301/302 with a reviewed intent and target, not an untested catch-all.
Cloudflare’s rules match source paths, not browser fragments. Redirects take precedence over _headers; Functions have separate behavior. 200 same-site rewrite does not proxy arbitrary external domains, and only first matching redirect applies. The file is not nginx/Caddy/Apache syntax.
Headers and cache
| Concern | Boundary |
|---|---|
_headers |
Host response rules for static requests |
| CSP | Must fit stock inline state scripts and local resources |
| Cache | Default Pages policy versus custom zone rules |
| Privacy | Access gate, not noindex or hidden navigation |
| Artifact freshness | Actual new bytes, deployment and fresh browser |
A default-src-self-only CSP example copied blindly can block stock inline initialization. Design/test a policy against the actual pin/template; editor CSP is not automatically a reader response policy. Do not weaken security merely to silence errors or claim a policy is correct without browser checks.
Current serving docs recommend avoiding unnecessary custom caching. Custom rules can serve stale assets and interfere with redirects/Functions. Preserve query-versioned resources coherently and inspect requests after deploy. Cache purge is an operator action to the selected zone, not part of ordinary Markdown build.
Domain and completion
Add custom domain through the actual Pages project before manually pointing a hostname at its observed Pages target. Apex and external-DNS subdomain paths differ; DNS setup and Cloudflare setup detail the workflow.
A push/deployment success is progress until the public URL is checked. Verify home/deep reload, current search target, fonts, diagram, download, unknown path, canonical redirects and cache. Retain previous deployment/artifact and actual rollback route. No provider account/branch/domain setting or production rollback is claimed tested by this guide.
Official sources
Checked 12 October 2026: