[moritzhartmeier]

The bug

docusaurus docs:version snapshots docs/ verbatim, so a newly frozen
version inherits the current version's convention of linking the unversioned
API reference. It is not the current version any more, and nothing in the bump
corrected it.

That breaks during a beta window:

• the frozen version (say 8.6.0) becomes lastVersion, served at the site root
• the beta (8.7.0-beta.1) becomes current, served at /next/
• both link docs.scandit.com/data-capture-sdk/

Whichever publish sets PUBLISH_DOCS_FOR_LATEST last owns that tree — so
readers of the released version silently get the beta's API reference.

It has happened. docusaurus.config.ts records the audit:

 *   version-8.5.3     210 files link docs.scandit.com/data-capture-sdk, 0 versioned
 *   version-7.6.14      0 unversioned, links docs.scandit.com/7.6/data-capture-sdk
 *   version-6.28.11     0 unversioned, links docs.scandit.com/6.28/data-capture-sdk

8.5.3 shipped frozen-but-unrewritten. 7.6.14 and 6.28.11 link their own
lines only because someone fixed them by hand — most recently #443, which
repointed 7.6's c_api links last week.

The fix

minor_beta now rewrites the snapshot's links to its own <major.minor> line,
for both data-capture-sdk/ and stable/c_api/. docs/ is deliberately
untouched — the current version should keep linking the unversioned tree.

No check that the target resolves — deliberately

An earlier revision verified that <major.minor>/data-capture-sdk/ resolved
before rewriting. That was wrong in principle: the bump runs well before the
release, so the snapshot and the release notes can be reviewed while there is
still time to change them. The API reference for that line is published by the
release pipeline, which has not run yet — so the check would have refused every
bump.

The links are correct by construction and unresolvable by definition at the
moment they are written. Verifying them belongs after the release publishes,
where the existing post-release checks live — not here. The rewrite touches no
network.

Verified

Simulated a real freeze of the current docs/:

Rewritten	2,267 links across 214 files
Left in the snapshot's Markdown pointing at the unversioned tree	0
docs/ changed	0 files — still 210 unversioned, as intended

Also runs clean under LC_ALL=C, and a snapshot with no API links raises rather
than passing silently.

And a version whose line does not exist yet (9.9.0) is rewritten rather than
refused, which is the case the bump actually runs in.

Context

Part of the docs-deploy cleanup (data-capture-sdk!38971, !39020, !39061).
This is also a prerequisite for automating the API-reference prune on the SDK
side: once a frozen version links <major.minor>/, that line becomes
load-bearing, and any pruning rule has to know not to delete it.

What this does NOT cover

Two things surfaced in review that this PR deliberately leaves alone. Both are
real; neither is fixable by a substitution over versioned_docs/.

src/data/features.json holds 143 unversioned apiUrl values. It is shared
rather than snapshotted — docs:version copies docs/ only — so
src/components/FeatureList renders the current data into whatever page shows it.

Correcting an earlier version of this section: no frozen version renders
that component today. <FeatureList/> is used on 10 pages, all in docs/;
7.6.14 has the 6 label-definitions.md pages and none uses it, and 6.28.11
does not have them. The risk starts at the next freeze, when the snapshot
picks up those 10 pages while still importing the shared data file. Fixing it
means resolving the version at render time rather than rewriting a file, which
is #447. The table above is scoped to the snapshot's Markdown accordingly.

The search tag moves in lockstep with the Algolia crawler.
linksToOwnApiLine() derives apiReferenceTagsByVersionTag by reading what each
version links, so after this rewrite the frozen version derives
api-reference-8.6. Until the crawler has an action producing records under that
tag, yarn verify:search-tags reports THIN — a warning on PRs, a failure on
main with --strict (THIN_PAGE_THRESHOLD = 100). docusaurus.config.ts
already predicts this for the 8.5 case.

Prerequisite of the next minor_beta, not of this PR. This is inert until
that freeze, so it merges ahead of the crawler action. But before the next freeze
runs, both of these have to be in place, or verify:search-tags --strict goes
THIN on main:

• an Algolia crawler action producing records under the new
  api-reference-<line> tag
• Resolve feature API-reference links against the reader's docs version #447, so the feature tables resolve against the frozen version too

Worth putting on the release checklist rather than leaving it to whoever
remembers this thread.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-07 09:00 UTC

[moritzhartmeier]

