How to Work on Documentation

Tip

You’ll need this guide if you’re contributing to or improving the freeCodeCamp contributing documentation itself. If you’re working on curriculum, codebase, or other areas, you can skip this guide.

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.

1. Open the fork page:

   Fork “freeCodeCamp/contribute”

2. Check the details, then click Create fork.

3. 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.

	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

Local Machine

Prerequisites

Prerequisite	Version	Notes
Git	latest	The version bundled with your operating system is often outdated.
Node.js	24.x	The “Active LTS” version.
pnpm	10.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.
• Run ESLint in your editor. Do not ignore its errors.

Clone your fork and start the site

1. 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.

2. 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.

3. Install the dependencies. This also sets up the Git hooks:

   pnpm install

4. Start the development server:

   pnpm develop

5. Open http://localhost:4321.

Congratulations - you're all set!

The documentation site now runs on your machine. See the Quick Commands Reference for linting, testing and building.

GitHub Codespaces

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

1. Go to your fork at https://github.com/YOUR_USER_NAME/contribute.

2. 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.

3. 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

Congratulations - you're all set!

The documentation site now runs in your codespace. See the Quick Commands Reference for linting, testing and building.

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.

1. 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

2. 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.

Note

When adding a new file to the docs directory, you should evaluate if the file should also be added to the sidebar navigation. We typically create a link in the src/sidebar.ts file for new and independent guides.

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:

Key Architecture

• 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 is deployed on Cloudflare Workers. Please check the wrangler config for deployment details.

Quick Commands Reference

Handy Scripts for Local Development

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 all tests
pnpm lint	Check formatting and linting
pnpm format	Auto-fix formatting and linting issues
pnpm check:astro	Run Astro type checking
pnpm check:links	Validate internal and external links
npx 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.