From 6576bd2c838fb6dd26239edde1a5db0779669b06 Mon Sep 17 00:00:00 2001
From: asdfer <58357836+asdfer-1234@users.noreply.github.com>
Date: Thu, 30 Jul 2026 21:51:08 +0900
Subject: [PATCH] docs: Add missing font fallback documentation (#55779)

Adds missing documentation about font fallbacks on `appearance.md` and
`all-settings.md`
`all-settings.md` only lacked terminal font fallback documentation so
that's the only thing I added there.

Self-Review Checklist:

- [X] I've reviewed my own diff for quality, security, and reliability
- [it's a doc update] Unsafe blocks (if any) have justifying comments
- [there is no ui] The content is consistent with the [UI/UX
checklist](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist)
- [it's a doc update] Tests cover the new/changed behavior
- [i really hope that my extra bytes on documentation cause no
performance impacts] Performance impact has been considered and is
acceptable

Release Notes:
- N/A
---
 docs/src/appearance.md             | 18 ++++++++++++------
 docs/src/reference/all-settings.md | 18 ++++++++++++++++++
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/docs/src/appearance.md b/docs/src/appearance.md
index 26c268e28c..00aff71b73 100644
--- a/docs/src/appearance.md
+++ b/docs/src/appearance.md
@@ -65,24 +65,30 @@ Like color themes, icon themes support separate light and dark variants:
 
 ## Fonts
 
-Zed uses three font settings for different contexts:
+Zed uses three font settings and their fallback counterparts for different contexts:
 
-| Setting                | Used for                  |
-| ---------------------- | ------------------------- |
-| `buffer_font_family`   | Editor text               |
-| `ui_font_family`       | Interface elements        |
-| `terminal.font_family` | [Terminal](./terminal.md) |
+| Setting                   | Used for                  |
+| ------------------------- | ------------------------- |
+| `buffer_font_family`      | Editor text               |
+| `buffer_font_fallbacks`   | Editor text               |
+| `ui_font_family`          | Interface elements        |
+| `ui_font_fallbacks`       | Interface elements        |
+| `terminal.font_family`    | [Terminal](./terminal.md) |
+| `terminal.font_fallbacks` | [Terminal](./terminal.md) |
 
 Example configuration:
 
 ```json [settings]
 {
   "buffer_font_family": "JetBrains Mono",
+  "buffer_font_fallbacks": ["Nerd Font"],
   "buffer_font_size": 14,
   "ui_font_family": "Inter",
+  "ui_font_fallbacks": ["Nerd Font"],
   "ui_font_size": 16,
   "terminal": {
     "font_family": "JetBrains Mono",
+    "font_fallbacks": ["Nerd Font"],
     "font_size": 14
   }
 }
diff --git a/docs/src/reference/all-settings.md b/docs/src/reference/all-settings.md
index b6e9ab745f..a0eed002c6 100644
--- a/docs/src/reference/all-settings.md
+++ b/docs/src/reference/all-settings.md
@@ -4500,6 +4500,24 @@ The name of any font family installed on the user's system
 }
 ```
 
+### Terminal: Font Fallbacks
+
+- Description: The font fallbacks to use for text in the terminal. Uses the buffer's font fallback if unset.
+- Setting: "font_fallbacks"
+- Default: `null`
+
+**Options**
+
+For example, to use Nerd Font as a fallback, add the following to your settings:
+
+```json [settings]
+{
+  "terminal": {
+    "font_fallbacks": ["Nerd Font"]
+  }
+}
+```
+
 ### Terminal: Font Features
 
 - Description: What font features to use for the terminal. When not set, defaults to matching the editor's font features.