Skip to content

docs: rewrite the upgrading page - #731

Draft
eizedev wants to merge 2 commits into
mainfrom
docs/upgrading-rewrite
Draft

eizedev wants to merge 2 commits into
mainfrom
docs/upgrading-rewrite

Conversation

@eizedev

@eizedev eizedev commented Nov 22, 2026

Copy link
Copy Markdown
Owner

The upgrading page had grown to 1,658 lines. Update steps, the newest release and every older release were mixed, and GitHub showed the raw { #anchor } after each heading. This rewrites it from scratch.

What changes:

  • docs/getting-started/upgrading.md has two parts. "Update an installation" has one short section per way of installing. "From 0.8 to 0.9" has a four-step summary at the top, the breaking changes with who and what to do, then the other changes that can break a test, a script or a client. Items with nothing to do are left out. They stay in the changelogs.
  • docs/getting-started/upgrading-older.md is new. It holds the steps for 0.8.1 and earlier, moved without content changes. It is in the nav under Upgrading.
  • Anchors use <span id> inside the heading. That renders cleanly on GitHub and on the site, and the strict build checks them.
  • Old anchors keep working. The redirect plugin cannot redirect anchors of a page that still exists. So overrides/main.html gets a small script: on a page whose front matter sets anchors_moved_to, a link to an anchor the page no longer has goes on to the same anchor on that page. Every anchor that changelogs, release notes, docs and the server's messages link to exists on one of the two pages.
  • docs/reference/localisation.md and docs/versioning.md point to the new page where needed.

Checked: zensical build --strict, check-readme-links.js, node --test tests/*.test.js, Vale on the new page, and a neutral review of the rendered page as a React/element user, a server operator and a core/CLI developer.

Places checked for descriptions of this page: README, PRODUCT.md, CONTRIBUTING.md, AGENTS.md, docs/versioning.md, docs/embed/index.md, the getting-started and reference pages that link it, the package READMEs and changelogs.

🤖 Generated with Claude Code

eizedev and others added 2 commits November 22, 2026 16:00
…elease

Older releases move to their own page. Old anchors on the upgrading page
go on to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ndings

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eizedev
eizedev marked this pull request as draft November 22, 2026 15:07

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant