coder · nickvigilante · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026
diff --git a/docs/.style/style-guide/accessibility-and-inclusion.md b/docs/.style/style-guide/accessibility-and-inclusion.md
@@ -24,7 +24,7 @@ Skipping a level breaks the outline.
 
 **Do**:
 
-```markdown
+```md
 # Configure your workspace
 
 This page walks through the configuration options exposed on a Coder workspace.
@@ -52,7 +52,7 @@ Define them in the template or in the workspace's parameters.
 
 **Don't**:
 
-```markdown
+```md
 # Configure your workspace
 
 # Configure your environment
@@ -129,7 +129,7 @@ Captions follow the image in a `<small>` tag.
 Aim for one or two sentences that convey the same information a sighted reader would extract from the image.
 Lead with the subject, not "An image of" or "A screenshot showing".
 
-```markdown
+```md
 ![Template Insights dashboard with weekly active users and connection latency charts](../../images/admin/templates/template-insights.png)
 
 <small>The Template Insights dashboard with active-user and connection-latency widgets.</small>
@@ -144,7 +144,7 @@ For complex diagrams that can't be summarized in alt text, provide a longer desc
 Mark images that carry no information beyond visual decoration with empty alt text.
 Empty alt text tells the screen reader to skip the image rather than announce a meaningless filename.
 
-```markdown
+```md
 ![](../../images/decorative/divider.png)
 ```
 

diff --git a/docs/.style/style-guide/audience-and-scope.md b/docs/.style/style-guide/audience-and-scope.md
@@ -29,7 +29,7 @@ Section tags don't save readers from scanning content that doesn't apply to them
 
 **Do**:
 
-```markdown
+```md
 # Connect Visual Studio Code to your Coder workspace
 
 *Audience: a developer with an existing Coder workspace.*
@@ -41,7 +41,7 @@ For Windsurf, refer to [Windsurf](./windsurf.md).
 
 **Don't**:
 
-```markdown
+```md
 # Connect to your Coder workspace
 
 This page covers Visual Studio Code, Cursor, Windsurf, JetBrains, Vim, the web terminal, and SSH.
@@ -66,7 +66,7 @@ A page that helps the reader accomplish two unrelated outcomes hides each outcom
 
 **Do**:
 
-```markdown
+```md
 # Configure single sign-on with Okta
 
 This page walks through configuring OIDC single sign-on against an Okta tenant.
@@ -76,7 +76,7 @@ For Google Workspace, refer to [Configure SSO with Google Workspace](./sso-googl
 
 **Don't**:
 
-```markdown
+```md
 # Authentication
 
 This page covers OIDC providers (Okta, Azure AD, Google Workspace, generic OIDC),
@@ -100,7 +100,7 @@ A hub page is appropriate when:
 
 **Do**:
 
-```markdown
+```md
 # Authentication
 
 This page is the entry point for configuring authentication in Coder.
@@ -114,7 +114,7 @@ Pick the provider that matches your identity source:
 
 **Don't**:
 
-```markdown
+```md
 # Authentication
 
 This page covers OIDC, SAML, GitHub OAuth, password authentication, and the API token model.
@@ -153,7 +153,7 @@ Name the audience by the role the reader recognizes from their own work (`develo
 
 **Do**:
 
-```markdown
+```md
 # Connect Visual Studio Code to your Coder workspace
 
 This guide is for a developer with an existing Coder workspace.
@@ -164,7 +164,7 @@ For Windsurf, refer to [Windsurf](./windsurf.md).
 
 **Don't**:
 
-```markdown
+```md
 # Kubernetes
 
 Coder runs on Kubernetes.
@@ -185,7 +185,7 @@ For pages of that kind, add an `IMPORTANT` callout at the beginning of the page
 
 **Do**:
 
-```markdown
+```md
 # Configure single sign-on with Okta
 
 This guide is for a Coder deployment administrator

diff --git a/docs/.style/style-guide/capitalization-and-punctuation.md b/docs/.style/style-guide/capitalization-and-punctuation.md
@@ -13,15 +13,15 @@ This rule covers H1 through H6 and matches the way the heading reads aloud.
 
 **Do**:
 
-```markdown
+```md
 # Configure your workspace
 ## Set up SSH access
 ### Connect through JetBrains Toolbox
 ```
 
 **Don't**:
 
-```markdown
+```md
 # Configure Your Workspace
 ## Set Up SSH Access
 ### Connect Through JetBrains Toolbox
@@ -38,7 +38,7 @@ Reserve gerund-leading headings for the rare case where neither alternative read
 
 **Do**:
 
-```markdown
+```md
 ## Install Coder
 ## Installation
 ## Configure your workspace
@@ -47,7 +47,7 @@ Reserve gerund-leading headings for the rare case where neither alternative read
 
 **Don't**:
 
-```markdown
+```md
 ## Installing Coder
 ## Configuring your workspace
 ```
