Drop versioning from the documentation site - #277
Conversation
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.
|
Looks great The site the branch produces has been checked: Remaining workNote to self
Improvements
Workflow improvements
Open question
After the first deployment
|
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.
|
Done in 60daf29: robots.txt,
Skipped: for a workflow deploy GitHub says "any existing CNAME file is ignored and is not required", the domain lives in the Pages setting (
Kept, it is the step that fails early and clearly if the source is still
I'd keep tags only, a typo can go out as a patch release and the site keeps matching the card. Your call. |
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.