diff --git a/docs/config.mdx b/docs/config.mdx
index c242b88..d41234f 100644
--- a/docs/config.mdx
+++ b/docs/config.mdx
@@ -62,3 +62,71 @@ For reference this is the current default configuration (v0.8.8):
     "telemetry:enabled": true
 }
 ```
+
+### Terminal Theming
+
+User-defined terminal themes are located in `~/.waveterm/config/termthemes.json`.  This JSON file is structured as an object, with each sub-key defining a theme.
+Themes are applied by right-clicking on the terminal's header bar and selecting an entry from the "Themes" sub-menu.  Alternatively they can be applied to
+the block's metadata key `term:theme`.  This uses the JSON key value as the identifier.  Note, for best consistency all colors should be of the format "#rrggbb" or "#rrggbbaa" (aa = alpha channel for transparency).
+
+`wsh setmeta this term:theme="default-dark"`
+
+Here is an example of defining a full terminal theme.  All of the built-in themes are defined here: https://github.com/wavetermdev/waveterm/blob/main/pkg/wconfig/defaultconfig/termthemes.json (if you'd like to add a popular terminal theme, please submit a PR!)
+
+```json
+{
+    "default-dark": {
+        "display:name": "Default Dark",
+        "display:order": 1,
+        "black": "#757575",
+        "red": "#cc685c",
+        "green": "#76c266",
+        "yellow": "#cbca9b",
+        "blue": "#85aacb",
+        "magenta": "#cc72ca",
+        "cyan": "#74a7cb",
+        "white": "#c1c1c1",
+        "brightBlack": "#727272",
+        "brightRed": "#cc9d97",
+        "brightGreen": "#a3dd97",
+        "brightYellow": "#cbcaaa",
+        "brightBlue": "#9ab6cb",
+        "brightMagenta": "#cc8ecb",
+        "brightCyan": "#b7b8cb",
+        "brightWhite": "#f0f0f0",
+        "gray": "#8b918a",
+        "cmdtext": "#f0f0f0",
+        "foreground": "#c1c1c1",
+        "selectionBackground": "",
+        "background": "#00000077",
+        "cursorAccent": ""
+    }
+}
+```
+
+| Key Name | Type | ANSI FG# | ANSI BG# | Function |
+|----------|------|----------|----------|----------|
+| display:name | string ||| the name as it will appear in the UI context menu |
+| display:order | float ||| entries in the context menu are sorted by display:order |
+| black   | CSS color | 30 | 40 | color for black |
+| red     | CSS color | 31 | 41 | color for red |
+| green   | CSS color | 32 | 42 | color for green |
+| yellow  | CSS color | 33 | 43 | color for yellow |
+| blue    | CSS color | 34 | 44 | color for blue |
+| magenta | CSS color | 35 | 45 | color for magenta |
+| cyan    | CSS color | 36 | 46 | color for cyan |
+| white   | CSS color | 37 | 47 | color for white |
+| brightBlack   | CSS color | 90 | 100 | color for bright black |
+| brightRed     | CSS color | 91 | 101 | color for bright red |
+| brightGreen   | CSS color | 92 | 102 | color for bright green |
+| brightYellow  | CSS color | 93 | 103 | color for bright yellow |
+| brightBlue    | CSS color | 94 | 104 | color for bright blue |
+| brightMagenta | CSS color | 95 | 105 | color for bright magenta |
+| brightCyan    | CSS color | 96 | 106 | color for bright cyan |
+| brightWhite   | CSS color | 97 | 107 | color for bright white |
+| gray          | CSS color ||| currently unused |
+| cmdtext       | CSS color ||| currently unused |
+| foreground    | CSS color ||| foreground color (default when no color code is applied) |
+| background    | CSS color ||| background color (default when no color code is applied), must have alpha channel (#rrggbbaa) if you want the terminal to be transparent |
+| cursorAccent  | CSS color ||| color for cursor |
+| selectionBackground | CSS color ||| background color for selected text |