From ed908ed019ffa50c873e0b367cf8a82345f2b33c Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 22 Jun 2026 17:04:19 -0400 Subject: [PATCH] fix(docs): repoint 7 broken external and anchor links (DOCS-415) (#26572) Closes [DOCS-415](https://linear.app/codercom/issue/DOCS-415). ## TL;DR Repoints 7 broken links across 5 docs files that the 2026-06-22 weekly `check-docs.yml` Linkspector run flagged. Two other links from the same run (the dead `nix` ref and the dead `reflectoring.io` ref in `CONTRIBUTING.md`) were already folded into [#26341](https://github.com/coder/coder/pull/26341). ## Why Broken external and anchor links degrade reader trust, leak SEO juice, and make the docs look stale. The weekly `check-docs` job exists precisely to catch this kind of rot before customers do; the surfacing-to-fix turnaround on these 7 is one PR. Run that surfaced them: [actions/runs/27948011619 job 82697664858](https://github.com/coder/coder/actions/runs/27948011619/job/82697664858). ## Scope | File | Line(s) | Old target | New target | Why | |------|---------|-----------|------------|-----| | `docs/tutorials/best-practices/organizations.md` | 62 | anchor `#update-template-metadata-by-id` | `#update-template-settings-by-id` | API endpoint renamed in [#19228](https://github.com/coder/coder/pull/19228) (Aug 2025). New heading at line 1105 of `docs/reference/api/templates.md`. | | `docs/install/registry-mirror-artifactory.md` | 197 | JFrog `terraform-registry` | `terraform-opentofu-and-terraform-backend-repositories` | JFrog consolidated their Terraform / OpenTofu / Backend docs into a single page. | | `docs/admin/templates/extending-templates/modules.md` | 76, 206 | JFrog `set-up-a-terraform-module/provider-registry` and `terraform-registry` | same consolidated JFrog page (root, no anchor) | Same JFrog consolidation. Anchor dropped, see decision log. | | `docs/admin/integrations/dx-data-cloud.md` | 84 | `https://help.getdx.com/en/` | `https://docs.getdx.com/` | DX migrated their help center to a separate docs domain. | | `docs/about/contributing/frontend.md` | 37, 71 | `https://reactrouter.com/en/main` | `https://reactrouter.com/` | React Router dropped the `/en/main` prefix. | ## Validation - All 7 replacement URLs return HTTP 200 (manual `curl -L -o /dev/null -w '%{http_code}'` per URL; linkspector's puppeteer crashed in the agent env, so it was run case-by-case) - `make lint/markdown lint/emdash` clean locally - Pre-commit hook (`scripts/githooks/pre-commit` -> `make pre-commit-light`) clean - No `/docs/` route changes; pure markdown content ## Not triggering `/coder-agents-review` Docs-only markdown edit, no CI or build config changes; per `AGENTS.md` the bot review is reserved for product / CI changes. `doc-check` handles this category. ## Pre-mortem | Concern | Mitigation | |---|---| | Replacement URL also turns out to be broken later | All 7 verified HTTP 200 today; next weekly `check-docs` run will catch any future regression. | | JFrog anchor drop on `modules.md` (76, 206) loses navigation context | Verified the consolidated JFrog page has no clean section anchor for the original target; linking the root page is the honest fix. If JFrog ships a better TOC anchor later, a follow-up can reattach. | | Anchor rename in `organizations.md` was actually a different rename | Confirmed via PR #19228 (Aug 2025) which is the exact rename that produced `## Update template settings by ID`. |
Decision log **Why drop the anchor on the JFrog `modules.md` links (76 + 206)**: JFrog's new consolidated page (`/terraform-opentofu-and-terraform-backend-repositories`) doesn't expose the original `set-up-a-terraform-module/provider-registry` section as a fragment-link target. The honest fix is to link the page root; readers can scroll. The `registry-mirror-artifactory.md:197` reference uses the same root link for symmetry. **Why DX `docs.getdx.com` over `help.getdx.com`**: DX's help center at `help.getdx.com/en/` now returns 404. They moved to a separate `docs.getdx.com` domain with a different content structure. Linking the docs root is the closest analog to the original "browse our docs" intent. **Why React Router root over `/en/main`**: React Router unified their docs under the root URL. The `/en/main` prefix is no longer routable. The root URL is the canonical successor.
CI: audit-docs-paths failure (pre-existing, unrelated) The `audit-docs-paths` job in `.github/workflows/weekly-docs.yaml` fails on this PR because its `Fetch redirects.json` step issues an unauthenticated `curl` to a file in private `coder/coder.com` and gets a 404 (exit code 22). Same failure on every recent PR in this repo. Tracked in [DOCS-409](https://linear.app/codercom/issue/DOCS-409) and fixed in [#26571](https://github.com/coder/coder/pull/26571), which authenticates the fetch through the Contents API. My changes are docs-content only (5 markdown files, 7 line changes) and don't touch the TS/TSX paths or `redirects.json` that the audit examines, so this is a pre-existing CI break, not a regression introduced here.
--- *Generated by Coder Agents on @nickvigilante's behalf.* --- docs/about/contributing/frontend.md | 4 ++-- docs/admin/integrations/dx-data-cloud.md | 2 +- docs/admin/templates/extending-templates/modules.md | 4 ++-- docs/install/registry-mirror-artifactory.md | 2 +- docs/tutorials/best-practices/organizations.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/about/contributing/frontend.md b/docs/about/contributing/frontend.md index 9e5e85ef7c..791f3172d2 100644 --- a/docs/about/contributing/frontend.md +++ b/docs/about/contributing/frontend.md @@ -34,7 +34,7 @@ the most important. - [React](https://reactjs.org/) for the UI framework - [Typescript](https://www.typescriptlang.org/) to keep our sanity - [Vite](https://vitejs.dev/) to build the project -- [react-router](https://reactrouter.com/en/main) for routing +- [react-router](https://reactrouter.com/) for routing - [TanStack Query](https://tanstack.com/query/v4/docs/react/overview) for fetching data - [Vitest](https://vitest.dev/) for integration testing @@ -68,7 +68,7 @@ the value. ## Routing -We use [react-router](https://reactrouter.com/en/main) as our routing engine. +We use [react-router](https://reactrouter.com/) as our routing engine. - Authenticated routes - Place routes requiring authentication inside the `` route. The `RequireAuth` component handles all the diff --git a/docs/admin/integrations/dx-data-cloud.md b/docs/admin/integrations/dx-data-cloud.md index 3556370535..c74bafe548 100644 --- a/docs/admin/integrations/dx-data-cloud.md +++ b/docs/admin/integrations/dx-data-cloud.md @@ -81,7 +81,7 @@ After the attribute is uploaded, you'll have a Coder filter option within your D ## Related Resources -- [DX Data Cloud Documentation](https://help.getdx.com/en/) +- [DX Data Cloud Documentation](https://docs.getdx.com/) - [Coder CLI](../../reference/cli/users.md) - [Coder API](../../reference/api/users.md) - [PlatformX Integration](./platformx.md) diff --git a/docs/admin/templates/extending-templates/modules.md b/docs/admin/templates/extending-templates/modules.md index 0f79d1535e..cc2bdca55a 100644 --- a/docs/admin/templates/extending-templates/modules.md +++ b/docs/admin/templates/extending-templates/modules.md @@ -73,7 +73,7 @@ for complete setup instructions. Air-gapped users can clone the [coder/registry](https://github.com/coder/registry/) repo and publish a -[local terraform module repository](https://jfrog.com/help/r/jfrog-artifactory-documentation/set-up-a-terraform-module/provider-registry) +[local terraform module repository](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-opentofu-and-terraform-backend-repositories) to resolve modules via [Artifactory](https://jfrog.com/artifactory/). 1. Create a local-terraform-repository with name `coder-modules-local` @@ -203,6 +203,6 @@ coder: ### Next steps - JFrog's - [Terraform Registry support](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry) + [Terraform Registry support](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-opentofu-and-terraform-backend-repositories) - [Configuring the JFrog toolchain inside a workspace](../../integrations/jfrog-artifactory.md) - [Coder Module Registry](https://registry.coder.com/modules) diff --git a/docs/install/registry-mirror-artifactory.md b/docs/install/registry-mirror-artifactory.md index f0c4b492c8..21e7a07078 100644 --- a/docs/install/registry-mirror-artifactory.md +++ b/docs/install/registry-mirror-artifactory.md @@ -194,5 +194,5 @@ Ensure the remote repository URL is set to `https://registry.coder.com` and not ## Next Steps - [Coder Module Registry](https://registry.coder.com/modules) -- [JFrog Terraform Registry Documentation](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry) +- [JFrog Terraform Registry Documentation](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-opentofu-and-terraform-backend-repositories) - [Air-gapped Deployments](./airgap.md) diff --git a/docs/tutorials/best-practices/organizations.md b/docs/tutorials/best-practices/organizations.md index 512cb92a97..bee1b5e702 100644 --- a/docs/tutorials/best-practices/organizations.md +++ b/docs/tutorials/best-practices/organizations.md @@ -59,7 +59,7 @@ use organizations for several use cases. Since templates and workspaces cannot be moved nor can they belong to multiple organizations, we recommend that you deprecate your template -[through the API](../../reference/api/templates.md#update-template-metadata-by-id) +[through the API](../../reference/api/templates.md#update-template-settings-by-id) or [through the Coder CLI](../../reference/cli/templates_edit.md#--deprecated). When a template is deprecated, the admin prevents new workspaces from being created and developers are notified with a deprecation message which can link to