cloudflare-docs: The Open-Source Repository Behind Cloudflare's Developer Site

What This Repository Is and What It Produces

cloudflare-docs does not ship software you install in an application. It is the source repository for the developer documentation site at developers.cloudflare.com, which documents Cloudflare Workers, Pages, Zero Trust, Tunnel, the API, and dozens of other products. The repository holds MDX content files, Astro configuration, Cloudflare Workers for server-side rendering, and tooling for fetching OpenAPI specifications and other data that feeds into the documentation build. The README is minimal: it points to the Cloudflare Style Guide for contribution instructions and records the dual license structure. Anyone who finds a mistake on the documentation site can fix it by submitting a pull request to the production branch of this repository. The repository is not the right place to report bugs in Cloudflare products; documentation errors and product bugs are distinct issues and go to different teams. The nimbus.json and openapi.lock.json files in the top-level directory suggest automated tooling for managing external API definitions and design tokens. The astro.config.ts file at the root is the main configuration entry point for the build, and the templates/ directory contains reusable patterns for common documentation page structures.

How the Site Is Built: Astro, MDX, and Workers

The package.json reveals the build toolchain. The site is built with Astro, using MDX for content and TypeScript throughout. The development server runs with:

npx --yes only-allow pnpm

The repository enforces pnpm as the package manager. The dev script pre-fetches skills, OpenAPI specs, and logpush datasets before starting the Astro dev server:

pnpm dev

The build command runs a full Astro production build:

pnpm build

Tests are run with Vitest, separated into prebuild and postbuild phases. The wrangler.jsonc configuration deploys the site and its Cloudflare Workers components. There is also an incremental build script (build:incremental) for faster partial rebuilds when only a subset of content has changed.

Repository Layout and Content Organization

The src/ directory holds the MDX content files organized by Cloudflare product. The public/ directory contains static assets. The plugins/ directory holds Astro plugins that process content. The scripts/ directory contains utilities for SVG optimization and GitHub contributor fetching. The worker/ directory holds Cloudflare Workers code that runs server-side on Cloudflare's network at build or request time. The .agents/, AGENTS.md, CLAUDE.md, GEMINI.md, and .opencode/ files indicate the repository has configuration for multiple AI coding assistant integrations. The README notes that Cloudflare may use AI tools to review pull requests and issues for mistakes and inconsistencies, and asks contributors not to share personal information in submissions.

Contributing a Change: What the Process Involves

The repository's default branch is production, which is where the live site deploys from. The Cloudflare Style Guide, linked from the README, describes the writing conventions contributors must follow: vocabulary choices, heading levels, code sample formatting, and product name capitalization all have documented rules. Pull requests against MDX content in src/ go through standard GitHub review. The README does not document a local preview workflow in detail; the package.json dev script starts an Astro dev server that renders the site locally. Changing the Astro configuration, the Workers code, or the tooling scripts involves a more complex setup than editing MDX files and is likely to require closer review from Cloudflare's documentation team.

License Structure: Content and Code Are Licensed Separately

The README states two distinct licenses. Documentation content in the repository is licensed under Creative Commons Attribution 4.0 International. Code in the repository (the build toolchain, scripts, Workers, and Astro configuration) is licensed under the MIT License. Both licenses are permissive with attribution requirements, but they apply to different parts of the repository. The README adds that the licenses do not grant rights to use Cloudflare's trademarks, names, or logos, which are governed by Cloudflare's separate trademark guidelines. Contributors retain copyright over their contributions; by submitting a pull request they grant Cloudflare and other users the right to use that content under the applicable license.

Practical Limits: What Contributions Cannot Change

The repository publishes documentation, not Cloudflare's products themselves. A contributor cannot change how Workers or Tunnel behave by editing this repository; they can only correct or extend what the documentation says about those products. Errors in the documentation that reflect bugs or limitations in the underlying Cloudflare product need to be addressed through Cloudflare's product teams, not through a docs pull request. The repository also does not document Cloudflare's internal APIs or unpublished features. Content that exists in closed Cloudflare products without public documentation is outside the scope of what this open-source repository covers. The .gitguardian.yml and .semgrep/ files in the repository indicate that secret scanning and static analysis are part of the CI pipeline, which means submissions that accidentally include API keys or sensitive strings will be flagged automatically before they reach reviewers.

AI Tooling and the Contribution Review Process

The README notes explicitly that Cloudflare may use AI tools to help review technical documentation, pull requests, and other issues submitted to the public GitHub page. The stated purpose is identifying and correcting mistakes and inconsistencies. The repository has configuration files for multiple AI coding assistants, including CLAUDE.md, AGENTS.md, GEMINI.md, and directories for .agents/, .opencode/, and .windsurf/, indicating that the maintainers have set up agent-friendly guidance for several tools. For contributors, this means submitted pull requests may be reviewed by a combination of human reviewers and automated tooling. The README asks contributors to refrain from sharing any personal information in submissions. From a contributor's perspective, the practical implication is that obvious errors in grammar or technical accuracy are likely to be caught before human review; more subtle issues like incorrect product behavior or outdated version information require a human familiar with the product.

Testing and Format Checking Before a Pull Request

The package.json reveals several checks contributors can run locally before submitting. The typecheck scripts validate TypeScript across both the Astro site and the Worker:

pnpm run check

Format checking uses Prettier and covers JavaScript, TypeScript, JSON, YAML, and Astro files:

pnpm run format:check

Test suites separate into prebuild tests (running in Node and Astro project environments) and postbuild tests (running in the Workers environment):

pnpm test

For contributors making changes only to MDX content files rather than tooling code, format checking and a local dev server preview are the most relevant steps. Changes to the Worker code, plugins, or build scripts involve the Workers-specific test suite and a wrangler-based preview that deploys the site on Cloudflare's infrastructure locally.

Editorial conclusion

cloudflare-docs is the right repository for engineers who want to correct errors, add missing details, or contribute examples to Cloudflare's public documentation at developers.cloudflare.com. It is not a library to install in your project. Before submitting a pull request, read the Cloudflare Style Guide at developers.cloudflare.com/style-guide/contributions/ to understand the tone, heading conventions, and code sample expectations the maintainers enforce. Contributors making changes only to MDX content need pnpm, a local clone, and a passing format check; changes to the Worker code or build tooling require a more involved setup with wrangler and the Workers test suite.

Frequently asked questions

Official sources

1. cloudflare/cloudflare-docs on GitHub
2. Issues
3. License: CC-BY-4.0
4. Project website
5. README