Contributing to the docs¶

This site is built with MkDocs + the Material theme and published as versioned docs to GitHub Pages using mike.

Adding or editing a page¶

Add or edit a Markdown file under docs/.
Register it in the nav: tree in mkdocs.yml (omitted files only produce a warning, so it is easy to forget — add it).

Preview locally:

make docs        # serves on http://localhost:8050
make docs-down   # stop the docs container

Before pushing, run the strict build — CI runs the same check and fails on broken links or nav:
```
make docs-strict
```

The version dropdown is not shown by make docs

make docs runs a plain mkdocs serve, which has no concept of versions. The version-picker dropdown only appears on the deployed gh-pages site, where mike builds it. Its absence locally is expected, not a bug.

How versioning works¶

Deploys are fully automated — never run mike by hand against the remote.

mike keeps a long-running orphan gh-pages branch. Each deploy writes the built site into a per-version subdirectory and updates a versions.json that powers the dropdown. Versions accumulate side by side; aliases (main, latest) are pointers mike repoints.

The Merge Main workflow (.github/workflows/merge-main.yml) calls the reusable mike-deploy workflow on every push to main:

Trigger	What gets deployed
Any push to `main`	`mike deploy main` — the in-flight dev docs (the `main` version)
A release-please release merge	additionally `mike deploy --update-aliases <version> latest` and `mike set-default latest`

So main always tracks the tip of main, and latest always points at the newest release. The bare site URL redirects to latest.

One-time GitHub Pages setup¶

The gh-pages branch is created automatically by the first deploy. Pages must then be told to serve from it (a repo setting, done once):

gh api -X POST repos/mcfilu/grinsystem-api/pages \
  -f source[branch]=gh-pages -f source[path]=/

Custom domain (`docs.grintest.pl`)¶

The site is served from https://docs.grintest.pl instead of the bare mcfilu.github.io/grinsystem-api/ URL. Three pieces have to line up — all one-time:

Cloudflare DNS (the grintest.pl zone). Add a CNAME record:

Type Name Target Proxy

CNAME docs mcfilu.github.io DNS only (grey cloud)

Keep it DNS-only, not proxied. GitHub issues the TLS certificate through a Let's Encrypt challenge it serves itself; a Cloudflare proxy would intercept that challenge and block cert issuance.
GitHub Pages custom domain. Repo → Settings → Pages → Custom domain → docs.grintest.pl → Save, or:
```
gh api -X PUT repos/mcfilu/grinsystem-api/pages -f cname=docs.grintest.pl
```
This writes a CNAME file to the root of the gh-pages branch and starts domain verification.
Enforce HTTPS. Once GitHub finishes provisioning the Let's Encrypt cert (can take up to ~24 h after the DNS record first resolves), tick Enforce HTTPS in the same Pages settings.

Why the CNAME is not in docs/

The CNAME belongs at the root of gh-pages, not inside a version subdirectory — so it is deliberately not committed under docs/ (that would copy it into every versioned subfolder and never reach the root GitHub Pages reads). Each mike deploy only rewrites the version subdirs, versions.json, and the redirect index, leaving the root CNAME untouched. If a deploy ever drops it, re-save the custom domain in Pages settings to re-commit it.

Release versioning (release-please)¶

Versions are produced by release-please from conventional commits; mike simply publishes whatever version string a release carries. Two things worth knowing when cutting the first release or a pre-release — these are not configured yet, apply them when you actually cut the release:

Force the first version (e.g. 0.0.1 instead of release-please's default bump). Either add a footer to a commit on main:
```
Release-As: 0.0.1
```
or set it for one release in release-please-config.json:
```
"release-as": "0.0.1"
```
Alpha / beta pre-releases. Enable a pre-release lane in release-please-config.json:
```
"prerelease": true,
"prerelease-type": "alpha"
```
mike deploys pre-release version strings (0.1.0-alpha.1, …) like any other. "Promoting" a pre-release to stable later is just another release — release-please cuts the stable version and the deploy repoints latest to it automatically.