Docs Deployment
How the two Docusaurus documentation sites are deployed on Cloudflare Pages. For authoring conventions (where files go, sidebars, links, i18n), see Docs Architecture & Publishing. For the app itself, see Next.js App Deployment (Vercel).
Two Pages projects, one Docusaurus installation
The documentation is two separate Docusaurus sites built from a single installation (website/), each deployed as its own Cloudflare Pages project:
| User docs | Dev docs | |
|---|---|---|
| URL | docs.rat.gd | dev-docs.rat.gd |
| Audience | End users (public) | Contributors (Zero Trust protected) |
| Content | docs/user/ | docs/dev/ |
| Docusaurus config | website/docusaurus.config.ts | website/docusaurus.dev.config.ts |
| Sidebar | website/sidebars-user.ts | website/sidebars-dev.ts |
| Build output | website/build/ | website/build-dev/ |
Both configs share node_modules, the CSS theme (website/src/css/custom.css), and static assets (website/static/).
Cloudflare Pages build configuration
Both Pages projects are Git-connected to github.com/GDPR-Labs/ropa2.0 via the Cloudflare Workers and Pages GitHub App (installed on the GDPR-Labs organization). Publishing is just pushing to main — there is no manual deploy step and no CI workflow involved (unlike the app, which deploys via GitHub Actions).
| Setting | User docs project | Dev docs project |
|---|---|---|
| Production branch | main | main |
| Root directory | website | website |
| Build command | npm run build | npm run build:dev |
| Build output directory | build | build-dev |
| Build watch paths (include) | website/*, docs/user/* | website/*, docs/dev/* |
Build status appears as a commit check on GitHub; build logs are in the Cloudflare dashboard under Workers & Pages → <project> → Deployments.
Both configs set
onBrokenLinks: "warn"— a broken internal link logs a warning during the build. Runnpm run build/npm run build:devlocally (fromwebsite/) before pushing doc changes.
Build watch paths
Watch paths make Cloudflare skip a build when a push doesn't touch the site's files — without them, every push to main would rebuild both docs sites.
To configure them (per project):
- dash.cloudflare.com → Workers & Pages → select the project
- Settings → Build (older UI: Builds & deployments) → Build watch paths → Edit
- Set Include paths to the values from the table above (one path per row); leave Exclude paths empty
- Save
How the matching works:
- Paths are relative to the repository root, not the project's root directory — that is why
docs/user/*anddocs/dev/*are needed even though the build root iswebsite. *matches across path segments, sodocs/dev/*also covers nested files likedocs/dev/testing/gforms.md.- On each push, Cloudflare diffs the commit against the last deployed commit. If no changed file matches an include path, the build is skipped — the deployment list shows it as skipped and the GitHub commit check passes immediately.
- The first deployment after connecting Git always builds (there is no previous deployment to diff against), and editing the watch paths setting itself does not trigger a build — it applies from the next push.
If a doc content change ever fails to trigger a deploy, check these paths first — e.g. a new content folder outside
docs/user/ordocs/dev/would silently be ignored. A push that only touches application code (e.g.src/) correctly triggers no docs build.
Domains and DNS
| Site | Domain | Why |
|---|---|---|
| User docs | docs.rat.gd (custom domain) | Public site, no auth — a plain CNAME from Vercel DNS to Cloudflare Pages works. |
| Dev docs | dev-docs.rat.gd (custom domain) | DNS points the dev-docs subdomain at the Cloudflare Pages project. The underlying dev-docs-rat.pages.dev URL still exists but dev-docs.rat.gd is the canonical access point. |
Access control (dev docs only)
The dev docs site is protected by Cloudflare Zero Trust Access: only members of the GDPR-Labs GitHub organization can view it, authenticating through a GitHub OAuth App owned by the org.
Full setup, member on/offboarding, and troubleshooting: Cloudflare Pages — Zero Trust Access Configuration.
Key facts:
- Team domain:
gdpr-labs.cloudflareaccess.com - Access is granted/revoked purely by GDPR-Labs GitHub org membership
- Cloudflare Access does not run locally — the dev site is unprotected on
localhost; protection only applies on the deployedpages.devdomain - The user docs site has no access control (public by design)
Operational notes
- A docs deploy failed? Check the Cloudflare build log (Workers & Pages → project → Deployments). The most common cause is a broken relative link.
- A docs change didn't deploy? Check the build watch paths (above) — the push may have been legitimately skipped.
- Renaming/moving a doc file changes its URL and its sidebar ID. Update the corresponding
website/sidebars-*.tsentry and any relative links pointing at it, then build locally to verify. - The GitHub commit check from Cloudflare is independent of the "Vercel Deploy" GitHub Actions check — a commit can have one green and the other red.