documenting features, themes

docs/features/index.mdx

@@ -0,0 +1,93 @@
+---
+title: Features
+description: The features Ghostty supports and associated documentation.
+---
+
+Ghostty is a very feature-rich terminal.
+
+Terminal features can be divided into two categories: features for
+end-users and features for terminal application developers.
+
+Features for end-users are things like multi-window, tabs, splits, ligatures,
+auto-update, etc. These are features that make using a terminal
+more pleasant without requiring any changes to the running terminal
+applications (such as your shell, text editor, etc.).
+
+Features for terminal application developers are things like the
+Kitty graphics protocol, Kitty keyboard protocol, synchronized
+rendering, light/dark mode notifications, etc. These features allow
+terminal applications to do more than they could in other terminal
+emulators. While these features are not directly used by end-users,
+end-users benefit from them because terminal applications they use
+every day can do more.
+
+## Feature Highlight
+
+Here is a list highlighting some of the larger or more interesting
+features that Ghostty supports:
+
+- **Cross-platform**: Ghostty runs on macOS and Linux. It uses native
+  UI components on each platform to provide an idiomatic experience.
+  Windows support is planned for the future.
+
+- **Windows, tabs, and splits**: Ghostty supports multiple windows,
+  each with its own tabs and splits. These are all rendered using
+  native UI components.
+
+- **GPU-accelerated rendering**: Ghostty uses Metal on macOS and
+  OpenGL on Linux to render the terminal screen.
+
+- **Themes**: Ghostty ships with hundreds of themes that can be
+  selected with a single line of configuration. Themes can be
+  switched automatically based on system dark/light mode. Users
+  can author their own themes.
+
+- **Ligatures**: You can use fonts that have ligatures and Ghostty
+  will render them correctly. You can also specify specific font
+  features to enable or disable.
+
+- **Grapheme clustering**: Multi-codepoint emoji such as flags,
+  skin tones, etc. are rendered correctly as a single character.
+  Certain languages like Arabic and Hebrew are also rendered
+  correctly (LTR only).
+
+- **Kitty graphics protocol**: Ghostty supports the Kitty graphics
+  protocol, which allows terminal applications to render images
+  directly in the terminal.
+
+## Terminal (VT) Features
+
+For terminal application developers, we believe Ghostty is one of
+the most modern and comprehensive terminal emulators available[^1].
+Our goal with Ghostty is to be the most compatible for legacy
+applications while also providing the most modern features for
+new applications.
+
+What that means in practice is that Ghostty supports a wide range
+of control sequences, terminal features, and terminal protocols.
+And to determine the behavior of these features, we follow
+the following principles:
+
+  1. Xterm compatibility: xterm is the de facto standard for
+     terminal emulation. If xterm does something, we should do
+     the same thing[^2].
+
+  2. Protocol origin compatibility: If the terminal that defined
+     a protocol behaves a certain way, we should follow that behavior,
+     even if it is not specified[^3].
+
+  3. Defacto standard compatibility: If a behavior is widely
+     accepted as the standard, we should follow that behavior.
+     "Widely accepted" is generally subjective based on popular
+     opinion and usage.
+
+
+For a list of terminal developer features Ghostty supports, see the
+[reference](/docs/vt/reference)
+(but note at the time of writing this is still a work-in-progress).
+
+[^1]: If not, we want to know! Please
+[open an discussion](https://github.com/ghostty-org/ghostty/discussions).
+[^2]: We may put some xterm behaviors behind a configuration flag if
+the behavior is questionable or not widely accepted.
+[^3]: If a behavior differs between the specification and the terminal that defined the protocol, we open a discussion to determine the correct behavior.

docs/features/theme.mdx

@@ -0,0 +1,123 @@
+---
+title: Color Theme
+description: |-
+  Ghostty supports full customization of the color theme,
+  ships with hundreds of built-in themes, supports custom themes
+  for light and dark mode, and more.
+---
+
+## Built-in Themes
+
+Ghostty ships with hundreds of built-in themes that can be selected
+with one line of configuration by using the [`theme` configuration option](/docs/config/reference#theme). For example, to use the popular Catppucin theme:
+
+```ini
+theme = catppuccin-frappe
+```
+
+<Tip>
+  Don't forget to [reload your configuration](/docs/config#reload)
+  after changing the theme.
+</Tip>
+
+The built-in themes are sourced from
+[iterm2-color-schemes](https://iterm2colorschemes.com) and
+updated in the Ghostty repository on the main branch weekly.
+If you want to contribute a new theme, please contribute it to
+iterm2-color-schemes and it will be automatically picked up by
+Ghostty.
+
+### Listing Available Themes
+
+To see a list of available themes, you can use the `+list-themes` CLI:
+
+```sh
+$ ghostty +list-themes
+```
+
+For built-in themes, you can also view the theme list online
+at [iterm2-color-schemes](https://iterm2colorschemes.com). This
+also includes a preview of each theme.
+
+## Separate Light and Dark Themes
+
+Ghostty supports specifying separate light and dark themes.
+
+```ini
+theme = dark:catppuccin-frappe,light:catppuccin-latte
+```
+
+When separate light and dark themes are specified, Ghostty will
+automatically switch between the light and dark theme based on
+the system appearance.
+
+## Authoring a Custom Theme
+
+Themes are no different than any other configuration file
+in Ghostty; they just happen to typically only set color options.
+However, a theme file _could_ set any configuration option such
+as cursor styles, fonts, etc.
+
+<Warning>
+  Themes can modify any configuration option, so be careful
+  when using themes from untrusted sources. Always review the
+  theme file before using it to ensure it doesn't contain
+  malicious configuration.
+</Warning>
+
+The primary difference between a theme file and a regular
+configuration file is how it is loaded. Themes are loaded
+_first_ and any conflicting options in the user configuration
+will override the theme (versus
+[`config-file`](/docs/config/reference#config-file)
+which is loaded _after_ the user configuration).
+
+To author a custom theme, create a new file and set the
+following options:
+
+  - [`background`](/docs/config/reference#background)
+  - [`foreground`](/docs/config/reference#foreground)
+  - [`cursor-color`](/docs/config/reference#cursor-color)
+  - [`selection-foreground`](/docs/config/reference#selection-foreground)
+  - [`selection-background`](/docs/config/reference#selection-background)
+  - [`palette`](/docs/config/reference#palette)
+
+### File Location
+
+Theme files can be located anywhere on the filesystem. The
+[`theme`](/docs/config/reference#theme) configuration option allows
+for absolute paths. However, if you want to reference a theme by
+name, they have to be located in specific directories.
+
+Theme lookup by name searches two directories:
+
+  1. `$XDG_CONFIG_HOME/ghostty/themes`
+  2. `$PREFIX/share/ghostty/themes`
+
+### Example
+
+Below is an example of a complete theme file:
+
+```ini
+palette = 0=#51576d
+palette = 1=#e78284
+palette = 2=#a6d189
+palette = 3=#e5c890
+palette = 4=#8caaee
+palette = 5=#f4b8e4
+palette = 6=#81c8be
+palette = 7=#a5adce
+palette = 8=#626880
+palette = 9=#e67172
+palette = 10=#8ec772
+palette = 11=#d9ba73
+palette = 12=#7b9ef0
+palette = 13=#f2a4db
+palette = 14=#5abfb5
+palette = 15=#b5bfe2
+background = 303446
+foreground = c6d0f5
+cursor-color = f2d5cf
+selection-background = 626880
+selection-foreground = c6d0f5
+```

docs/nav.json

@@ -28,9 +28,21 @@
       ]
     },
     {
-      "type": "link",
+      "type": "folder",
       "path": "/features",
-      "title": "Features"
+      "title": "Features",
+      "children": [
+        {
+          "type": "link",
+          "path": "/",
+          "title": "Overview"
+        },
+        {
+          "type": "link",
+          "path": "/theme",
+          "title": "Color Theme"
+        }
+      ]
     },
     {
       "type": "folder",