Status Update: 2023 - January/February

Pantheon's Docs team has suspended publishing all updates to docs.pantheon.io following the 4 January CircleCI incident.

We took the incident as an opportunity to revoke and rotate tokens and auths in a variety of places. Doing so showed us that the way that we were publishing changes to the site wasn't ideal and that the docs site is a perfect candidate for Pantheon's Front-End Sites offering, currently in Early Access.

We're looking forward to re-deploying on the Front-End architecture sometime in mid-February. Until then, changes that have been merged to main since 4 January are available in the GitHub repository code and can be built locally using the steps below.

We'll remove this notice and update the Changelog below after we've migrated the site.

Pantheon Documentation

https://docs.pantheon.io/

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

Changelog

2019/08/05: We've relaunched the project using Gatsby for faster development, and much faster page speed.

Contributing

Our docs are written in Markdown, 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.2/install.sh | bash
nvm install 14
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:

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.

GitHub Tokens (classic)

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
```

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.

Testing

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.

Merge Conflicts

To check for merge conflict messages accidentally committed into the docs, run merge_conflicts.sh from scripts.

aweingarten/documentation