Skip to content

Cloudflare Pages — MkDocs Portal

The DevOps portal is published from this repository to the Cloudflare Pages project:

Project: akshaya-devops
Production branch: master
Public Pages hostname: https://akshaya-devops.pages.dev/

Cloudflare Pages is only the documentation hosting layer. It does not deploy the AkshayaBazaar backend, Kubernetes workloads, Terraform infrastructure, or production databases.

Source and build contract

Repository: Thirunk/AkshayaBazaar
Config: mkdocs.yml
Docs root: docs/devops
Dependency file: requirements-docs.txt
Output: site/

The repository CI validates documentation with:

pip install -r requirements-docs.txt
mkdocs build --strict

For Cloudflare Pages, prefer interpreter-qualified commands when editing build settings:

python -m pip install -r requirements-docs.txt && python -m mkdocs build --strict

Build output directory:

site

Root directory:

repository root

Deployment flow

  1. Create a branch and edit documentation.
  2. Run mkdocs build --strict locally when possible.
  3. Push the branch and open a PR.
  4. GitHub Actions docs job must pass.
  5. Cloudflare Pages may build a preview deployment for the branch/PR.
  6. Merge only after review.
  7. A new master commit triggers the production Pages build through the Git integration.
  8. Open the production Pages hostname and verify navigation/search/content.

Cloudflare dashboard verification

Use:

Cloudflare Dashboard
→ Workers & Pages
→ akshaya-devops
→ Deployments

Confirm:

  • Environment is Production for master.
  • Source commit matches the intended merged commit.
  • Status is green/successful.
  • The deployment URL opens successfully.

A historical failed deployment does not indicate the current site is broken if a later production deployment is green.

Build-environment configuration

If Python selection is required, configure a non-secret build variable such as:

PYTHON_VERSION = 3.12

or use a repository-level .python-version if the project standard adopts one. Keep the Cloudflare Pages dashboard and repository build commands consistent.

Secrets

The MkDocs portal currently should not require application secrets to build. Never add production database, payment, Hetzner, or Kubernetes credentials merely to build documentation.

If a future plugin genuinely requires a token, store it as a Cloudflare/GitHub secret and reference the name only in this portal.

Failure troubleshooting

pip not found

Change the build command to interpreter-qualified form:

python -m pip install -r requirements-docs.txt && python -m mkdocs build --strict

Confirm Python is available in the build log and configure PYTHON_VERSION if necessary.

MkDocs strict build fails

Run locally:

python -m pip install -r requirements-docs.txt
python -m mkdocs build --strict

Fix missing pages, invalid nav entries, broken references, or warnings before retrying Pages.

GitHub CI passes but Pages fails

Compare:

  • Python version,
  • build command,
  • repository root,
  • output directory,
  • environment variables,
  • exact commit being built.

The GitHub Actions docs job is the repository source of truth for the expected build semantics.

Pages is green but content looks old

  1. Confirm the production deployment commit SHA.
  2. Hard refresh/open a private browser window.
  3. Verify the requested page exists in mkdocs.yml navigation.
  4. Confirm the merge reached master rather than only a preview branch.

Rollback

Documentation rollback is a source-control rollback, not an infrastructure rollback.

Preferred procedure:

  1. Revert the bad documentation commit/PR on master.
  2. Let GitHub CI validate the revert.
  3. Let Cloudflare Pages automatically deploy the new master state.
  4. Verify the production portal.

Do not manually redeploy an unrelated old application release to fix a documentation problem.