Skip to content

Documentation Hosting

This site is built with MkDocs Material and deployed to Cloudflare Pages at https://stake-engine-math.pages.dev/.

This site is publicly readable

The repository is private, but the published docs are not. Anyone with the URL can read every page here. Never put credentials, internal hostnames, partner names, or tuned math for live games (paytables, real RTP splits, volatility settings) in docs/ — put those in the private repo outside docs/, or in Confluence.

Why not GitHub Pages

The Raw-Fun-Gaming organisation is on the GitHub Free plan, where GitHub Pages is only available for public repositories. When this repo was made private, Pages stopped serving and the old raw-fun-gaming.github.io/stake-engine-math/ URL went dead.

Upgrading to GitHub Team would re-enable Pages for private repos, at $4/user/month. Cloudflare Pages does the same job on a free tier with unmetered bandwidth, so the site moved there instead.

Local preview

No Cloudflare account needed:

make docs          # serve at http://127.0.0.1:8000 with live reload
make docs-build    # build the static site into site/

Both targets install requirements-docs.txt into the venv on first run.

Automatic deploys

.github/workflows/deploy-docs.yml runs on every push to main that touches docs/, mkdocs.yml, or requirements-docs.txt. It builds the site and uploads it with wrangler pages deploy. A run takes well under a minute.

It reads two repository secrets:

Secret Where to find it
CLOUDFLARE_API_TOKEN Cloudflare dashboard → My Profile → API Tokens
CLOUDFLARE_ACCOUNT_ID Cloudflare dashboard sidebar, or wrangler whoami

Note that Actions minutes are metered on private repos (2,000/month on the Free plan), unlike public ones. This workflow only fires on docs changes, so its share is small.

One-time setup

Already done. Only needed if you are re-provisioning from scratch.

1. Create the Pages project

The project must exist before CI can deploy into it:

npx wrangler login
npx wrangler pages project create stake-engine-math --production-branch=main

The project name must match --project-name in the workflow. Note that *.pages.dev subdomains are globally unique across all of Cloudflare, first come first served.

2. Create the API token

Cloudflare dashboard → My Profile → API Tokens → Create Token → Create Custom Token (not a template — none of them cover Pages) with exactly one permission:

  • Account → Cloudflare Pages → Edit

Leave client IP filtering empty; GitHub-hosted runners have dynamic IPs.

3. Add the GitHub secrets

gh secret set CLOUDFLARE_API_TOKEN --repo Raw-Fun-Gaming/stake-engine-math
gh secret set CLOUDFLARE_ACCOUNT_ID --repo Raw-Fun-Gaming/stake-engine-math

If the docs ever need to be private

Two options, neither currently in use:

  • Cloudflare Access (Zero Trust) — add a self-hosted application on stake-engine-math.pages.dev with an Allow policy scoped to specific email addresses or domains. Gives per-person identity and an audit trail. Free for up to 50 users, but Cloudflare requires a payment method on file even on the $0 plan.
  • HTTP Basic Auth — a functions/_middleware.js in the built output checking a password held in a Pages environment secret. No payment method, no Zero Trust, but a single shared credential with no per-person identity.

Changing the URL

If you rename the Pages project or attach a custom domain, update:

  • site_url in mkdocs.yml (used for canonical links and sitemap.xml)
  • --project-name in .github/workflows/deploy-docs.yml