From d6ba0d17eabcde251daeaef1bf9b4241aa778c38 Mon Sep 17 00:00:00 2001 From: Huon Wilson Date: Mon, 11 Mar 2024 09:57:23 +1100 Subject: [PATCH] Document which types of content are where, and how to edit them --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/README.md b/README.md index 25da3035f..fec8f9877 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,28 @@ All of the material and stitching for [pantsbuild.org](pantsbuild.org). +## Layout + +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. + +### Evergreen pages + +`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](https://www.pantsbuild.org) and [community information](https://www.pantsbuild.org/community/getting-help) among others. `src/` also contains helpers like MDX/React components, CSS and JS. + +These should be edited directly in this repository. + +### Blog + +`blog/` contains [the Pants blog](https://www.pantsbuild.org/blog). To write a post, follow the structure of other blog posts. + +These should be edited directly in this repository. + +### Per-version documentation + +`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`](.github/workflows/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 . To make changes to documentation for stable release series, edit there and cherry-pick to the appropriate milestone (still in ), so that it's included in the next release in that series. + ## Development The docs site is a JS project, so you'll want `nvm` and `yarn` installed.