docs: normalize code-fence languages for Shiki compatibility (#27161)

Normalizes non-standard code-fence language tags across `docs/**` so a strict highlighter (Shiki, used by Fumadocs) won't fail the build on an unrecognized language, and unifies redundant synonym tags onto one canonical form per language. The current renderer (Speed-Highlight) detects the language from the code content, not the fence label, so this drift wasn't visible until now. ## Changes - `hcl` -> `tf` (199 fences, including indented ones nested in numbered/bulleted lists). Shiki ships `hcl` and `terraform` as two distinct grammars (not aliases); every `hcl`-tagged fence in `docs/**` is actually Terraform resource/data/provider syntax, so the more specific `terraform` grammar is correct for all of them. `tf` is Shiki's own alias for that grammar, and it's also what GitHub's own markdown renderer resolves to the same HCL/Terraform highlighting. - `pwsh`/`powershell` -> `ps1`. Both `ps` and `ps1` are registered PowerShell aliases in Shiki, but on GitHub's renderer only `.ps1` is a registered file extension (`.ps` isn't), so `ps1` renders identically to `powershell` there today while bare `ps` would silently lose highlighting. - `env` -> `dotenv` (a dedicated Shiki grammar for `KEY=VALUE` files) - `text`/`output`/`none`/`url` -> `txt`. Same built-in plain-text fallback either way, just shorter. - `Dockerfile` -> `dockerfile` (lowercase) - `bash`/`shell` -> `sh` (732 fences). Shiki and GitHub both alias all three to a single shell grammar; this was already the style guide's stated preference, just not enforced across the existing corpus until now. - `markdown` -> `md` (4 fences). Alias of the same grammar in both Shiki and GitHub. - `jsonc` -> `json` (1 fence). The block has no comments or trailing commas, so it doesn't need the comments-capable grammar. - `ts` -> `tsx` (2 fences, `docs/about/contributing/frontend.md`). Verified the actual content tokenizes identically under both grammars, and a sibling block in the same file already needs `tsx` for real JSX, so unifying to one tag is safe for this file. Documented a caveat: `tsx` mis-tokenizes the legacy angle-bracket type-assertion syntax (`<Type>value`), which is invalid in real `.tsx` files anyway, so use `value as Type` instead. - `yml` -> `yaml` (1 fence) - Updated `docs/.style/style-guide/formatting.md` to document all canonical tags `promql` (2 fences) and `caddyfile` (2 fences) are left as-is. Shiki doesn't bundle a grammar for either, so they need a custom grammar registration when the site adopts Shiki, rather than degrading to `txt`. Tracked as follow-up work under DOCS-118 and [DOCS-544](https://linear.app/codercom/issue/DOCS-544/vendor-a-local-promql-grammar-for-shiki-syntax-highlighting) (promql). Does not touch `offlinedocs/`. Linear: [DOCS-476](https://linear.app/codercom/issue/DOCS-476/normalize-docs-code-fence-languages-de-risk-shikifumadocs) <details> <summary>How the fence tags were verified</summary> Each tag was tested against a real `shiki@latest` highlighter instance (`codeToHtml`/`codeToTokens`) and cross-checked against GitHub's `@wooorm/starry-night` grammar sources (the renderer that actually displays these `.md` files today, in repo browsing and PR diffs), since that's what determines whether brevity is safe before Shiki adoption: ```text FAIL env -- Language `env` is not included in this bundle. FAIL Dockerfile -- Language `Dockerfile` is not included in this bundle. FAIL promql -- Language `promql` is not included in this bundle. FAIL caddyfile -- Language `caddyfile` is not included in this bundle. FAIL pwsh -- Language `pwsh` is not included in this bundle. FAIL output -- Language `output` is not included in this bundle. ``` `hcl` doesn't error in Shiki, since it's a real grammar, but that's exactly the trap: it was silently rendering every fence with the generic HCL grammar instead of the Terraform-specific one. Every `hcl`-tagged fence in `docs/**` was manually checked against `origin/main` and is genuinely Terraform content. For `ts`/`tsx`, tokenizing the actual doc content confirmed identical output under both grammars; a synthetic test with the legacy angle-bracket cast syntax confirmed `tsx` degrades on that specific construct, which the style guide now calls out. The first normalization pass only matched fence tags at column 0 (`^```tag$`), missing tags indented inside numbered/bulleted lists. A follow-up pass caught the remaining occurrences at any indentation level. </details> --- *This PR description and the underlying changes were prepared with Coder Agents assistance.*
2026-09-24 15:04:27 +08:00 · 2026-07-15 14:07:09 -04:00
parent d0982e3cc7
commit c84aa564ba
181 changed files with 997 additions and 980 deletions
@@ -25,7 +25,7 @@ choose a template from the

 1. Use the `template init` command to initialize your choice of image:

-   ```shell
+   ```sh
   coder template init --id kubernetes-devcontainer
   ```

@@ -34,7 +34,7 @@ choose a template from the

 1. `cd` into the directory and push the template to your Coder deployment:

-   ```shell
+   ```sh
   cd kubernetes-devcontainer && coder templates push
   ```

@@ -52,7 +52,7 @@ choose a template from the

   - CLI:

-   ```shell
+   ```sh
   coder templates push <template-name> -d <path to folder containing main.tf>
   ```

@@ -65,7 +65,7 @@ choose a template from the

      - To zip the files through the command line:

-        ```shell
+        ```sh
        zip templates.zip Dockerfile main.tf
        ```

@@ -40,7 +40,7 @@ Use the
 [devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module
 to ensure the `@devcontainers/cli` is installed in your workspace:

-```terraform
+```tf
 module "devcontainers-cli" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/devcontainers-cli/coder"
@@ -57,7 +57,7 @@ The
 resource automatically starts a Dev Container in your workspace, ensuring it's
 ready when you access the workspace:

-```terraform
+```tf
 resource "coder_devcontainer" "my-repository" {
  count            = data.coder_workspace.me.start_count
  agent_id         = coder_agent.dev.id
@@ -83,7 +83,7 @@ default behavior.
 If you need to explicitly disable Dev Containers, set the
 `CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `false`:

-```terraform
+```tf
 resource "docker_container" "workspace" {
  count = data.coder_workspace.me.start_count
  image = "codercom/oss-dogfood:latest"
@@ -153,7 +153,7 @@ and [`coder_env`](https://registry.terraform.io/providers/coder/coder/latest/doc
 resources to a `coder_devcontainer` by referencing its `subagent_id` attribute
 as the `agent_id`:

-```terraform
+```tf
 resource "coder_devcontainer" "my-repository" {
  count            = data.coder_workspace.me.start_count
  agent_id         = coder_agent.dev.id
@@ -227,7 +227,7 @@ For the full reference, see
 Here's a simplified template example that uses Dev Containers with manual
 configuration:

-```terraform
+```tf
 terraform {
  required_providers {
    coder  = { source = "coder/coder" }
@@ -277,7 +277,7 @@ resource "coder_env" "env" {
 By default, discovered containers appear in the dashboard but developers must
 manually start them. To have them start automatically, enable autostart:

-```terraform
+```tf
 resource "docker_container" "workspace" {
  count = data.coder_workspace.me.start_count
  image = "codercom/oss-dogfood:latest"
@@ -32,7 +32,7 @@ If your organization already uses the Coder-DX integration, you can find a list

 Use `users list` to export the list of users to a CSV file:

-```shell
+```sh
 coder users list > users.csv
 ```

@@ -42,7 +42,7 @@ Visit the [users list](../../reference/cli/users_list.md) documentation for more

 Use [get users](../../reference/api/users.md#get-users):

-```bash
+```sh
 curl -X GET http://coder-server:8080/api/v2/users \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'
@@ -50,7 +50,7 @@ curl -X GET http://coder-server:8080/api/v2/users \

 To export the results to a CSV file, you can use the `jq` tool to process the JSON response:

-```bash
+```sh
 curl -X GET http://coder-server:8080/api/v2/users \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY' | \
@@ -56,7 +56,7 @@ To set this up, follow these steps:
 1. Add a new [external authentication](../external-auth/index.md) to Coder by setting these
   environment variables in a manner consistent with your Coder deployment. Replace `JFROG_URL` with your JFrog Artifactory base URL:

-   ```env
+   ```dotenv
   # JFrog Artifactory External Auth
   CODER_EXTERNAL_AUTH_1_ID="jfrog"
   CODER_EXTERNAL_AUTH_1_TYPE="jfrog"
@@ -13,7 +13,7 @@ or deployment, such as:
 Install the `coder-logstream-kube` helm chart on the cluster where the
 deployment is running.

-```shell
+```sh
 helm repo add coder-logstream-kube https://helm.coder.com/logstream-kube
 helm install coder-logstream-kube coder-logstream-kube/coder-logstream-kube \
    --namespace coder \
@@ -12,7 +12,7 @@ in the Terraform provider.
 First, create a kubeconfig file with
 [multiple contexts](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).

-```shell
+```sh
 kubectl config get-contexts

 CURRENT   NAME                        CLUSTER
@@ -27,7 +27,7 @@ If you deployed Coder on Kubernetes, you can attach a kubeconfig as a secret.
 This assumes Coder is deployed on the `coder` namespace and your kubeconfig file
 is in ~/.kube/config.

-```shell
+```sh
 kubectl create secret generic kubeconfig-secret -n coder --from-file=~/.kube/config
 ```

@@ -104,7 +104,7 @@ cluster. Change the namespace accordingly.
 Run this command against your remote cluster to create a ServiceAccount, Role,
 RoleBinding, and token:

-```shell
+```sh
 kubectl apply -n coder-workspaces -f - <<EOF
 apiVersion: v1
 kind: ServiceAccount
@@ -147,7 +147,7 @@ EOF

 The output should be similar to:

-```text
+```txt
 serviceaccount/coder-v2 created
 secret/coder-v2 created
 role.rbac.authorization.k8s.io/coder-v2 created
@@ -193,7 +193,7 @@ macOS and Linux.

 To get the cluster address:

-```shell
+```sh
 kubectl cluster-info
 Kubernetes control plane is running at https://example.domain:6443

@@ -202,7 +202,7 @@ export CLUSTER_ADDRESS=https://example.domain:6443

 To fetch the CA certificate and token:

-```shell
+```sh
 export CLUSTER_CA_CERTIFICATE=$(kubectl get secrets coder-v2 -n coder-workspaces -o jsonpath="{.data.ca\.crt}")

 export CLUSTER_SERVICEACCOUNT_TOKEN=$(kubectl get secrets coder-v2 -n coder-workspaces -o jsonpath="{.data.token}")
@@ -210,7 +210,7 @@ export CLUSTER_SERVICEACCOUNT_TOKEN=$(kubectl get secrets coder-v2 -n coder-work

 Create the template with these values:

-```shell
+```sh
 coder templates push \
    --variable host=$CLUSTER_ADDRESS \
    --variable cluster_ca_certificate=$CLUSTER_CA_CERTIFICATE \
@@ -221,7 +221,7 @@ coder templates push \
 If you're on a Windows machine (or if one of the commands fail), try grabbing
 the values manually:

-```shell
+```sh
 # Get cluster API address
 kubectl cluster-info

@@ -22,13 +22,13 @@ Coder can act as an OAuth2 authorization server, allowing third-party applicatio

 Add the `oauth2` experiment flag to your Coder server:

-```bash
+```sh
 coder server --experiments oauth2
 ```

 Or set the environment variable:

-```env
+```dotenv
 CODER_EXPERIMENTS=oauth2
 ```

@@ -47,7 +47,7 @@ CODER_EXPERIMENTS=oauth2

 Create an application using the Coder API:

-```bash
+```sh
 curl -X POST \
  -H "Authorization: Bearer $CODER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
@@ -61,7 +61,7 @@ curl -X POST \

 Generate a client secret:

-```bash
+```sh
 curl -X POST \
  -H "Authorization: Bearer $CODER_SESSION_TOKEN" \
  "$CODER_URL/api/v2/oauth2-provider/apps/$APP_ID/secrets"
@@ -86,7 +86,7 @@ If client authentication fails, the token endpoint returns **HTTP 401** with an

 1. **Authorization Request**: Redirect users to Coder's authorization endpoint:

-   ```url
+   ```txt
   https://coder.example.com/oauth2/authorize?
     client_id=your-client-id&
     response_type=code&
@@ -98,7 +98,7 @@ If client authentication fails, the token endpoint returns **HTTP 401** with an

   **Option A: HTTP Basic authentication (`client_secret_basic`, recommended)**

-   ```bash
+   ```sh
   curl -X POST \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -H "Content-Type: application/x-www-form-urlencoded" \
@@ -110,7 +110,7 @@ If client authentication fails, the token endpoint returns **HTTP 401** with an

   **Option B: Form parameters (`client_secret_post`)**

-   ```bash
+   ```sh
   curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
@@ -123,7 +123,7 @@ If client authentication fails, the token endpoint returns **HTTP 401** with an

 3. **API Access**: Use the access token to call Coder's API:

-   ```bash
+   ```sh
   curl -H "Authorization: Bearer $ACCESS_TOKEN" \
     "$CODER_URL/api/v2/users/me"
   ```
@@ -141,14 +141,14 @@ confidential clients must include PKCE parameters:

 1. Generate a code verifier and challenge:

-   ```bash
+   ```sh
   CODE_VERIFIER=$(openssl rand -base64 96 | tr -d "=+/" | cut -c1-128)
   CODE_CHALLENGE=$(echo -n $CODE_VERIFIER | openssl dgst -sha256 -binary | base64 | tr -d "=+/" | cut -c1-43)
   ```

 2. Include PKCE parameters in the authorization request:

-   ```url
+   ```txt
   https://coder.example.com/oauth2/authorize?
     client_id=your-client-id&
     response_type=code&
@@ -159,7 +159,7 @@ confidential clients must include PKCE parameters:

 3. Include the code verifier in the token exchange (see [Client Authentication Methods](#client-authentication-methods)):

-   ```bash
+   ```sh
   curl -X POST \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -H "Content-Type: application/x-www-form-urlencoded" \
@@ -187,7 +187,7 @@ Refresh an expired access token.

 **Option A: HTTP Basic authentication (`client_secret_basic`)**

-```bash
+```sh
 curl -X POST \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
@@ -198,7 +198,7 @@ curl -X POST \

 **Option B: Form parameters (`client_secret_post`)**

-```bash
+```sh
 curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
@@ -212,7 +212,7 @@ curl -X POST \

 Revoke all tokens for an application:

-```bash
+```sh
 curl -X DELETE \
  -H "Authorization: Bearer $CODER_SESSION_TOKEN" \
  "$CODER_URL/oauth2/tokens?client_id=$CLIENT_ID"
@@ -222,7 +222,7 @@ curl -X DELETE \

 Coder provides comprehensive test scripts for OAuth2 development:

-```bash
+```sh
 # Navigate to the OAuth2 test scripts
 cd scripts/oauth2/

@@ -38,6 +38,6 @@ This module installs and authenticates the `vault` CLI in your Coder workspace.
 Users then can use the `vault` CLI to interact with Vault; for example, to fetch
 a secret stored in the KV backend.

-```shell
+```sh
 vault kv get -namespace=YOUR_NAMESPACE -mount=MOUNT_NAME SECRET_NAME
 ```