more > Note

coder · EdwardAngert · Mar 10, 2025 · Mar 7, 2025 · Mar 7, 2025 · Mar 7, 2025
commit 0dab25c5013ad0ca45e39617945ae55421e32538
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -142,7 +142,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

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
 
@@ -176,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
 

diff --git a/docs/admin/infrastructure/scale-utility.md b/docs/admin/infrastructure/scale-utility.md
@@ -28,7 +28,8 @@ 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
 

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/networking/index.md b/docs/admin/networking/index.md
@@ -18,7 +18,8 @@ networking logic.
 
 In order for clients and workspaces to be able to connect:
 
-> **Note:** We strongly recommend that clients connect to Coder and their
+> [!NOTE]
+> We strongly recommend that clients connect to Coder and their
 > workspaces over a good quality, broadband network connection. The following
 > are minimum requirements:
 >
@@ -33,7 +34,8 @@ In order for clients and workspaces to be able to connect:
 
 In order for clients to be able to establish direct connections:
 
-> **Note:** Direct connections via the web browser are not supported. To improve
+> [!NOTE]
+> Direct connections via the web browser are not supported. To improve
 > latency for browser-based applications running inside Coder workspaces in
 > regions far from the Coder control plane, consider deploying one or more
 > [workspace proxies](./workspace-proxies.md).

diff --git a/docs/admin/networking/stun.md b/docs/admin/networking/stun.md
@@ -1,13 +1,13 @@
 # STUN and NAT
 
