Skip to content

docs: give the README a header block and the live link #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MobileMage merged 1 commit into from
Oct 3, 2026
Merged

docs: give the README a header block and the live link #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 41 additions & 46 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,68 +1,63 @@
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gatepost-dev/.github/main/brand/gatepost-lockup-dark.svg">
<img src="https://raw.githubusercontent.com/gatepost-dev/.github/main/brand/gatepost-lockup.svg" alt="gatepost" height="48">
</picture>
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gatepost-dev/.github/main/brand/gatepost-lockup-dark.svg">
<img src="https://raw.githubusercontent.com/gatepost-dev/.github/main/brand/gatepost-lockup.svg" alt="Gatepost" width="280">
</picture>
</p>

<p align="center">The docs site of Gatepost, the open-source tools for Nigeria's digital postcode.</p>

<p align="center">
<a href="https://github.com/gatepost-dev/docs/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/gatepost-dev/docs/actions/workflows/ci.yml/badge.svg?branch=main&style=flat"></a>
<a href="LICENSE"><img alt="Licence" src="https://img.shields.io/badge/licence-Apache--2.0-blue?style=flat"></a>
</p>

<p align="center">
<a href="https://gatepost-dev.github.io/docs/">Docs</a> ·
<a href="https://gatepost-dev.github.io/docs/playground/">Playground</a> ·
<a href="https://gatepost-dev.github.io/docs/readiness/">Readiness tracker</a> ·
<a href="https://github.com/gatepost-dev/.github/blob/main/CONTRIBUTING.md">Contributing</a> ·
<a href="https://github.com/gatepost-dev/docs/discussions">Discussions</a>
</p>

# 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 <https://gatepost-dev.github.io/docs/>. Astro and Starlight build it as a static site for GitHub Pages.

> Unofficial. Not made or endorsed by NIPOST.
## What the site holds

[![CI](https://github.com/gatepost-dev/docs/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gatepost-dev/docs/actions/workflows/ci.yml)
[![Licence](https://img.shields.io/badge/licence-Apache--2.0-blue)](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

Expand Down