Pantheon Documentation

https://docs.pantheon.io/

This repository contains the Pantheon documentation as well as the tools to build local test environments.

Changelog

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

Contributing

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.

Style Guide

Read our Style Guide for our guidelines on how to write documentation.

Local Installation

Prerequisites

• MacOS or Linux system (untested with Bash on Windows)

• Node.js

• NVM

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

Mac Steps

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

Get the Code

Fork and clone this repository:

git clone git@github.com:pantheon-systems/documentation.git
cd documentation

Create a GitHub API Token

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:

1. Log in to GitHub and go to https://github.com/settings/tokens
2. Click Generate new token.
3. Give the token a name, expiration, and description.
4. Select your GitHub user as the resource owner.
5. For repository access, select Only select repositories and select your fork of this repository.
6. Under Repository permissions, choose Access: Read-only from the Access dropdown button for Contents.
7. Click Generate token.

GitHub Tokens (classic)

Alternatively, if you'd rather create a classic-style token:

1. Log in to GitHub and go to https://github.com/settings/tokens

2. Click Generate new token (classic)

3. Give the token a name and click the public_repo checkbox, then the Generate Token button at the bottom

4. Copy the token to your clipboard

5. In the root documentation directory, create a new file called .env.development and add (replacing $TOKENHASH ):

   GITHUB_API=$TOKENHASH

Using GitHub Codespaces

A GitHub Codespace can be used to test the site as well. To set up a Codespace, navigate to the branch you want to use as the base (e.g. main) and click the Code dropdown.

This will take you to a VSCode-like interface with a Terminal window. From here, export your GitHub API token you created in the previous step using the following command (replacing $TOKENHASH with your API token):

export GITHUB_API=$TOKENHASH

Now you can run npm ci and npm start in the Terminal panel at the bottom of the page. The docs site will build inside the Codespaces container and install Node dependencies just like it would on your local machine. When the Node server is running, a dialog box will appear at the bottom right corner asking if you want to open the Codespace in a browser and if you want to make the Codespace public.

Clicking on the link will take you to a live site that's running on the current branch of the repository. If you opted to make the Codespace public, you can share the link to others and they will be able to view the site after accepting a warning that they are visiting someone else's Codespace. If the Codespace was not made public, only your GitHub user will be able to see it.

Working with branches on Codespaces

You can open a Codespace (or load an existing Codespace) on a particular branch by first navigating to that branch in the GitHub repository. Alternately, if you already have the VSCode editor open, you can select a specific branch by clicking the branch name at the bottom left, then selecting the branch you would like to switch to in the panel that appears at the top of the screen. The Codespace will make the necessary adjustments and rebuild the docs site on that branch.

Notes on running in Codespaces

Codespaces is free for individuals for 60 hours of runtime for 2 cores, after which your user is billed for additional time. It's unclear whether Pantheon's Enterprise account would own billing, but as of this writing it appears to be billed on a per user basis. For this reason, it's important to not leave your Codespaces running when you're done with them.

Install With The Gatsby Cli

From the documentation directory:

npm ci

Run

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.

Install With Lando

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.

Code Formatting

We use Prettier to enforce code style on changed files. On each pull request to the repository, if any .js, .jsx, .ts or .tsx files are modified in the /src directory, We run Prettier to check for code styling issues on the updated/changed files. If Prettier made any changes, those changes are automatically committed back to the PR (see example PR).

To automatically fix formatting issues across the entire /src directory, run:

npm run format

Be cautious when running this command, as it will automatically fix any formatting issues it can.

Testing

To reduced the likelihood of regressions and bugs this site uses a few different testing tools:

Visual Regression Tests

Within the tests directory there are a number of visual regression tests that can be run to compare the current state of the site to a PR preview or the live site. These tests are meant to be run locally instead of CI as they have a high rate of false positives.

Unit Tests

Unit tests for custom logic are written in in Vitest and can be executed with

npx vitest src/components

These tests are executed in CI via a GitHub Action.