fix(docs): serve released docs at canonical root - #553
Conversation
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6b055c2db5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| run: node scripts/generate-standard-journeys.mjs --check | ||
|
|
||
| - name: Build Main-source preview | ||
| - name: Build unreleased Main documentation |
There was a problem hiding this comment.
Commit bdd43f39706fd4d548f51367767a7f02b987f085 has no Signed-off-by trailer, so it does not satisfy the repository's mandatory DCO policy; recreate this commit with the required sign-off before merging.
AGENTS.md reference: AGENTS.md:L68-L70
Useful? React with 👍 / 👎.
| if stack.get("status") == "released": | ||
| released_manifest_tags.append(docset_id) |
There was a problem hiding this comment.
Adding this validation under release/ while the same change modifies the docs/site/ deployment and data spans two explicitly separate owning areas. Move the release-tool changes into their own owning-area change, or implement the selector validation within the docs area, so the change remains reviewable under the repository's required ownership boundary.
AGENTS.md reference: AGENTS.md:L76-L78
Useful? React with 👍 / 👎.
| const legacyRedirects = rootRouteEntries.map((entry) => { | ||
| const relativeIndex = entry.route === '/' | ||
| ? 'index.html' | ||
| : `${entry.route.slice(1)}index.html`; |
There was a problem hiding this comment.
When a client follows an existing machine-readable URL such as /preview/llms.txt or /preview/<slug>.md, it now receives a 404: the workflow no longer builds dist/preview, while this compatibility list is derived only from index.html routes and emits only corresponding index.html redirects. These endpoints were served by the previous /preview/ build and matching release files are promoted at the root, so generate compatibility redirects or copies for the non-HTML public routes as well.
Useful? React with 👍 / 👎.
| for (const promoted of promotedFiles) { | ||
| await mkdir(dirname(promoted.destination), { recursive: true }); | ||
| if (textExtensions.has(extname(promoted.relative))) { | ||
| const contents = await readFile(promoted.source, 'utf8'); | ||
| await writeFile( |
There was a problem hiding this comment.
Because the selected release is built as an archive, astro.config.mjs sets pagefind: !isArchivedBuild to false and the locked tree contains no Pagefind index. Promoting that tree directly here therefore leaves the new canonical / documentation without site search, while only the unreleased /dev/ build remains searchable. Generate a deployment-time search index for the promoted copy, or build a separate canonical release copy, without changing the immutable /v/<version>/ archive.
Useful? React with 👍 / 👎.
| return `User-agent: * | ||
| Allow: / | ||
|
|
||
| Sitemap: https://docs.registrystack.org/sitemap-index.xml |
There was a problem hiding this comment.
The /dev/ build publishes per-page .md files and llms*.txt, but those plain-text responses cannot carry the HTML noindex meta added by apply-archive-seo.mjs. Since this root policy explicitly allows every path, crawlers following the development HTML's alternate Markdown links can index unreleased source content even though /dev/ is intended to be search-excluded. Disallow /dev/ here, stop publishing those artifacts in that mount, or arrange an X-Robots-Tag: noindex response policy.
Useful? React with 👍 / 👎.
2 participants
Summary
//dev/withnoindex/v/<version>/archives and mark every archivenoindex/preview/as compatibility redirects to the canonical release routesRoot cause
The v0.15.2 release manifest and documentation archive were published, but
docsets.yamlstill selected v0.13.0. The deployment also treated the root as a redirect surface and made the Main preview the indexable documentation source. This left the public root redirecting to v0.13.0 and did not provide a canonical latest-release copy at/.Production model
/: canonical, indexable copy derived from the selected locked release archive/dev/: unreleased Main documentation,noindex/v/<version>/: immutable release archives,noindex/preview/: legacynoindexredirects to matching canonical root routesThe selected archive tree digest is checked before and after promotion.
/v/0.15.2/remains byte-for-byte locked, and only a deployment-time copy is rewritten for the canonical root namespace.Validation
npm test: 248 passed, 1 intentional skipnpm run check: passed end to endpython3 -m unittest release/scripts/test_registry_release.py: 99 passedrelease/scripts/registry-release validate-docsets: passed for 14 versioned docsets/dev/pages, 4,296 archive pages, 254 legacy redirects/dev/: 199 passedExisting non-failing documentation warnings remain unchanged: 2 Vale warnings, 14 Redocly warnings, and the existing Astro/Rhai build notices.