@@ -80,7 +80,7 @@ The rule has scoped exceptions:
 
 **Do**:
 
-```markdown
+```md
 ## What's a workspace
 ## Quick reference
 ## What does the `panic!` macro do?
@@ -89,7 +89,7 @@ The rule has scoped exceptions:
 
 **Don't**:
 
-```markdown
+```md
 ## What's a workspace?
 ## Quick reference!
 ## Workspaces are great!

diff --git a/docs/.style/style-guide/formatting.md b/docs/.style/style-guide/formatting.md
@@ -136,27 +136,44 @@ Use the most specific language tag available:
   Use `sh` when the block is input the reader types or a script they save, and the block doesn't also show output.
 - `console` for an interactive session that shows the typed command and its output together.
   Prefix each typed line with `$`.
-- `powershell` for Windows command-line blocks.
+- `ps1` for Windows command-line blocks.
   PowerShell is the default Windows shell in the Coder docs.
+  `pwsh` and `powershell` are not the canonical tag; use `ps1`.
+  `ps1` is Shiki's PowerShell alias, and it's also GitHub's `.ps1` file extension, which its markdown renderer falls back to when a fence label isn't a recognized language name; `ps` isn't registered either way and won't highlight on GitHub today.
 - `tf` for Terraform and HCL.
+  `terraform` and `hcl` are not the canonical tag; use `tf`.
+  Shiki ships `terraform` and `hcl` as two distinct grammars; `tf` is an alias of the more specific `terraform` grammar (not `hcl`), and matches what nearly every Coder docs code block actually is.
 - `yaml` for YAML.
+  `yml` is not the canonical tag; use `yaml`.
 - `go` for Go.
 - `json` for JSON.
-- `text` for command output shown on its own, and for any block with no syntax to highlight.
+  `jsonc` is a distinct Shiki grammar for JSON that permits comments; use it only for blocks that actually contain comments, otherwise use `json`.
+- `dotenv` for `.env`-style `KEY=VALUE` blocks.
+- `txt` for command output shown on its own, and for any block with no syntax to highlight.
+  `text`, `output`, `none`, and `url` are not the canonical tag; use `txt`.
+- `dockerfile` for Dockerfiles, lowercase.
+  `Dockerfile` (capitalized) is not a valid tag.
+- `md` for Markdown, including Markdown shown as a fenced example inside another Markdown file.
+  `markdown` is not the canonical tag; use `md`.
+- `tsx` for TypeScript, including plain (non-JSX) TypeScript.
+  `ts` and `typescript` are not the canonical tag; use `tsx`.
+  `tsx` mis-tokenizes the legacy angle-bracket type-assertion syntax (`<Type>value`), which is invalid in real `.tsx` files anyway; write casts as `value as Type` instead, which is unambiguous under both grammars and is already the idiomatic style.
 
 `bash` and `shell` are aliases of `sh`.
 Use `sh` so the corpus stays consistent.
 
 A command with no output shown is `sh`, not `console`.
