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
@@ -141,7 +141,7 @@ per template. You can do so by installing the
 [binary](https://github.com/coder/boundary) into the workspace image or at
 start-up. You can do so with the following command:

-```bash
+```sh
 curl -fsSL https://raw.githubusercontent.com/coder/boundary/main/install.sh | bash
 ```

@@ -93,7 +93,7 @@ above (or add "clone" to the list of allowed syscalls).

 Once updated, you can run the container with the custom seccomp profile:

-```bash
+```sh
 docker run -it \
  --cap-add=NET_ADMIN \
  --security-opt seccomp=seccomp-v25.0.13.json \
@@ -26,7 +26,7 @@ with `NET_ADMIN`) so that Agent Firewall can create namespaces and run nsjail.

 **Task definition (Terraform) — `linuxParameters`:**

-```hcl
+```tf
 container_definitions = jsonencode([{
  name      = "coder-agent"
  image     = "your-coder-agent-image"
@@ -97,7 +97,7 @@ spec:
 User namespaces are often disabled (`user.max_user_namespaces=0`) on Bottlerocket
 nodes. Check and enable user namespaces:

-```bash
+```sh
 # Check current value
 sysctl user.max_user_namespaces

@@ -108,7 +108,7 @@ sysctl -w user.max_user_namespaces=65536
 If `sysctl -w` is not allowed, configure it via Bottlerocket bootstrap settings
 when creating the node group (e.g., in Terraform):

-```hcl
+```tf
 bootstrap_extra_args = <<-EOT
  [settings.kernel.sysctl]
  "user.max_user_namespaces" = "65536"
@@ -39,7 +39,7 @@ a path-safe convenience for reading supporting files.

 ### Directory structure

-```text
+```txt
 .agents/skills/
 ├── deep-review/
 │   ├── SKILL.md
@@ -57,7 +57,7 @@ a path-safe convenience for reading supporting files.
 Each `SKILL.md` starts with YAML frontmatter containing a `name` and an
 optional `description`, followed by the full instructions in markdown:

-```markdown
+```md
 ---
 name: deep-review
 description: "Multi-reviewer code review with domain-specific reviewers"
@@ -93,7 +93,7 @@ frontmatter with a kebab-case `name`, an optional `description`, and a
 markdown body. This keeps content portable between personal skills and
 workspace skills.

-```markdown
+```md
 ---
 name: personal-reviewer
 description: "Personal review guidance"
@@ -269,7 +269,7 @@ curl -X POST https://coder.example.com/api/experimental/chats \

 Stream updates in real time by connecting to the WebSocket endpoint:

-```text
+```txt
 GET /api/experimental/chats/{chat}/stream
 ```

@@ -6,13 +6,13 @@

 ## Enable the experiment

-```shell
+```sh
 coder server --experiments=chat-advisor
 ```

 Or set the environment variable:

-```shell
+```sh
 CODER_EXPERIMENTS=chat-advisor
 ```

@@ -27,7 +27,7 @@ is `3650` days.

 Use the experimental admin API to read or update the value:

-```text
+```txt
 GET  /api/experimental/chats/config/debug-retention-days
 PUT  /api/experimental/chats/config/debug-retention-days
 ```
@@ -30,7 +30,7 @@ disable retention entirely.

 Use the experimental admin API to read or update the value:

-```text
+```txt
 GET  /api/experimental/chats/config/retention-days
 PUT  /api/experimental/chats/config/retention-days
 ```
@@ -13,7 +13,7 @@ For public `github.com`, no additional configuration is needed.
 For self-hosted GitHub Enterprise, add `API_BASE_URL` to your
 [existing configuration](../../../admin/external-auth/index.md#github-enterprise):

-```env
+```dotenv
 CODER_EXTERNAL_AUTH_0_ID="primary-github"
 CODER_EXTERNAL_AUTH_0_TYPE=github
 CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
@@ -45,7 +45,7 @@ The default GitLab scopes (`read_user`) are sufficient for basic
 authentication. To use merge request features (diffs, status checks) with
 Coder Agents, configure:

-```env
+```dotenv
 CODER_EXTERNAL_AUTH_0_ID="primary-gitlab"
 CODER_EXTERNAL_AUTH_0_TYPE=gitlab
 CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
@@ -62,7 +62,7 @@ pushing commits and creating merge requests.
 For self-hosted GitLab, set `AUTH_URL` and `TOKEN_URL` to your instance.
 Coder derives `API_BASE_URL` automatically from `AUTH_URL`:

-```env
+```dotenv
 CODER_EXTERNAL_AUTH_0_ID="primary-gitlab"
 CODER_EXTERNAL_AUTH_0_TYPE=gitlab
 CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
@@ -236,7 +236,7 @@ The agent reads `display_name` and `description` fields to understand what a
 parameter controls. Treat these the same way you treat template descriptions —
 be specific and use natural language.

-```hcl
+```tf
 data "coder_parameter" "region" {
  name         = "region"
  display_name = "Deployment Region"
@@ -288,7 +288,7 @@ For guidance on building and maintaining workspace images, see
 If the template targets a specific repository, pre-clone it and set the
 working directory so the agent starts in the right place:

-```hcl
+```tf
 resource "coder_agent" "main" {
  os   = "linux"
  arch = "amd64"
@@ -6,13 +6,13 @@

 ## Enable the experiment

-```shell
+```sh
 coder server --experiments=chat-virtual-desktop
 ```

 Or set the environment variable:

-```shell
+```sh
 CODER_EXPERIMENTS=chat-virtual-desktop
 ```

@@ -167,7 +167,7 @@ curl https://coder.example.com/api/v2/tasks/me/my-task/logs \

 **Chats API**. You open a one-way WebSocket connection:

-```text
+```txt
 GET wss://coder.example.com/api/experimental/chats/{chat}/stream
 ```

@@ -90,7 +90,7 @@ outranks a lower tier, regardless of usage.
 Within a relevance tier, or when no query is given, templates are ordered by
 an affinity score:

-```text
+```txt
 affinity = 10 x (active + 0.5 x deleted) x 0.5^(days_since_last_use / 14)
         + ln(1 + active_developers)
 ```
@@ -14,7 +14,7 @@ Once enabled, `coderd` runs the AI Gateway Proxy in-process and intercepts traff

 AI Gateway Proxy is disabled by default. To enable it, set the following configuration options:

-```shell
+```sh
 CODER_AI_GATEWAY_ENABLED=true \
 CODER_AI_GATEWAY_PROXY_ENABLED=true \
 CODER_AI_GATEWAY_PROXY_CERT_FILE=/path/to/ca.crt \
@@ -34,7 +34,7 @@ See [CA Certificate](#ca-certificate) for how to generate and obtain these files
 By default, the proxy listener accepts plain HTTP connections.
 To serve the listener over HTTPS, provide a TLS certificate and key:

-```shell
+```sh
 CODER_AI_GATEWAY_PROXY_TLS_CERT_FILE=/path/to/listener.crt
 CODER_AI_GATEWAY_PROXY_TLS_KEY_FILE=/path/to/listener.key
 # or via CLI flags:
@@ -56,7 +56,7 @@ By default, this is the embedded AI Gateway at `<coderd-access-url>/api/v2/ai-ga

 To forward intercepted requests to an AI Gateway that is not embedded in this Coder deployment, set:

-```shell
+```sh
 CODER_AI_GATEWAY_PROXY_TARGET=https://ai-gateway.example.com/
 # or via CLI flag:
 --ai-gateway-proxy-target=https://ai-gateway.example.com/
@@ -97,7 +97,7 @@ To prevent unauthorized use, restrict network access to the proxy so that only a
 In case the AI Gateway [proxy target](#proxy-target) hostname (the Coder access URL by default) resolves to a private address, it is automatically exempt from this restriction so the proxy can always reach the configured AI Gateway.
 If you need to allow access to additional internal networks via the proxy, use the Allowlist CIDRs option ([`CODER_AI_GATEWAY_PROXY_ALLOWED_PRIVATE_CIDRS`](../../../reference/cli/server.md#--ai-gateway-proxy-allowed-private-cidrs)):

-```shell
+```sh
 CODER_AI_GATEWAY_PROXY_ALLOWED_PRIVATE_CIDRS=10.0.0.0/8,172.16.0.0/12
 # or via CLI flag:
 --ai-gateway-proxy-allowed-private-cidrs=10.0.0.0/8,172.16.0.0/12
@@ -117,14 +117,14 @@ Generate a CA certificate specifically for AI Gateway Proxy:

 1) Generate a private key:

-```shell
+```sh
 openssl genrsa -out ca.key 4096
 chmod 400 ca.key
 ```

 1) Create a self-signed CA certificate (valid for 10 years):

-```shell
+```sh
 openssl req -new -x509 -days 3650 \
  -key ca.key \
  -out ca.crt \
@@ -133,7 +133,7 @@ openssl req -new -x509 -days 3650 \

 Configure AI Gateway Proxy with both files:

-```shell
+```sh
 CODER_AI_GATEWAY_PROXY_CERT_FILE=/path/to/ca.crt
 CODER_AI_GATEWAY_PROXY_KEY_FILE=/path/to/ca.key
 ```
@@ -145,7 +145,7 @@ This simplifies deployment since AI tools that already trust your organization's

 Your organization's CA issues a certificate and private key pair for the proxy. Configure the proxy with both files:

-```shell
+```sh
 CODER_AI_GATEWAY_PROXY_CERT_FILE=/path/to/intermediate-ca.crt
 CODER_AI_GATEWAY_PROXY_KEY_FILE=/path/to/intermediate-ca.key
 ```
@@ -167,7 +167,7 @@ AI tools need to trust the CA certificate before connecting through the proxy.

 For **self-signed certificates**, AI tools must be configured to trust the CA certificate. The certificate (without the private key) is available at:

-```shell
+```sh
 https://<coder-url>/api/v2/ai-gateway/proxy/ca-cert.pem
 ```

@@ -191,7 +191,7 @@ The AI Gateway Proxy enforces a minimum TLS version of 1.2.

 In addition to the required proxy configuration, set the following to enable TLS on the proxy:

-```shell
+```sh
 CODER_AI_GATEWAY_PROXY_TLS_CERT_FILE=/path/to/listener.crt
 CODER_AI_GATEWAY_PROXY_TLS_KEY_FILE=/path/to/listener.key
 # or via CLI flags:
@@ -210,14 +210,14 @@ Without a matching SAN, clients will reject the connection.

 1) Generate a private key:

-```shell
+```sh
 openssl genrsa -out listener.key 4096
 chmod 400 listener.key
 ```

 1) Create a self-signed certificate:

-```shell
+```sh
 openssl req -new -x509 -days 365 \
  -key listener.key \
  -out listener.crt \
@@ -269,13 +269,13 @@ To ensure AI Gateway also routes requests through the upstream proxy, make sure

 Configure the upstream proxy URL:

-```shell
+```sh
 CODER_AI_GATEWAY_PROXY_UPSTREAM=http://<corporate-proxy-url>:8080
 ```

 For HTTPS upstream proxies, if the upstream proxy uses a certificate not trusted by the system, provide the CA certificate:

-```shell
+```sh
 CODER_AI_GATEWAY_PROXY_UPSTREAM=https://<corporate-proxy-url>:8080
 CODER_AI_GATEWAY_PROXY_UPSTREAM_CA=/path/to/corporate-ca.crt
 ```
@@ -296,7 +296,7 @@ Consult the tool's documentation for specific instructions.

 Alternatively, most tools support the standard `HTTPS_PROXY` environment variable, though this is not guaranteed for all tools:

-```shell
+```sh
 export HTTPS_PROXY="https://coder:${CODER_SESSION_TOKEN}@<proxy-host>:8888"
 ```

@@ -320,7 +320,7 @@ Consult the tool's documentation for specific instructions.

 Download the certificate:

-```shell
+```sh
 curl -o coder-ai-gateway-proxy-ca.pem \
  -H "Coder-Session-Token: ${CODER_SESSION_TOKEN}" \
  https://<coder-url>/api/v2/ai-gateway/proxy/ca-cert.pem
@@ -331,7 +331,7 @@ Replace `<coder-url>` with your Coder deployment URL.
 When [TLS is enabled](#proxy-tls-configuration) on the proxy, AI tools must trust both the [MITM CA certificate](#ca-certificate) and the [TLS certificate](#proxy-tls-configuration).
 Combine both certificates into a single PEM file:

-```shell
+```sh
 cat coder-ai-gateway-proxy-ca.pem listener.crt > combined-ca.pem
 ```

@@ -351,7 +351,7 @@ Different AI tools use different runtimes, each with their own environment varia
 Set the environment variables associated with the AI tool's runtime.
 If you're unsure which runtime the tool uses, or if you use multiple AI tools, the simplest approach is to set all of them:

-```shell
+```sh
 export NODE_EXTRA_CA_CERTS="/path/to/coder-ai-gateway-proxy-ca.pem"
 export SSL_CERT_FILE="/path/to/coder-ai-gateway-proxy-ca.pem"
 export REQUESTS_CA_BUNDLE="/path/to/coder-ai-gateway-proxy-ca.pem"
@@ -365,7 +365,7 @@ This makes the certificate trusted by all applications on the system.

 On Linux:

-```shell
+```sh
 sudo cp coder-ai-gateway-proxy-ca.pem /usr/local/share/ca-certificates/
 sudo update-ca-certificates
 ```
@@ -400,7 +400,7 @@ This primarily affects deployments using a self-signed or internal CA, since pub
 in the system trust store.
 If the certificate is signed by a CA not in the system trust store, the connection fails and the Coder server logs:

-```shell
+```sh
 WARN: Cannot read TLS response from mitm'd server tls: failed to verify certificate: x509: certificate signed by unknown authority
 ```

@@ -412,7 +412,7 @@ reloads the trust store.

 If an AI tool fails with:

-```shell
+```sh
 x509: certificate signed by unknown authority
 ```

@@ -426,7 +426,7 @@ The proxy intercepts HTTPS traffic only for hostnames matching the base URL of a
 Gateway. Check that the provider is enabled and its base URL matches the hostname the tool is connecting to. Verify that
 `HTTPS_PROXY` points at the proxy. When interception is working, coderd logs:

-```shell
+```sh
 routing MITM request to AI Gateway
 ```

@@ -438,7 +438,7 @@ The Coder token must be supplied as the password in the proxy credentials, for e
 `https://coder:${CODER_SESSION_TOKEN}@<proxy-host>:8888`. When a CONNECT request has no usable token, the proxy replies
 with `407 Proxy Authentication Required` and logs:

-```shell
+```sh
 WARN  rejecting CONNECT request  host=... provider=... reason=missing_credentials
 ```

@@ -459,7 +459,7 @@ See [Client Configuration](#client-configuration) for how to configure the proxy

 Tunneled requests to private or reserved IP ranges are blocked by default. When a request is blocked, coderd logs:

-```shell
+```sh
 WARN  blocking connection to private/reserved IP  hostname=... port=... resolved_ip=...
 ```

@@ -9,7 +9,7 @@ Claude Code can be configured using environment variables. All modes require a *

 ## Centralized API Key

-```bash
+```sh
 # AI Gateway base URL.
 export ANTHROPIC_BASE_URL="<your-deployment-url>/api/v2/ai-gateway/anthropic"

@@ -19,7 +19,7 @@ export ANTHROPIC_AUTH_TOKEN="<your-coder-api-token>"

 ## BYOK (Personal API Key)

-```bash
+```sh
 # AI Gateway base URL.
 export ANTHROPIC_BASE_URL="<your-deployment-url>/api/v2/ai-gateway/anthropic"

@@ -35,7 +35,7 @@ unset ANTHROPIC_AUTH_TOKEN

 ## BYOK (Claude Subscription)

-```bash
+```sh
 # AI Gateway base URL.
 export ANTHROPIC_BASE_URL="<your-deployment-url>/api/v2/ai-gateway/anthropic"

@@ -53,7 +53,7 @@ account.

 Template admins can pre-configure Claude Code for a seamless experience. Admins can automatically inject the user's Coder session token and the AI Gateway base URL into the workspace environment.

-```hcl
+```tf
 module "claude-code" {
  source            = "registry.coder.com/coder/claude-code/coder"
  version           = "4.7.3"
@@ -67,7 +67,7 @@ module "claude-code" {

 [Coder Tasks](../../tasks.md) provides a framework for agents to complete background development operations autonomously. Claude Code can be configured in your Tasks automatically:

-```hcl
+```tf
 resource "coder_ai_task" "task" {
  count  = data.coder_workspace.me.start_count
  app_id = module.claude-code.task_app_id
@@ -23,7 +23,7 @@ wire_api = "responses"

 To authenticate with AI Gateway, get your **[Coder API token](../../../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself)** and set it in your environment:

-```bash
+```sh
 export OPENAI_API_KEY="<your-coder-api-token>"
 ```

@@ -46,7 +46,7 @@ env_http_headers = { "X-Coder-AI-Governance-Token" = "CODER_API_TOKEN" }

 Set both environment variables:

-```bash
+```sh
 # Your personal OpenAI API key, forwarded to OpenAI.
 export OPENAI_API_KEY="<your-openai-api-key>"

@@ -79,7 +79,7 @@ env_http_headers = { "X-Coder-AI-Governance-Token" = "CODER_API_TOKEN" }

 Set your Coder API token and ensure `OPENAI_API_KEY` is not set:

-```bash
+```sh
 # Your Coder API token, used for authentication with AI Gateway.
 export CODER_API_TOKEN="<your-coder-api-token>"

@@ -150,7 +150,7 @@ Responses API. AI Gateway does not support WebSocket transport, so each
 request attempts a WebSocket connection and retries up to 5 times before
 falling back to HTTPS. When this happens you will see:

-```text
+```txt
 Falling back from WebSockets to HTTPS transport.
 ```

@@ -27,7 +27,7 @@ For installation instructions, see [GitHub Copilot CLI documentation](https://do

 Set the `HTTPS_PROXY` environment variable:

-```shell
+```sh
 export HTTPS_PROXY="https://coder:${CODER_API_TOKEN}@<proxy-host>:8888"
 ```

@@ -39,7 +39,7 @@ Note: if [TLS is not enabled](../ai-gateway-proxy/setup.md#proxy-tls-configurati

 Copilot CLI is built on Node.js and uses the `NODE_EXTRA_CA_CERTS` environment variable for custom certificates:

-```shell
+```sh
 export NODE_EXTRA_CA_CERTS="/path/to/coder-ai-gateway-proxy-ca.pem"
 ```

@@ -47,7 +47,7 @@ See [Client Configuration CA certificate trust](../ai-gateway-proxy/setup.md#tru

 When [TLS is enabled](../ai-gateway-proxy/setup.md#proxy-tls-configuration) on the proxy, combine the MITM CA certificate and the TLS certificate into a single file:

-```shell
+```sh
 cat coder-ai-gateway-proxy-ca.pem listener.crt > combined-ca.pem
 export NODE_EXTRA_CA_CERTS="/path/to/combined-ca.pem"
 ```
@@ -68,7 +68,7 @@ While users can manually configure these tools with a long-lived API key, templa

 In this example, Claude Code respects these environment variables and will route all requests via AI Gateway.

-```hcl
+```tf
 data "coder_workspace_owner" "me" {}

 data "coder_workspace" "me" {}
@@ -85,7 +85,7 @@ module "mux" {

 If you prefer a file-based config, edit `~/.mux/providers.jsonc`:

-```jsonc
+```json
 {
  "openai": {
    "apiKey": "<your-coder-api-token>",
@@ -26,7 +26,7 @@ AI Gateway makes use of [External Auth](../../admin/external-auth/index.md) appl

 For example, GitHub has a [remote MCP server](https://github.com/github/github-mcp-server?tab=readme-ov-file#remote-github-mcp-server) and we can use it as follows.

-```bash
+```sh
 CODER_EXTERNAL_AUTH_0_TYPE=github
 CODER_EXTERNAL_AUTH_0_CLIENT_ID=...
 CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=...
@@ -38,7 +38,7 @@ See the diagram in [Implementation Details](./reference.md#implementation-detail

 You can also control which tools are injected by using an allow and/or a deny regular expression on the tool names:

-```env
+```dotenv
 CODER_EXTERNAL_AUTH_0_MCP_TOOL_ALLOW_REGEX=(.+_gist.*)
 CODER_EXTERNAL_AUTH_0_MCP_TOOL_DENY_REGEX=(create_gist)
 ```
@@ -146,7 +146,7 @@ Unlike the scalar settings above, you **cannot mix the two prefixes**. Setting
 both `CODER_AIBRIDGE_PROVIDER_*` and `CODER_AI_GATEWAY_PROVIDER_*` variables in
 the same deployment causes startup to fail with:

-```text
+```txt
 cannot mix CODER_AIBRIDGE_PROVIDER_* and CODER_AI_GATEWAY_PROVIDER_* environment variables, please consolidate onto CODER_AI_GATEWAY_PROVIDER_*
 ```

@@ -47,7 +47,7 @@ persistence on the agentapi module. Set `enable_state_persistence = true`
 so that AgentAPI saves and restores conversation history across pause and
 resume cycles:

-```hcl
+```tf
 module "agentapi" {
  source                   = "registry.coder.com/coder/agentapi/coder"
  version                  = ">= 2.2.0"
@@ -96,7 +96,7 @@ You must also set `coder-template-name` as part of this. The GHA example has thi
 - By viewing the URL of the template in the UI, e.g. `https://<your-coder-url>/templates/<org-name>/<template-name>`
 - Using the Coder CLI:

-```bash
+```sh
 # List all templates in your organization
 coder templates list

@@ -110,7 +110,7 @@ You can also choose to modify the other [input parameters](https://github.com/co

 If your prompt uses the GitHub CLI `gh`, your template must pass the user's GitHub token to the agent. Add this to your template's Terraform:

-```terraform
+```tf
 data "coder_external_auth" "github" {
  id = "github" # Must match your CODER_EXTERNAL_AUTH_0_ID
 }
@@ -165,7 +165,7 @@ We recommend that you further adapt this workflow to better match your process.
 - Modify the underlying use case to handle updating documentation, implementing a small feature, reviewing bug reports for completeness, or even writing unit tests
 - Modify the workflow trigger for other scenarios such as:

-```yml
+```yaml
 # Comment-based trigger slash commands
 on:
  issue_comment:
@@ -251,7 +251,7 @@ Generate a new token with these permissions at `https://<your-coder-url>/deploym

 From within the running task workspace, check if the token is still valid:

-```bash
+```sh
 # Check if the token still works
 curl -H "Authorization: token ${GITHUB_TOKEN}" \
  https://api.github.com/user
@@ -66,7 +66,7 @@ The following code snippet can be dropped into any existing template in Coder v2
 > [!NOTE]
 > This requires at least version 2.13.0 of the `coder/coder` Terraform provider.

-```hcl
+```tf
 data "coder_parameter" "setup_script" {
  name         = "setup_script"
  display_name = "Setup Script"
@@ -108,7 +108,7 @@ version that includes this support.

 For Claude Code, update the module version in your template:

-```hcl
+```tf
 module "claude-code" {
  source   = "registry.coder.com/coder/claude-code/coder"
  version  = ">= 4.8.0" # Minimum version with pause/resume support
@@ -160,7 +160,7 @@ modules performing cleanup.

 **Docker**: Add to your `docker_container` resource:

-```hcl
+```tf
 resource "docker_container" "workspace" {
  # Both attributes are needed for graceful shutdown.
  destroy_grace_seconds = 300 # 5 minutes
@@ -172,7 +172,7 @@ resource "docker_container" "workspace" {

 **Kubernetes**: Add to your `kubernetes_pod` resource:

-```hcl
+```tf
 resource "kubernetes_pod" "main" {
  timeouts {
    delete = "6m" # Must exceed the grace period below.
@@ -72,7 +72,7 @@ resource "coder_ai_task" "task" {
 Below is a minimal illustrative example of a Coder Tasks template pre-2.28.0.
 **Note that this is NOT a full template.**

-```hcl
+```tf
 terraform {
  required_providers {
    coder = {
@@ -128,7 +128,7 @@ In v2.28 and above, the following changes were made:

 Example (**not** a full template):

-```hcl
+```tf
 terraform {
  required_providers {
    coder = {
@@ -63,7 +63,7 @@ A template becomes a Task-capable template if it defines a `coder_ai_task` resou
 > [!NOTE]
 > The `coder_ai_task` resource is not defined within the [Claude Code Module](https://registry.coder.com/modules/coder/claude-code?tab=readme). You need to define it yourself.

-```hcl
+```tf
 terraform {
  required_providers {
    coder = {