Creating a local environment

You can run the GitHub Docs application locally on your computer.

In this article

About GitHub Docs site structure

The GitHub Docs site was originally a Ruby on Rails web application. Some time later it was converted into a static site powered by Jekyll. A few years after that it was migrated to Nanoc, another Ruby static site generator.

Today it's a dynamic Node.js webserver powered by Express, using middleware to support proper HTTP redirects, language header detection, and dynamic content generation to support the various flavors of GitHub's product documentation, like Free, Pro, & Team and GitHub Enterprise Server.

The tooling for this site has changed over the years, but many of the tried-and-true authoring conventions of the original Jekyll site have been preserved.

  • Content is written in Markdown files, which live in the content directory.
  • Files in the data directory are available to templates via the {% data %} tag.
  • Markdown files can contain frontmatter.
  • The redirect_from Jekyll plugin behavior is supported.

Setting up your local environment

You can clone the GitHub Docs repository and run the application locally on your computer, after some initial setup.

Installing Node.js

The GitHub Docs site is powered by Node.js. It runs on macOS, Windows, and Linux environments.

To run the site, you'll need Node.js. To install Node.js, download the "LTS" installer from nodejs.org. To check which Node version you need, you can see the package.json file in the GitHub Docs repository. The Node version is listed in the engine field, similar to the following example, which indicates you can use Node major version 16 or Node major version 18.

"engines": {
    "node": "^16 || ^18"
}

If you're using nodenv, see the nodenv docs for instructions on switching Node.js versions.

Starting a local GitHub Docs server

Once you've installed Node.js (which includes the popular npm package manager), open your terminal and run the following commands.

git clone https://github.com/github/docs
cd docs
npm ci
npm start

You should now have a running server. To access your local preview environment, visit localhost:4000 in your browser.

When you're ready to stop your local server, type Ctrl+C in your terminal window.

Note

You should typically only need to run npm ci and npm run build each time you pull the latest version of a branch.

  • npm ci does a clean install of dependencies, without updating the package-lock.json file.
  • npm run build creates static assets, such as JavaScript and CSS files.

If you would like to read more about debugging and troubleshooting the GitHub Docs application, see "Troubleshooting your environment" in the github/docs repository.

Using browser shortcuts

The src/bookmarklets directory in the GitHub Docs repository contains browser shortcuts that can help with reviewing GitHub documentation. For more information, see the directory's README.

Enabling different languages

By default, the local server does not run with all supported languages enabled. If you need to run a local server with a particular language, you can temporarily edit the start script in package.json and update the ENABLED_LANGUAGES variable.

For example, to enable Japanese and Portuguese in addition to English, you can edit package.json and set ENABLED_LANGUAGES='en,ja,pt' in the start script. Then restart the server for the change to take effect.

Note

Before you commit your changes, you should revert the package.json file to its original state.

The supported language codes are defined in src/languages/lib/languages.js.

Using GitHub Codespaces

As an alternative to running GitHub Docs locally, you can use GitHub Codespaces. GitHub Codespaces enable you to edit, preview, and test your changes directly from your browser.

For more information about using a codespace for working on GitHub documentation, see "Working on GitHub Docs in a codespace."

Further reading