-To show a command together with its output, either use one `console` block with `$` before the typed line, or split the command into an `sh` block and the output into a `text` block.
+To show a command together with its output, either use one `console` block with `$` before the typed line, or split the command into an `sh` block and the output into a `txt` block.
 
 The auto-generated Coder CLI reference under `docs/reference/cli/` labels its command-usage blocks `console`.
 That output is generated.
 Do not copy the pattern into hand-written pages.
 
 The docs site highlights code with [Speed-Highlight](https://github.com/speed-highlight/core), which detects the language from the code content, not from the fence label.
 The fence label still drives highlighting on GitHub and in most editors, and `markdownlint` rule `MD040` requires one, so always declare the most specific language.
-For content with no sensible language tag, fall back to `text`.
+A future docs renderer may adopt [Shiki](https://shiki.style), which fails the build on a fence label it doesn't recognize as a language or alias, so use only tags Shiki supports.
+For content with no sensible language tag, fall back to `txt`.
+A fence label needing a grammar Shiki doesn't bundle (for example `promql` or `caddyfile`) stays as-is; register it as a custom grammar when the site adopts Shiki, rather than degrading it to `txt`.
 
 **Do**:
 
@@ -233,7 +250,7 @@ curl -L https://coder.com/install.sh | sh
 
 ### Windows
 
-```powershell
+```ps1
 winget install Coder.Coder
 ```
 
@@ -266,21 +283,21 @@ If one item is a complete sentence, rewrite the rest so every item is a complete
 
 **Do**:
 
-```markdown
+```md
 1. Run `coder login` to authenticate.
 2. Create the workspace template.
 3. Build the workspace from the template.
 ```
 
-```markdown
+```md
 The provisioner supports:
 
 - AWS
 - Azure
 - Google Cloud
 ```
 
-```markdown
+```md
 The agent reconnect logic uses the following timeouts:
 
 - Initial reconnect: 1 second.
@@ -290,13 +307,13 @@ The agent reconnect logic uses the following timeouts:
 
 **Don't**:
 
-```markdown
+```md
 1. The user runs `coder login` to authenticate
 2. Creating the workspace template comes next.
 3. Then the workspace gets built from the template
 ```
 
-```markdown
+```md
 The provisioner supports:
 
 - AWS.
@@ -312,14 +329,14 @@ When such a list needs a lead-in, end the lead-in with a colon on a clause that
 
 **Do**:
 
-```markdown
+```md
 You have two options:
 
 - Install the tool with `apt-get` in the template's startup script.
 - Bake the tool into the workspace image.
 ```
 
-```markdown
+```md
 ## Learn more
 
 - [Extending templates](./extending-templates.md)
@@ -328,7 +345,7 @@ You have two options:
 
 **Don't**:
 
-```markdown
+```md
 Install it where it persists across rebuilds:
 
 - Add it to the template's startup script with `apt-get`.
@@ -383,7 +400,7 @@ Reference the asset with a relative path from the Markdown source.
 
 Captions follow the image in a `<small>` tag.
 
-```markdown
+```md
 ![Template Insights dashboard with weekly active users and connection latency charts](../../images/admin/templates/template-insights.png)
 
 <small>The Template Insights dashboard with active-user and connection-latency widgets.</small>

diff --git a/docs/.style/style-guide/numbers-units-and-dates.md b/docs/.style/style-guide/numbers-units-and-dates.md
@@ -45,7 +45,7 @@ The visible result is the same as a regular space, but the line breaker treats t
 
 In the Markdown source (what you type):
 
-```markdown
+```md
 The default timeout is 30&nbsp;seconds.
 Connection latency under 150&nbsp;ms shows green.
 ```
@@ -64,7 +64,7 @@ The number and the unit move to the next line together rather than separating.
 
 In the Markdown source:
 
-```markdown
+```md
 The default timeout is 30 seconds.
 Connection latency under 150ms shows green.
 ```

diff --git a/docs/.style/style-guide/word-choice.md b/docs/.style/style-guide/word-choice.md
@@ -51,7 +51,7 @@

 | Do                                  | Don't                                 |
 |-------------------------------------|---------------------------------------|
 | HashiCorp                           | Hashicorp, HASHICORP                  |
 | GitHub                              | Github, GITHUB                        |
 | OpenTofu                            | Opentofu, OpenTOFU                    |
 | Kubernetes                          | kubernetes (in prose), K8s (in prose) |
@@ -200,7 +200,7 @@
 
 **Do**:
 
-```markdown
+```md
 ## Learn more
 
 - [Configure SSH access](./ssh.md)
@@ -209,7 +209,7 @@
 
 **Don't**:
 
-```markdown
+```md
 ## Next steps
 
 - [Configure SSH access](./ssh.md)

diff --git a/docs/about/contributing/CONTRIBUTING.md b/docs/about/contributing/CONTRIBUTING.md
@@ -14,7 +14,7 @@ Learn more [how Nix works](https://nixos.org/guides/how-nix-works).
 1. After you've installed Nix, instantiate the development with the `nix-shell`
    command:
 
-   ```shell
+   ```sh
    cd ~/code/coder
 
    # https://nix.dev/tutorials/declarative-and-reproducible-developer-environments
@@ -31,7 +31,7 @@ Learn more [how Nix works](https://nixos.org/guides/how-nix-works).
    [hooks configured](https://direnv.net/docs/hook.html), you can add `use nix`
    to `.envrc` to automatically instantiate the development environment:
 
-   ```shell
+   ```sh
    cd ~/code/coder
    echo "use nix" >.envrc
    direnv allow
@@ -41,7 +41,7 @@ Learn more [how Nix works](https://nixos.org/guides/how-nix-works).
    [`direnv`](https://direnv.net/docs/hook.html) will prepare the environment
    for you:
 
-   ```shell
+   ```sh
    cd ~/code/coder
 
    direnv: loading ~/code/coder/.envrc
@@ -232,7 +232,7 @@ RC tags can be created from `main` or from a release branch. The
 `create-release-branch` type creates `release/X.Y` and tags the next RC in one
 step, continuing the RC numbering sequence.
 
-```text
+```txt
 main:  --*--*--*--*--*--*--*--*--*--
               |  rc.0   rc.1  |
               |               +--- create-release-branch ---+
@@ -358,7 +358,7 @@ If `./scripts/develop.sh` exits with a "database migration conflict" error,
 it means the database has migrations from another branch that don't exist
 on the current one. You have two options:
 
-```shell
+```sh
 # Roll back the mismatched migrations (preserves your dev data):
 ./scripts/develop.sh --db-rollback
 
@@ -373,7 +373,7 @@ On macOS, a [direnv bug](https://github.com/direnv/direnv/issues/1345) can cause
 `error: creating directory` when you attempt to run, build, or test, add a
 `mkdir` line to your `.envrc`:
 
-```shell
+```sh
 use nix
 mkdir -p "$TMPDIR"
 ```