Handbook pages hardcode version strings in frontmatter descriptions, body text, and internal links. When a new version is created by copying the previous one, these strings need manual updating. They don't always get updated.
Affected pages
v1000.3.2/select/+page.md line 120 — links to /v1000.3.1/lens instead of /v1000.3.2/lens. Every other version's select page links to its own version correctly. This one was copied from v1000.3.1 and the path wasn't changed.
v1000.3.2/llms/+page.md line 19 — uses v1000.3.1 as the example version string. Should reference its own version or use latest.
latest/architecture/+page.md lines 3 and 6 — frontmatter description says "How Beacon v1000.3.1 works internally" and the opening sentence says "Beacon v1000.3.1 is ~480 lines." The latest route should reflect v1000.3.2.
All three are the same class of error: version strings baked into page content that fall out of sync on copy.
Proposed fix
The DocLayout.svelte layout already derives versionPrefix from the URL path. The version is known at render time but never flows into page content.
Options, from least to most invasive:
-
Fix the three stale strings directly. Fast, but the same problem recurs on every version bump.
-
Expose the version prefix as a layout prop or store that mdsvex pages can reference. Internal links become {versionPrefix}/lens instead of /v1000.3.1/lens. Frontmatter descriptions that mention a version would need to move into the template body where they can interpolate.
-
Generate version-specific pages from a single source during the build. Each version directory would contain only the content that actually diverges (migration notes, changelog entries), not full copies of every page. This eliminates the copy-paste vector entirely but requires rethinking the routing structure.
Option 2 is likely the right balance. It keeps the current file-per-version layout intact while removing the manual step that produces these errors.
Handbook pages hardcode version strings in frontmatter descriptions, body text, and internal links. When a new version is created by copying the previous one, these strings need manual updating. They don't always get updated.
Affected pages
v1000.3.2/select/+page.md line 120 — links to
/v1000.3.1/lensinstead of/v1000.3.2/lens. Every other version's select page links to its own version correctly. This one was copied from v1000.3.1 and the path wasn't changed.v1000.3.2/llms/+page.md line 19 — uses
v1000.3.1as the example version string. Should reference its own version or uselatest.latest/architecture/+page.md lines 3 and 6 — frontmatter description says "How Beacon v1000.3.1 works internally" and the opening sentence says "Beacon v1000.3.1 is ~480 lines." The
latestroute should reflect v1000.3.2.All three are the same class of error: version strings baked into page content that fall out of sync on copy.
Proposed fix
The
DocLayout.sveltelayout already derivesversionPrefixfrom the URL path. The version is known at render time but never flows into page content.Options, from least to most invasive:
Fix the three stale strings directly. Fast, but the same problem recurs on every version bump.
Expose the version prefix as a layout prop or store that mdsvex pages can reference. Internal links become
{versionPrefix}/lensinstead of/v1000.3.1/lens. Frontmatter descriptions that mention a version would need to move into the template body where they can interpolate.Generate version-specific pages from a single source during the build. Each version directory would contain only the content that actually diverges (migration notes, changelog entries), not full copies of every page. This eliminates the copy-paste vector entirely but requires rethinking the routing structure.
Option 2 is likely the right balance. It keeps the current file-per-version layout intact while removing the manual step that produces these errors.