This document describes the process for running this application on your local computer.
This site is powered by Node.js! ✨ 🐢 🚀 ✨
It runs on macOS, Windows, and Linux environments.
You'll need Node.js to run the site. Check the version in package.json
. To install Node.js, download the "LTS" installer from nodejs.org. If you're using nodenv
, read the nodenv
docs for instructions on switching Node.js versions.
Once you've installed Node.js (which includes the popular npm
package manager), open Terminal and run the following:
git clone https://github.com/github/docs
cd docs
npm ci
npm run build
npm start
You should now have a running server! Visit localhost:4000 in your browser.
When you're ready to stop your local server, type Ctrl+C in your terminal window.
Note that npm ci
and npm run build
are steps that should typically only need to be run once each time you pull the latest for a branch.
npm ci
does a clean install of dependencies, without updating thepackage-lock.json
filenpm run build
creates static assets, such as JavaScript and CSS files
Power users may want to read more about debugging the docs application with VSCode.
As an alternative, you can simply use GitHub Codespaces. For more information about using a codespace for working on GitHub documentation, see "Working in a codespace."
In a matter of minutes, you will be ready to edit, preview and test your changes directly from the comfort of your browser.
The src/bookmarklets
directory contains some browser shortcuts that can help with reviewing GitHub documentation. See src/bookmarklets/README.md
for details.
By default the local server won't run with all supported languages enabled. If you need to run the 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, you can set it to ENABLED_LANGUAGES='en,ja,pt'
and then you need to restart the server for the change to take effect.
The supported language codes are defined in lib/languages.js.
This 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 GitHub.com 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. - Content can use the Liquid templating language.
- 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.
For more info about working with this site, check out these READMEs: