Build

• 1: CI/CD
• 2: Git repo info and branch model

1 - CI/CD

Agent-support checks

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

• Config: docsy.dev/agent-docs.config.yml
• Script: _check:afdocs in docsy.dev/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 docsy.dev/content/en, 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 Docsy and the website 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 repo info and branch model

Monorepo

The main Docsy repository is effectively a monorepo containing the Docsy:

• Theme at the repo root
• Website in the docsy.dev directory. The website uses the Docsy theme, of course, with extra styling.

The main Docsy example site is Goldydocs, located in the Docsy example site repository.

Branch model

This repository’s branch model is as follows:

• main: development branch for the next theme release and next site content.
• release: release and maintenance branch for the latest theme release.
• deploy/prod and doc-rooted: publishing branches used by Netlify. These branches determine what is published (see the table below); they are not feature development branches.

The Goldydocs repo has the same model, except for doc-rooted which is not used.

Published sites

Netlify publishes the following site variants. A variant’s version identity (version and related params) comes from its config directory under docsy.dev/config/:

PR deploy previews build like the Next variant.

Tags

• Release tags (vX.Y.Z and theme/vX.Y.Z) mark official theme releases.
• They never move: the release-tag-integrity ruleset blocks their update and deletion, with no bypass.
• Only the designated releaser creates them, per the release-tags ruleset.

Workflow

Overview

1. Theme and site work is done on main.

2. When ready to release:

   • Release from main (the usual case).
   • Patch on release (when main carries work that isn’t ready to release).

3. Publish site updates: fast-forward deploy/prod from release.

4. Netlify deploys from deploy/prod and doc-rooted.

Release from main

1. After git fetch upstream, if release has commits that main doesn’t (git log upstream/main..upstream/release lists them, after a patch on release), restore the fast-forward path before the release-preparation PR merges.

2. Once the release tag, RELEASE_TAG (for example, v0.17.1), is pushed, fast-forward release to it:

   git fetch upstream --tags
   git switch -C release upstream/release
   git merge --ff-only RELEASE_TAG
   git push upstream release
   

Patch on release

Fix on main first whenever the fix applies there; a fix that doesn’t apply there lands only on release. Then:

1. Open a PR against release with the fix (cherry-picked from main when it landed there) and the release-preparation changes, and merge it.
2. Port the release-facing site updates (changelog, release blog post, tdVersion.latest) onto a branch off main and merge them by PR. A PR from release itself would carry the patch’s version stamps.

Branch sync and invariants

main: for its rules and the merge gates, see Merge requirements.

release:

• Follows main: divergence lasts only from a patch on release to the next release from main.
• Every official release tag is reachable from it.
• Stays at the latest release between releases: it is the base for patches.
• Never rewritten: no force pushes, no deletion (enforced by its ruleset).
• Receives content only through releases from main or patches on release.
• Checks (including EasyCLA and workflow security analysis) run on PRs into release; acting on them is the merging maintainer’s call. Merge with EasyCLA green, though: a miss on release can’t be undone and blocks the next restore until the author signs.

deploy/prod: follows release as a pointer, never with commits of its own; the published docs change only when release moves.

Why this model?

• Keeps theme releases predictable while main moves quickly.
• Keeps release a follower of main, so a patch never opens a second line of development.
• Protects release against rewriting without gating it: requiring main’s PR-scoped gates there would refuse the fast-forward from main, whose content already passed them.
• Keeps deploy/prod a pointer, so publishing is a deliberate last step, separate from cutting the release.