Build

• 1: CI/CD
• 2: Git repository layout and branch model

1 - CI/CD

Agent-support checks

The site has an AFDocs configuration and npm script to generate a scorecard locally:

• Config: agent-docs.config.yml
• Script: _check:afdocs in package.json

To generate a fresh scorecard, run each of these commands in separate terminals:

npm run serve             # From one terminal
npm run check:afdocs:dev  # From another terminal

The latter command saves the generated scorecard to docs/content/agent-support/afdocs-scorecard.txt under content, which will be included in Scorecard examples on the next build.

Note that the scorecard generation is not run as a part of the full CI/CD pipeline. It needs to be run manually.

Read more: AFDocs config file format.

Prettier formatting

We use Prettier to format the project-site files using the following command:

npm run check:format

To fix formatting, run:

npm run fix:format

Workaround for i18n files

The translation files in the i18n directory are formatted using Prettier. But Prettier removes the blank line before the # Feedback section heading. This seems to be a known issue, for example see:

• Bug: Inconsistent newline formatting in YAML when changing scopes #15528
• Bug: New Line before comments at end of YAML files are removed #15720

We’ve worked around this bug, and avoided using prettier-ignore directives, by formatting the preceding entry in the YAML file to be a block scalar, like this:

community_guideline: >-
  Contribution Guidelines

This ensures that the blank line is preserved. Hopefully Prettier will be fixed and we’ll be able to remove this hack.

2 - Git repository layout and branch model

Repositories

Oink uses two focused repositories:

The theme repository has no embedded example site or npm workspace. Consumer sites import github.com/pgsty/oink; the project site is one such consumer.

For local development, clone both repositories as siblings and connect them with an ignored Go workspace:

~/pgsty/
├── oink/
└── oink.pgsty.com/

cd ~/pgsty/oink.pgsty.com
go work init .
go work edit -replace=github.com/pgsty/oink=../oink
export HUGO_MODULE_WORKSPACE=go.work
npm install
npm run serve

Branch model

The theme repository uses:

• main for the next theme release;
• release for the current stable release and maintenance work;
• vX.Y.Z tags for immutable public releases.

The site repository uses:

• main as its only long-lived branch for documentation, previews, and production deployment.

Site-only changes do not require a theme release. Theme changes are first validated against a local sibling checkout, released from the theme repository, then pinned in the site’s go.mod.

Published site variants

A variant’s identity comes from its configuration directory under config/:

The production workflow builds directly from main, uploads public/ as a GitHub Pages artifact, and deploys it through the Pages API. The repository does not maintain a generated Pages branch.

Pull request deploy previews use the Next configuration.

Release workflow

1. Develop the theme on main and test it against the sibling site checkout.
2. Merge the release candidate to release and create the vX.Y.Z tag in the theme repository.
3. Update the site with hugo mod get github.com/pgsty/oink@vX.Y.Z, run its checks, and merge the resulting go.mod and go.sum changes.
4. Merge and push the reviewed site update to main; that push triggers the production deployment.

This keeps theme artifacts immutable and lets documentation deploy on its own schedule.