Cloudflare Pages¶

Every platform repo deploys its MkDocs site to Cloudflare Pages using the same build configuration. This page documents that standard setup.

Build settings¶

Setting	Value
Build command	see below
Build output directory	`site`
Root directory	`/` (default)

Configure these in the Cloudflare Pages project under Settings > Builds & deployments.

Build command¶

# Fetch hook and platform CSS locally, install deps, then build; fetching CSS locally prevents instant-navigation stylesheet flash
mkdir -p hooks docs/stylesheets \
  && curl -fsSL -o hooks/config.py \
     https://raw.githubusercontent.com/${PLATFORM_REPO:-rtsko/ireul}/${PLATFORM_VERSION:-main}/mkdocs/hooks/config.py \
  && curl -fsSL -o docs/stylesheets/platform.css \
     "${DOCS_CSS_URL:-https://ireul.pages.dev/platform.css}" \
  && pip install -r \
     https://raw.githubusercontent.com/${PLATFORM_REPO:-rtsko/ireul}/${PLATFORM_VERSION:-main}/requirements-doc.txt \
  && mkdocs build

Or for single-line format:

# Fetch hook and platform CSS locally, install deps, then build; fetching CSS locally prevents instant-navigation stylesheet flash
mkdir -p hooks docs/stylesheets && curl -fsSL -o hooks/config.py https://raw.githubusercontent.com/${PLATFORM_REPO:-rtsko/ireul}/${PLATFORM_VERSION:-main}/mkdocs/hooks/config.py && curl -fsSL -o docs/stylesheets/platform.css "${DOCS_CSS_URL:-https://ireul.pages.dev/platform.css}" && pip install -r https://raw.githubusercontent.com/${PLATFORM_REPO:-rtsko/ireul}/${PLATFORM_VERSION:-main}/requirements-doc.txt && mkdocs build

PLATFORM_REPO defaults to rtsko/ireul. Deployers who fork Ireul set this to their own owner/repo. PLATFORM_VERSION defaults to main. Set it to a tag (e.g. v1.0.1) once the deployment is stable.

The CSS fetch uses DOCS_CSS_URL as the source URL. The hook detects docs/stylesheets/platform.css and injects it as a local extra_css path rather than an external URL, eliminating the flash that occurs when Material instant navigation re-evaluates external stylesheets on each page transition.

Environment variables¶

Set these in the Cloudflare Pages project under Settings > Environment variables. Apply to both Production and Preview environments unless noted.

Variable	Required	Description
`PLATFORM_REPO`	Deployers only	GitHub `owner/repo` of your Ireul fork (e.g. `acme/ireul`); omit if using the canonical `rtsko/ireul`
`PLATFORM_VERSION`	Recommended	Ireul tag to pin dependencies and hook (e.g. `v0.1.0`); defaults to `main` if unset
`DOCS_CSS_URL`	Yes	Platform stylesheet source URL (e.g. `https://ireul.pages.dev/platform.css`); fetched locally by the build command so the hook can inject it as a same-origin asset
`DOCS_SITE_NAME`	Yes	Display name shown in the docs header and browser tab
`DOCS_REPO_URL`	Recommended	GitHub repo URL; shown as the top-right link in the site
`DOCS_EDIT_URI`	Optional	Edit-page link base; omit to disable edit links
`DOCS_ANALYTICS_ID`	Optional	Google Analytics measurement ID

Branch deployments¶

Branch	Deployment
`main`	Production: primary site URL
All other branches	Preview: unique preview URL per push

Ireul-specific: serving platform.css¶

Ireul itself hosts platform.css and serves it from the Pages root. Its build command copies the stylesheet into the output directory before Cloudflare Pages serves the site:

# Build docs using local files and copy platform CSS into site root so it is served at the Pages domain root
pip install -r requirements-doc.txt && mkdocs build && cp mkdocs/stylesheets/platform.css site/platform.css

The resulting URL (https://ireul.pages.dev/platform.css) is the value all other repos use for DOCS_CSS_URL.

Creating a new project¶

Log in to the Cloudflare dashboard and navigate to Workers & Pages.
Select Create application > Pages > Connect to Git.
Authorise the rtsko GitHub account and select the repo.
Set the build settings from the table above.
Add the environment variables from the table above.
Deploy. Cloudflare Pages assigns a *.pages.dev subdomain automatically.
Set DOCS_SITE_URL to the assigned Pages URL and redeploy, or leave it unset if a custom domain is not yet configured.

Note

DOCS_CSS_URL must point to the live Ireul Pages deployment. Confirm https://ireul.pages.dev/platform.css is reachable before setting it in other repos.

Python projects¶

Cloudflare Pages v2 detects pyproject.toml at the repo root and runs pip install . automatically before the custom build command. This step is separate from the framework preset and cannot be disabled from the dashboard.

For pip install . to succeed, the [build-system] section of pyproject.toml must use a backend compatible with the setuptools version in the Cloudflare build environment. Use setuptools.build_meta with a minimum requirement of setuptools>=45:

# /─[ pyproject.toml build-system block — use build_meta for Cloudflare Pages compatibility ]
[build-system]
requires = ["setuptools>=45"]
build-backend = "setuptools.build_meta"

The legacy backend setuptools.backends.legacy:build requires setuptools 61 or later and will fail in the Cloudflare Pages build environment with BackendUnavailable.

If your repo has pyproject.toml but is not a Python project (for example, a Julia server with a Python client package in a subdirectory), the same rule applies: the root-level pyproject.toml must use setuptools.build_meta or the docs build will fail.