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
@@ -39,7 +39,7 @@ following:

 Here's an example Dockerfile:

-```Dockerfile
+```dockerfile
 FROM ghcr.io/coder/coder:latest

 USER root
@@ -147,13 +147,13 @@ filesystem mirror without re-building the image.

 First, create an empty plugins directory:

-```shell
+```sh
 mkdir $HOME/plugins
 ```

 Next, add a volume mount to compose.yaml:

-```shell
+```sh
 vim compose.yaml
 ```

@@ -35,7 +35,7 @@ Alternatively, you can use the
 [`winget`](https://learn.microsoft.com/en-us/windows/package-manager/winget/#use-winget)
 package manager to install Coder:

-```powershell
+```ps1
 winget install Coder.Coder
 ```

@@ -60,7 +60,7 @@ Coder a multitude of different ways. You can learn more about those

 In the Azure VM instance, run the following command to install Coder

-```shell
+```sh
 curl -fsSL https://coder.com/install.sh | sh
 ```

@@ -68,13 +68,13 @@ curl -fsSL https://coder.com/install.sh | sh

 Run the following command to start Coder as a system level service:

-```shell
+```sh
 sudo systemctl enable --now coder
 ```

 The following command will get you information about the Coder launch service

-```shell
+```sh
 journalctl -u coder.service -b
 ```

@@ -84,7 +84,7 @@ Embedded in the logs is the Coder Access URL.
 Copy the URL and run the following command to create the first user, either on
 your local machine or in the instance terminal.

-```shell
+```sh
 coder login <url***.try.coder.app>
 ```

@@ -119,7 +119,7 @@ to initialize the template.
 Run the following commands to copy the Azure credentials and give the `coder`
 user access to them:

-```shell
+```sh
 sudo cp -r ~/.azure /home/coder/.azure
 sudo chown -R coder:coder /home/coder/.azure/
 ```
@@ -127,7 +127,7 @@ sudo chown -R coder:coder /home/coder/.azure/
 Navigate to the `./azure-linux` folder where you created your template and run
 the following command to put the template on your Coder instance.

-```shell
+```sh
 coder templates push
 ```

@@ -54,7 +54,7 @@ Given you created or added key-pairs when launching the instance, you can
 [configure your Coder deployment](../../admin/setup/index.md) by logging in via
 SSH or using the console:

-```shell
+```sh
 ssh ubuntu@<gcp-public-IPv4>
 sudo vim /etc/coder.d/coder.env # edit config
 sudo systemctl daemon-reload
@@ -36,7 +36,7 @@ which includes a PostgreSQL container and volume.
 1. Update `group_add:` in `docker-compose.yaml` with the `gid` of `docker`
   group. You can get the `docker` group `gid` by running the below command:

-   ```shell
+   ```sh
   getent group docker | cut -d: -f3
   ```

@@ -57,7 +57,7 @@ Coder's [configuration options](../admin/setup/index.md).
 For proof-of-concept deployments, you can run a complete Coder instance with the
 following command.

-```shell
+```sh
 export CODER_DATA=$HOME/.config/coderv2-docker
 export DOCKER_GROUP=$(getent group docker | cut -d: -f3)
 mkdir -p $CODER_DATA
@@ -74,7 +74,7 @@ For production deployments, we recommend using an external PostgreSQL database
 (version 13 or higher). Set `CODER_ACCESS_URL` to the external URL that users
 and workspaces will use to connect to Coder.

-```shell
+```sh
 export DOCKER_GROUP=$(getent group docker | cut -d: -f3)
 docker run --rm -it \
  -e CODER_ACCESS_URL="https://coder.example.com" \
@@ -105,7 +105,7 @@ Replace `ghcr.io/coder/coder:latest` in the `docker run` command in the

 If you see an error like:

-```text
+```txt
 Error: Error pinging Docker server: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
 ```

@@ -45,7 +45,7 @@ Alternatively, you can use the
 [`winget`](https://learn.microsoft.com/en-us/windows/package-manager/winget/#use-winget)
 package manager to install Coder:

-```powershell
+```ps1
 winget install Coder.Coder
 ```

@@ -55,7 +55,7 @@ helm install postgresql bitnami/postgresql \

 The cluster-internal DB URL for the above database is:

-```shell
+```sh
 postgres://coder:coder@postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable
 ```

@@ -75,7 +75,7 @@ kubectl create secret generic coder-db-url -n coder \

 ## 4. Install Coder with Helm

-```shell
+```sh
 helm repo add coder-v2 https://helm.coder.com/v2
 ```

@@ -131,7 +131,7 @@ We support two release channels: mainline and stable - read the
  - **Chart Registry**
    <!-- autoversion(mainline): "--version [version]" -->

-    ```shell
+    ```sh
    helm install coder coder-v2/coder \
        --namespace coder \
        --values values.yaml \
@@ -142,7 +142,7 @@ We support two release channels: mainline and stable - read the

    <!-- autoversion(mainline): "--version [version]" -->

-    ```shell
+    ```sh
    helm install coder oci://ghcr.io/coder/chart/coder \
        --namespace coder \
        --values values.yaml \
@@ -155,7 +155,7 @@ We support two release channels: mainline and stable - read the

    <!-- autoversion(stable): "--version [version]" -->

-    ```shell
+    ```sh
    helm install coder coder-v2/coder \
        --namespace coder \
        --values values.yaml \
@@ -166,7 +166,7 @@ We support two release channels: mainline and stable - read the

    <!-- autoversion(stable): "--version [version]" -->

-    ```shell
+    ```sh
    helm install coder oci://ghcr.io/coder/chart/coder \
        --namespace coder \
        --values values.yaml \
@@ -190,7 +190,7 @@ to the proper Coder URL.
 To upgrade Coder in the future or change values, you can run the following
 command:

-```shell
+```sh
 helm repo update
 helm upgrade coder coder-v2/coder \
  --namespace coder \
@@ -100,13 +100,13 @@ The steps here follow the Microsoft tutorial for a Coder deployment.

 1. Create Coder namespace:

-   ```shell
+   ```sh
   kubectl create ns coder
   ```

 1. Deploy non-production PostgreSQL instance to AKS cluster:

-   ```shell
+   ```sh
   helm repo add bitnami https://charts.bitnami.com/bitnami
   helm install coder-db bitnami/postgresql \
   --set image.repository=bitnamilegacy/postgresql \
@@ -119,13 +119,13 @@ The steps here follow the Microsoft tutorial for a Coder deployment.

 1. Create the PostgreSQL secret:

-   ```shell
+   ```sh
   kubectl create secret generic coder-db-url -n coder --from-literal=url="postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable"
   ```

 1. Deploy Coder to AKS cluster:

-   ```shell
+   ```sh
   helm repo add coder-v2 https://helm.coder.com/v2
   helm install coder coder-v2/coder \
       --namespace coder \
@@ -13,13 +13,13 @@

 Run the following command to login to your OpenShift cluster:

-```shell
+```sh
 oc login --token=w4r...04s --server=<cluster-url>
 ```

 Next, you will run the below command to create a project for Coder:

-```shell
+```sh
 oc new-project coder
 ```

@@ -171,7 +171,7 @@ oc apply -f route.yaml
 You can now install Coder using the values you've set from the above steps. To
 do so, run the series of `helm` commands below:

-```shell
+```sh
 helm repo add coder-v2 https://helm.coder.com/v2
 helm repo update
 helm install coder coder-v2/coder \
@@ -247,7 +247,7 @@ Security Context Constraints (SCCs) in OpenShift.
   > For more information, please consult the
   > [OpenShift Documentation](https://docs.openshift.com/container-platform/4.12/cicd/builds/understanding-buildconfigs.html).

-   ```shell
+   ```sh
   oc create -f - <<EOF
   kind: BuildConfig
   apiVersion: build.openshift.io/v1
@@ -292,7 +292,7 @@ Security Context Constraints (SCCs) in OpenShift.

 1. Create an `ImageStream` as a target for the previous step:

-   ```shell
+   ```sh
   oc create imagestream enterprise-base
   ```

@@ -309,7 +309,7 @@ Security Context Constraints (SCCs) in OpenShift.

 Start from the default "Kubernetes" template:

-```shell
+```sh
 echo kubernetes | coderv2 templates init ./openshift-k8s
 cd ./openshift-k8s
 ```
@@ -323,7 +323,7 @@ Edit `main.tf` and update the following fields of the Kubernetes pod resource:

 Finally, create the template:

-```shell
+```sh
 coder template push kubernetes -d .
 ```

@@ -22,7 +22,7 @@ Installing Coder on Rancher involves four key steps:

 Create a namespace for the Coder control plane. In this tutorial, we call it `coder`:

-```shell
+```sh
 kubectl create namespace coder
 ```

@@ -65,7 +65,7 @@ helm install coder-db bitnami/postgresql \

 After installation, the cluster-internal database URL will be:

-```text
+```txt
 postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable
 ```

@@ -78,7 +78,7 @@ For more advanced PostgreSQL management, consider using the

 Create a Kubernetes secret with your PostgreSQL connection URL:

-```shell
+```sh
 kubectl create secret generic coder-db-url -n coder \
  --from-literal=url="postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable"
 ```
@@ -51,7 +51,7 @@ Create or update your Terraform CLI configuration file to use Artifactory.

 On Linux/macOS, create `~/.terraformrc`. On Windows, create `%APPDATA%\terraform.rc`.

-```hcl
+```tf
 host "<your-artifactory-host>" {
  services = {
    "modules.v1" = "https://<your-artifactory-host>/artifactory/api/terraform/coder-registry/v1/modules/"
@@ -43,13 +43,13 @@ access features:

 - Enable all early access features:

-  ```shell
+  ```sh
  coder server --experiments=*
  ```

 - Enable multiple early access features:

-  ```shell
+  ```sh
  coder server --experiments=feature1,feature2
  ```

@@ -67,7 +67,7 @@ our GitHub [releases page](https://github.com/coder/coder/releases).
 You can also use our `install.sh` script with the `stable` flag to install the
 latest stable release:

-```shell
+```sh
 curl -fsSL https://coder.com/install.sh | sh -s -- --stable
 ```

@@ -15,19 +15,19 @@ To uninstall your Coder server, delete the following directories.

 ## Debian, Ubuntu

-```shell
+```sh
 sudo apt remove coder
 ```

 ## Fedora, CentOS, RHEL, SUSE

-```shell
+```sh
 sudo yum remove coder
 ```

 ## Alpine

-```shell
+```sh
 sudo apk del coder
 ```

@@ -36,25 +36,25 @@ sudo apk del coder
 If you installed Coder manually or used the install script on an unsupported
 operating system, you can remove the binary directly:

-```shell
+```sh
 sudo rm /usr/local/bin/coder
 ```

 ## macOS

-```shell
+```sh
 brew uninstall coder
 ```

 If you installed Coder manually, you can remove the binary directly:

-```shell
+```sh
 sudo rm /usr/local/bin/coder
 ```

 ## Windows

-```powershell
+```ps1
 winget uninstall Coder.Coder
 ```

@@ -62,7 +62,7 @@ winget uninstall Coder.Coder

 ## Coder as a system service configuration

-```shell
+```sh
 sudo rm /etc/coder.d/coder.env
 ```

@@ -76,20 +76,20 @@ performing the following step or copying the directory to another location.

 ## Linux

-```shell
+```sh
 rm -rf ~/.config/coderv2
 rm -rf ~/.cache/coder
 ```

 ## macOS

-```shell
+```sh
 rm -rf ~/Library/Application\ Support/coderv2
 ```

 ## Windows

-```powershell
+```ps1
 rmdir %AppData%\coderv2
 ```

@@ -43,14 +43,14 @@ prevent the new pod from acquiring necessary locks.
     when the upgrade starts. This momentarily ensures no application access to
     the database, allowing migrations to acquire locks immediately:

-     ```shell
+     ```sh
     kubectl scale deployment coder --replicas=0
     ```

   - **Scale to one** if you prefer to minimize downtime. This keeps one pod
     running but eliminates contention from multiple replicas:

-     ```shell
+     ```sh
     kubectl scale deployment coder --replicas=1
     ```

@@ -82,7 +82,7 @@ killing the pod prematurely.
 To confirm whether Kubernetes is killing pods due to liveness probe failures,
 check the Kubernetes events and pod logs:

-```shell
+```sh
 # Check events for the Coder deployment
 kubectl get events --field-selector involvedObject.name=coder -n <namespace>

@@ -98,7 +98,7 @@ liveness probe, will be restarted`.
 If you have liveness probes enabled and experience issues during upgrades,
 disable them before upgrading:

-```shell
+```sh
 kubectl edit deployment coder
 ```

@@ -135,7 +135,7 @@ If an upgrade gets stuck in a restart loop due to database locks:
 1. **Scale to zero:** Scale the Coder deployment to 0 to stop all application
   activity.

-   ```shell
+   ```sh
   kubectl scale deployment coder --replicas=0
   ```

@@ -19,13 +19,13 @@ of [install](../install/index.md).
 1. If you installed Coder using the `install.sh` script, re-run the below command
   on the host:

-   ```shell
+   ```sh
   curl -L https://coder.com/install.sh | sh
   ```

 1. If you're running Coder as a system service, you can restart it with `systemctl`:

-   ```shell
+   ```sh
   systemctl daemon-reload
   systemctl restart coder
   ```
@@ -39,7 +39,7 @@ of [install](../install/index.md).
 If you installed using `docker-compose`, run the below command to upgrade the
 Coder container:

-```shell
+```sh
 docker-compose pull coder && docker-compose up -d coder
 ```

@@ -52,7 +52,7 @@ See

 1. Run the Coder installation script on the host:

-   ```shell
+   ```sh
   curl -L https://coder.com/install.sh | sh
   ```

@@ -61,7 +61,7 @@ See

 1. Restart the Coder system process with `systemctl`:

-   ```shell
+   ```sh
   systemctl daemon-reload
   systemctl restart coder
   ```
@@ -72,7 +72,7 @@ Download the latest Windows installer or binary from
 [GitHub releases](https://github.com/coder/coder/releases/latest), or upgrade
 from Winget.

-```pwsh
+```ps1
 winget install Coder.Coder
 ```