coder · aslilac · Oct 12, 2023 · Oct 11, 2023 · Oct 11, 2023 · Oct 12, 2023
diff --git a/docs/images/icons-gallery.png b/docs/images/icons-gallery.png
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -207,6 +207,11 @@
           "description": "Audit commands in workspaces with exectrace",
           "path": "./templates/process-logging.md",
           "state": "enterprise"
+        },
+        {
+          "title": "Icons",
+          "description": "Coder includes icons for popular cloud providers and programming languages for you to use",
+          "path": "./templates/icons.md"
         }
       ]
     },

diff --git a/docs/templates/icons.md b/docs/templates/icons.md
@@ -0,0 +1,68 @@
+# Icons
+
+---
+
+Coder uses icons in several places, including ones that can be configured
+throughout the app, or specified in your Terraform. They're specified by a URL,
+which can be to an image hosted on a CDN of your own, or one of the icons that
+come bundled with your Coder deployment.
+
+- **Template Icons**:
+
+  - Make templates and workspaces visually recognizable with a relevant or
+    memorable icon
+
+- [**Terraform**](https://registry.terraform.io/providers/coder/coder/latest/docs):
+
+  - [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app#icon)
+  - [`coder_parameter`](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter#icon)
+    and
+    [`option`](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter#nested-schema-for-option)
+    blocks
+  - [`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script#icon)
+
+  These can all be configured to use an icon by setting the `icon` field.
+
+  ```terraform
+  data "coder_parameter" "my_parameter" {
+    icon = "/icon/coder.svg"
+
+    option {
+      icon = "/emojis/1f3f3-fe0f-200d-26a7-fe0f.png"
+    }
+  }
+  ```
+
+- [**Authentication Providers**](https://coder.com/docs/v2/latest/admin/external-auth):
+
+  - Use icons for external authentication providers to make them recognizable
+
+## Bundled icons
+
+Coder is distributed with a bundle of icons for popular cloud providers and
+programming languages. You can see all of the icons (or suggest new ones) in our
+repository on
+[GitHub](https://github.com/coder/coder/tree/main/site/static/icon).
+
+You can also view the entire list, with search and previews, by navigating to
+/icons on your Coder deployment. E.g. [https://coder.example.com/icons](#). This
+can be particularly useful in airgapped deployments.
+
+![The icon gallery](../images/icons-gallery.png)
+
+## External icons
+
+You can use any image served over HTTPS as an icon, by specifying the full URL
+of the image. We recommend that you use a CDN that you control, but it can be
+served from any source that you trust.
+
+You can also embed an image by using data: URLs.
+
+- Only the https: and data: protocols are supported in icon URLs (not http:)
+
+- Be careful when using images hosted by someone else; they might disappear or
+  change!
+
+- Be careful when using data: URLs. They can get rather large, and can
+  negatively impact loading times for pages and queries they appear in. Only use
+  them for very small icons that compress well.