This repository contains the Pantheon documentation as well as the tools to build local test environments.
- 2023/02: Pantheon Docs is now a Pantheon Front-End site running Gatsby 4.
- 2019/08: We've relaunched the project using Gatsby for faster development, and much faster page speed.
Our docs are written in Markdown and extended with MDX components. The pages live in source/content
. Read CONTRIBUTING for more details on contributing documentation improvements.
origin Read our Style Guide for our guidelines on how to write documentation.
-
MacOS or Linux system (untested with Bash on Windows)
-
Gatsby CLI:
npm install -g gatsby-cli
-
Alternatively, you can use Lando. Use Lando to bypass installing Node.js and the Gatsby CLI on your local machine. Lando requires a Docker version in the
2.1.0.0
-3.1.99
range.
This list of steps should work on a Mac with Homebrew:
brew install node
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
nvm install 18
npm install -g gatsby-cli
Fork and clone this repository:
git clone [email protected]:pantheon-systems/documentation.git
cd documentation
We use the gatsby-remark-embed-snippet to use files from GitHub in our docs. Before you can build a local development site, you need to provide a GitHub token to the environment:
- Log in to GitHub and go to https://github.com/settings/tokens
- Click Generate new token.
- Give the token a name, expiration, and description.
- Select your GitHub user as the resource owner.
- For repository access, select Only select repositories and select your fork of this repository.
- Under Repository permissions, choose Access: Read-only from the Access dropdown button.
- Click Generate token.
Alternatively, if you'd rather create a classic-style token:
-
Log in to GitHub and go to https://github.com/settings/tokens
-
Click Generate new token (classic)
-
Give the token a name and click the public_repo checkbox, then the Generate Token button at the bottom
-
Copy the token to your clipboard
-
In the root
documentation
directory, create a new file called.env.development
and add (replacing$TOKENHASH
):GITHUB_API=$TOKENHASH
From the documentation
directory:
npm ci
Still in the documentation
directory:
npm start
Use your local browser to navigate to localhost:8000/
.
Locally saved updates to docs are automatically refreshed in the browser.
Alternatively, you can use Lando. The lando start
command initiates the app, installs node dependencies, and starts the gatsby develop
server for you:
lando start
You can view the local environment at localhost:8000/
. Updates to docs are automatically refreshed in the browser.
We include several tools to test that new content doesn't break the documentation. Most of these tests are performed automatically by our continuous integration service, but pull requests created from external contributors aren't included in CI tests. If you want to manually test your branch, you can execute the following tests within the Docker container.
To check for merge conflict messages accidentally committed into the docs, run merge_conflicts.sh
from scripts
.