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
@@ -80,7 +80,7 @@ Template admins can overwrite the site-wide access URL at the template level by
 leveraging the `url` argument when
 [defining the Coder provider](https://registry.terraform.io/providers/coder/coder/latest/docs#url-1):

-```terraform
+```tf
 provider "coder" {
  url = "https://coder.namespace.svc.cluster.local"
 }
@@ -126,7 +126,7 @@ for both public and [Air-gapped deployments](../../install/airgap.md).
 However, Tailscale maintains a global fleet of [DERP relays](https://tailscale.com/kb/1118/custom-derp-servers/#what-are-derp-servers) intended for their product, and has allowed Coder to access and use them.
 You can launch `coder server` with Tailscale's DERPs like so:

-```bash
+```sh
 coder server --derp-config-url https://controlplane.tailscale.com/derpmap/default
 ```

@@ -159,7 +159,7 @@ After you have custom DERP servers, you can launch Coder with them like so:
 }
 ```

-```bash
+```sh
 coder server --derp-config-path derpmap.json
 ```

@@ -171,7 +171,7 @@ protocol configuration for each shared port individually.
 You can access any port on the workspace and can configure the port protocol
 manually by appending a `s` to the port in the URL.

-```text
+```txt
 # Uses HTTP
 https://33295--agent--workspace--user--apps.example.com/
 # Uses HTTPS
@@ -194,7 +194,7 @@ must include credentials (set `credentials: "include"` if using `fetch`) or the
 requests cannot be authenticated and you will see an error resembling the
 following:

-```text
+```txt
 Access to fetch at
 '<https://coder.example.com/api/v2/applications/auth-redirect>' from origin
 '<https://8000--dev--user--apps.coder.example.com>' has been blocked by CORS
@@ -207,7 +207,7 @@ resource. If an opaque response serves your needs, set the request's mode to

 Below is a list of the cross-origin headers Coder sets with example values:

-```text
+```txt
 access-control-allow-credentials: true
 access-control-allow-methods: PUT
 access-control-allow-headers: X-Custom-Header
@@ -24,7 +24,7 @@ The following tools require wildcard access URL:

 `CODER_WILDCARD_ACCESS_URL` is necessary for [port forwarding](port-forwarding.md#dashboard) via the dashboard or running [coder_apps](../templates/index.md) on an absolute path. Set this to a wildcard subdomain that resolves to Coder (e.g. `*.coder.example.com`).

-```bash
+```sh
 export CODER_WILDCARD_ACCESS_URL="*.coder.example.com"
 coder server
 ```
@@ -40,7 +40,7 @@ Wildcard access URLs require a TLS certificate that covers the wildcard domain.

 Configure Coder to handle TLS directly using the wildcard certificate:

-```bash
+```sh
 export CODER_TLS_ENABLE=true
 export CODER_TLS_CERT_FILE=/path/to/wildcard.crt
 export CODER_TLS_KEY_FILE=/path/to/wildcard.key
@@ -72,13 +72,13 @@ You'll need to configure DNS to point wildcard subdomains to your Coder server:
 > browsers consider these "public" domains and will refuse Coder's cookies,
 > which are vital to the proper operation of this feature.

-```text
+```txt
 *.coder.example.com    A    <your-coder-server-ip>
 ```

 Or alternatively, using a CNAME record:

-```text
+```txt
 *.coder.example.com    CNAME    coder.example.com
 ```

@@ -86,7 +86,7 @@ Or alternatively, using a CNAME record:

 If you're using [workspace proxies](workspace-proxies.md) for geo-distributed teams, each proxy requires its own wildcard access URL configuration:

-```bash
+```sh
 # Main Coder server
 export CODER_WILDCARD_ACCESS_URL="*.coder.example.com"

@@ -99,7 +99,7 @@ export CODER_WILDCARD_ACCESS_URL="*.london.coder.example.com"

 Each proxy's wildcard domain must have corresponding DNS records:

-```text
+```txt
 *.sydney.coder.example.com    A    <sydney-proxy-ip>
 *.london.coder.example.com    A    <london-proxy-ip>
 ```
@@ -108,7 +108,7 @@ Each proxy's wildcard domain must have corresponding DNS records:

 In your Coder templates, enable subdomain applications using the `subdomain` parameter:

-```hcl
+```tf
 resource "coder_app" "code-server" {
  agent_id     = coder_agent.main.id
  slug         = "code-server"
@@ -132,7 +132,7 @@ If workspace applications are not working:
   - Restart the Coder server if you made changes to the environment variable
 2. Check DNS resolution for wildcard subdomains:

-   ```bash
+   ```sh
   dig test.coder.example.com
   nslookup test.coder.example.com
   ```
@@ -35,7 +35,7 @@ Create the workspace proxy and make sure to save the returned authentication
 token for said proxy. This is the token the workspace proxy will use to
 authenticate back to primary coderd.

-```bash
+```sh
 $ coder wsproxy create --name=newyork --display-name="USA East" --icon="/emojis/2194.png"
 Workspace Proxy "newyork" created successfully. Save this token, it will not be shown again.
 Token: 2fb6500b-bb47-4783-a0db-dedde895b865:05271b4ef9432bac14c02b3c56b5a2d7f05453718a1f85ba7e772c0a096c7175
@@ -43,7 +43,7 @@ Token: 2fb6500b-bb47-4783-a0db-dedde895b865:05271b4ef9432bac14c02b3c56b5a2d7f054

 To verify it was created.

-```bash
+```sh
 $ coder wsproxy ls
 NAME         URL                    STATUS STATUS
 newyork                             unregistered
@@ -55,7 +55,7 @@ Deploying the workspace proxy will also register the proxy with coderd and make
 the workspace proxy usable. If the proxy deployment is successful,
 `coder wsproxy ls` will show an `ok` status code:

-```shell
+```sh
 $ coder wsproxy ls
 NAME              URL                         STATUS STATUS
 primary           https://dev.coder.com        ok
@@ -80,7 +80,7 @@ Workspace proxy configuration overlaps with a subset of the coderd
 configuration. To see the full list of configuration options:
 `coder wsproxy server --help`

-```bash
+```sh
 # Proxy specific configuration. These are REQUIRED
 # Example: https://coderd.example.com
 CODER_PRIMARY_ACCESS_URL="https://<url_of_coderd_dashboard>"
@@ -133,7 +133,7 @@ coder:

 Using Helm, install the workspace proxy chart

-```bash
+```sh
 helm install coder coder-v2/coder --namespace <your workspace proxy namespace> -f ./values-wsproxy.yaml
 ```

@@ -143,7 +143,7 @@ and up the deployment's replicas.

 ### Running on a VM

-```bash
+```sh
 # Set configuration options via environment variables, a config file, or cmd flags
 coder wsproxy server
 ```
@@ -156,7 +156,7 @@ can configure the workspace proxy by settings in

 To run workspace proxy as a system service on the host:

-```bash
+```sh
 # Use systemd to start workspace proxy now and on reboot
 sudo systemctl enable --now coder-workspace-proxy

@@ -166,7 +166,7 @@ journalctl -u coder-workspace-proxy.service -b

 To restart workspace proxy after applying system changes:

-```shell
+```sh
 sudo systemctl restart coder-workspace-proxy
 ```

@@ -188,13 +188,13 @@ file to include a custom entrypoint:

 #### Docker run

-```bash
+```sh
 docker run --rm -it --entrypoint /opt/coder ghcr.io/coder/coder:latest wsproxy server
 ```

 #### Custom Dockerfile

-```Dockerfile
+```dockerfile
 FROM ghcr.io/coder/coder:latest
 ENTRYPOINT ["/opt/coder", "wsproxy", "server"]
 ```