lxbme opened a new pull request, #2095:
URL: https://github.com/apache/apisix-website/pull/2095
Changes:
The docs version picker linked every entry to a **version root directory**
(`/docs/apisix/3.16/`). Those directories contain no `index.html`, and
`.htaccess` sets `Options -Indexes`, so ASF httpd answers **HTTP 403**, which
`ErrorDocument 403 /404.html` then renders as the 404 page. The status code is
403 rather than 404, which reads to crawlers as access-denied rather than gone.
Measured against the published `asf-site` tree:
| Picker link | Result today |
|---|---|
| `/docs/apisix/` | 200 — rescued by the `301` at `.htaccess:158` |
| `/docs/apisix/3.10/` … `/docs/apisix/3.16/` | **403** (7 links) |
| `/docs/apisix/next/` | **403** |
|
`/docs/{ingress-controller,helm-chart,docker,java-,go-,python-plugin-runner}/next/`
| **403** (6 links) |
That is 8 dead links on each of the 249 English version-less docs pages,
plus the Chinese mirror.
This is the same class of bug `.htaccess:156-160` already fixes for
`/docs/apisix/` and `/docs/ingress-controller/`, under the comment *"Bare
landing directories have no index page and return 403"*. The versioned
directories were simply missed.
### The fix
Each entry now links **that version's landing doc**, derived from the first
leaf of the project's sidebar — no new data, and it tracks upstream sidebar
changes automatically. URL construction moves out of `DocPage.astro` into two
pure functions in `content.ts`; the layout receives a prepared `versions[]`
array and only renders it. Splitting that knowledge across the layout and its
callers is what allowed the bug.
The full landing path is required, not just the version segment:
`.htaccess:160` redirects `/docs/apisix/3.<n>/getting-started/` to the
**latest** version, so emitting the shorter form would silently defeat the
version switch. `versionedLandingHref`'s doc comment records this so a future
simplification is pre-refuted.
`helm-chart` now renders no "Next (unreleased)" entry at all. Docusaurus
does not version-publish it — there is no `/docs/helm-chart/next/` tree and
never has been — so that entry was a 403 by construction. With one version
left, the picker collapses to a plain label instead of a one-item dropdown.
Two small corrections on lines already being touched: the current-version
entry links its landing doc directly (one less redirect hop, one less
dependency on `.htaccess`), and its `aria-current` becomes `"true"` instead of
`"page"` — it marks the current *version*, so on any page other than the
landing doc `"page"` told screen readers something false.
### Failure handling
`next/src/**` degrades rather than throwing, matching this project's split
between a degrading render path and hard-failing validators: an unresolvable
entry is dropped, an empty sidebar renders no picker. The new `deploy.yml` step
is where failure is loud — after the overlay, it walks every built docs page,
collects each `.version-picker` href, and fails the deploy if any has no file
behind it. That is the only layer that can catch `APISIX_ARCHIVED_VERSIONS` (a
hardcoded list) drifting from what is actually published, because the Astro
build never sees archived-version content.
**This gate is deliberately deploy-blocking.** If a listed archived version
is ever unpublished, the site deploy fails until the list is corrected. That is
the point, but it is worth knowing before merging.
### Testing
`next/tests/e2e/docs-version-picker.spec.mjs` collects every picker href and
asserts each opens a real docs page.
It asserts on page **content**, never on HTTP status, because the e2e static
server (`python3 -m http.server`) answers an index-less directory with `200`
plus a directory listing where production returns `403` — a status assertion
would have passed on the exact build the test exists to reject. It accepts both
`.docs-content h1` and `.theme-doc-markdown h1`, because version-less pages are
Astro-built and archived versions are still Docusaurus-built. A bare `h1` would
not work either: the 404 page a 403 renders has exactly one `h1`, with the text
`404`.
Verified against production before the fix: 5 failures, each on the intended
assertion, naming `/docs/apisix/3.16/`, `/zh/docs/apisix/3.16/`,
`/docs/ingress-controller/next/`, `/docs/docker/next/`, and the helm-chart
`next` link.
### Known limitations, disclosed
- **Switching versions now lands on that version's landing doc, not the
equivalent page.** Deliberate: it carries zero 403 risk and is fully verifiable
at build time. The cost is losing the reader's position.
- **Direct access to a version root (`/docs/apisix/3.16/`) still returns
403.** This PR fixes the links that produce those URLs; bookmarks and
already-indexed URLs need an `.htaccess` redirect, which is intentionally out
of scope here.
- **Sub-project archived versions remain unreachable from the picker**
(ingress-controller 2.1.0, java 0.6.0, go 0.5.0, python 0.2.0). Pre-existing
and unchanged — a missing feature, not a broken link.
- **The e2e spec skips in PR CI** (`EXPECT_DOCUSARUS_ROUTES` is unset) and
runs fully only in the deploy pipeline against the overlaid tree. It is red
against production until the first post-merge deploy. I have not claimed a
green run here, because the archived pages it needs exist only in that
assembled tree.
Screenshots of the change:
No visual change to the docs layout. The one user-visible difference is on
`/docs/helm-chart/*`, where the version picker becomes a plain label instead of
a dropdown whose only entry was broken.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
