Skip to content

Publishing

Overview

The documentation is configured as an MkDocs Material site and can be: - previewed locally - built into a static site - published automatically through Cloudflare Pages

Local Preview

Create a Python virtual environment and install the docs dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-docs.txt

Run the docs site locally:

mkdocs serve

Or, if MkDocs is installed in your active Python environment, use the npm helper:

npm run docs:serve

Default local URL: 

http://127.0.0.1:8000

Static Build

To build the site into the local docs_site/ directory:

bash scripts/build-docs.sh

Or:

npm run docs:build

Screenshot Publishing

Screenshots are published as normal static assets. Store them under:

docs/manual/assets/

Reference them with relative paths inside Markdown:

![Message Center inbox](./assets/message-center/inbox-list.png)

or from a workflow file:

![Thread view](../assets/message-center/thread-view.png)
  1. Update the relevant workflow or manual page
  2. Add or update screenshots in docs/manual/assets/
  3. Preview locally with mkdocs serve
  4. Commit changes
  5. Push to main
  6. Verify the published site

Cloudflare Pages Publishing

This repository also includes a Cloudflare Pages deployment workflow.

Option A: Cloudflare Pages via GitHub Actions

Use .github/workflows/docs-cloudflare-pages.yml.

Required GitHub repository secrets: - CLOUDFLARE_API_TOKEN - CLOUDFLARE_ACCOUNT_ID

Optional GitHub repository variable: - CLOUDFLARE_PAGES_PROJECT

If CLOUDFLARE_PAGES_PROJECT is not set, the workflow defaults to:

gmpro-manual

Option B: Cloudflare Pages via Dashboard

If you prefer configuring Cloudflare Pages directly in the dashboard: 1. Connect the GitHub repository to Cloudflare Pages 2. Set the production branch to main 3. Configure the build command as:

bash scripts/build-docs.sh

Output directory:

docs_site
  • Framework preset: None
  • Build command: bash scripts/build-docs.sh
  • Build output directory: docs_site
  • Root directory: /

Why MkDocs Is Still Correct

Cloudflare Pages is the host, not the site generator.

MkDocs remains the correct tool because: - the source content is already Markdown-based - the manual uses a docs-style navigation tree - screenshots are simple static assets - Cloudflare Pages serves the generated site/ output cleanly

So the pipeline is: 1. write docs in docs/ 2. build with MkDocs 3. deploy the generated docs_site/ folder to Cloudflare Pages