---
title: "How to Work on Documentation"
---

> Documentation Index
> Fetch the complete documentation index at: https://contribute.freecodecamp.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://help.github.com/articles/about-forks) is your own copy of the codebase. You need one to contribute.

1. Open the fork page:

   [Fork "freeCodeCamp/contribute"](https://github.com/freeCodeCamp/contribute/fork)

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.

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

### Local Machine

### Prerequisites

| Prerequisite | Version | Notes |
| - | - | - |
| [Git](https://git-scm.com/) | latest | The version bundled with your operating system is often outdated. |
| [Node.js](http://nodejs.org) | `26.x` | The "Active LTS" version. |
| [pnpm](https://pnpm.io/installation) | `12.x` | - |

Check what you have:

```bash
node -v && pnpm -v
```

Recommended, but not required:

- [Set up an SSH key](https://help.github.com/articles/generating-an-ssh-key/) for GitHub.
- Use a code editor. [Visual Studio Code](https://code.visualstudio.com/) 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

1. Clone your fork, replacing `YOUR_USER_NAME` with your GitHub username:

   ```bash
   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:

   ```bash
   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 pnpm version pinned by this repository, then install the dependencies. This also sets up the Git hooks:

   ```bash
   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.

4. Start the development server:

   ```bash
   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](#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:

   ```bash
   pnpm develop
   ```

> **Congratulations - you're all set!**
>
> The documentation site now runs in your codespace. See the [Quick Commands Reference](#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:

   ```bash
   git checkout -b feature/your-feature-name
   ```

2. Ensure you are on your new branch:

   ```bash
   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](https://github.com/freeCodeCamp/contribute/tree/main/src/content/docs). 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`](https://github.com/freeCodeCamp/contribute/blob/main/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:

```md
[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](/how-to-open-a-pull-request/).

Source: https://contribute.freecodecamp.org/how-to-work-on-the-docs-site/index.mdx