The docs site of Gatepost, the open-source tools for Nigeria's digital postcode.

Docs · Playground · Readiness tracker · Contributing · Discussions

Unofficial. Not made or endorsed by NIPOST.

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.

What the site holds

• A playground where you check a postcode in your browser.
• Guides for the TypeScript core, the TypeScript client, the PHP package, the HTML field, the React field and the WooCommerce plugin.
• An API reference that the build writes from the TSDoc comments and the PHP doc comments.
• The spec pages: the grammar, the client contract, the field and the glossary.
• A readiness tracker of common tools that reject the new postcode.

Run it on your computer

You need Node 24.15 or later, pnpm 12 through Corepack, and PHP 8.1 or later with Composer.

git clone --recurse-submodules https://github.com/gatepost-dev/docs
cd docs
pnpm install
pnpm sdk
pnpm dev

pnpm sdk builds the js and php submodules, because the site documents their source. The woocommerce submodule needs no build. The site copies one screenshot from it. pnpm dev serves the site at http://localhost:4321/docs/.

Add a page

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.

The code examples on each hand-written page run against the SDKs, so a wrong example fails the check.

Contribute

Read the contributing guide before you open a pull request. Ask questions in Discussions. Report a problem with a page in Issues. Report a security problem through the private form.

Licence

Apache-2.0. See LICENSE and NOTICE.