Skip to content

Publish documentation

Limen docs are markdown in the monorepo, built with MkDocs Material, hosted on Cloudflare Pages at https://limen.fordsworth.com.

Local preview

./scripts/docs.sh serve

Open http://127.0.0.1:8000.

Other commands:

./scripts/docs.sh install   # venv + dependencies only
./scripts/docs.sh build     # strict production build → site/
./scripts/docs.sh clean     # remove site/ and .venv-docs/

Production

What Where
Live site https://limen.fordsworth.com
Pages project Cloudflare Pages (limen-docs or your project name)
DNS cPanel CNAME limen → *.pages.dev (nameservers stay at host)

How deploys work (CI/CD)

Two systems, one pipeline:

Edit docs/ or mkdocs.yml
        │
        ├─► Open PR ──► GitHub Actions (docs.yml)
        │                 mkdocs build --strict
        │                 must pass before merge
        │
        └─► Merge to main
                  │
                  ├─► GitHub Actions runs again (validation)
                  │
                  └─► Cloudflare Pages (Git hook)
                        pip install + mkdocs build
                        deploy → limen.fordsworth.com
                        usually 1–3 minutes

Cloudflare Pages is the deployer — it watches fordsworth-associates/limen on GitHub and rebuilds on every push to main that touches the build.

GitHub Actions (.github/workflows/docs.yml) is the quality gate — strict build on PRs so broken docs never merge.

You do not need a separate deploy step in GitHub Actions; Pages pulls from Git directly.

Verify a deploy

  1. Cloudflare → Workers & Pages → your Pages project → Deployments
  2. Latest row should match your latest main commit SHA
  3. Status Success → live at limen.fordsworth.com

Preview deployments (optional)

In the Pages project → Settings → enable Preview deployments for branches/PRs. Each PR can get a *.pages.dev preview URL before merge.

One-time Cloudflare Pages setup

  1. Push the monorepo to private GitHub (fordsworth-associates/limen).
  2. Cloudflare → Workers & Pages → Create application → Looking to deploy Pages? Get started.
  3. Connect GitHub → select limen.
  4. Build settings:
Setting Value
Framework preset None
Build command pip install -r requirements-docs.txt && mkdocs build
Build output directory site
Environment variable PYTHON_VERSION = 3.12
  1. Custom domains → add limen.fordsworth.com → copy the CNAME target.
  2. cPanel Zone Editor → CNAME limen → your *.pages.dev hostname (not *.workers.dev).
  3. Wait for SSL (5–30 min). Nameservers stay at your host — only the limen record points at Pages.
  4. Optional — keep it private: Cloudflare Zero Trust → Access → protect limen.fordsworth.com.

Adding a page

  1. Create or edit a file under docs/.
  2. Add it to the nav: section in mkdocs.yml at the repo root.
  3. Open a PR — CI must pass.
  4. Merge — site updates within a minute or two.

Folder layout

docs/
  index.md                 # Home
  platform/                # Cross-cutting architecture map
  modules/                 # Product Studio + runtime engines
    product-studio/        # Configuration layer (with submodules)
    graph-e/
    quantum-tree/
    kinetic/
    fluid-gl/
    decisioning/
    projections/
  doctrine/                # Locked principles
  decisions/               # ADRs
  how-to/                  # Runbooks
  reference/               # Glossary, API refs
  stylesheets/limen.css    # Brand theme (light + dark)
  assets/                  # Logo, images
  archive/                 # Historical — not current doctrine