-> [Session Traversal Utilities for NAT (STUN)](https://www.rfc-editor.org/rfc/rfc8489.html)
-> is a protocol used to assist applications in establishing peer-to-peer
-> communications across Network Address Translations (NATs) or firewalls.
->
-> [Network Address Translation (NAT)](https://en.wikipedia.org/wiki/Network_address_translation)
-> is commonly used in private networks to allow multiple devices to share a
-> single public IP address. The vast majority of home and corporate internet
-> connections use at least one level of NAT.
+[Session Traversal Utilities for NAT (STUN)](https://www.rfc-editor.org/rfc/rfc8489.html)
+is a protocol used to assist applications in establishing peer-to-peer
+communications across Network Address Translations (NATs) or firewalls.
+
+[Network Address Translation (NAT)](https://en.wikipedia.org/wiki/Network_address_translation)
+is commonly used in private networks to allow multiple devices to share a
+single public IP address. The vast majority of home and corporate internet
+connections use at least one level of NAT.
 
 ## Overview
 
@@ -33,8 +33,9 @@ counterpart can be reached. Once communication succeeds in one direction, we can
 inspect the source address of the received packet to determine the return
 address.
 
-> The below glosses over a lot of the complexity of traversing NATs. For a more
-> in-depth technical explanation, see
+> [!TIP]
+> The below glosses over a lot of the complexity of traversing NATs.
+> For a more in-depth technical explanation, see
 > [How NAT traversal works (tailscale.com)](https://tailscale.com/blog/how-nat-traversal-works).
 
 At a high level, STUN works like this:

diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md
@@ -226,7 +226,8 @@ This is illustrated in the below table:
 | scope=user owner=aaa environment=on-prem datacenter=chicago       | scope=user owner=aaa environment=on-prem datacenter=new_york     | ✅        | ❌            |
 | scope=organization owner= environment=on-prem                     | scope=organization owner= environment=on-prem                    | ❌        | ❌            |
 
-> **Note to maintainers:** to generate this table, run the following command and
+> [!TIP]
+> To generate this table, run the following command and
 > copy the output:
 >
 > ```go

diff --git a/docs/admin/security/database-encryption.md b/docs/admin/security/database-encryption.md
@@ -43,7 +43,8 @@ Additional database fields may be encrypted in the future.
 
 ## Enabling encryption
 
-> NOTE: Enabling encryption does not encrypt all existing data. To encrypt
+> [!NOTE]
+> Enabling encryption does not encrypt all existing data. To encrypt
 > existing data, see [rotating keys](#rotating-keys) below.
 
 - Ensure you have a valid backup of your database. **Do not skip this step.** If
@@ -115,7 +116,8 @@ data:
   This command will re-encrypt all tokens with the specified new encryption key.
   We recommend performing this action during a maintenance window.
 
-  > Note: this command requires direct access to the database. If you are using
+  > [!NOTE]
+  > this command requires direct access to the database. If you are using
   > the built-in PostgreSQL database, you can run
   > [`coder server postgres-builtin-url`](../../reference/cli/server_postgres-builtin-url.md)
   > to get the connection URL.
@@ -138,7 +140,8 @@ To disable encryption, perform the following actions:
   This command will decrypt all encrypted user tokens and revoke all active
   encryption keys.
 
-  > Note: for `decrypt` command, the equivalent environment variable for
+  > [!NOTE]
+  > for `decrypt` command, the equivalent environment variable for
   > `--keys` is `CODER_EXTERNAL_TOKEN_ENCRYPTION_DECRYPT_KEYS` and not
   > `CODER_EXTERNAL_TOKEN_ENCRYPTION_KEYS`. This is explicitly named differently
   > to help prevent accidentally decrypting data.
@@ -152,7 +155,8 @@ To disable encryption, perform the following actions:
 
 ## Deleting Encrypted Data
 
-> NOTE: This is a destructive operation.
+> [!CAUTION]
+> This is a destructive operation.
 
 To delete all encrypted data from your database, perform the following actions:
 

diff --git a/docs/admin/security/secrets.md b/docs/admin/security/secrets.md
@@ -38,7 +38,8 @@ Users can view their public key in their account settings:
 
 ![SSH keys in account settings](../../images/ssh-keys.png)
 
-> Note: SSH keys are never stored in Coder workspaces, and are fetched only when
+> [!NOTE]
+> SSH keys are never stored in Coder workspaces, and are fetched only when
 > SSH is invoked. The keys are held in-memory and never written to disk.
 
 ## Dynamic Secrets

diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md
@@ -44,7 +44,8 @@ coder server
 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`).
 
-> Note: We do not recommend using a top-level-domain for Coder wildcard access
+> [!NOTE]
+> We do not recommend using a top-level-domain for Coder wildcard access
 > (for example `*.workspaces`), even on private networks with split-DNS. Some
 > browsers consider these "public" domains and will refuse Coder's cookies,
 > which are vital to the proper operation of this feature.

diff --git a/docs/admin/templates/extending-templates/index.md b/docs/admin/templates/extending-templates/index.md
@@ -49,8 +49,7 @@ Persistent resources stay provisioned when workspaces are stopped, where as
 ephemeral resources are destroyed and recreated on restart. All resources are
 destroyed when a workspace is deleted.
 
-> You can read more about how resource behavior and workspace state in the
-> [workspace lifecycle documentation](../../../user-guides/workspace-lifecycle.md).
+You can read more about how resource behavior and workspace state in the [workspace lifecycle documentation](../../../user-guides/workspace-lifecycle.md).
 
 Template resources follow the
 [behavior of Terraform resources](https://developer.hashicorp.com/terraform/language/resources/behavior#how-terraform-applies-a-configuration)
@@ -65,6 +64,7 @@ When a workspace is deleted, the Coder server essentially runs a
 [terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all
 resources associated with the workspace.
 
+> [!TIP]
 > Terraform's
 > [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy)
 > and

diff --git a/docs/admin/templates/extending-templates/process-logging.md b/docs/admin/templates/extending-templates/process-logging.md
@@ -3,7 +3,8 @@
 The workspace process logging feature allows you to log all system-level
 processes executing in the workspace.
 
-> **Note:** This feature is only available on Linux in Kubernetes. There are
+> [!NOTE]
+> This feature is only available on Linux in Kubernetes. There are
 > additional requirements outlined further in this document.
 
 Workspace process logging adds a sidecar container to workspace pods that will
@@ -164,7 +165,8 @@ would like to add workspace process logging to, follow these steps:
    }
    ```
 
-   > **Note:** If you are using the `envbox` template, you will need to update
+   > [!NOTE]
+   > If you are using the `envbox` template, you will need to update
    > the third argument to be
    > `"${local.exectrace_init_script}\n\nexec /envbox docker"` instead.
 
@@ -212,7 +214,8 @@ would like to add workspace process logging to, follow these steps:
    }
    ```
 
-   > **Note:** `exectrace` requires root privileges and a privileged container
+   > [!NOTE]
+   > `exectrace` requires root privileges and a privileged container
    > to attach probes to the kernel. This is a requirement of eBPF.
 
 1. Add the following environment variable to your workspace pod:

diff --git a/docs/admin/templates/extending-templates/workspace-tags.md b/docs/admin/templates/extending-templates/workspace-tags.md
@@ -71,7 +71,8 @@ added that can handle its combination of tags.
 Before releasing the template version with configurable workspace tags, ensure
 that every tag set is associated with at least one healthy provisioner.
 
-> **Note:** It may be useful to run at least one provisioner with no additional
+> [!NOTE]
+> It may be useful to run at least one provisioner with no additional
 > tag restrictions that is able to take on any job.
 
 ### Parameters types

diff --git a/docs/admin/templates/managing-templates/dependencies.md b/docs/admin/templates/managing-templates/dependencies.md
@@ -94,7 +94,8 @@ directory. When you next run
 [`coder templates push`](../../../reference/cli/templates_push.md), the lock
 file will be stored alongside with the other template source code.
 
-> Note: Terraform best practices also recommend checking in your
+> [!NOTE]
+> Terraform best practices also recommend checking in your
 > `.terraform.lock.hcl` into Git or other VCS.
 
 The next time a workspace is built from that template, Coder will make sure to

diff --git a/docs/admin/templates/managing-templates/image-management.md b/docs/admin/templates/managing-templates/image-management.md
@@ -11,9 +11,9 @@ practices around managing workspaces images for Coder.
 3. Allow developers to bring their own images and customizations with Dev
    Containers
 
-> Note: An image is just one of the many properties defined within the template.
-> Templates can pull images from a public image registry (e.g. Docker Hub) or an
-> internal one, thanks to Terraform.
+An image is just one of the many properties defined within the template.
+Templates can pull images from a public image registry (e.g. Docker Hub) or an
+internal one, thanks to Terraform.
 
 ## Create a minimal base image
 

diff --git a/docs/admin/templates/open-in-coder.md b/docs/admin/templates/open-in-coder.md
@@ -46,7 +46,8 @@ resource "coder_agent" "dev" {
 }
 ```
 
-> Note: The `dir` attribute can be set in multiple ways, for example:
+> [!NOTE]
+> The `dir` attribute can be set in multiple ways, for example:
 >
 > - `~/coder`
 > - `/home/coder/coder`

diff --git a/docs/admin/templates/troubleshooting.md b/docs/admin/templates/troubleshooting.md
@@ -144,15 +144,17 @@ if [ $status -ne 0 ]; then
 fi
 ```
 
-> **Note:** We don't use `set -x` here because we're manually echoing the
+> [!NOTE]
+> We don't use `set -x` here because we're manually echoing the
 > commands. This protects against sensitive information being shown in the log.
 
 This script tells us what command is being run and what the exit status is. If
 the exit status is non-zero, it means the command failed and we exit the script.
 Since we are manually checking the exit status here, we don't need `set -e` at
 the top of the script to exit on error.
 
-> **Note:** If you aren't seeing any logs, check that the `dir` directive points
+> [!NOTE]
+> If you aren't seeing any logs, check that the `dir` directive points
 > to a valid directory in the file system.
 
 ## Slow workspace startup times

diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md
@@ -47,12 +47,12 @@ GitHub will ask you for the following Coder parameters:
   `https://coder.domain.com`)
 - **User Authorization Callback URL**: Set to `https://coder.domain.com`
 
-> Note: If you want to allow multiple coder deployments hosted on subdomains
-> e.g. coder1.domain.com, coder2.domain.com, to be able to authenticate with the
-> same GitHub OAuth app, then you can set **User Authorization Callback URL** to
-> the `https://domain.com`
+If you want to allow multiple Coder deployments hosted on subdomains, such as
+`coder1.domain.com`, `coder2.domain.com`, to authenticate with the
+same GitHub OAuth app, then you can set **User Authorization Callback URL** to
+the `https://domain.com`
 
-Note the Client ID and Client Secret generated by GitHub. You will use these
+Take note of the Client ID and Client Secret generated by GitHub. You will use these
 values in the next step.
 
 Coder will need permission to access user email addresses. Find the "Account
@@ -67,8 +67,8 @@ server:
 coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
 ```
 
-> For GitHub Enterprise support, specify the
-> `--oauth2-github-enterprise-base-url` flag.
+> [!NOTE]
+> For GitHub Enterprise support, specify the `--oauth2-github-enterprise-base-url` flag.
 
 Alternatively, if you are running Coder as a system service, you can achieve the
 same result as the command above by adding the following environment variables
@@ -81,11 +81,12 @@ CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
 CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
 ```
 
-**Note:** To allow everyone to signup using GitHub, set:
-
-```env
-CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
-```
+> [!NOTE]
+> To allow everyone to sign up using GitHub, set:
+>
+> ```env
+> CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
+> ```
 
 Once complete, run `sudo service coder restart` to reboot Coder.
 

diff --git a/docs/admin/users/idp-sync.md b/docs/admin/users/idp-sync.md
@@ -521,7 +521,8 @@ Below are some details specific to individual OIDC providers.
 
 ### Active Directory Federation Services (ADFS)
 
-> **Note:** Tested on ADFS 4.0, Windows Server 2019
+> [!NOTE]
+> Tested on ADFS 4.0, Windows Server 2019
 
 1. In your Federation Server, create a new application group for Coder.
    Follow the steps as described in the [Windows Server documentation]

diff --git a/docs/admin/users/oidc-auth.md b/docs/admin/users/oidc-auth.md
@@ -32,7 +32,8 @@ signing in via OIDC as a new user. Coder will log the claim fields returned by
 the upstream identity provider in a message containing the string
 `got oidc claims`, as well as the user info returned.
 
-> **Note:** If you need to ensure that Coder only uses information from the ID
+> [!NOTE]
+> If you need to ensure that Coder only uses information from the ID
 > token and does not hit the UserInfo endpoint, you can set the configuration
 > option `CODER_OIDC_IGNORE_USERINFO=true`.
 
@@ -44,7 +45,8 @@ for the newly created user's email address.
 If your upstream identity provider users a different claim, you can set
 `CODER_OIDC_EMAIL_FIELD` to the desired claim.
 
-> **Note** If this field is not present, Coder will attempt to use the claim
+> [!NOTE]
+> If this field is not present, Coder will attempt to use the claim
 > field configured for `username` as an email address. If this field is not a
 > valid email address, OIDC logins will fail.
 
@@ -59,7 +61,8 @@ disable this behavior with the following setting:
 CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
 ```
 
-> **Note:** This will cause Coder to implicitly treat all OIDC emails as
+> [!NOTE]
+> This will cause Coder to implicitly treat all OIDC emails as
 > "verified", regardless of what the upstream identity provider says.
 
 ### Usernames
@@ -70,7 +73,8 @@ claim field named `preferred_username` as the the username.
 If your upstream identity provider uses a different claim, you can set
 `CODER_OIDC_USERNAME_FIELD` to the desired claim.
 
-> **Note:** If this claim is empty, the email address will be stripped of the
+> [!NOTE]
+> If this claim is empty, the email address will be stripped of the
 > domain, and become the username (e.g. `example@coder.com` becomes `example`).
 > To avoid conflicts, Coder may also append a random word to the resulting
 > username.

diff --git a/docs/admin/users/organizations.md b/docs/admin/users/organizations.md
@@ -1,6 +1,7 @@
 # Organizations (Premium)
 
-> Note: Organizations requires a
+> [!NOTE]
+> Organizations requires a
 > [Premium license](https://coder.com/pricing#compare-plans). For more details,
 > [contact your account team](https://coder.com/contact).