Thank you — all four reproduce, and the first two are fixed in 912677aba.

Encoding. Confirmed exactly: 57 of the 676 files under docs/ fail to decode
as cp1252, including the three you named. And your point about where it sits is
the part that made it blocking rather than cosmetic — docs:version has already
written versioned_docs/, versioned_sidebars/ and versions.json, files
earlier in sorted() order are already rewritten, and main()'s catch-all
reports it as "Unexpected error". Re-running then fails at docs:version
because the version exists. Both calls are explicit UTF-8 now, and I verified the
rewrite under LC_ALL=C (preferred encoding US-ASCII) as well as normally.

Zero-match. Agreed, and the direction was wrong. Every version so far carries
hundreds of these links, so zero means the convention moved and the patterns no
longer match — in which case the snapshot silently keeps linking the unversioned
tree, which is the 8.5.3 bug this exists to prevent. It now raises and names the
patterns that found nothing.

features.json. You are right, and I overstated the result. src/data/features.json
is shared rather than snapshotted, src/components/FeatureList renders it, and
versioned_docs/version-7.6.14/barcode-scanning.md is among the frozen pages
that use it — so those 143 apiUrl values keep pointing at the unversioned tree
whatever this PR does. A substitution over versioned_docs/ cannot reach them;
it needs the version resolved at render time. I have narrowed the claim in the
description to "the snapshot's Markdown" and added a section saying so. Happy to
open that separately — it is the same class of bug in a different place.

Search tag. Also right, and this is the one I would most like your steer on.
The rewrite makes linksToOwnApiLine() derive api-reference-8.6 for the frozen
version, and until the crawler has an action for that path verify:search-tags
goes THIN — warning on PRs, failing on main under --strict.
docusaurus.config.ts already predicts this for the 8.5 case, so the behaviour is
expected rather than surprising, but it means the crawler change has to land
with the first freeze that uses this, not with this PR. I have written that into
the description. If you would rather this not merge until the crawler action
exists, that seems reasonable to me — it is inert until the next minor_beta
either way.

And thank you for confirming the core substitution — non-overlapping, idempotent,
already-versioned links skipped. That was the part I had tested least
adversarially.

[moritzhartmeier]

Correcting one thing I said above about features.json, because I overstated it.

I wrote that versioned_docs/version-7.6.14/barcode-scanning.md is among the
frozen pages rendering FeatureList. It is not. My grep was
FeatureList|features, and the loose features matched the word inside
features-by-framework links. Checking the component properly:

docs/                          10 pages use <FeatureList/>
versioned_docs/version-7.6.14   0
versioned_docs/version-6.28.11  0

FeatureList landed in 909d295cb (2025-12-02) and 7.6.14 froze in 7777abbe0
(2026-05-08), but those label-definitions pages did not carry the component
then — 7.6.14 has 6 of them and none uses it.

So nothing is broken today: the 143 unversioned apiUrl values are rendered
only by current-version pages, where linking the unversioned API reference is the
correct convention.

Your conclusion still holds, though, and the timing is the uncomfortable part.
docs:version copies docs/ verbatim, so the next minor_beta snapshots all 10
pages with <FeatureList/> intact, and the component imports the shared
src/data/features.json rather than a snapshot of it. The frozen version then
renders today's unversioned URLs, and once the next minor publishes they resolve
to its API reference. That is the same bug this PR fixes for Markdown, in a place
a substitution over versioned_docs/ structurally cannot reach — and it lands at
the very freeze this PR exists to make safe.

I also checked withCurrentDocsPath(), which looked like it might already cover
this. It does not:

const match = path.match(/^\/sdks\/([^/]+)/);
if (!match || !isUnreleasedFramework(match[1])) return path;

Only relative /sdks/<framework> paths for unreleased frameworks are prefixed;
an absolute https://docs.scandit.com/data-capture-sdk/... is returned untouched.

Opening it as a separate PR, taking the tidier option: version-agnostic paths in
features.json with the component building the URL from the active version —
the shape products.json already uses, so the two data files end up consistent.

One consequence to flag: that fix makes a frozen version's feature links point at
<major.minor>/ too, so it runs into the same Algolia api-reference-<line> tag
question as this PR. The two want to land alongside the crawler action rather
than independently.

[eugenia-scandit]

Non-blocking: check for matching links before docs:version runs, so the zero-match guard can't leave the repo half-frozen.