Skip to main content

Documentation site and Cloudflare Pages

The documentation is a Docusaurus 3 site under website/. It uses the classic preset with docs served at the site root and Mermaid for architecture diagrams.

Repository layout​

schema_apps/
├── .github/workflows/deploy-docs.yml
└── website/
    ├── docs/
    ├── src/css/custom.css
    ├── static/.nojekyll
    ├── docusaurus.config.ts
    ├── sidebars.ts
    ├── package.json
    └── pnpm-lock.yaml

This follows Docusaurus guidance for placing a documentation site in a website directory inside an existing repository.

Local development​

Docusaurus 3.10 requires Node.js 20 or newer. The project pins pnpm through the packageManager field.

cd website
pnpm install
pnpm start

The development server reloads documentation and theme changes automatically.

Production verification​

cd website
pnpm typecheck
pnpm build
pnpm serve

The configuration sets onBrokenLinks: 'throw', so unresolved internal links fail the production build.

Cloudflare Pages configuration​

The production URL is:

https://schema-apps-docs.pages.dev/

Accordingly, Docusaurus uses:

url: 'https://schema-apps-docs.pages.dev'
baseUrl: '/'
organizationName: 'fell1107'
projectName: 'schema_apps'

The Cloudflare project is a Direct Upload project named schema-apps-docs, with redash_api configured as its production branch. GitHub Actions builds the site and uploads the static output with Wrangler; Cloudflare does not need GitHub App access to the private repository.

The workflow:

  1. Runs for documentation pull requests targeting redash_api and builds the site.
  2. Deploys same-repository pull requests as branch previews.
  3. Runs after documentation changes are pushed to redash_api and updates production.
  4. Skips deployment for forked pull requests because repository secrets are not available to them.
  5. Installs dependencies from the committed lockfile.
  6. Builds website/build and uploads it with wrangler pages deploy.

The repository requires these GitHub Actions secrets:

SecretPurpose
CLOUDFLARE_TOKENAccount API token limited to Pages: Edit
CLOUDFLARE_ACCOUNT_IDTarget Cloudflare account identifier

The workflow requests only contents: read. The Cloudflare token is encrypted by GitHub and passed only to the Wrangler deployment step.

Updating documentation​

Add or edit Markdown under website/docs/, then register new pages in website/sidebars.ts. Prefer tables for repeated comparable records, Mermaid for flows with several components, and prose for behavioral caveats.

Before opening a pull request:

cd website
pnpm typecheck
pnpm build

Official references​

Site visibility

Keeping the GitHub repository private does not make the Pages deployment private. Protect internal documentation with Cloudflare Access before sharing the production or preview URLs.