From 7afd9d400e794417c5cfdc134d2b8f9d03147e35 Mon Sep 17 00:00:00 2001
From: Marshall Bowers <git@maxdeviant.com>
Date: Mon, 3 Feb 2025 19:06:46 -0500
Subject: [PATCH] docs: Add docs for icon theme extensions

---
 docs/src/SUMMARY.md                          |  1 +
 docs/src/extensions.md                       |  1 +
 docs/src/extensions/developing-extensions.md |  1 +
 docs/src/extensions/icon-themes.md           | 64 ++++++++++++++++++++
 4 files changed, 67 insertions(+)
 create mode 100644 docs/src/extensions/icon-themes.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index d807da8193d20d..01f9c3ffb0e078 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -53,6 +53,7 @@
 - [Developing Extensions](./extensions/developing-extensions.md)
 - [Language Extensions](./extensions/languages.md)
 - [Theme Extensions](./extensions/themes.md)
+- [Icon Theme Extensions](./extensions/icon-themes.md)
 - [Slash Command Extensions](./extensions/slash-commands.md)
 - [Context Server Extensions](./extensions/context-servers.md)
 
diff --git a/docs/src/extensions.md b/docs/src/extensions.md
index ece7e88467b951..25bae742d75705 100644
--- a/docs/src/extensions.md
+++ b/docs/src/extensions.md
@@ -6,4 +6,5 @@ Zed lets you add new functionality using user-defined extensions.
 - [Developing Extensions](./extensions/developing-extensions.md)
   - [Developing Language Extensions](./extensions/languages.md)
   - [Developing Themes](./extensions/themes.md)
+  - [Developing Icon Themes](./extensions/icon-themes.md)
   - [Developing Slash Commands](./extensions/slash-commands.md)
diff --git a/docs/src/extensions/developing-extensions.md b/docs/src/extensions/developing-extensions.md
index c404d260a0c724..d1009c8ed97c82 100644
--- a/docs/src/extensions/developing-extensions.md
+++ b/docs/src/extensions/developing-extensions.md
@@ -6,6 +6,7 @@ Extensions can add the following capabilities to Zed:
 
 - [Languages](./languages.md)
 - [Themes](./themes.md)
+- [Icon Themes](./icon-themes.md)
 - [Slash Commands](./slash-commands.md)
 - [Context Servers](./context-servers.md)
 
diff --git a/docs/src/extensions/icon-themes.md b/docs/src/extensions/icon-themes.md
new file mode 100644
index 00000000000000..c8321e19388360
--- /dev/null
+++ b/docs/src/extensions/icon-themes.md
@@ -0,0 +1,64 @@
+# Icon Themes
+
+Extensions may provide icon themes in order to change the icons Zed uses for folders and files.
+
+## Example extension
+
+The [Material Icon Theme](https://github.com/zed-extensions/material-icon-theme) serves as an example for the structure of an extension containing an icon theme.
+
+## Directory structure
+
+There are two important directories for an icon theme extension:
+
+- `icon_themes`: This directory will contain one or more JSON files containing the icon theme definitions.
+- `icons`: This directory contains the icons assets that will be distributed with the extension. You can created subdirectories in this directory, if so desired.
+
+Each icon theme file should adhere to the JSON schema specified at [`https://zed.dev/schema/icon_themes/v0.1.0.json`](https://zed.dev/schema/icon_themes/v0.1.0.json).
+
+Here is an example of the structure of an icon theme:
+
+```json
+{
+  "$schema": "https://zed.dev/schema/icon_themes/v0.1.0.json",
+  "name": "My Icon Theme",
+  "author": "Your Name",
+  "themes": [
+    {
+      "name": "My Icon Theme",
+      "appearance": "dark",
+      "directory_icons": {
+        "collapsed": "./icons/folder.svg",
+        "expanded": "./icons/folder-open.svg"
+      },
+      "chevon_icons": {
+        "collapsed": "./icons/chevron-right.svg",
+        "expanded": "./icons/chevron-down.svg"
+      },
+      "file_icons": {
+        "audio": { "path": "./icons/audio.svg" },
+        "default": { "path": "./icons/file.svg" },
+        "rust": { "path": "./icons/rust.svg" }
+        // ...
+      }
+    }
+  ]
+}
+```
+
+Each icon path is resolved relative to the root of the extension directory.
+
+In this example, the extension would have a structure like so:
+
+```
+extension.toml
+icon_themes/
+  my-icon-theme.json
+icons/
+  audio.svg
+  chevron-down.svg
+  chevron-right.svg
+  file.svg
+  folder-open.svg
+  folder.svg
+  rust.svg
+```