Repository navigation
ci: make docs redirects relative and block removed routes - #30805
Conversation
Katarinya
left a comment
There was a problem hiding this comment.
Review
Verdict: OK to merge once findings 1 and 2 are decided. The other findings are small follow-ups.
Findings
| # | Finding | Severity | Location |
|---|---|---|---|
| 1 | A 404 on an unpublished version blocks CI. A new release/X.Y branch with no published beta-docs version makes every PR into that branch fail with exit 2, and the author can't fix it. The test at main_test.go:690 requires this behavior. Treat a 404 as "not published, skip with a note"; the base-branch comparison would still run. |
Medium | inventory.go:137-158 |
| 2 | Every PR's lint now depends on coder.com being up. make lint runs for nearly every PR into main, including ones that don't touch docs, so a coder.com outage blocks them all. Confirm this is accepted, or fetch the live list only when docs change. |
Medium (policy) | main.go:236-260 |
| 3 | Git errors are silently treated as "no base redirects file". Any git show failure drops the base redirect sources without a note, so a PR that deletes an existing redirect could pass. Tell "file not found" apart from other errors, or at least print a note. |
Low to medium | main.go:310 |
| 4 | The hop limit only applies when a chain ends on a page. z→a→b→c→end (4 hops) fails, but z→a→b→c→/ passes (confirmed with a throwaway test). Impact is low because chains are rejected elsewhere. Apply the limit to every destination type and add a test case. |
Low | inventory.go:236 |
| 5 | The &^1 assertion accepts exit 0 or 1. It only checks that the code isn't 2, and prGit(manifestBase[:0]) obscures that the run actually exits 1. Use require.NotEqual(t, 2, code), or give it a base with nothing removed and assert 0. |
Low (test clarity) | main_test.go:1000 |
Security
No exploitable issues. Two optional hardening fixes:
https://github.com/coder/../other-orgpasses the external destination check. Parse the URL and reject..segments. (rules.go:225-242)- One message prints a route from the head manifest without quoting it. Use
%qlike the rest of the file. (rules.go:475)
Go practices (optional)
segmentis both a package-level regexp and a parameter name in three places. Rename the regexp tosegmentRe. (rules.go:134;inventory.go:95, 137;main.go:241)- The context isn't passed down, and the retry wait uses
time.Sleep, so cancelling can't stop it. (main.go:251,inventory.go:141)
Before merging
- Confirm coder/coder.com#1153 is deployed, not just merged.
- Decide how a 404 on an unpublished version should behave (finding 1).
- Confirm the team accepts the dependency on coder.com (finding 2).
Note
Generated by Coder Agents on behalf of @Katarinya.
Rewrite docs/redirects.json in the relative route format (routes below /docs, trailing /* wildcards, / for the docs root) with the rules that cover pages retired from main, some of them non-permanent. docsredirectscheck now enforces that format, rejects the old absolute /docs/... form with the converted rule, and fails when a route from the base manifest, the live page list for the target branch, or a base redirect source no longer resolves. -offline skips the live list. Generated with Coder Agents.
…check Skip the live page list when it answers 404, so a new release branch without published docs does not fail every pull request into it. Skip it too when docs/manifest.json and docs/redirects.json match the base branch, so a coder.com outage only blocks changes to those files. Tell a missing base redirects file apart from other git failures, apply the hop limit to every destination type, reject "\" and dot segments in external destinations, quote the hidden route, rename the segment regexp, and pass the context through so the retry wait can be cancelled.
2c200f7 to
f8ba5b9
Compare
|
@Katarinya, thanks for the review. Pre-merge checklist
Other findings
RebaseThe rebase conflicted in Note Generated by Coder Agents on behalf of @nickvigilante. |
Main rewrote the doc-check skill; keep main's version and carry the relative redirect format into its Repository facts entry. Assisted-by: AI
The live list URL is under /beta-docs. When the docs move to /docs and that URL redirects there, the list's links use /docs, the check would find no pages, and every docs PR would fail with exit status 2. Accept links under either base, preferring /beta-docs. Also drop a stale "advisory check" reference in a comment. Assisted-by: AI
Assisted-by: AI
|
@nickvigilante, the doc-check job on
|
…idebar (#31645) > [!NOTE] > Generated by Coder Agents. The branch and this description were written by an AI agent and need human review. ## Summary First of three stacked PRs for the docs IA overhaul (Proposal 1, section 3). This PR dissolves `docs/ai-coder/` into four top-level sidebar sections, in this order, where "Run AI coding agents in Coder" used to be: **Coder Agents**, **AI Governance** (with Agent Firewall and AI Gateway nested under it), **Agent Relay**, and **MCP server**. - Files move with `git mv`, so `git log --follow` keeps their history. The move includes every file in the moved folders, including pages that are not in the sidebar, such as `agent-firewall/example-policy.md`, and pages added to `main` after the first version of this PR, such as `agents/projects.md` (#30684) and `agents/acp-subagents.md` (#31430). - `docs/ai-coder/index.md`, `best-practices.md`, and `ide-agents.md` are deleted. Each has a redirect (see below). - `docs/manifest/` mirrors the new folders: `coder-agents.yml` (+ `coder-agents/`), `ai-governance.yml` (+ `ai-governance/`), `agent-relay.yml`, and `mcp-server.yml`. `ai-coder.yml` is deleted. The Projects and ACP subagents entries from `main` move with Coder Agents. - Every relative link and image path is fixed, both in the moved pages (their base directory changed) and in pages that link to them. This was done in one scripted pass from a clean `main` checkout. Every link was then checked to resolve on disk. - Commit 2, `chore: point in-product docs links at the new docs paths`, updates docs URLs outside `docs/`: `site/` `docs()` links, Go error strings and comments, `README.md`, `server.json`, templatebuilder modules, and the doc-check skill. Commit 4 reverts the unversioned `https://coder.com/docs/...` URLs among them (see below), so after this PR only these differ from `main` outside `docs/`: the `site/` `docs()` links, the versioned `cli/cliui` troubleshooting links, and repo file paths in comments and the doc-check skill's examples (`docs/coder-agents/...`, `docs/templates/...`). You can drop commit 2; the redirects cover the old URLs. - **#31646 (Templates) was squash-merged into this branch** as `98377a3a3b`. This PR now also carries the Templates move (`docs/admin/templates/**` → `docs/templates/**`, plus `template-from-scratch.md` and `testing-templates.md`) and its chore changes. Refer to #31646 for that part's move map, redirects, and review. - Commit 4, `fix: keep docs links healthy before the release`, keeps links working on the live site until a release that includes this stack becomes the default docs version: - Hand-written pages that linked to moved pages with absolute `https://coder.com/docs/...` URLs now use relative links, anchors kept. The new paths 404 on the live site today, but relative links resolve for every version and are checked locally. - Hardcoded, unversioned `https://coder.com/docs/<new path>` URLs outside `docs/` that the chore commits introduced (Go strings including the prebuilds metric help, CLI help, the `agentFallbackTroubleshootingURL` default, `README.md`, `server.json`, examples, templatebuilder files, and one `site/` constant) go back to their current paths. Then `make gen` regenerated the generated table in `docs/admin/integrations/prometheus.md`, `scripts/metricsdocgen/generated_metrics`, the CLI golden files, and `docs/reference/cli/templates/{create,edit}.md`. See "Post-release follow-up". - The `site/` `docs()` changes and the `cli/cliui` links stay, because those URLs are versioned (`/docs/@vX.Y.Z/...`) and resolve once the release ships. - Commit 5, `docs: prefix relative links in the moved pages with ./`, adds `./` to 13 relative links that the move script wrote without it, in `docs/mcp-server.md` and three Templates pages. They resolved, but every other relative link in the docs starts with `./` or `../`. - Commit 6, `docs: keep the coding agent module guidance in the templates docs`, adds an **AI agent modules** section to `docs/templates/extending-templates/modules.md`. Deleting `docs/ai-coder/index.md` removed the only instructions for adding a terminal coding agent to a template with a registry module. The example (`registry.coder.com/coder/claude-code/coder`, `version = "~> 5.2"`) passes `terraform validate`, and the Template Builder labels it cites match `site/src/pages/TemplateBuilder/ModuleSelectStep.tsx`. Stack: **this PR** (with #31646 squash-merged in) → `docs/ia-tutorials-nav` (#31647, Tutorials + nav renames) → `docs/ia-workspaces-folder` (#31650, folder rename). Refs: Linear DOCS-1154, DOCS-1179, and DOCS-1479 for the coder.com and router redirect fix. ## Move map | Old | New | | --- | --- | | `docs/ai-coder/agents/**` (25 files) | `docs/coder-agents/**` | | `docs/ai-coder/ai-governance.md` | `docs/ai-governance/index.md` | | `docs/ai-coder/agent-firewall/**` (9 files) | `docs/ai-governance/agent-firewall/**` | | `docs/ai-coder/ai-gateway/**` (26 files) | `docs/ai-governance/ai-gateway/**` | | `docs/ai-coder/agent-relay/**` (3 files) | `docs/agent-relay/**` | | `docs/ai-coder/mcp-server.md` | `docs/mcp-server.md` | | `docs/ai-coder/index.md` | deleted | | `docs/ai-coder/best-practices.md` | deleted | | `docs/ai-coder/ide-agents.md` | deleted | ## Redirects added Appended to `docs/redirects.json`, using the absolute `/docs/...` format that `main` validates today. Wildcards cover every page under each moved folder, including pages that are not in the sidebar and the pages added to `main` since the first version of this PR. | Source | Destination | | --- | --- | | `/docs/ai-coder` | `/docs/coder-agents` (deleted hub, **please confirm**) | | `/docs/ai-coder/best-practices` | `/docs/coder-agents` (deleted, **please confirm**) | | `/docs/ai-coder/ide-agents` | `/docs/user-guides/workspace-access` (deleted, **please confirm**) | | `/docs/ai-coder/ai-governance` | `/docs/ai-governance` | | `/docs/ai-coder/mcp-server` | `/docs/mcp-server` | | `/docs/ai-coder/agents/:path*` | `/docs/coder-agents/:path*` | | `/docs/ai-coder/agent-firewall/:path*` | `/docs/ai-governance/agent-firewall/:path*` | | `/docs/ai-coder/ai-gateway/:path*` | `/docs/ai-governance/ai-gateway/:path*` | | `/docs/ai-coder/agent-relay/:path*` | `/docs/agent-relay/:path*` | None of the 3 existing rules in `docs/redirects.json` points into `ai-coder/`, so no destinations needed updating. **coder.com and router static redirects.** coder.com applies its own `redirects.json` and the rules it generates from this file before it hands `/docs` to the docs-engine router, which applies its own static `redirects.json` before the page. Three older static rules in both repos send `/docs/templates`, `/docs/templates/open-in-coder`, and `/docs/templates/troubleshooting` to `/docs/admin/templates/...`, and the `/docs/admin/templates/:path*` rule here sends them back, so each loops once a release with this layout is the docs mainline. A static `/docs/workspaces` rule would also hide the new `docs/workspaces/index.md` page from #31650. coder/coder.com#1201 and coder/docs-engine#304 (draft, DOCS-1479) remove those rules; they must merge when that release becomes the mainline, not before, because the old-layout mainline still needs them. A chain simulation of every page and static source on each branch of this stack finds no other loops or hidden pages. The `/docs/ai-coder/...` and other legacy rules there still work; some now take two redirects. ## Deviations from the proposal - **Glossary "IDE agent" entry.** The proposal says to remove this link and leave plain text. I pointed it at Access your workspace (`docs/user-guides/workspace-access/index.md`) instead, the same page the `ide-agents` redirect uses, because "Refer to IDE agents." with no link reads as a dead end. The "Coding agent" entry now links to Coder Agents, as the proposal says. - **Top-level icons.** The new sections need icons. I chose `wand.svg` (Coder Agents, the old ai-coder icon), `ai_intelligence.svg` (AI Governance), `link.svg` (Agent Relay), and `plug.svg` (MCP server). - **Coding agent module guidance.** Kept on the Reuse template code page (commit 6) instead of deleted with `docs/ai-coder/index.md`. The best-practices and IDE-agent pages are deleted as proposed. - **Order relative to Administration.** In this PR the four sections sit where `ai-coder` was, after Administration. PR C moves Administration after MCP server to reach the final order. - **`docs/mcp-server.md` repo link.** A relative link to `codersdk/toolsdk/toolsdk.go`, outside `docs/`, was re-based for the new depth. - **Left unchanged on purpose:** - Database migrations and the notification `.golden` files rendered from them still contain `coder.com/docs/ai-coder/...` URLs. Existing migrations can't be edited, so those links rely on the redirects. - `aibridge/client/client.go` links to a commit-pinned GitHub permalink, which still resolves. - Test fixtures in `scripts/docsredirectscheck` and `.github/workflows/test-docs-preview-mapper.sh` use `ai-coder` as sample data. - `site/src/pages/AgentsPage/components/ChatElements/tools/Tool.stories.tsx` uses `https://coder.com/docs/ai-coder/ai-gateway` as a sample web search result. Changing it would only change a visual snapshot. ## Open questions for Nick 1. Do you agree with the three redirect targets for the deleted pages above? 2. Should the "IDE agent" glossary entry link to Access your workspace (current) or be plain text (proposal)? 3. Are the icons for the new top-level sections OK? 4. Open PRs that touch the moved files, checked with `git merge-tree` against this branch. I didn't change them. - #31169 merges cleanly: Git's rename detection carries its edit to `docs/ai-governance/ai-gateway/clients/claude-code.md`, and its new relative link still resolves at the new path. - #30262 now targets `tk/ai-gateway-responses-ws-endpoint` and conflicts with `main` in 21 files. Against this branch it conflicts in the same 21 files, with `codex.md` at its new path, so this PR doesn't add new conflicts. Its new relative links still resolve after the move. - #30805 conflicts in `docs/redirects.json`. It already conflicts with `main` there, because `main` added the `/docs/about/screenshots` and `/docs/install/cli` rules. ## Release No backport to `release/2.39` for now; Nick may apply it by hand later. A cherry-pick of this branch onto `release/2.39` conflicts in 25 files, and #31647 and #31650 would need the same treatment to keep the stack together. coder/coder.com#1201 and coder/docs-engine#304 merge when the first release line that carries this layout becomes the docs mainline (2.38 today). ## Known limitations - **CLI newer than its server.** The `cli/cliui` troubleshooting links append `/templates/troubleshooting#...` to the server's versioned docs URL. A CLI from this release against an older server prints `/docs/@v2.38.x/templates/troubleshooting#...`. The router's static `/docs/templates/:page(open-in-coder|troubleshooting)` rule redirects that to the old page today, but coder/docs-engine#304 removes that rule to fix the loop, so after the cutover that case gets the version's not-found page. ## Post-release follow-up After a release that includes this stack becomes the default docs version on coder.com, point these hardcoded URLs at the new paths. They work today and redirect after the release, so nothing breaks in the meantime. Anchors are unchanged. Rerun `make gen` afterward to update `docs/admin/integrations/prometheus.md`, `scripts/metricsdocgen/generated_metrics`, the CLI golden files, and `docs/reference/cli/templates/{create,edit}.md`. | Current (old) URL | Post-release URL | Files | | --- | --- | --- | | `https://coder.com/docs/ai-coder/agents` | `https://coder.com/docs/coder-agents` | `.claude/skills/doc-check/output.md`, `README.md` | | `https://coder.com/docs/ai-coder/agents/architecture` | `https://coder.com/docs/coder-agents/architecture` | `coderd/x/chatd/chattool/execute_test.go`, `codersdk/toolsdk/workspacetools/execute.go` | | `https://coder.com/docs/ai-coder/ai-gateway` | `https://coder.com/docs/ai-governance/ai-gateway` | `README.md`, `coderd/templatebuilder/modules/claude-code/module.json`, `coderd/templatebuilder/modules/codex/module.json` | | `https://coder.com/docs/ai-coder/mcp-server` | `https://coder.com/docs/mcp-server` | `server.json` | | `https://coder.com/docs/admin/templates` | `https://coder.com/docs/templates` | `README.md` | | `https://coder.com/docs/admin/templates/extending-templates/docker-in-workspaces` | `https://coder.com/docs/templates/extending-templates/docker-in-workspaces` | `examples/templates/docker-devcontainer/main.tf` | | `https://coder.com/docs/admin/templates/extending-templates/parameters` | `https://coder.com/docs/templates/extending-templates/parameters` | `examples/parameters-dynamic-options/README.md`, `examples/parameters/README.md`, `examples/parameters/main.tf`, `examples/templates/kubernetes-envbox/README.md`, `examples/workspace-tags/README.md` | | `https://coder.com/docs/admin/templates/extending-templates/prebuilt-workspaces` | `https://coder.com/docs/templates/extending-templates/prebuilt-workspaces` | `coderd/prebuilds/api.go`, `enterprise/coderd/prebuilds/metricscollector.go` (metric help text) | | `https://coder.com/docs/admin/templates/extending-templates/workspace-tags` | `https://coder.com/docs/templates/extending-templates/workspace-tags` | `examples/workspace-tags/README.md` | | `https://coder.com/docs/admin/templates/managing-templates` | `https://coder.com/docs/templates/managing-templates` | `cli/templatecreate.go`, `cli/templateedit.go` (CLI help) | | `https://coder.com/docs/admin/templates/managing-templates/image-management` | `https://coder.com/docs/templates/managing-templates/image-management` | `coderd/templatebuilder/bases/docker/README.md`, `coderd/templatebuilder/bases/kubernetes/README.md` | | `https://coder.com/docs/admin/templates/troubleshooting` | `https://coder.com/docs/templates/troubleshooting` | `agent/agentscripts/agentscripts.go`, `coderd/render/escape_internal_test.go`, `codersdk/deployment.go` (`agentFallbackTroubleshootingURL` default) | | `https://coder.com/docs/tutorials/template-from-scratch` | `https://coder.com/docs/templates/template-from-scratch` | `site/src/pages/TemplateBuilder/TemplateAlternatives.tsx` | ## Validation run - `make gen/docs-manifest`: clean diff afterward. - `make lint/docs-manifest`, `lint/docs-redirects` (`go run ./scripts/docsredirectscheck -base origin/main`: 15 rules OK, no removed-route warning), `lint/docs-html`, `lint/emdash`: pass. - `pnpm check-docs` (markdownlint + table formatter): pass. - Vale (`vale --no-exit docs/`): the same 12 warnings and 1 error as `main`, all pre-existing. Suggestions drop from 646 to 645; the one removed was in the deleted `ide-agents.md`. - Local relative-link check over `docs/**/*.md`: 0 unresolved links or images (also 0 on `main`). - Pre-commit hook: `make pre-commit-light` on the docs commit, and the full `make pre-commit` (gen, fmt, lint/go, lint/ts, build, and others) on the chore commit. Both passed. - Targeted tests: - Go: `go test ./coderd/x/chatd/chattool/... ./codersdk/toolsdk/... ./coderd/templatebuilder/...`. - Site: Vitest for the touched directories (107 files, 1879 tests), and the story tests for `CoderAgentsProductCard`, `GroupSettingsPageView`, `GatewayKeysPageView`, and `ModelForm` (4 files, 63 tests). - Every `docs()` path and anchor in the `site/` and Go diff resolves to a page and heading in this branch. - Frontend deep review (all 8 roles) on the `site/` diff of PRs A and B: no blocking or should-fix findings. Nits on existing code that this PR only touched, not changed here: a single-use `docsLink` constant in `ChatAccessDeniedAlert.tsx`, and assertion-only `play` functions in the `GatewayKeysPageView`, `ModelForm`, `CoderAgentsProductCard`, and `GroupSettingsPageView` stories. - Page counts: `docs/**/*.md` (excluding `.style`) 490 → 487; `manifest.json` routes 495 → 492. With #31646 squash-merged in, the counts don't change, because the Templates move only moves files. - **Link health (commit 4):** - linkspector 0.5.6 with `.github/.linkspector.yml` over all of `docs/`, like the weekly docs job (`umbrelladocs/action-linkspector`, `reporter: local`, `filter_mode: nofilter`). I ran it locally with Chrome in `--no-sandbox` mode. - `origin/main`: 0 errors. Before the fix (`17e54ad555`): 6 errors, all `https://coder.com/docs/<new path>` 404s (`shared-workspaces.md:19`, `esr-2.24-2.29-upgrade.md:80-82`, `tasks-to-chats-migration.md:73`, `prometheus.md:298`). After the fix (`def074caab`): 0 errors. A first run after the fix also flagged a Red Hat URL in `install/server/openshift.md`. That URL is unchanged from `main`, and it passed on a rerun, so the failure was transient. - After the fix: `make gen/docs-manifest` (clean), `lint/docs-manifest`, `lint/docs-redirects` (15 rules OK against `origin/main`), `lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the relative-link check (0 unresolved in 3416 links) pass. The full `make pre-commit`, including `make gen`, passed on the commit. - Tests after the fix: - Go: `go test ./cli -run 'TestCommandHelp|TestServerYAMLConfig'`, `./enterprise/cli -run TestEnterpriseCommandHelp`, `./coderd/render`, `./agent/agentscripts`, `./coderd/prebuilds`, `./enterprise/coderd/prebuilds`, `./coderd/x/chatd/chattool/...`, `./codersdk/toolsdk/...`, `./coderd/templatebuilder/...`. - Site: Vitest for `src/pages/TemplateBuilder` (7 files, 67 tests). - **After the rebase onto `ccf5ec74ae`** (commits 5 and 6 included): `make gen/docs-manifest` (clean), `lint/docs-manifest`, `lint/docs-redirects` (15 rules OK), `lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and a relative-link and anchor check over the changed pages pass. The only unresolved anchor, `docs/ai-governance/ai-gateway/cost-controls.md` → `enterprise.md#list-organization-ai-spend-by-user`, is also broken on `main`. The pre-commit hook (`make pre-commit-light`, because both new commits touch only `docs/`) passed on commits 5 and 6. The rebased code commits rely on CI for Go and TypeScript checks. - **Redirect chains:** a Node simulation of coder.com's static rules, its generated rules from this branch's `docs/redirects.json`, the router's static rules, the page, then this branch's rules on a miss, over every page and exact static source, reports the 3 loops above and nothing else new; with coder/coder.com#1201 and coder/docs-engine#304 applied, 0. - **Skipped:** the docs-engine sync check, which was not available in this environment. <details> <summary>Implementation notes</summary> - Rebuilt on `main` at `ccf5ec74ae` (2026-11-03) to clear conflicts with `main`, after an earlier rebase the same day onto `1a963c628d`. The previous rebuild was on `9839406ff7` (2026-11-02), and the first version on `9b8d880d63` (2026-10-23). - Rebase conflicts with #31603, which added `target="_blank" rel="noreferrer"` to docs links: 4 `site/` files in the chore commit and 5 in the Templates commit. Each kept `main`'s version of the link with only the docs path changed. Vitest for the 7 affected page directories (233 tests) and the story tests for the 8 changed or affected stories (102 tests) pass, and every `docs()` path in `site/src` resolves except the same 13 that are unresolved on `main`. - Rebase conflict: `docs/manifest/coder-agents.yml`. `main` added `docs/ai-coder/agents/bring-your-own-mcp-servers.md`; it moves to `docs/coder-agents/` with its sidebar entry, and its `../../user-guides/` links become `../user-guides/`. - Folded into the Templates commit: a link that `main` added to `docs/user-guides/workspace-dotfiles.md` (#31606) now points at `../templates/extending-templates/environment-variables.md`. - `git range-diff` against `def074caab`, the head before both rebases, shows only those changes. - The move script reads every page from the clean `main` checkout and resolves each relative link (inline, reference-style, and HTML `src`/`href`) against the page's **old** directory. It maps the target through the move map and recomputes the link from the page's **new** directory. It runs once and refuses to run on a dirty `docs/` tree, so it can't apply the path math twice. It also rewrites absolute `coder.com/docs/...` and `github.com/coder/coder/(blob|edit|tree)/main/docs/...` URLs, and skips fenced code blocks and inline code. - Before reusing the script, I ran it on the old base and diffed the result against the old commit. The only differences were the two hand-edited glossary entries and table padding from the formatter, so the rebuild applies the same changes to the current `main`. - Afterward, `grep -r ai-coder docs/` finds matches only in `docs/redirects.json`. - Changes from the earlier version of this branch: 2 more pages move (`agents/projects.md`, `agents/acp-subagents.md`) and their sidebar entries move with them. The chore commit also updates `SessionSummaryTable.tsx` (new on `main`) and the doc-check skill's `output.md` (its examples moved there from `SKILL.md`). The `AICostControl.tsx` anchor question is gone, because `main` fixed it. </details> --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
Resolve conflicts with the docs IA moves on main (templates, workspaces, coder-agents, ai-governance, and the redistributed tutorials). - Convert the redirects main added to the relative form. - Point existing rules at the pages' new locations. - Drop rules whose source is now a live page: templates, templates/open-in-coder, templates/troubleshooting, and workspaces. - Replace guides/* -> tutorials/* with exact rules for the old guides pages and a guides/* -> / fallback, and send tutorials/ai-agents/* to coder-agents, because tutorials and ai-coder no longer have pages. - Update the route examples in the checker README and the content guidelines to routes that exist.
|
Merged Resolution
Checks
Still to do after this merges: the Note Generated by Coder Agents on behalf of @nickvigilante. |
Summary
Moves
docs/redirects.jsonto relative routes and makeslint/docs-redirectsfail when a PR removes a live docs route without a redirect.coder.com and docs-engine build each version's redirects from that branch's file, so this file becomes the only place contributors add docs redirects.
Part of DOCS-1290; tracked in DOCS-1296.
Changes
{"source": "path/to/page", "destination": "path/to/another-page"}, relative to the docs root of the branch's version.Trailing
/*is the only wildcard,/is the version's docs root, one#fragmentis allowed on exact destinations, and external destinations are limited tohttps://github.com/coder/andhttps://coder.com/.The old
/docs/...form is rejected with the converted rule in the message.Every route in the base manifest, the live page list for the target branch (
coder.com/beta-docs/<version>/llms.txt), and the base file's sources must be a page or resolve through a rule.The failure names the old file and prints a paste-ready rule, suggesting a renamed sibling, a page with the same last segment, or
/.An unreadable live list exits 2 in CI;
-offlineskips it locally.Links under
/docscount as well, so the check keeps working if the list URL redirects there after the move to/docs.docs/redirects.jsononmain: 304 rules.It carries the coder.com docs rules that 404 under
/docs/@maintoday, plus the 144@main-only rules coder.com holds, with three sibling sets condensed into wildcards (networking/*,admin/notifications/*,guides/*).Testing
go test ./scripts/docsredirectscheck/...(also-race),golangci-lint, and the pre-commit hook.go run ./scripts/docsredirectscheck -base origin/main -branch mainonline, after merging currentmain: 304 rules OK, 497 routes resolve.admin/integrations/istio.mdwithout a rule fails with{"source": "admin/integrations/istio", "destination": "admin/integrations/istio-mesh"}; adding that rule passes.generateRedirectswith this file andmain's manifest: 0 dropped; 336 of 336 sampled old URLs resolve to the expected page with Next's matcher.curlon every destination undercoder.com/docs/@main: all 200./docs/@mainURLs return 404.ci.yaml'slintjob; the package's unit tests also run on macOS and Windows intest-go-pg.Merge order
Merge after the coder.com generator (coder/coder.com,
vigilante/docs-redirects-relative) is deployed, otherwise coder.com drops these rules with warnings until it is.The docs-engine change (coder/docs-engine,
vigilante/version-redirects) can land before or after.Then merge the
release/2.38backport.Contract shared by coder/coder, coder.com, and docs-engine
Docs redirects contract (coder/coder owns the data; coder.com and docs-engine consume it)
Ownership
coder/coderdocs/redirects.json, one file per branch (main,release/X.Y).main's file applies to@main;release/X.Y's file applies to vX.Y, and to unversioned/docswhile X.Y is mainline./docs/v1,/docs/v2/...,/docs/coder-oss/...,/docs/coder/...,/docs/code-server/..., classic/@v<line>forms) are not content moves. They stay in the consumer that owns the URL scheme, as code or a static engine-owned file.File format
docs/redirects.jsonis a JSON array. Each entry is an object with exactly these fields:sourcedestination/for the docs root, or an allowedhttps://URLpermanenttrue.trueanswers 308,falseanswers 307Unknown fields are an error.
Routes
/docswith no version, no leading slash, no trailing slash, and no.md:admin/templates/extending-templates./. Each segment matches[A-Za-z0-9._-]+. Nothing else is allowed (no@,%,:,(,?,#, spaces, empty segments,.or..segments).docs/manifest.jsonthe way the sites do today: strip a leading./, then stripREADME.md,index.md,.mdin that order as plain text, trim slashes. The empty result is the docs root.Wildcards
sourcemay end in/*:ai-coder/ai-bridge/*. It matches the prefix itself and every route beneath it.destinationmay end in/*only when the source does. The part the source's*matched (possibly empty) replaces the destination's*; an empty match means the destination prefix itself (ai-coder/ai-gateway/*with an empty match isai-coder/ai-gateway).*into their own matcher. For Next.js that is:path([A-Za-z0-9._-]+)*, never(.*),.+, or a bare:name*.Destinations
/is the docs root of the same version (/docs,/docs/@main,/beta-docs/v2.37, and so on). Pages with no suitable home redirect to/.#fragment, where the fragment matches[A-Za-z0-9._-]+:user-guides/workspace-access#web-ides. The route part must still be a live route. A wildcard destination and/never carry a fragment.https://URL whose host and path start with an allowed prefix:https://github.com/coder/orhttps://coder.com/. It contains no:after the scheme and no parameter. A*is not allowed in an external destination.Order and precedence
Legacy entries
sourceordestinationthat starts with/docs/(or equals/docs) and treat it as the route after/docs/(or/for/docs). A legacy:name*or:name(.*)trailing parameter is treated as/*. The coder/coder checker accepts only the new form.CI check (coder/coder
scripts/docsredirectscheck)Structural checks as today, adapted to the new form, plus a blocking removed-route check:
docs/manifest.jsonroutes,https://coder.com/beta-docs/<segment>/llms.txtwhere the segment is@mainformainandvX.Yforrelease/X.Y, keeping only links under that segment,sourcein the base branch'sdocs/redirects.json(exact sources as-is; wildcard sources contribute the prefix)./, or an allowed external URL.{"source": "path/to/page", "destination": "path/to/another-page"}, pointing at/when no candidate is obvious.-offlineskips the live list and says so.esr-2.24-2.29-upgradeis served asesr-2-24-2-29-upgrade). Until docs-engine fixes it, a live route that equals a head route with.replaced by-in each segment counts as present.Consumers
scripts/generate-docs-redirects.ts): readsmain(scoped to/docs/@main/...) and the mainline release branch (unversioned/docs/...) as today, in the new format, and emits Next.js redirects. Version coverage beyond those two is out of scope.docs/redirects.jsonfrom the commit it builds, validates it, and stores the compiled rules with that version's archive. The router applies a version's own rules on a miss inside that version. Versions published before this change keep today's behavior.🤖 Built with AI assistance.