How to Work on Documentation

Follow these guidelines for setting up a development environment for the freeCodeCamp documentation site. This is highly recommended if you want to contribute regularly to our contributing guidelines.

Fork the contribute repository on GitHub

You will need to fork the contribute repository on GitHub to get your own copy of the codebase. This will allow you to follow a Git-based workflow to contribute to freeCodeCamp’s documentation.

Follow these steps to fork the repository:

1. Click the button below to fork the contribute repository on GitHub.

   Fork “freeCodeCamp/contribute”

2. On the create new fork page, check the details and click the Create fork button.

3. You should automatically be redirected to your fork, the URL should be something like https://github.com/YOUR_USER_NAME/contribute.

That’s it! You have successfully forked the contribute repository.

Did you know?

The main repository at https://github.com/freeCodeCamp/contribute is often referred to as the upstream repository. Your fork at https://github.com/YOUR_USER_NAME/contribute is often referred to as the origin repository.

Cloud IDE or your own machine?

Next, you need to choose between setting up a cloud IDE or your own machine.

If you’re looking to make a one-time contribution or want the fastest setup, use GitHub Codespaces which provides a ready-to-code environment in your web browser using devcontainers. For long-term contributions where you prefer local development, you can set up the documentation site on your local machine.

Feature	GitHub Codespaces Recommended	Your own machine
Hardware requirements	No minimum hardware requirements	Minimum hardware requirements (Node.js, pnpm)
Software installation	No need to install any software	Additional software needed
Repository status	Always up-to-date repository	Manual updates required
Setup complexity	Easy setup with devcontainers, works in any browser	Larger download and setup time
Internet dependency	Requires an internet connection to work	Minimal internet connection required once set up
Performance	Consistent cloud-based performance	Depends on your machine capabilities
Usage limits	60 hours free per month for personal accounts	No usage limits
Environment consistency	Identical setup for all contributors via devcontainers	May vary between different machines and OS

Once you have decided, follow the relevant tab below to continue with the setup.

GitHub Codespaces

GitHub Codespaces

We have automated the development environment setup using devcontainers. With GitHub Codespaces, you get a consistent, ready-to-code environment that runs in your browser with all dependencies pre-installed.

Launch a Codespace from your fork:

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

2. Click the green Code button

3. Select the Codespaces tab

4. Click Create codespace on main

   Your codespace will automatically set up the development environment using our devcontainer configuration. This includes:

   • Installing Node.js, pnpm, and all dependencies
   • Configuring VS Code extensions
   • Preparing the environment

5. Wait for the setup to complete (usually 1-2 minutes)

Start the development server:

Once your Codespace is ready, the development server should start automatically. If not, you can start it manually:

pnpm develop

Once ready, you will see a notification to open the site. Click on the notification to open the client application in a new browser tab.

Congratulations - you're all set!

You now have a copy of freeCodeCamp’s documentation site running in your Codespace. Go ahead and start making changes to the documentation.

Local Machine

Prerequisites

System Requirements

Prerequisite	Version	Notes
Node.js	22.x	We use the “Active LTS” version
pnpm	10.x

Did you check the version?

If you have a different version installed, please install the recommended version. You can check your versions by running node -v and pnpm -v in your terminal.

Run the following commands to validate the versions:

node -v

pnpm -v

Once you have the prerequisites installed, you need to prepare your development environment. This is common for many development workflows, and you will only need to do this once.

Additional Prerequisites

1. Install Git or your favorite Git client, if you haven’t already. Update to the latest version; the version that came bundled with your OS may be outdated.

2. (Optional but recommended) Set up an SSH Key for GitHub.

3. Install a code editor of your choice. If you aren’t sure which one to use, we recommend Visual Studio Code — it’s free and open source.

4. Set up linting for your code editor.

   You should have ESLint running in your editor, and it will highlight anything that doesn’t conform to freeCodeCamp’s JavaScript Style Guide.

   Pay Attention to errors

   Please do not ignore any linting errors. They are meant to help you and to ensure a clean and simple codebase.

Clone your Fork from GitHub

Next, you will need to clone your fork to your local machine.

Run these commands on your local machine:

1. Open a terminal in your projects directory, for example:

   /home/username/projects/

2. Clone your fork of the contribute repository, replacing YOUR_USER_NAME with your GitHub Username

   git clone --depth=1 https://github.com/YOUR_USER_NAME/contribute.git

   This will download the entire contribute repository to your projects directory.

   Note

   --depth=1 creates a shallow clone of your fork, with files from the most recent history/commit.

Set up Syncing from Parent

Now that you have downloaded a copy of your fork, you will need to set up an upstream remote to the parent repository.

As mentioned earlier, the main repository is referred to as the upstream repository. Your fork is referred to as the origin repository.

You need a reference from your local clone to the upstream repository in addition to the origin repository. This is so that you can sync changes from the main repository without the requirement of forking and cloning repeatedly.

1. Change the directory to the new contribute directory:

   cd contribute

2. Add a remote reference to the main contribute repository:

   git remote add upstream https://github.com/freeCodeCamp/contribute.git

3. Ensure the configuration looks correct:

   git remote -v

   The output should look something like below (replacing YOUR_USER_NAME with your GitHub username):

   origin    https://github.com/YOUR_USER_NAME/contribute.git (fetch)
   origin    https://github.com/YOUR_USER_NAME/contribute.git (push)
   upstream    https://github.com/freeCodeCamp/contribute.git (fetch)
   upstream    https://github.com/freeCodeCamp/contribute.git (push)

Install Dependencies

First, ensure you have pnpm installed globally:

npm install -g pnpm

Then install the project dependencies:

pnpm install

This will install all required dependencies and set up Git hooks automatically.

Start the Development Server

You can now start up the development server:

pnpm develop

Once ready, open a web browser and visit http://localhost:4321:

http://localhost:4321

Congratulations - you're all set!

You now have a copy of freeCodeCamp’s documentation site running on your local machine. Go ahead and start making changes to the documentation.

Note

If you have issues with the setup or need to run other commands like linting, testing, or building for production, check the Quick Commands Reference at the end of this guide.

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 test:update	Update test snapshots
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.