How to Work on Documentation | Contribute

This guide sets up a development environment for the freeCodeCamp documentation site. Work through it once, in order.

Fork the contribute repository on GitHub

A fork is your own copy of the codebase. You need one to contribute.

Open the fork page:

Fork “freeCodeCamp/contribute”
(opens in a new tab)
Check the details, then click Create fork.
GitHub redirects you to your fork at https://github.com/YOUR_USER_NAME/contribute.

In this guide, origin means your fork and upstream means the main repository.

Choose where to run the docs site

There are two ways to run the site. Both work.

Feature	Local Machine	GitHub Codespaces
Where it runs	Directly on your machine	On a GitHub server
You install	Node.js, pnpm, Git	Nothing
Machine needed	Any machine that runs Node.js	The default machine is enough
Works offline	Yes, after setup	No
Cost	Free	A free monthly quota, then paid

Prerequisites

Prerequisite	Version	Notes
Git	latest	The version bundled with your operating system is often outdated.
Node.js	`26.x`	The “Active LTS” version.
pnpm	`12.x`	-

Check what you have:

node -v && pnpm -v

Recommended, but not required:

Set up an SSH key for GitHub.
Use a code editor. Visual Studio Code is free and open source.
Install the recommended workspace extensions: Astro, Oxc and ESLint. Oxfmt formats files. Oxlint checks JavaScript and TypeScript, including type-aware rules. ESLint checks Astro templates only.

Clone your fork and start the site

Clone your fork, replacing YOUR_USER_NAME with your GitHub username:
```
git clone --depth=1 https://github.com/YOUR_USER_NAME/contribute.git
cd contribute
```
--depth=1 fetches only the most recent commit, which keeps the download small.
Add a remote that points at the main repository, so that you can sync later:
```
git remote add upstream https://github.com/freeCodeCamp/contribute.git
```
Run git remote -v to confirm. You should see origin on your fork and upstream on freeCodeCamp/contribute.
Install the pnpm version pinned by this repository, then install the dependencies. This also sets up the Git hooks:
```
npm install --global pnpm@12.17.0
pnpm install --frozen-lockfile
```
Use the Node.js version in .nvmrc. The seven-day dependency release cooldown applies to installs and updates.
Start the development server:
```
pnpm develop
```
Open http://localhost:4321.

A codespace runs the site on a GitHub server. You install nothing, and you work in your browser or in VS Code.

Go to your fork at https://github.com/YOUR_USER_NAME/contribute.
Click the green Code button, select the Codespaces tab, then click Create codespace on main.

The codespace installs Node.js, pnpm and the dependencies, then starts the development server for you.
Wait for the setup to finish. Your browser opens the site on port 4321 automatically.

If it does not, start the server yourself:
```
pnpm develop
```

Create a Working Branch

Before making any changes, it’s important to create a new branch for your work. This keeps your changes organized and separate from the main codebase.

Create and switch to a new branch, replacing feature/your-feature-name with a descriptive name for your changes:
```
git checkout -b feature/your-feature-name
```
Ensure you are on your new branch:
```
git branch
```
You should see your new branch name with an asterisk (*) next to it, indicating it’s the active branch.

Working on Documentation Content

You can edit or add files in the src/content/docs directory available here. When your changes are merged, they will be made available automatically at the documentation site.

Creating Internal Links

If you want to create a link targeting a different section of the contributing guidelines, follow this format:

[Link text](/target-file-name#target-section-heading-id)

// If the target section is within the same page, you can omit the file name
[Link text](#target-section-heading-id)

This is necessary to make these links work for the translated version of the document. Otherwise, they will redirect to the English version of the page regardless of the language.

Structure of the Docs Website

The site is generated using Astro and served using Cloudflare Workers. Here’s how it works:

All documentation content is stored in src/content/docs/ as MDX files
The sidebar navigation is configured in src/sidebar.ts
Site configuration is managed in astro.config.ts
The site is automatically built and deployed via Cloudflare Workers

Deployment

The site uses Cloudflare Workers Static Assets. cloudflare.config.ts defines the Worker, domain and runtime settings. wrangler.config.ts points the Cloudflare build backend at dist/.

pnpm build runs Astro and packages Cloudflare Build Output in .cloudflare/output/v0/. pnpm preview builds and serves the static site locally, including _headers and _redirects. pnpm preview:built serves an existing build without rebuilding it.

The pinned Cloudflare CLI detects Astro directly when you run bare cf build or cf dev. Use the repository scripts to keep the prebuild Git-history step, static asset packaging and production-like preview.

Cloudflare Workers Builds runs pnpm run build. The production deploy command is pnpm exec cf deploy --prebuilt; the non-production command is pnpm exec cf workers versions create --prebuilt. These commands are saved in Workers Builds settings, not in cloudflare.config.ts. Non-production builds upload a version without deploying it to production traffic.

Use pnpm exec cf deploy --prebuilt --dry-run after a local build to validate the package without uploading. Deployment requires Cloudflare access; local development and tests do not.

Quick Commands Reference

Command	Description
`pnpm install`	Install all dependencies
`pnpm develop`	Start the Astro development server (localhost:4321)
`pnpm build`	Build the site for production
`pnpm preview`	Build and preview locally using Cloudflare Workers
`pnpm test`	Run unit tests
`pnpm lint`	Check formatting and linting
`pnpm format`	Auto-fix formatting and linting issues
`pnpm check:astro`	Run Astro type checking
`pnpm test:usability`	Check accessibility and internal links in a browser
`pnpm exec vitest run tests/filename.test.ts`	Run a specific test file

Proposing a Pull Request (PR)

After you’ve committed your changes, check here for how to open a Pull Request.