Skip to main content
This guide walks you through setting up a local development environment for the GitHub Docs project and making your first content contribution. The full site runs locally at localhost:4000 so you can preview changes before opening a pull request.

​
Prerequisites

Node.js v24

The site requires Node.js ^24. Download the LTS installer from nodejs.org or use a version manager like nodenv. The required version is specified in package.json.

Git

You’ll need Git to clone the repository and manage branches. See the Set up Git guide if you’re starting from scratch.

​
Set up your environment

1

Fork and clone the repository

Fork github/docs on GitHub, then clone your fork locally:
git clone https://github.com/YOUR-USERNAME/docs
cd docs
If you only want to read the source without contributing, you can clone the upstream directly:
git clone https://github.com/github/docs
cd docs
2

Install dependencies

Install all Node.js dependencies using a clean install. This does not modify package-lock.json:
npm ci
Run npm ci again any time you pull new changes from the remote — dependency versions may have been updated.
3

Build static assets

Generate the JavaScript and CSS bundles needed by the application:
npm run build
You only need to run this once per branch checkout. It does not need to be re-run when you edit Markdown content.
4

Start the development server

Start the local Node.js/Express server:
npm start
Open http://localhost:4000 in your browser. You should see the full docs site running locally.To stop the server, press Ctrl+C in your terminal.
Prefer working in the browser? Use GitHub Codespaces to get a fully configured environment in minutes — no local installation required. Open the github/docs repo and click Code > Codespaces > New codespace.

​
Make your first content edit

All English documentation lives in the /content directory, organized by product. Files are written in Markdown and use YAML frontmatter and Liquid templating.
1

Create a new branch

Always work on a dedicated branch, not on main:
git checkout -b my-content-fix
2

Find and edit a content file

Navigate to the relevant file under content/. For example, to edit the GitHub CLI overview:
content/
└── github-cli/
    └── github-cli/
        └── about-github-cli.md
Every content file starts with frontmatter:
---
title: About GitHub CLI
intro: 'You can use GitHub CLI to work with GitHub from the command line.'
versions:
  fpt: '*'
  ghes: '*'
  ghec: '*'
---
Edit the Markdown body below the frontmatter. The dev server does not hot-reload content — refresh your browser at localhost:4000 to see changes.
3

Run the content linter

The content linter enforces style, structure, and quality rules across all Markdown files. Run it on your changed files before committing:
npm run lint-content -- --paths content/github-cli/github-cli/about-github-cli.md
To lint all changed files at once:
npm run lint-content
Linting errors will block your pull request’s required checks. Fix them locally to save time.
The linter can auto-fix some issues. Run with --fix to apply safe automatic corrections:
npm run lint-content -- --fix --paths content/path/to/file.md
4

Commit your changes

Stage and commit your edits:
git add content/github-cli/github-cli/about-github-cli.md
git commit -m "docs: clarify GitHub CLI authentication steps"

​
Open a pull request

Push your branch to your fork and open a pull request against github/docs: 
git push origin my-content-fix
Then go to your fork on GitHub and click Compare & pull request. The PR template will guide you through describing your change.

Contribution guidelines

Learn about the review process, what reviewers look for, and how long merges take.

Translations

Understand how merged content is translated into supported languages automatically.

​
Enabling additional languages locally

By default, the local server only runs with English enabled. To run with additional languages, set ENABLED_LANGUAGES inline when starting the server: 
ENABLED_LANGUAGES=en,ja,pt npm start
Or set it in your .env file to avoid typing it every time. Restart the server after any change to ENABLED_LANGUAGES. Supported language codes are defined in src/languages/lib/languages.ts.

​
Next steps

Site architecture

Understand how the full repository is organized across content, data, and source directories.

Frontmatter reference

Learn all available frontmatter fields, including versions, redirects, and layout options.

Versioning

Version content across GitHub.com, GitHub Enterprise Server, and GitHub Enterprise Cloud.

Liquid helpers

Use Liquid tags for conditional content, reusables, variables, and tool switching.

Build docs developers (and LLMs) love

Get started for freeTalk to us