Skip to content

Drop versioning from the documentation site - #277

Merged
jnioche merged 3 commits into
mainfrom
docs-unversioning
Aug 29, 2026
Merged

Drop versioning from the documentation site#277
jnioche merged 3 commits into
mainfrom
docs-unversioning

Conversation

@dpol1

@dpol1 dpol1 commented Aug 29, 2026

Copy link
Copy Markdown
Collaborator

Closes #274.

Zensical already shows the latest GitHub release in the repository card, so no separate build-time version label. First deploy from the next release, not 1.2: switch the Pages source to GitHub Actions when publishing it, then delete gh-pages.

dpol1 added 2 commits August 29, 2026 09:32
Versioned docs were introduced in #229 but SPRUCE users run the latest
release, so nobody needs 1.1 alongside 1.2. Meanwhile Google was holding
three self-canonical copies of the site (/1.1/, /1.2/, /dev/) and there
was no sitemap at the root to consolidate them. See #274.

The workflow goes back to the shape it had before #229: zensical build,
upload-pages-artifact, deploy-pages, with read-only contents permission
and no gh-pages branch. It runs when a release is published, or by hand
for a given tag, and always checks out refs/tags/ so the site describes
a release rather than main. A guard refuses tags that still carry the
mike configuration, so 1.2 cannot be deployed from here by mistake.

No redirects for the old /latest/ and /1.2/ paths; Zensical writes the
sitemap at the root of the build. The header card already shows the
latest GitHub release, which replaces the version selector.

After merging, the Pages source has to be switched from the gh-pages
branch to GitHub Actions when the next release is published, and the
gh-pages branch can then be deleted.
@dpol1
dpol1 requested a review from jnioche August 29, 2026 07:34
@dpol1 dpol1 added the bug Something isn't working label Aug 29, 2026
@dpol1 dpol1 added this to the 1.3 milestone Aug 29, 2026
@jnioche

jnioche commented Aug 29, 2026

Copy link
Copy Markdown
Member

Looks great

The site the branch produces has been checked: zensical build --clean --strict passes with no
issues, the home page canonicalises to https://opensourcegreenops.cloud/, and sitemap.xml lists
all 17 pages at unversioned URLs.

Remaining work

Note to self

  • Switch the repository publishing source to GitHub Actions. The repository is still set to
    publish from the gh-pages branch (build_type: legacy), so actions/deploy-pages cannot
    deploy. Change it under Settings, Pages, Source, or with
    gh api -X PUT repos/DigitalPebble/spruce/pages -f build_type=workflow. Note that the
    actions/configure-pages step in the workflow does not do this: its enablement input
    defaults to false and, even when enabled, needs a token other than GITHUB_TOKEN.

Improvements

  • Add docs/src/robots.txt. There is currently no robots.txt at the root and no sitemap
    reference:

    ```
    User-agent: *
    Allow: /
    
    Sitemap: https://opensourcegreenops.cloud/sitemap.xml
    ```
    
  • Add docs/src/CNAME containing opensourcegreenops.cloud. The custom domain is stored as
    a repository setting, and changing the publishing source is the point at which it is most
    likely to be disturbed. Losing it takes the site offline. Zensical copies both of these files
    from docs_dir into the build output verbatim, so they ship inside the artifact.

Workflow improvements

  • Build with --strict (zensical build --clean --strict) so warnings such as a broken
    internal link fail the build instead of shipping. The branch already passes with it enabled.
  • Rename the concurrency group from gh-pages to pages. No branch is involved any more.
  • Print a message when the version guard trips. It currently fails on a bare non-zero exit
    from grep, which does not explain itself to whoever hits it.
  • Decide whether to keep actions/configure-pages. It is close to a no-op here, since
    Zensical does not use its outputs. It is worth keeping only as an early, clear failure if
    Pages is not enabled.

Open question

  • workflow_dispatch currently requires a release tag, so there is no way to publish a
    documentation-only fix without cutting a release. That is consistent with "the site describes
    the latest release", but it does mean a typo waits for the next one. An optional ref input
    falling back to the tag would allow both. Worth deciding deliberately.

After the first deployment

  • Check that https://opensourcegreenops.cloud/ resolves and the TLS certificate is intact.
  • Confirm the old URLs (for example /1.2/methodology/) now return 404.
  • Submit the root sitemap.xml in Google Search Console and Bing Webmaster Tools, and request
    removal of the outdated versioned URLs so they drop out of the index sooner.
  • The gh-pages branch can be deleted once the deployment is confirmed. Nothing reads it, and
    keeping it for a while is a cheap rollback path.

@jnioche jnioche added the documentation Improvements or additions to documentation label Aug 29, 2026
robots.txt points crawlers at the root sitemap, which is the whole reason
for dropping the versioned URLs. Zensical copies it into the build as is.

The build now runs with --strict so a broken internal link fails the job
instead of shipping, the version guard explains itself when it trips, and
the concurrency group is called pages since no branch is involved any more.
@dpol1

dpol1 commented Aug 29, 2026

Copy link
Copy Markdown
Collaborator Author

Done in 60daf29: robots.txt, --strict, an error message on the guard, and the pages concurrency group.

Add docs/src/CNAME

Skipped: for a workflow deploy GitHub says "any existing CNAME file is ignored and is not required", the domain lives in the Pages setting (gh api repos/DigitalPebble/spruce/pages shows cname today). Worth rereading that field right after the switch.

Decide whether to keep actions/configure-pages

Kept, it is the step that fails early and clearly if the source is still gh-pages.

An optional ref input falling back to the tag would allow both

I'd keep tags only, a typo can go out as a patch release and the site keeps matching the card. Your call.

@jnioche
jnioche merged commit 6031c88 into main Aug 29, 2026
3 checks passed
@jnioche
jnioche deleted the docs-unversioning branch August 29, 2026 10:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Remove versioning for the documentation

2 participants