coder · EdwardAngert · Mar 10, 2025 · Mar 7, 2025 · Mar 7, 2025 · Mar 7, 2025
diff --git a/.vscode/markdown.code-snippets b/.vscode/markdown.code-snippets
@@ -1,14 +1,14 @@
 {
 	// For info about snippets, visit https://code.visualstudio.com/docs/editor/userdefinedsnippets
+    // https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
 
-    "admonition": {
-        "prefix": "#callout",
+	"alert": {
+        "prefix": "#alert",
         "body": [
-            "<blockquote class=\"admonition ${1|caution,important,note,tip,warning|}\">\n",
-            "${TM_SELECTED_TEXT:${2:add info here}}\n",
-            "</blockquote>\n"
+            "> [!${1|CAUTION,IMPORTANT,NOTE,TIP,WARNING|}]",
+            "> ${TM_SELECTED_TEXT:${2:add info here}}\n"
         ],
-        "description": "callout admonition caution info note tip warning"
+        "description": "callout admonition caution important note tip warning"
     },
 	"fenced code block": {
 		"prefix": "#codeblock",
@@ -23,9 +23,8 @@
 	"premium-feature": {
 		"prefix": "#premium-feature",
 		"body": [
-			"<blockquote class=\"info\">\n",
-			"${1:feature} ${2|is,are|} an Enterprise and Premium feature. [Learn more](https://coder.com/pricing#compare-plans).\n",
-			"</blockquote>"
+			"> [!NOTE]\n",
+			"> ${1:feature} ${2|is,are|} an Enterprise and Premium feature. [Learn more](https://coder.com/pricing#compare-plans).\n"
 		]
 	},
 	"tabs": {

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -117,9 +117,7 @@ This mode is useful for testing HA or validating more complex setups.
 
 ### Deploying a PR
 
-> You need to be a member or collaborator of the of
-> [coder](https://github.com/coder) GitHub organization to be able to deploy a
-> PR.
+You need to be a member or collaborator of the [coder](https://github.com/coder) GitHub organization to be able to deploy a PR.
 
 You can test your changes by creating a PR deployment. There are two ways to do
 this:
@@ -142,7 +140,8 @@ this:
   name and PR number, etc.
 - `-y` or `--yes`, will skip the CLI confirmation prompt.
 
-> Note: PR deployment will be re-deployed automatically when the PR is updated.
+> [!NOTE]
+> PR deployment will be re-deployed automatically when the PR is updated.
 > It will use the last values automatically for redeployment.
 
 Once the deployment is finished, a unique link and credentials will be posted in
@@ -256,8 +255,7 @@ Our frontend guide can be found [here](./contributing/frontend.md).
 
 ## Reviews
 
-> The following information has been borrowed from
-> [Go's review philosophy](https://go.dev/doc/contribute#reviews).
+The following information has been borrowed from [Go's review philosophy](https://go.dev/doc/contribute#reviews).
 
 Coder values thorough reviews. For each review comment that you receive, please
 "close" it by implementing the suggestion or providing an explanation on why the
@@ -345,6 +343,7 @@ Breaking changes can be triggered in two ways:
 
 ### Security
 
+> [!IMPORTANT]
 > If you find a vulnerability, **DO NOT FILE AN ISSUE**. Instead, send an email
 > to <security@coder.com>.
 

diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md
@@ -90,7 +90,8 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
 CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com/<TENANT ID>/oauth2/authorize"
 ```
 
-> Note: Your app registration in Entra ID requires the `vso.code_write` scope
+> [!NOTE]
+> Your app registration in Entra ID requires the `vso.code_write` scope
 
 ### Bitbucket Server
 
@@ -120,11 +121,8 @@ The Redirect URI for Gitea should be
 
 ### GitHub
 
-<blockquote class="admonition tip">
-
-If you don't require fine-grained access control, it's easier to [configure a GitHub OAuth app](#configure-a-github-oauth-app).
-
-</blockquote>
+> [!TIP]
+> If you don't require fine-grained access control, it's easier to [configure a GitHub OAuth app](#configure-a-github-oauth-app).
 
 ```env
 CODER_EXTERNAL_AUTH_0_ID="USER_DEFINED_ID"
@@ -179,7 +177,8 @@ CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info"
 CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org
 ```
 
-> Note: The `REGEX` variable must be set if using a custom git domain.
+> [!NOTE]
+> The `REGEX` variable must be set if using a custom git domain.
 
 ## Custom scopes
 
@@ -222,26 +221,16 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
 
    ![Install GitHub App](../images/admin/github-app-install.png)
 
-## Multiple External Providers
-
-<blockquote class="info">
-
-Multiple providers is an Enterprise and Premium feature.
-[Learn more](https://coder.com/pricing#compare-plans).
-
-</blockquote>
+## Multiple External Providers (Enterprise)(Premium)
 
 Below is an example configuration with multiple providers:
 
-<blockquote class="admonition warning">
-
-**Note:** To support regex matching for paths like `github\.com/org`, add the following `git config` line to the [Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
-
-```shell
-git config --global credential.useHttpPath true
-```
-
-</blockquote>
+> [!IMPORTANT]
+> To support regex matching for paths like `github\.com/org`, add the following `git config` line to the [Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
+>
+> ```shell
+> git config --global credential.useHttpPath true
+> ```
 
 ```env
 # Provider 1) github.com

diff --git a/docs/admin/infrastructure/scale-utility.md b/docs/admin/infrastructure/scale-utility.md
@@ -28,27 +28,25 @@ hardware sizing recommendations.
 | Kubernetes (GKE) | 4 cores   | 16 GB     | 2              | db-custom-8-30720 | 2000  | 50                | 2000 simulated                        | `v2.8.4`      | Feb 28, 2024 |
 | Kubernetes (GKE) | 2 cores   | 4 GB      | 2              | db-custom-2-7680  | 1000  | 50                | 1000 simulated                        | `v2.10.2`     | Apr 26, 2024 |
 
-> Note: A simulated connection reads and writes random data at 40KB/s per connection.
+> [!NOTE]
+> A simulated connection reads and writes random data at 40KB/s per connection.
 
 ## Scale testing utility
 
 Since Coder's performance is highly dependent on the templates and workflows you
 support, you may wish to use our internal scale testing utility against your own
 environments.
 
-<blockquote class="admonition important">
-
-This utility is experimental.
-
-It is not subject to any compatibility guarantees and may cause interruptions
-for your users.
-To avoid potential outages and orphaned resources, we recommend that you run
-scale tests on a secondary "staging" environment or a dedicated
-[Kubernetes playground cluster](https://github.com/coder/coder/tree/main/scaletest/terraform).
-
-Run it against a production environment at your own risk.
-
-</blockquote>
+> [!IMPORTANT]
+> This utility is experimental.
+>
+> It is not subject to any compatibility guarantees and may cause interruptions
+> for your users.
+> To avoid potential outages and orphaned resources, we recommend that you run
+> scale tests on a secondary "staging" environment or a dedicated
+> [Kubernetes playground cluster](https://github.com/coder/coder/tree/main/scaletest/terraform).
+>
+> Run it against a production environment at your own risk.
 
 ### Create workspaces
 

diff --git a/docs/admin/infrastructure/validated-architectures/index.md b/docs/admin/infrastructure/validated-architectures/index.md
@@ -36,9 +36,8 @@ cloud/on-premise computing, containerization, and the Coder platform.
 | Reference architectures for up to 3,000 users  | An approval of your architecture; the CVA solely provides recommendations and guidelines |
 | Best practices for building a Coder deployment | Recommendations for every possible deployment scenario                                   |
 
-> For higher level design principles and architectural best practices, see
-> Coder's
-> [Well-Architected Framework](https://coder.com/blog/coder-well-architected-framework).
+For higher level design principles and architectural best practices, see Coder's
+[Well-Architected Framework](https://coder.com/blog/coder-well-architected-framework).
 
 ## General concepts
 

diff --git a/docs/admin/integrations/jfrog-artifactory.md b/docs/admin/integrations/jfrog-artifactory.md
@@ -131,11 +131,8 @@ To set this up, follow these steps:
    }
    ```
 
-   <blockquote class="info">
-
-   The admin-level access token is used to provision user tokens and is never exposed to developers or stored in workspaces.
-
-   </blockquote>
+   > [!NOTE]
+   > The admin-level access token is used to provision user tokens and is never exposed to developers or stored in workspaces.
 
 If you don't want to use the official modules, you can read through the [example template](https://github.com/coder/coder/tree/main/examples/jfrog/docker), which uses Docker as the underlying compute. The
 same concepts apply to all compute types.

diff --git a/docs/admin/integrations/jfrog-xray.md b/docs/admin/integrations/jfrog-xray.md
@@ -56,14 +56,11 @@ workspaces using Coder's [JFrog Xray Integration](https://github.com/coder/coder
      --set artifactory.secretName="jfrog-token"
    ```
 
-   <blockquote class="admonition warning">
-
-   To authenticate with the Artifactory registry, you may need to
-   create a [Docker config](https://jfrog.com/help/r/jfrog-artifactory-documentation/docker-advanced-topics) and use it in the
-   `imagePullSecrets` field of the Kubernetes Pod. See the [Defining ImagePullSecrets for Coder workspaces](../../tutorials/image-pull-secret.md) guide for more
-   information.
-
-   </blockquote>
+> [!IMPORTANT]
+> To authenticate with the Artifactory registry, you may need to
+> create a [Docker config](https://jfrog.com/help/r/jfrog-artifactory-documentation/docker-advanced-topics) and use it in the
+> `imagePullSecrets` field of the Kubernetes Pod.
+> See the [Defining ImagePullSecrets for Coder workspaces](../../tutorials/image-pull-secret.md) guide for more information.
 
 ## Validate your installation
 

diff --git a/docs/admin/integrations/opentofu.md b/docs/admin/integrations/opentofu.md
@@ -2,17 +2,17 @@
 
 <!-- Keeping this in as a placeholder for supporting OpenTofu. We should fix support for custom terraform binaries ASAP. -->
 
-> ⚠️ This guide is a work in progress. We do not officially support using custom
+> [!IMPORTANT]
+> This guide is a work in progress. We do not officially support using custom
 > Terraform binaries in your Coder deployment. To track progress on the work,
 > see this related [GitHub Issue](https://github.com/coder/coder/issues/12009).
 
 Coder deployments support any custom Terraform binary, including
 [OpenTofu](https://opentofu.org/docs/) - an open source alternative to
 Terraform.
 
-> You can read more about OpenTofu and Hashicorp's licensing in our
-> [blog post](https://coder.com/blog/hashicorp-license) on the Terraform
-> licensing changes.
+You can read more about OpenTofu and Hashicorp's licensing in our
+[blog post](https://coder.com/blog/hashicorp-license) on the Terraform licensing changes.
 
 ## Using a custom Terraform binary
 

diff --git a/docs/admin/licensing/index.md b/docs/admin/licensing/index.md
@@ -7,8 +7,7 @@ features, you can [request a trial](https://coder.com/trial) or
 
 <!-- markdown-link-check-disable -->
 
-> If you are an existing customer, you can learn more our new Premium plan in
-> the [Coder v2.16 blog post](https://coder.com/blog/release-recap-2-16-0)
+You can learn more about Coder Premium in the [Coder v2.16 blog post](https://coder.com/blog/release-recap-2-16-0)
 
 <!-- markdown-link-check-enable -->
 

diff --git a/docs/admin/monitoring/health-check.md b/docs/admin/monitoring/health-check.md
@@ -40,7 +40,7 @@ If there is an issue, you may see one of the following errors reported:
 [`url.Parse`](https://pkg.go.dev/net/url#Parse). Example:
 `https://dev.coder.com/`.
 
-> **Tip:** You can check this [here](https://go.dev/play/p/CabcJZyTwt9).
+You can use [the Go playground](https://go.dev/play/p/CabcJZyTwt9) for additional testing.
 
 ### EACS03
 
@@ -117,15 +117,12 @@ Coder's current activity and usage. It may be necessary to increase the
 resources allocated to Coder's database. Alternatively, you can raise the
 configured threshold to a higher value (this will not address the root cause).
 
-<blockquote class="admonition tip">
-
-You can enable
-[detailed database metrics](../../reference/cli/server.md#--prometheus-collect-db-metrics)
-in Coder's Prometheus endpoint. If you have
-[tracing enabled](../../reference/cli/server.md#--trace), these traces may also
-contain useful information regarding Coder's database activity.
-
-</blockquote>
+> [!TIP]
+> You can enable
+> [detailed database metrics](../../reference/cli/server.md#--prometheus-collect-db-metrics)
+> in Coder's Prometheus endpoint. If you have
+> [tracing enabled](../../reference/cli/server.md#--trace), these traces may also
+> contain useful information regarding Coder's database activity.
 
 ## DERP
 
@@ -150,12 +147,9 @@ This is not necessarily a fatal error, but a possible indication of a
 misconfigured reverse HTTP proxy. Additionally, while workspace users should
 still be able to reach their workspaces, connection performance may be degraded.
 
-<blockquote class="admonition note">
-
-**Note:** This may also be shown if you have
-[forced websocket connections for DERP](../../reference/cli/server.md#--derp-force-websockets).
-
-</blockquote>
+> [!NOTE]
+> This may also be shown if you have
+> [forced websocket connections for DERP](../../reference/cli/server.md#--derp-force-websockets).
 
 **Solution:** ensure that any proxies you use allow connection upgrade with the
 `Upgrade: derp` header.
@@ -305,13 +299,10 @@ that they are able to successfully connect to Coder. Otherwise, ensure
 [`--provisioner-daemons`](../../reference/cli/server.md#--provisioner-daemons)
 is set to a value greater than 0.
 
-<blockquote class="admonition note">
-
-**Note:** This may be a transient issue if you are currently in the process of
+> [!NOTE]
+> This may be a transient issue if you are currently in the process of
 updating your deployment.
 
-</blockquote>
-
 ### EPD02
 
 #### Provisioner Daemon Version Mismatch
@@ -324,13 +315,10 @@ of API incompatibility.
 **Solution:** Update the provisioner daemon to match the currently running
 version of Coder.
 
-<blockquote class="admonition note">
-
-**Note:** This may be a transient issue if you are currently in the process of
+> [!NOTE]
+> This may be a transient issue if you are currently in the process of
 updating your deployment.
 
-</blockquote>
-
 ### EPD03
 
 #### Provisioner Daemon API Version Mismatch
@@ -343,13 +331,10 @@ connect to Coder.
 **Solution:** Update the provisioner daemon to match the currently running
 version of Coder.
 
-<blockquote class="admonition note">
-
-**Note:** This may be a transient issue if you are currently in the process of
+> [!NOTE]
+> This may be a transient issue if you are currently in the process of
 updating your deployment.
 
-</blockquote>
-
 ### EUNKNOWN
 
 #### Unknown Error

diff --git a/docs/admin/monitoring/logs.md b/docs/admin/monitoring/logs.md
@@ -43,7 +43,8 @@ Agent logs are also stored in the workspace filesystem by default:
   [azure-windows](https://github.com/coder/coder/blob/2cfadad023cb7f4f85710cff0b21ac46bdb5a845/examples/templates/azure-windows/Initialize.ps1.tftpl#L64))
   to see where logs are stored.
 
-> Note: Logs are truncated once they reach 5MB in size.
+> [!NOTE]
+> Logs are truncated once they reach 5MB in size.
 
 Startup script logs are also stored in the temporary directory of macOS and
 Linux workspaces.

diff --git a/docs/admin/monitoring/notifications/index.md b/docs/admin/monitoring/notifications/index.md
@@ -242,12 +242,9 @@ notification is indicated on the right hand side of this table.
 
 ## Delivery Preferences
 
-<blockquote class="info">
-
-Delivery preferences is an Enterprise and Premium feature.
-[Learn more](https://coder.com/pricing#compare-plans).
-
-</blockquote>
+> [!NOTE]
+> Delivery preferences is an Enterprise and Premium feature.
+> [Learn more](https://coder.com/pricing#compare-plans).
 
 Administrators can configure which delivery methods are used for each different
 [event type](#event-types).

diff --git a/docs/admin/monitoring/notifications/slack.md b/docs/admin/monitoring/notifications/slack.md
@@ -181,12 +181,11 @@ To build the server to receive webhooks and interact with Slack:
 Slack requires the bot to acknowledge when a user clicks on a URL action button.
 This is handled by setting up interactivity.
 
-1. Under "Interactivity & Shortcuts" in your Slack app settings, set the Request
-   URL to match the public URL of your web server's endpoint.
+Under "Interactivity & Shortcuts" in your Slack app settings, set the Request
+URL to match the public URL of your web server's endpoint.
 
-> Notice: You can use any public endpoint that accepts and responds to POST
-> requests with HTTP 200. For temporary testing, you can set it to
-> `https://httpbin.org/status/200`.
+You can use any public endpoint that accepts and responds to POST requests with HTTP 200.
+For temporary testing, you can set it to `https://httpbin.org/status/200`.
 
 Once this is set, Slack will send interaction payloads to your server, which
 must respond appropriately.