Skip to content

Publishing the docs

The site rebuilds and republishes itself on every push to main. You do not normally need to do anything. This page is for when you want to force a publish, or when the site is not showing what you expect.

python scripts/deploy_docs.py            # build, push, deploy, verify
python scripts/deploy_docs.py --check    # verify what is live, change nothing
python scripts/deploy_docs.py --dry-run  # preflight and build, publish nothing

--check is safe to run at any time and is the fastest way to answer "is the site actually up?".

Why a script rather than a green tick

A successful Actions run is not evidence that the site works. Each of the following leaves the workflow green while the published site is stale, broken or unreachable, and every one of them happened while the site was being set up:

What goes wrong What you see
Uncommitted edits mike publishes the committed tree, so the run succeeds and republishes the previous content. The edit looks like it did not work.
No default version mike serves each version from its own directory and redirects the root only for the default. / 404s while /dev/ is fine.
Dropped CNAME mike rewrites gh-pages on every deploy. If the custom domain is not re-asserted, it detaches and the site falls back to the github.io URL.
Pages never enabled The branch is pushed and the run is green, but no Pages site exists to serve it.
Cancelled run concurrency.cancel-in-progress kills an in-flight deploy when a newer one starts, leaving the old content published.

So the script asserts on the result — real HTTP status codes, the state of the gh-pages root, the Pages API — instead of the workflow's exit status.

What it checks

Before deploying

  • The working tree is clean, because anything uncommitted will not ship.
  • main is not behind origin, so you do not publish stale content.
  • mkdocs build --strict passes, so a broken link fails here in seconds rather than in CI in minutes.

After deploying

  • The workflow run it started — not a previous one — reached success. A cancelled conclusion is treated as a failure, because it is one.
  • Pages is enabled and its custom domain matches docs/CNAME.
  • The CNAME at the gh-pages root survived the mike rewrite.
  • Every page in the smoke set returns 200, including the bare root.
  • The canonical link points at the configured site_url.

Configuration is read from mkdocs.yml and docs/CNAME rather than repeated, so changing the domain in one place is enough.

When something is wrong

Each failure prints the command that fixes it. The three most likely:

No version is marked as default, so nothing redirects /.

mike set-default --push dev

The CNAME was lost in a rewrite. Confirm the workflow's Pin the custom domain at the gh-pages root step ran, then:

gh api -X PUT repos/twmmason/science-adk/pages -f cname=science-adk.dev

Pages is not enabled on the repository.

gh api -X POST repos/twmmason/science-adk/pages \
  -f "source[branch]=gh-pages" -f "source[path]=/"

Versions

main publishes as dev. A v* tag publishes under its version number and takes over the latest alias, which then becomes the default the root redirects to. Until the first release, dev is the default — the workflow sets that automatically so a fresh clone never publishes a site with an unreachable root.