Skip to content

Publishing this documentation to Cloudflare

This page explains how to publish the documentation site you're reading right now (built with MkDocs + Material) to Cloudflare Pages, so it's available at a URL like docs.totlcom.com.

This is separate from deploying the app itself — see Deployment for that. Do these steps in order; they assume no prior experience with Python or MkDocs.

1. Install Python and MkDocs

  1. Install Python. Go to https://www.python.org/downloads/, download the latest version, run the installer, and — on Windows — tick "Add python.exe to PATH" before clicking Install.
  2. Open a terminal (Windows: PowerShell; macOS: Terminal).

  3. Confirm Python works:

    python --version

    You should see Python 3.x.x.

  4. Install MkDocs and the Material theme (this project's theme):

    pip install mkdocs-material

2. Move into the project folder

The documentation lives in the same project folder as the app, under docs/, with the config file mkdocs.yml at the top.

cd "C:\LocalDev\Nable Cove Reports"

mkdocs serve

Open the address it prints (usually http://127.0.0.1:8000) in a browser. You'll see the docs live, and the page reloads as you edit any .md file. Press Ctrl+C in the terminal to stop.

4. Build the static site

This converts the Markdown into a folder of plain HTML that Cloudflare can host:

mkdocs build

When it finishes, a new folder named site/ appears in the project. That folder is the entire website.

5. Publish to Cloudflare Pages

You already have Wrangler logged in from deploying the app (if not, run npx wrangler login first — see Deployment §4).

The first time, create the Pages project and upload in one step:

npx wrangler pages deploy site --project-name cove-audit-docs
  • If it asks "Create a new project?", choose Yes and accept the name cove-audit-docs.
  • If it asks for a production branch, accept the default (main).

When it finishes it prints a URL like https://cove-audit-docs.pages.dev. That's your live documentation.

Every time you update the docs afterward, just re-run the build and deploy:

mkdocs build
npx wrangler pages deploy site --project-name cove-audit-docs

6. Put it on your own domain (optional)

  1. Go to https://dash.cloudflare.com and select your account.
  2. Open Workers & Pages → click cove-audit-docs.
  3. Open the Custom domains tab → Set up a custom domain.
  4. Enter the subdomain you want (for example docs.totlcom.com) and follow the prompts. If the domain is already on your Cloudflare account, DNS is configured automatically.

Warning

These docs describe how the app is deployed and secured. If any of that is sensitive, put the documentation site behind Cloudflare Access too — add an Access application for the docs domain the same way you did for the app.

Alternative: automatic builds from GitHub

If you'd rather not run mkdocs build by hand each time, connect the repository so Cloudflare rebuilds on every push:

  1. In Workers & Pages, click Create application → Pages → Connect to Git, and select this repository.
  2. Set the build settings:
    • Build command: pip install mkdocs-material && mkdocs build
    • Build output directory: site
  3. Save and Deploy.

After this, every push to the repository rebuilds and republishes the docs automatically — no local build needed.