From 14bc768e448e148ce724241978ef6ff553fcb63f Mon Sep 17 00:00:00 2001
From: Kirill Bulatov <kirill@zed.dev>
Date: Thu, 13 Aug 2026 10:22:47 +0000
Subject: [PATCH] Adjust language docs (#62551)

Closes https://github.com/zed-industries/zed/issues/62548

Puts
https://github.com/zed-industries/zed/issues/61908#issuecomment-5142104901
into docs.

Release Notes:

- N/A
---
 docs/src/configuring-languages.md | 40 +++++++++++++++++++------------
 1 file changed, 25 insertions(+), 15 deletions(-)

diff --git a/docs/src/configuring-languages.md b/docs/src/configuring-languages.md
index 5907ef6626..d37cc967ef 100644
--- a/docs/src/configuring-languages.md
+++ b/docs/src/configuring-languages.md
@@ -134,29 +134,39 @@ Suppose you're working with Ruby. The default configuration is:
 
 ```json [settings]
 {
-  "language_servers": [
-    "solargraph",
-    "!ruby-lsp",
-    "!rubocop",
-    "!sorbet",
-    "!steep",
-    "!kanayago",
-    "..."
-  ]
+  "languages": {
+    "Ruby": {
+      "language_servers": [
+        "solargraph",
+        "!ruby-lsp",
+        "!rubocop",
+        "!sorbet",
+        "!steep",
+        "!kanayago",
+        "!fuzzy-ruby-server",
+        "..."
+      ]
+    }
+  }
 }
 ```
 
 When you override `language_servers` in your settings, your list **replaces** the default entirely. This means default-disabled servers like `kanayago` will be re-enabled by `"..."` unless you explicitly disable them again.
 
-| Configuration                                     | Result                                                             |
-| ------------------------------------------------- | ------------------------------------------------------------------ |
-| `["..."]`                                         | `solargraph`, `ruby-lsp`, `rubocop`, `sorbet`, `steep`, `kanayago` |
-| `["ruby-lsp", "..."]`                             | `ruby-lsp`, `solargraph`, `rubocop`, `sorbet`, `steep`, `kanayago` |
-| `["ruby-lsp", "!solargraph", "!kanayago", "..."]` | `ruby-lsp`, `rubocop`, `sorbet`, `steep`                           |
-| `["ruby-lsp", "solargraph"]`                      | `ruby-lsp`, `solargraph`                                           |
+| Configuration                                     | Result                                                                                  |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `["..."]`                                         | `solargraph`, `ruby-lsp`, `rubocop`, `sorbet`, `steep`, `kanayago`, `fuzzy-ruby-server` |
+| `["ruby-lsp", "..."]`                             | `ruby-lsp`, `solargraph`, `rubocop`, `sorbet`, `steep`, `kanayago`, `fuzzy-ruby-server` |
+| `["ruby-lsp", "!solargraph", "!kanayago", "..."]` | `ruby-lsp`, `rubocop`, `sorbet`, `steep`, `fuzzy-ruby-server`                           |
+| `["ruby-lsp", "solargraph"]`                      | `ruby-lsp`, `solargraph`                                                                |
 
 > Note: In the first example, `"..."` includes `kanayago` even though it is disabled by default. The override replaced the default list, so the `"!kanayago"` entry is no longer present. To keep it disabled, you must include `"!kanayago"` in your configuration.
 
+#### Top-level language settings
+
+Every language setting can also be set at the top level of `settings.json`, outside the `languages` map.
+Top-level entries are the default for all languages: a language-specific value always **replaces** the top-level one entirely, the two are never merged.
+
 ### Toolchains
 
 Some language servers need to be configured with a current "toolchain", which is an installation of a specific version of a programming language compiler or/and interpreter, which can possibly include a full set of dependencies of a project.