How to Work on Documentation

Welcome to the guide for contributing to freeCodeCamp’s documentation site! This site is built using Astro with the Starlight theme and deployed on Cloudflare Pages.

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:

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

Fork “freeCodeCamp/contribute”
On the create new fork page, check the details and click the Create fork button.
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. You can always delete your fork if you want to start fresh.

Clone your Fork from GitHub

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

Run these commands on your local machine:

Open a terminal in your projects directory, for example:
```
/home/username/projects/
```
Clone your fork of the contribute repository, replacing YOUR_USER_NAME with your GitHub Username
Terminal window
```
git clone --depth=1 https://github.com/YOUR_USER_NAME/contribute.git
```
This will download the entire contribute repository to your projects directory.

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

Change the directory to the new contribute directory:
Terminal window
```
cd contribute
```

Add a remote reference to the main contribute repository:

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

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)

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:
Terminal window
```
git checkout -b feature/your-feature-name
```
Ensure you are on your new branch:
Terminal window
```
git branch
```
You should see your new branch name with an asterisk (*) next to it, indicating it’s the active branch.

Prerequisites

Node.js (LTS version recommended)
pnpm v10 (required - do not use npm or yarn)

Core Development Commands

# Install pnpm globally if not already installed
npm install -g pnpm

# Install dependencies
pnpm install

# Start the development server (localhost:4321)
pnpm develop

# Build for production
pnpm build

# Build and preview locally using Cloudflare Pages
pnpm preview

Code Quality Commands

# Run Prettier and ESLint checks
pnpm lint

# Auto-fix Prettier and ESLint issues
pnpm format

# Install Git hooks (runs automatically on install)
pnpm prepare

Testing Commands

# Run all tests once
pnpm test

# Update test snapshots
pnpm test:update

# Run a specific test file
npx vitest run tests/homepage.test.ts

# Run tests matching a pattern
npx vitest run -t "has correct title"

Working on Documentation Content

To work on the contributing guidelines, 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.

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.

Translating Docs with Internal Links

When you work on translating docs on Crowdin, make sure to replace the #target-section-heading-id with the id on the translated document. Learn more about translating files here.

Structure of the Docs Website

The site is generated using Astro and served using Cloudflare Pages. 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 Pages

Serving the Documentation Site Locally

The documentation site can be served locally using the development command:

pnpm develop

The documentation site should be available at http://localhost:4321

Deployment

The site is deployed on Cloudflare Pages. Please check the wrangler config for deployment details.

Proposing a Pull Request (PR)

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