-# Gatepost docs
+> Unofficial. Not made or endorsed by NIPOST.
-The docs site of Gatepost: guides for each SDK, the API reference, the spec and a playground.
+This repo holds the source of the site at . Astro and Starlight build it as a static site for GitHub Pages.
-> Unofficial. Not made or endorsed by NIPOST.
+## What the site holds
-[](https://github.com/gatepost-dev/docs/actions/workflows/ci.yml)
-[](LICENSE)
+- A [playground](https://gatepost-dev.github.io/docs/playground/) where you check a postcode in your browser.
+- Guides for the TypeScript core, the TypeScript client and the PHP package.
+- An API reference that the build writes from the TSDoc comments and the PHP doc comments.
+- The spec pages: the grammar, the client contract and the glossary.
+- A [readiness tracker](https://gatepost-dev.github.io/docs/readiness/) of common tools that reject the new postcode.
-## Install
+## Run it on your computer
+
+You need Node 24.15 or later, pnpm 12 through Corepack, and PHP 8.1 or later with Composer.
```sh
git clone --recurse-submodules https://github.com/gatepost-dev/docs
cd docs
pnpm install
pnpm sdk
-```
-
-`pnpm sdk` installs and builds the SDKs in the `js` and `php` submodules, because the site documents their source and runs its examples against them.
-
-## Quickstart
-
-```sh
pnpm dev
```
-Astro serves the site at `http://localhost:4321/docs/`. The scripts disable Astro's usage data, so the build sends nothing.
-
-## What it does
-
-- Builds a static site with Astro and Starlight, for GitHub Pages.
-- Writes the API reference from the TSDoc comments and the PHP doc comments of the submodules.
-- Shows the grammar, the client contract and the glossary of the `spec` submodule.
-- Runs each code example of each hand-written page against the SDKs and Gatepost's mock gateway.
-- Checks each page with axe for WCAG 2.2 AA, in the light and the dark theme.
-- Fails when a page loads anything from another website, when a page lacks the line that says that NIPOST did not make the site, or when a link inside the site breaks. The link check serves the site under `/docs/`, as GitHub Pages does.
-
-## Requirements
-
-| Requirement | Version |
-| ----------------------------------- | ----------------------------------- |
-| Node | 24.15 or later |
-| pnpm | 12, through Corepack |
-| PHP, for the PHP pages | 8.1 or later, with Composer |
-| Python, for `check-tells` and REUSE | 3.11 or later, with uv |
-| Gatepost spec | the version in the `spec` submodule |
-
-`pnpm check` runs every check that CI runs. The browser tests need Chromium: run `pnpm exec playwright install chromium` once.
-
-## Docs
+`pnpm sdk` builds the `js` and `php` submodules, because the site documents their source. `pnpm dev` serves the site at `http://localhost:4321/docs/`.
-The site itself is the docs. CI uploads the built site of each pull request as an artifact.
+## Add a page
-## Support
+1. Add a Markdown file under `src/content/docs/`. Put it in `guides/` to add a guide. The sidebar lists that folder by itself.
+2. Give the file a `title` and a `description` in its front matter.
+3. For a page outside `guides/` and `spec/`, add its name to the `sidebar` list in `astro.config.mjs`.
+4. Run `pnpm check`. It builds the site and runs every check that CI runs. The browser tests need Chromium. Run `pnpm exec playwright install chromium` one time.
-Ask questions and report problems with a page in GitHub Issues. Report security problems privately, as [`SECURITY.md`](https://github.com/gatepost-dev/.github/blob/main/SECURITY.md) describes.
+The code examples on each hand-written page run against the SDKs, so a wrong example fails the check.
-## Contributing
+## Contribute
-Read [`CONTRIBUTING.md`](https://github.com/gatepost-dev/.github/blob/main/CONTRIBUTING.md) before you open a pull request.
+Read the [contributing guide](https://github.com/gatepost-dev/.github/blob/main/CONTRIBUTING.md) before you open a pull request. Ask questions in [Discussions](https://github.com/gatepost-dev/docs/discussions). Report a problem with a page in [Issues](https://github.com/gatepost-dev/docs/issues). Report a security problem through the [private form](https://github.com/gatepost-dev/docs/security/advisories/new).
## Licence
-
+ 