Build

Tooling, local development setup, CI/CD workflows, deployment environments, and automation details.

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

1 - CI/CD

Prettier formatting

We use Prettier to format Docsy and the website files using the following command:

npm run check:format

To fix formatting, run Prettier: npm run fix:format.

i18n workaround

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:

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.

These two projects are kept in sync at release points, but they may diverge between releases, usually to allow the website to ship doc content and UX improvements without forcing a theme release.

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 current stable theme version
Publishing branches used by Netlify:
- deploy/prod: production site for the current stable release docs.
- doc-rooted: production branch for the doc-rooted site variant.
- These branches determine what is published. They are not feature development branches.

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

Workflow

General workflow

Theme and site work is done on main.
When ready to release:
- Stable release: fast-forward merge from main to release.
- Patch release: create and merge a release PR from main to release, e.g., by cherry-picking relevant commits.
Publish site updates:
- Fast-forward deploy/prod from main when possible.
- Otherwise (usually because of release was patched),
- Bring release-facing site updates (for example changelog and release blog updates) onto main from release.
Netlify deploys from deploy/prod and doc-rooted.

This keeps theme releases and site deploys coordinated, but not tightly coupled.

Patch release workflow

For patches to the theme or website, generally prefer making the changes to main first, though you can apply them to release then merge back to main. Assuming the former, the patch-release workflow is as follows:

Cherry-pick relevant commits from main to release.
Create a and merge a release PR from main to release.
Bring release-facing site updates (for example changelog and release blog updates) back onto main from release.
Update deploy/prod from main by fast-forward merging if possible, if not then selectively bring in release relevant changes.

Branch sync and invariants

release:

The theme release and maintenance branch.
Theme tags come from this branch.
Flow is usually from main to release via fast-forward merge, when possible, cherry-picking otherwise (on patch releases)
Periodically, after a patch release, record branch ancestry without taking content by periodically running git merge -s ours release on main.

deploy/prod:

Reflects the current release docs baseline
Can include site-only improvements that are compatible with the current release

Why this model?

Keeps stable theme releases predictable while main moves quickly.
Lets the website ship docs UX improvements without forcing a theme release.
Preserves clear release tags for theme consumers.
Keeps branch responsibilities explicit for a small maintainer team.