Documentation Architecture & Publishing

How the ROPA 2.0 documentation is structured, built, and published on Cloudflare Pages — and what you need to know to add or change documentation.

Architecture overview

The documentation is two separate Docusaurus sites built from a single Docusaurus installation (website/), each deployed as its own Cloudflare Pages project:

Site	URL	Audience	Content	Config
User docs	docs.rat.gd	End users (public)	docs/user/	website/docusaurus.config.ts
Dev docs	dev-docs.rat.gd	Contributors	docs/dev/	website/docusaurus.dev.config.ts

Both configs share the same node_modules, CSS (website/src/css/custom.css), and static assets (website/static/). The Docusaurus CLI selects the config with --config; the dev site builds to a separate output directory (build-dev/).

docs/
├── user/        ← public user docs content
└── dev/         ← contributor docs content (this site)
website/
├── docusaurus.config.ts       ← public site (docs.rat.gd)
├── docusaurus.dev.config.ts   ← dev site (dev-docs.rat.gd)
├── sidebars-user.ts           ← public site sidebar
├── sidebars-dev.ts            ← dev site sidebar
├── src/                       ← shared theme, CSS, public homepage
└── static/                    ← shared images and assets

The dev site is protected by Cloudflare Zero Trust Access (GitHub org membership). See Cloudflare Pages — Zero Trust Access Configuration for the full access-control setup, including how to grant and revoke access.

The dev site is served at its pages.dev URL rather than a rat.gd subdomain: the rat.gd DNS zone is managed by Vercel, which prevents Cloudflare from proxying traffic — and Access enforcement requires the Cloudflare proxy. The public site has no such constraint (no auth), so docs.rat.gd works via a plain CNAME.

Where to create documentation files

You are writing…	Put the file in…	Register it in…
User-facing documentation	docs/user/	website/sidebars-user.ts
Developer/contributor documentation	docs/dev/ (subfolders OK, e.g. testing/)	website/sidebars-dev.ts

Rules and conventions:

• Both sidebars are manual (not autogenerated). A new .md file builds but is unreachable until you add its doc ID to the appropriate sidebar file. The doc ID is the file path relative to the docs root, without extension — e.g. docs/dev/testing/tier-1-unit-tests.md → "testing/tier-1-unit-tests".
• Use frontmatter sidebar_label: to control the name shown in the sidebar; the # H1 is the page title.
• Do not remove slug: / from docs/dev/architecture.md — it is the dev site's homepage. With pages: false in the dev config there is otherwise nothing at / and the build breaks.
• Images go in website/static/img/ and are referenced as /img/<name> from both sites.
• Markdown links between docs of the same site are relative file links (./other-doc.md) — Docusaurus validates them at build time.
• Links across sites must be absolute URLs: from dev docs to user docs use https://docs.rat.gd/docs/<id>; from user docs to dev docs use https://dev-docs.rat.gd/<id>. Root-relative links to the other site break the build (onBrokenLinks: throw).

Local preview and build

All commands run from website/ (or use the root-level npm run docs* aliases):

cd website
npm ci                # first time only

npm run start         # public site dev server  → http://localhost:3000
npm run start:dev     # dev site dev server     → http://localhost:3001

npm run build         # public site → website/build/
npm run build:dev     # dev site    → website/build-dev/
npm run serve         # serve the public build locally
npm run serve:dev     # serve the dev build locally (port 3001)

Do not run start and start:dev simultaneously — both configs share the same .docusaurus working directory and will corrupt each other's state.

Cloudflare Access does not run locally; the dev site is unprotected on localhost. Protection only applies on the deployed pages.dev domain.

Publishing

Both Cloudflare Pages projects are Git-connected to github.com/GDPR-Labs/ropa2.0. Publishing is just pushing to main — there is no manual deploy step. A push that only touches application code (e.g. src/) triggers no docs build, thanks to build watch paths.

Both configs set onBrokenLinks: "warn" — a broken internal link logs a warning. Run npm run build / npm run build:dev locally before pushing doc changes.

Full Cloudflare Pages configuration (build settings, watch paths, domains/DNS, access control) is documented in Docs Deployment (Cloudflare).

Localization

The user docs support 10 locales (en ca de es eu fr gl it nl pt). The dev docs are English-only. See Localization Architecture for the full i18n file layout, fallback behaviour, how the Next.js app consumes the same translation files, and how to add a new locale.

Housekeeping rules

• website/sidebars-dev.ts is referenced by docusaurus.dev.config.ts — do not delete it when touching the public site config.
• The dev config sets blog: false, pages: false; the public homepage (website/src/pages/index.tsx) belongs to the public site only.
• website/build/ and website/build-dev/ are git-ignored build artifacts — never commit them.
• The public site must not reference /dev/* routes — that content no longer exists there; link to https://dev-docs.rat.gd/… instead.