Publishing the docs

These docs are an mdBook. The book root is docs/ — book.toml is the config and SUMMARY.md is the table of contents. Every page listed in SUMMARY.md becomes a chapter; files outside it (e.g. _scans/) are ignored by the build.

Build locally

# one-off build → docs/book/ (gitignored)
mdbook build docs

# live-reload preview on http://localhost:3000
mdbook serve docs --open

Install mdBook with brew install mdbook, cargo install mdbook, or a release binary. CI pins the version in .github/workflows/docs.yml.

Deploy

Pushes and PRs that touch docs/** build the book and deploy it to Cloudflare Pages (project helex-tx-docs) via .github/workflows/docs.yml:

• push to main → production deploy at https://helex-tx-docs.pages.dev
• pull request → preview deploy at https://<branch>.helex-tx-docs.pages.dev (the run summary prints the exact URL), so docs can be reviewed before merge
• Run workflow button (Actions tab) → manual deploy of the current branch

Preview URLs are covered by the same Cloudflare Access policy as long as it includes *.helex-tx-docs.pages.dev (see below).

GitHub Pages is not used: the tx repo is private on a GitHub Team plan, and access-controlled Pages requires GitHub Enterprise Cloud. Publishing a private repo’s Pages on Team makes the site world-readable, so we host on Cloudflare instead, where Cloudflare Access gives real authentication.

One-time Cloudflare setup

Done once by someone with access to the Cloudflare account. No account creation or credential entry is scripted — do these in the dashboard.

1. Pages project. The workflow creates it automatically on first run (wrangler pages project create helex-tx-docs --production-branch=main), so you can skip this — or pre-create it in the dashboard (Workers & Pages → Create → Pages → Direct Upload, name helex-tx-docs). The site is served at https://helex-tx-docs.pages.dev — optionally add a custom domain.

2. Create a scoped API token. My Profile → API Tokens → Create Token → template “Edit Cloudflare Workers” (or a custom token with Account › Cloudflare Pages › Edit). Copy the token.

3. Find the Account ID. Any Workers & Pages page shows it in the right rail.

4. Add the two GitHub secrets on helex-solutions/tx (Settings → Secrets and variables → Actions):

   • CLOUDFLARE_API_TOKEN — the token from step 2
   • CLOUDFLARE_ACCOUNT_ID — the ID from step 3

   gh secret set CLOUDFLARE_API_TOKEN  --repo helex-solutions/tx
   gh secret set CLOUDFLARE_ACCOUNT_ID --repo helex-solutions/tx
   

Gate the site with Cloudflare Access (the “password”)

Cloudflare Access sits in front of the Pages site and requires a login before any page loads — one-time email codes (OTP) by default, or Google/GitHub/SSO.

1. Cloudflare dashboard → Zero Trust → Access → Applications → Add an application → Self-hosted.
2. Application domain: helex-tx-docs.pages.dev (and the custom domain, if any). Cover *.helex-tx-docs.pages.dev too so preview deploys are protected.
3. Add a policy → Action Allow → include rule Emails (list the people who may read the docs) or Emails ending in @helex-solutions....
4. Save. Visitors now get a Cloudflare login screen; approved emails receive a one-time code and are let through. Everyone else is blocked.

For a shared static password instead of per-person email, use a Service Token or a “Service Auth” policy — but per-email OTP is stronger and needs no secret sharing, so prefer it.

Zero Trust’s free plan covers up to 50 seats, which is plenty here.