Contributions

The Cloudflare Docs ↗ are open source and hosted on the cloudflare-docs repository ↗ on GitHub. This means that anyone, including those who are not part of the Cloudflare organization, can contribute to them. We welcome all suggestions that help keep our docs high quality and up to date.

To contribute to our docs, you will need to create an account on GitHub ↗ (if you do not have one already) and log in. Then you have three options:

GitHub issue: Quickly submit a general suggestion.
Quick edit (edit button): Quickly create a pull request. This is best if you want to edit a single page in your web browser and do not need to preview your changes.
Full development: Create a pull request. This is best if you want to edit multiple pages and preview your changes. This can be done in your web browser (with Codespaces ↗) or on your local machine (with Visual Studio Code ↗).

In addition to using the Cloudflare Style Guide for guidance on grammar and style, we recommend browsing our components to add additional formatting such as buttons, tabs, and collapsible sections.

Create a GitHub issue

To create a GitHub issue:

Log in to GitHub ↗ and go to the cloudflare-docs repository ↗.
Select Issues and then New issue.
Select the issue type, fill out the form, and select Create.

Learn more about creating GitHub issues. ↗

Quick edit

To quickly create a pull request using the edit button:

Log in to GitHub ↗.
Go to the page you want to edit in the Cloudflare Docs ↗
Select
Edit or Edit page

Every page in the Cloudflare Docs (including this one) has an Edit button on the right sidebar and an Edit page button on the very bottom of the page.
The page's Markdown opens.
Note
The first time you create a pull request in the cloudflare-docs repo, you will see a GitHub landing page that says "You need to fork this repository to propose changes." Select Fork this repository. All of your future pull requests for cloudflare-docs will write to a new branch on your fork.
Make your edits and select Commit changes.
In the form, update the Commit message with the product you changed in brackets and a brief description of your changes. For example “[Images] Fixed broken link."
Update the Extended description with more details about what you changed and why. The more details, the better.
Select Propose changes > Create pull request > Create pull request again.

Full development

To edit and create a pull request with the full development workflow ↗:

Log in to GitHub ↗ and fork the cloudflare-docs repository ↗.
If you are editing in your web browser (with Codespaces ↗), move on to step 3.

If you are editing on your local machine (with Visual Studio Code ↗): * (Required) Install Node.js ↗ (version 24 or later). * (Recommended, but not required) Install Volta ↗ for easier package management. * (Required) Clone the fork to your local machine. ↗
Create a branch from your fork (or from your clone).
Make your edits.
Preview your edits by installing the dependencies and starting the local development server:
```
pnpm install
pnpm run dev
```
A link appears in the terminal, for example https://localhost:1111/, where you can preview your changes. The preview updates automatically as you edit.
Commit your changes.
Push your commits to your branch and then back to your fork.
Return to GitHub and create a pull request from your committed changes. In the description form, add the product you changed in brackets and a brief description of your changes. For example, "[Images] Fixed broken link."

After you create an issue or PR

After you create an issue or PR, a member of the Cloudflare organization will review your suggestion. Here is what to expect:

A member of the Cloudflare organization may tag others for technical or content reviews or feedback.
If your suggestion requires more information, a member of the Cloudflare organization may comment with a follow-up or clarification question. If they add the more-information-needed tag, the issue or pull request will automatically close if you do not respond within 14 days.
If your changes are approved:
- For GitHub issues, a Cloudflare member might create and link a new pull request that addresses your request. When they merge the PR, they will also close your issue.
- For GitHub PRs, the Cloudflare member will merge your PR.
If your suggestion is not approved, the Cloudflare member will respond with the reasoning and close your issue or PR.

Thank you for contributing to our open-source ecosystem and being a part of the Cloudflare community.

Content reviews

We work (and appreciate working) in GitHub ↗, but it's not a perfect tool by any means.

We've added several ergonomic improvements to help us triage incoming work, streamline reviews, and automate communication.

Triage work

To help our writers triage work (and help with backend reporting), we automate a few labels and issue / pull request assignment.

Pull requests

For pull requests, we use a specific GitHub action ↗ to add labels and assign codeowners.

Label products ↗: We add labels for the top-level product folder, which helps writers scan incoming pull requests and see which are relevant to them.
Label size ↗: We add labels for the size of the pull request, which helps writers see the relative size of the difference. It's not a perfect measure, but we use the lines changed to estimate the size of the pull request:
Assign codeowners ↗: We use our CODEOWNERS ↗ file to automatically assign people to pull requests based on the files changed. This assignment helps writers scan and filter to see which pull requests are relevant to them.

Issues

For issues, we use a similar GitHub action ↗ to add labels and assign codeowners.

Our script ↗ treats issues because usually they contain links to our site instead of files within the repository. We grab the associated links in the issue description fields and then use those to assign writers (again based on CODEOWNERS) and add product labels.

Streamline reviews

To streamline reviews, we use several automations to help solve common reviewer issues.

Will this break anything?

We have one required check that runs on every commit, CI ↗.

This check makes sure that:

The site builds correctly.
All internal links are valid.
There are no infinite redirects.
Specific pages and functionality in our docs behave as expected ↗.

Who needs to approve this?

We commonly get questions about approvals, especially for pull requests that touch multiple product areas (or our components).

We have a specific part of CI ↗ that posts a comment ↗ with the relevant codeowners.

What changed?

We use a GitHub action ↗ to publish preview builds for every commit on a pull request (and comment those links ↗ on the pull request). This action ensures that reviewers can see exactly what the site and content will look like when they're rendered (and not just look at the changed markdown in GitHub).

We are in the process of migrating to Workers Builds, which provides that functionality natively.

Based on feedback, we have also added a before/after table of links to help reviewers easily find links in the preview builds.

Is there anything else I need to check?

One difficult thing to check is potential redirects when a pull request renames or deletes content file paths.

We have a specific action ↗ that posts a comment to help reviewers identify and then check these paths.

Automate communication

We automate communication primarily through the no-response ↗ GitHub Action.

Being open source means that we accept issues and pull requests from anyone! And a lot of these are either self explanatory or have enough context for us to follow up on them.

The ones without enough context, however, are often painful (especially in a busy repo ↗ like ours). A writer has to ask for more detail, then remember to check back in, and then sometimes re-ask for more detail, and then check in again.

To help avoid some of this mental toil, we'll ask a question and then apply the more-information-needed label. This label starts a 14-day clock ↗ for the author to respond. If they do respond, the label gets removed and the conversation can continue. If they don't respond, the issue automatically gets closed with a comment explaining why ↗.

This workflow - we hope - balances the needs our of team with a healthy respect for our contributors.

Stale issues

We intentionally avoid the stale workflow ↗ that closes pull requests or issues that have been inactive for a specific period of time.

In our opinion, this workflow causes more friction and frustration than it solves. Just because something has been around for a year doesn't mean it's not still relevant.

Contribute to Cloudflare documentation with AI

The cloudflare-docs repository includes an AGENTS.md ↗ file that helps AI coding agents understand the structure, tooling, and conventions of the repository so they can make correct, buildable changes when contributing to documentation.

AGENTS.md ↗ is a simple, open format for guiding coding agents.

The repository includes configuration for the following AI tools out of the box:

Agent skills, commands, and agent definitions all live in .agents/ and are symlinked into the expected locations for each tool automatically.