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
@@ -34,13 +34,13 @@ To use the default configuration:
 1. By default, only the admin user can sign up.
   To allow additional users to sign up with GitHub, add:

-   ```shell
+   ```sh
   CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
   ```

 1. (Optional) If you want to limit sign-ups to specific GitHub organizations, set:

-   ```shell
+   ```sh
   CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
   ```

@@ -49,7 +49,7 @@ To use the default configuration:
 You can disable the default GitHub app by [configuring your own app](#step-1-configure-the-oauth-application-in-github)
 or by adding the following environment variable to your [Coder server configuration](../../reference/cli/server.md#options):

-```shell
+```sh
 CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE=false
 ```

@@ -87,7 +87,7 @@ CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE=false

 Go to your Coder host and run the following command to start up the Coder server:

-```shell
+```sh
 coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
 ```

@@ -98,7 +98,7 @@ Alternatively, if you are running Coder as a system service, you can achieve the
 same result as the command above by adding the following environment variables
 to the `/etc/coder.d/coder.env` file:

-```shell
+```sh
 CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
 CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
 CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
@@ -136,7 +136,7 @@ coder:

 To upgrade Coder, run:

-```shell
+```sh
 helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
 ```

@@ -152,7 +152,7 @@ This is enabled by default for the default GitHub app and cannot be disabled for

 For your own custom GitHub OAuth app, you can enable device flow by setting:

-```shell
+```sh
 CODER_OAUTH2_GITHUB_DEVICE_FLOW=true
 ```

@@ -15,7 +15,7 @@ synchronize Coder groups, roles, and organizations based on claims from your IdP
 To confirm that your OIDC provider is sending claims, log in with OIDC and visit
 the following URL with an `Owner` account:

-```text
+```txt
 https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
 ```

@@ -53,7 +53,7 @@ group sync for each organization.

 1. Fetch the corresponding group IDs using the following endpoint:

-   ```text
+   ```txt
   https://[coder.example.com]/api/v2/groups
   ```

@@ -301,7 +301,7 @@ Visit the Coder UI to confirm these changes:

 1. Set the following in your Coder server [configuration](../setup/index.md).

-   ```env
+   ```dotenv
    # Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
   CODER_OIDC_SCOPES=openid,profile,email,offline_access,roles

@@ -335,7 +335,7 @@ You can initiate an organization sync through the Coder dashboard or CLI:

 1. Fetch the corresponding organization IDs using the following endpoint:

-   ```text
+   ```txt
   https://[coder.example.com]/api/v2/organizations
   ```

@@ -454,12 +454,12 @@ If you enable this, your OIDC provider might be sending over many unnecessary
 groups. Use filtering options on the OIDC provider to limit the groups sent over
 to prevent creating excess groups.

-```env
+```dotenv
 # as an environment variable
 CODER_OIDC_GROUP_AUTO_CREATE=true
 ```

-```shell
+```sh
 # as a flag
 --oidc-group-auto-create=true
 ```
@@ -471,12 +471,12 @@ want to filter out groups that do not match a certain pattern. For example, if
 you want to only allow groups that start with `my-group-` to be created, you can
 set the following environment variable.

-```env
+```dotenv
 # as an environment variable
 CODER_OIDC_GROUP_REGEX_FILTER="^my-group-.*$"
 ```

-```shell
+```sh
 # as a flag
 --oidc-group-regex-filter="^my-group-.*$"
 ```
@@ -82,7 +82,7 @@ The new user will appear in the **Users** list. Use the toggle to change their

 To create a user via the Coder CLI, run:

-```shell
+```sh
 coder users create
 ```

@@ -116,7 +116,7 @@ To suspend a user via the web UI:

 To suspend a user via the CLI, run:

-```shell
+```sh
 coder users suspend <username|user_id>
 ```

@@ -135,7 +135,7 @@ To activate a user via the web UI:

 To activate a user via the CLI, run:

-```shell
+```sh
 coder users activate <username|user_id>
 ```

@@ -161,7 +161,7 @@ logging in.

 You can also reset a password via the CLI:

-```shell
+```sh
 # run `coder reset-password <username> --help` for usage instructions
 coder reset-password <username>
 ```
@@ -172,7 +172,7 @@ coder reset-password <username>

 ### Resetting a password on Kubernetes

-```shell
+```sh
 kubectl exec -it deployment/coder -n coder -- /bin/bash

 coder reset-password <username>
@@ -232,7 +232,7 @@ You can use the Coder CLI or API to retrieve your list of users.

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

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

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

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

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

 To export the results to a CSV file, you can use [`jq`](https://jqlang.org/) to process the JSON response:

-```shell
+```sh
 curl -X GET http://coder-server:8080/api/v2/users \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY' | \
@@ -19,7 +19,7 @@ This guide shows how to configure Coder to authenticate users with Google using

 Set the following environment variables on your Coder deployment and restart Coder:

-```env
+```dotenv
 CODER_OIDC_ISSUER_URL=https://accounts.google.com
 CODER_OIDC_CLIENT_ID=<client id>
 CODER_OIDC_CLIENT_SECRET=<client secret>
@@ -39,7 +39,7 @@ CODER_OIDC_ICON_URL=/icon/google.svg

 Google uses auth URL parameters to issue refresh tokens. Configure:

-```env
+```dotenv
 # Keep standard scopes
 CODER_OIDC_SCOPES=openid,profile,email
 # Add Google-specific auth URL params
@@ -13,7 +13,7 @@ Your OIDC provider will ask you for the following parameter:

 Set the following environment variables on your Coder deployment and restart Coder:

-```env
+```dotenv
 CODER_OIDC_ISSUER_URL="https://issuer.corp.com"
 CODER_OIDC_EMAIL_DOMAIN="your-domain-1,your-domain-2"
 CODER_OIDC_CLIENT_ID="533...des"
@@ -57,7 +57,7 @@ Coder requires all OIDC email addresses to be verified by default. If the
 provider, Coder will validate that its value is `true`. If needed, you can
 disable this behavior with the following setting:

-```env
+```dotenv
 CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
 ```

@@ -84,7 +84,7 @@ If your upstream identity provider uses a different claim, you can set
 If you'd like to change the OpenID Connect button text and/or icon, you can
 configure them like so:

-```env
+```dotenv
 CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
 CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
 ```
@@ -107,13 +107,13 @@ The general steps to configure persistent user sessions are:

   For most providers, add the `offline_access` scope:

-   ```env
+   ```dotenv
   CODER_OIDC_SCOPES=openid,profile,email,offline_access
   ```

   For Google, add auth URL parameters (`CODER_OIDC_AUTH_URL_PARAMS`) too:

-   ```env
+   ```dotenv
   CODER_OIDC_SCOPES=openid,profile,email
   CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
   ```
@@ -130,7 +130,7 @@ The general steps to configure persistent user sessions are:
 To remove email and password login, set the following environment variable on
 your Coder deployment:

-```env
+```dotenv
 CODER_DISABLE_PASSWORD_AUTH=true
 ```

@@ -157,7 +157,7 @@ authentication. Upon deactivation, users are
 [Configure](../../setup/index.md) your SCIM application with an auth key and supply
 it the Coder server.

-```env
+```dotenv
 CODER_SCIM_AUTH_HEADER="your-api-key"
 ```

@@ -166,7 +166,7 @@ CODER_SCIM_AUTH_HEADER="your-api-key"
 If your OpenID Connect provider requires client TLS certificates for
 authentication, you can configure them like so:

-```env
+```dotenv
 CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
 CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
 ```
@@ -24,7 +24,7 @@ This guide shows how to configure Coder to authenticate users with Microsoft Ent

 Set the following environment variables on your Coder deployment and restart Coder:

-```env
+```dotenv
 CODER_OIDC_ISSUER_URL=https://login.microsoftonline.com/{tenant-id}/v2.0 # Replace {tenant-id} with your Azure tenant ID
 CODER_OIDC_CLIENT_ID=<client id, located in "Overview">
 CODER_OIDC_CLIENT_SECRET=<client secret, saved from step 6>
@@ -42,7 +42,7 @@ CODER_OIDC_ICON_URL=/icon/microsoft.svg

 ## Enable refresh tokens (recommended)

-```env
+```dotenv
 # Keep standard scopes
 CODER_OIDC_SCOPES=openid,profile,email,offline_access
 ```
@@ -35,7 +35,7 @@ Go to the Azure Portal > **Azure Active Directory** > **App registrations** > Yo

 1. In your [Coder configuration](../../../reference/cli/server.md#--oidc-auth-url-params), request the same scopes:

-   ```env
+   ```dotenv
   CODER_OIDC_SCOPES=openid,profile,email,offline_access
   ```

@@ -60,7 +60,7 @@ Without this, users will be logged out when their access token expires.

 In your [Coder configuration](../../../reference/cli/server.md#--oidc-auth-url-params):

-```env
+```dotenv
 CODER_OIDC_SCOPES=openid,profile,email
 CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
 ```
@@ -76,7 +76,7 @@ including the ability to refresh access tokens without requiring the user to rea
 Add the `offline_access` scope to enable refresh tokens in your
 [Coder configuration](../../../reference/cli/server.md#--oidc-auth-url-params):

-```env
+```dotenv
 CODER_OIDC_SCOPES=openid,profile,email,offline_access
 CODER_OIDC_AUTH_URL_PARAMS='{"access_type":"offline"}'
 ```
@@ -99,7 +99,7 @@ CODER_OIDC_AUTH_URL_PARAMS='{"access_type":"offline"}'

 1. In your [Coder configuration](../../../reference/cli/server.md#--oidc-scopes), add the `offline_access` scope:

-   ```env
+   ```dotenv
   CODER_OIDC_SCOPES=openid,profile,email,offline_access
   ```

@@ -79,7 +79,7 @@ provisioner as the built-in provisioners are scoped to the default organization.
 1. Using Coder CLI, run the following command to create a key that will be used
   to authenticate the provisioner:

-   ```shell
+   ```sh
   coder provisioner keys create data-cluster-key --org data-platform
   Successfully created provisioner key data-cluster! Save this authentication token, it will not be shown again.

@@ -29,7 +29,7 @@ quota than an online workspace.
 A common use case is separating costs for a persistent volume and ephemeral
 compute:

-```hcl
+```tf
 resource "docker_volume" "home_volume" {
  name = "coder-${data.coder_workspace_owner.me.name}-${data.coder_workspace.me.name}-root"
 }