refactor(docs): convert absolute coder/coder blob/tree/main links to relative (DOCS-351) (#26341)

Closes [DOCS-351](https://linear.app/codercom/issue/DOCS-351). > [!WARNING] > **DO NOT MERGE** until [DOCS-349](https://linear.app/codercom/issue/DOCS-349) ([coder.com#877](https://github.com/coder/coder.com/pull/877)) has shipped to production and baked for at least one Vercel cycle. > > Without DOCS-349, the relative links in this PR resolve to broken docs-route URLs (`/docs/helm/coder/values.yaml` -> 404) instead of GitHub URLs tagged with the displayed docs version. DOCS-349 fixes the rewriter to classify these as GitHub blob/tree URLs with the page's resolved ref. ## TL;DR Converts 121 absolute `https://github.com/coder/coder/(blob|tree)/main/<path>` links across 39 docs markdown files to relative paths. After this lands AND DOCS-349 deploys, every one of these links will follow the displayed docs version (mainline tag on bare URLs, explicit tag on `/@vX.Y.Z/`, `main` on `/@main/`) instead of always pointing to `main`. ## Why Today a reader on `/docs/@v2.30.0/install/docker` follows a `compose.yaml` link and arrives at `main`'s `compose.yaml`, which doesn't necessarily match what the docs page describes. Helm values, Terraform templates, and source-code references in particular drift across versions. The fix is to let the coder.com rewriter substitute the page's resolved ref into the URL; that only works on relative links. ## Example payoff (post-DOCS-349) | URL | Today (absolute, always `main`) | After (relative + rewriter) | |---|---|---| | `/docs/install/docker` | `https://github.com/coder/coder/blob/main/compose.yaml` | `https://github.com/coder/coder/blob/v2.34.1/compose.yaml` (today's mainline) | | `/docs/@v2.30.0/install/docker` | same as above | `https://github.com/coder/coder/blob/v2.30.0/compose.yaml` | | `/docs/@main/install/docker` | same as above | `https://github.com/coder/coder/blob/main/compose.yaml` | ## Scope - **121 conversions** across **39 files**. - Verb breakdown: `tree/main` (directories) and `blob/main` (files), both flipped to relative paths. - Line anchors (`#L23-L24`) and query strings preserved verbatim. - Conversion is mechanical: relative path computed from the doc file's directory to the target via `os.path.relpath`. Any path starting at the same directory or below gets a `./` prefix; otherwise `../` chains. ## Rebased on main The branch was rebased onto `main` after the DOCS-350 hotfix ([#26339](https://github.com/coder/coder/pull/26339)) merged. The hotfix repointed 3 `docs-backend-contrib-guide` refs in `backend.md` to `main`, which then needed the same `main` -> relative conversion this PR is doing for the other 121 links. The conflict was resolved by reapplying the mechanical conversion to `backend.md` after taking the hotfix's content. Net result: those 3 links land here as relative, same as everything else. New HEAD `3f501cb622`. ## Inline fix folded in: dead `nix` link - `docs/about/contributing/CONTRIBUTING.md:7` -> `../../../nix` The original absolute URL `https://github.com/coder/coder/tree/main/nix` already returned 404 today. Repointed to `flake.nix` (modern Nix entrypoint, what the prose "Nix environment" semantically refers to). Closes [DOCS-357](https://linear.app/codercom/issue/DOCS-357) here since the `check-docs` Linkspector job surfaced it during rebase; cheaper to fix inline than in a separate single-line PR. ## Out of scope (filed separately) - [DOCS-350](https://linear.app/codercom/issue/DOCS-350): 3 dead `docs-backend-contrib-guide` branch refs in `backend.md` ([#26339](https://github.com/coder/coder/pull/26339), merged). - [DOCS-352](https://linear.app/codercom/issue/DOCS-352): 10 SHA-pinned `(blob|tree)/<sha>` links pending intent review. - [DOCS-355](https://linear.app/codercom/issue/DOCS-355): code-server analog (4 absolute `(blob|tree)/main` links in `coder/code-server`). - [DOCS-356](https://linear.app/codercom/issue/DOCS-356): 2 upstream content bugs in `coder/code-server/docs/CONTRIBUTING.md` (independent of this PR). ## Not triggering `/coder-agents-review` Docs-only edit; per `AGENTS.md` the bot review is reserved for product/CI changes. ## Pre-mortem | Concern | Mitigation | |---|---| | Merging before DOCS-349 deploys regresses ~120 currently-working links into 404s on coder.com | Clear DO-NOT-MERGE banner; tracked as blocker in Linear. | | Relative path computed incorrectly (off-by-one `..`) | Verified all 114 newly-relative non-md/non-image paths resolve to existing files in the repo (only exception is the pre-existing dead `nix` link above). | | Line anchors stripped during conversion | Preserved by the substitution regex; verified `#L<n>-L<m>` cases in `airgap.md` and `speed-up-templates.md`. | | Future code reorgs change file locations | Relative links will start pointing to nothing. Same failure mode as absolute links pointing to renamed files; can be caught with a future link-checker job. | ## Validation ``` $ grep -rE 'github\.com/coder/coder/(blob|tree)/main' docs --include="*.md" | wc -l 0 $ git diff --stat origin/main | tail -1 39 files changed, 118 insertions(+), 118 deletions(-) ``` 114 newly-relative paths verified to resolve to existing repo files (Python `os.path.exists` check on each computed target). <details> <summary>Decision log + planning context</summary> **Why relative over `(blob|tree)/{{currentDocsVersion}}/...` templating**: relative paths require zero markdown-system support and zero upstream churn beyond this one PR. Templating would require a preprocessor on `coder.com` side AND a convention upstream authors have to remember; relative paths just work in a plain editor and `github.com`'s own renderer too. **Why `./` prefix on same-directory targets**: makes the conversion grep-able later (`grep -E '\((\.\./|\./)'`). **Why preserve `#L<n>-L<m>` anchors verbatim**: the anchor is meaningful to the linked file's content, not to the URL form; keeping it as-is preserves authorial intent. If the file later changes such that the line range drifts, that's a different problem the SHA-pin audit ([DOCS-352](https://linear.app/codercom/issue/DOCS-352)) will surface. </details> --- *Generated by Coder Agents on @nickvigilante's behalf.* ## Drive-by external link fix folded in `docs/about/contributing/CONTRIBUTING.md:296` cited `https://reflectoring.io/meaningful-commit-messages/` which is returning HTTP 503 (the host appears to be down site-wide right now). `check-docs` Linkspector flagged it after the rebase. Replaced with `https://cbea.ms/git-commit/` (Chris Beams' canonical "If applied, this commit will..." article, confirmed 200), which is the original source of the rule the prose recites anyway.
2026-09-24 15:04:27 +08:00 · 2026-06-22 11:39:12 -04:00
parent 46916bf899
commit e458692cb8
39 changed files with 119 additions and 119 deletions
@@ -4,7 +4,7 @@ We scale-test Coder with a built-in utility that can
 be used in your environment for insights into how Coder scales with your
 infrastructure. For scale-testing Kubernetes clusters we recommend that you install
 and use the dedicated Coder template,
-[scaletest-runner](https://github.com/coder/coder/tree/main/scaletest/templates/scaletest-runner).
+[scaletest-runner](../../../scaletest/templates/scaletest-runner).

 Learn more about [Coder’s architecture](./architecture.md) and our
 [scale-testing methodology](./scale-testing.md).
@@ -138,7 +138,7 @@ This will delete all workspaces and users with the prefix `scaletest-`.
 ## Scale testing template

 Consider using a dedicated
-[scaletest-runner](https://github.com/coder/coder/tree/main/scaletest/templates/scaletest-runner)
+[scaletest-runner](../../../scaletest/templates/scaletest-runner)
 template alongside the CLI utility for testing large-scale Kubernetes clusters.

 The template deploys a main workspace with scripts used to orchestrate Coder,
@@ -177,7 +177,7 @@ Scale testing concurrency can be controlled with the following parameters:
 It is recommended to learn how to operate the _scaletest-runner_ before running
 it against the staging cluster (or production at your own risk). Coder provides
 different
-[workspace configurations](https://github.com/coder/coder/tree/main/scaletest/templates)
+[workspace configurations](../../../scaletest/templates)
 that operators can deploy depending on the traffic projections.

 There are a few cluster options available:
@@ -205,7 +205,7 @@ Use this template variant to verify limits of the cluster performance.

 During scale tests, operators can monitor progress using a Grafana dashboard.
 Coder offers a comprehensive overview
-[dashboard](https://github.com/coder/coder/blob/main/scaletest/scaletest_dashboard.json)
+[dashboard](../../../scaletest/scaletest_dashboard.json)
 that can seamlessly integrate into the internal Grafana deployment.

 This dashboard provides insights into various aspects, including:
@@ -157,7 +157,7 @@ to schedule the control plane pods on the appropriate node group.

 Coder workspaces can be deployed either as Pods or Deployments in Kubernetes.
 See our
-[example Kubernetes workspace template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
+[example Kubernetes workspace template](../../../../examples/templates/kubernetes).
 Configure the workspace node group to be auto-scaling, to dynamically allocate
 compute as users start/stop workspaces at the beginning and end of their day.
 Set nodeSelectors, affinities, and tolerations in Coder templates to assign
@@ -378,7 +378,7 @@ could affect workspace users experience once the platform is live.
 ### Helm Chart Configuration

 1. Reference our
-   [Helm chart values file](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
+   [Helm chart values file](../../../../helm/coder/values.yaml)
   and identify the required values for deployment.
 1. Create a `values.yaml` and add it to your version control system.
 1. Determine the necessary environment variables. Here is the
@@ -16,7 +16,7 @@ choose a template from the

 1. In the Coder dashboard, select **Templates** then **Create Template**.
 1. Use a
-   [starter template](https://github.com/coder/coder/tree/main/examples/templates)
+   [starter template](../../../../../examples/templates)
   or create a new template:

   - Starter template:
@@ -119,12 +119,12 @@ their development environments:

 ## Example templates

-| Template                                                                                                            | Description                                                                                                                                                         |
-|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [Docker dev containers](https://github.com/coder/coder/tree/main/examples/templates/docker-devcontainer)            | Docker provisions a development container.                                                                                                                          |
-| [Kubernetes dev containers](https://github.com/coder/coder/tree/main/examples/templates/kubernetes-devcontainer)    | Provisions a development container on the Kubernetes cluster.                                                                                                       |
-| [Google Compute Engine dev container](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer) | Runs a development container inside a single GCP instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
-| [AWS EC2 dev container](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer)               | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
+| Template                                                                                  | Description                                                                                                                                                         |
+|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Docker dev containers](../../../../../examples/templates/docker-devcontainer)            | Docker provisions a development container.                                                                                                                          |
+| [Kubernetes dev containers](../../../../../examples/templates/kubernetes-devcontainer)    | Provisions a development container on the Kubernetes cluster.                                                                                                       |
+| [Google Compute Engine dev container](../../../../../examples/templates/gcp-devcontainer) | Runs a development container inside a single GCP instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
+| [AWS EC2 dev container](../../../../../examples/templates/aws-devcontainer)               | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |

 Your template can prompt the user for a repo URL with
 [parameters](../../../templates/extending-templates/parameters.md):
@@ -305,7 +305,7 @@ With autostart enabled:

 ## Example Template

-The [Docker (Dev Containers)](https://github.com/coder/coder/tree/main/examples/templates/docker-devcontainer)
+The [Docker (Dev Containers)](../../../../examples/templates/docker-devcontainer)
 starter template demonstrates Dev Containers integration using Docker-in-Docker.
 It includes the `devcontainers-cli` module, `git-clone` module, and the
 `coder_devcontainer` resource.
@@ -126,7 +126,7 @@ To set this up, follow these steps:
 > [!NOTE]
 > The admin-level access token is used to provision user tokens and is never exposed to developers or stored in workspaces.

-If you don't want to use the official modules, you can read through the [example template](https://github.com/coder/coder/tree/main/examples/jfrog/docker), which uses Docker as the underlying compute. The
+If you don't want to use the official modules, you can read through the [example template](../../../examples/jfrog/docker), which uses Docker as the underlying compute. The
 same concepts apply to all compute types.

 ## Air-Gapped Deployments
@@ -135,7 +135,7 @@ See the [air-gapped deployments](../templates/extending-templates/modules.md#off

 ## Next Steps

- See the [full example Docker template](https://github.com/coder/coder/tree/main/examples/jfrog/docker).
+- See the [full example Docker template](../../../examples/jfrog/docker).

 - To serve extensions from your own VS Code Marketplace, check out
  [code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
@@ -57,7 +57,7 @@ If you deployed Coder on a VM, copy the kubeconfig file to
 ### Create a Coder template

 You can start from our
-[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
+[example template](../../../examples/templates/kubernetes).
 From there, add
 [template parameters](../templates/extending-templates/parameters.md) to allow
 developers to pick their desired cluster.
@@ -158,7 +158,7 @@ rolebinding.rbac.authorization.k8s.io/coder-v2 created
 ### 2. Modify the Kubernetes template

 You can start from our
-[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
+[example template](../../../examples/templates/kubernetes).

 ```tf
 variable "host" {
@@ -239,7 +239,7 @@ eval $(./setup-test-app.sh)
 ./cleanup-test-app.sh
 ```

-For more details on testing, see the [OAuth2 test scripts README](https://github.com/coder/coder/blob/main/scripts/oauth2/README.md).
+For more details on testing, see the [OAuth2 test scripts README](../../../scripts/oauth2/README.md).

 ## Common Issues

@@ -20,4 +20,4 @@ You can change your deployment custom Terraform binary as long as it is in
 `PATH` and is within the
 [supported versions](https://github.com/coder/coder/blob/f57ce97b5aadd825ddb9a9a129bb823a3725252b/provisioner/terraform/install.go#L22-L25).
 The hardcoded version check ensures compatibility with our
-[example templates](https://github.com/coder/coder/tree/main/examples/templates).
+[example templates](../../../examples/templates).
@@ -30,7 +30,7 @@ coderd_api_active_users_duration_hour 0

 ### Kubernetes deployment

-The Prometheus endpoint can be enabled in the [Helm chart's](https://github.com/coder/coder/tree/main/helm)
+The Prometheus endpoint can be enabled in the [Helm chart's](../../../helm)
 `values.yml` by setting `CODER_PROMETHEUS_ENABLE=true`. Once enabled, the environment variable `CODER_PROMETHEUS_ADDRESS` will be set by default to
 `0.0.0.0:2112`. A Service Endpoint will not be exposed; if you need to
 expose the Prometheus port on a Service, (for example, to use a
@@ -178,7 +178,7 @@ regular Coder server.
 #### Docker Compose

 Change the provided
-[`compose.yml`](https://github.com/coder/coder/blob/main/compose.yaml)
+[`compose.yml`](../../../compose.yaml)
 file to include a custom entrypoint:

 ```diff
@@ -162,7 +162,7 @@ This can also be done in the UI when building a template:
 ![template tags](../../images/admin/provisioner-tags.png)

 Alternatively, a template can target a provisioner via
-[workspace tags](https://github.com/coder/coder/tree/main/examples/workspace-tags)
+[workspace tags](../../../examples/workspace-tags)
 inside the Terraform. See the
 [workspace tags documentation](../../admin/templates/extending-templates/workspace-tags.md)
 for more information.
@@ -332,7 +332,7 @@ will use in concert with the Helm chart for deploying the Coder server.
   created. The set of tags is inferred automatically from the provisioner key.

   > Refer to the
-   > [values.yaml](https://github.com/coder/coder/blob/main/helm/provisioner/values.yaml)
+   > [values.yaml](../../../helm/provisioner/values.yaml)
   > file for the coder-provisioner chart for information on what values can be
   > specified.

@@ -9,7 +9,7 @@ For other security tips, visit our guide to

 > [!CAUTION]
 > If you discover a vulnerability in Coder, please do not hesitate to report it
-> to us by following the [security policy](https://github.com/coder/coder/blob/main/SECURITY.md).
+> to us by following the [security policy](../../../SECURITY.md).

 Security advisories are published on the
 [GitHub Security Advisories](https://github.com/coder/coder/security/advisories)
@@ -56,7 +56,7 @@ If you are providing TLS certificates directly to the Coder server, either

 1. Use a single certificate and key for both the root and wildcard domains.
 1. Configure multiple certificates and keys via
-   [`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
+   [`coder.tls.secretNames`](../../../helm/coder/values.yaml)
   in the Helm Chart, or
   [`--tls-cert-file`](../../reference/cli/server.md#--tls-cert-file) and
   [`--tls-key-file`](../../reference/cli/server.md#--tls-key-file) command line
@@ -10,7 +10,7 @@ the data.
 ## What we collect

 You can find a full list of the data we collect in our source code
-[here](https://github.com/coder/coder/blob/main/coderd/telemetry/telemetry.go).
+[here](../../../coderd/telemetry/telemetry.go).
 In particular, look at the struct types such as `Template` or `Workspace`.

 As a rule, we **do not collect** the following types of information:
@@ -142,7 +142,7 @@ nodes. Refer to sysbox's
 to ensure your nodes are compliant.

 To get started with `envbox` check out the
-[starter template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes-envbox)
+[starter template](../../../../examples/templates/kubernetes-envbox)
 or visit the [repo](https://github.com/coder/envbox).

 ### Authenticating with a Private Registry
@@ -17,7 +17,7 @@ authenticate. After that, Coder will store and refresh tokens for future
 operations.

 <video autoplay playsinline loop>
-  <source src="https://github.com/coder/coder/blob/main/site/static/external-auth.mp4?raw=true" type="video/mp4">
+  <source src="../../../../site/static/external-auth.mp4?raw=true" type="video/mp4">
 Your browser does not support the video tag.
 </video>

@@ -54,7 +54,7 @@ come bundled with your Coder deployment.
 Coder is distributed with a bundle of icons for popular cloud providers and
 programming languages. You can see all of the icons (or suggest new ones) in our
 repository on
-[GitHub](https://github.com/coder/coder/tree/main/site/static/icon).
+[GitHub](../../../../site/static/icon).

 You can also view the entire list, with search and previews, by navigating to
 `/icons` on your Coder deployment (for example,
@@ -6,7 +6,7 @@ templates using the
 [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs).
 The provider docs will provide code examples for usage; alternatively, you can
 view our
-[example templates](https://github.com/coder/coder/tree/main/examples/templates)
+[example templates](../../../../examples/templates)
 to get started.

 ## Workspace agents
@@ -122,9 +122,9 @@ Based on the instructions
 #### Example template

 We have an example template
-[here](https://github.com/coder/coder/blob/main/examples/jfrog/remote/main.tf)
+[here](../../../../examples/jfrog/remote/main.tf)
 that uses our
-[JFrog Docker](https://github.com/coder/coder/blob/main/examples/jfrog/docker/main.tf)
+[JFrog Docker](../../../../examples/jfrog/docker/main.tf)
 template as the underlying module.

 ### Private git repository
@@ -37,7 +37,7 @@ data "coder_workspace_tags" "custom_workspace_tags" {
  `feature_cache_enabled`

 Review the
-[full template example](https://github.com/coder/coder/tree/main/examples/workspace-tags)
+[full template example](../../../../examples/workspace-tags)
 using `coder_workspace_tags` and `coder_parameter`s.

 ## How it Works
@@ -58,7 +58,7 @@ resource "coderd_template" "kubernetes" {
 ```

 For an example, see how we push our development image and template
-[with GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml).
+[with GitHub actions](../../../../.github/workflows/dogfood.yaml).

 ## Coder CLI

@@ -23,7 +23,7 @@ dependencies to work in your network and work with Coder. Here are some things
 to consider:

 - `curl`, `wget`, or `busybox` is required to download and run
-  [the agent](https://github.com/coder/coder/blob/main/provisionersdk/scripts/bootstrap_linux.sh)
+  [the agent](../../../../provisionersdk/scripts/bootstrap_linux.sh)
 - `git` is recommended so developers can clone repositories
 - If the Coder server is using a certificate from an internal certificate
  authority (CA), you'll need to add or mount these into your image
@@ -28,13 +28,13 @@ If you prefer to use Coder on the
 [command line](../../../reference/cli/index.md), `coder templates init`.

 Coder starter templates are also available on our
-[GitHub repo](https://github.com/coder/coder/tree/main/examples/templates).
+[GitHub repo](../../../../examples/templates).

 ## Community Templates

 As well as Coder's starter templates, you can see a list of community templates
 by our users
-[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md).
+[here](../../../../examples/templates/community-templates.md).

 ## Editing templates

@@ -4,7 +4,7 @@ You can embed an "Open in Coder" button into your git repos or internal wikis to
 let developers quickly launch a new workspace.

 <video autoplay playsinline loop>
-  <source src="https://github.com/coder/coder/blob/main/docs/images/templates/open-in-coder.mp4?raw=true" type="video/mp4">
+  <source src="../../images/templates/open-in-coder.mp4?raw=true" type="video/mp4">
 Your browser does not support the video tag.
 </video>

@@ -8,7 +8,7 @@ has failed or timed out.
 ## Agent connection issues

 If the agent is not connected, it means the agent or
-[init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts)
+[init script](../../../provisionersdk/scripts)
 has failed on the resource.

 ```console