All of the material and stitching for pantsbuild.org.

This repository contains three categories of content. Most of it should be edited in this repository, except for the auto-generated documentation for each version of Pants.

src/ contains content and configuration that isn't associated with a particular version of Pants. In particular, in src/pages/ you'll find the definitions of the front page and community information among others. src/ also contains helpers like MDX/React components, CSS and JS.

These should be edited directly in this repository.

blog/ contains the Pants blog. To write a post, follow the structure of other blog posts.

These should be edited directly in this repository.

docs/ and versioned_docs/ contains the documentation for each 2.x release series of pants. After each release of Pants, the documentation is synced to this repository automatically from https://github.com/pantsbuild/pants: the sync_docs.yml workflow manages this, and is triggered by the main repository release process.

This should not be edited directly in this repository. Instead, edit in https://github.com/pantsbuild/pants. To make changes to documentation for stable release series, edit there and cherry-pick to the appropriate milestone (still in https://github.com/pantsbuild/pants), so that it's included in the next release in that series.

The docs site is a JS project, so you'll want nvm and yarn installed.

Afterwards

nvm use
yarn install

The following command will start the dev server:

npm start

By default, only the "next" docs (e.g. the docs for the version that maps to main) will get built.

To include the blog, use:

PANTSBUILD_ORG_INCLUDE_BLOG=1 npm start

To include any version(s) in addition to the "next" version:

PANTSBUILD_ORG_INCLUDE_VERSIONS=$version1,$version2 npm start

To build the site, run:

NODE_ENV=production NODE_OPTIONS="--max-old-space-size=12288" npm run build

(Note: Node needs more than the default amount of RAM because this site is beefy)

The site is fully managed via https://docusaurus.io/ and is published via GitHub Actions to GitHub Pages.