docs: Update lsp.settings examples for yaml-language-server (#18081)

notpeter · web-flow · commit 3fd690ade401 · 2024-09-19T12:00:13.000-04:00
diff --git a/docs/src/configuring-zed.md b/docs/src/configuring-zed.md
@@ -575,8 +575,13 @@ Each option controls displaying of a particular toolbar element. If all elements
 The following settings can be overridden for specific language servers:
 
 - `initialization_options`
+- `settings`
 
-To override settings for a language, add an entry for that language server's name to the `lsp` value. Example:
+To override configuration for a language server, add an entry for that language server's name to the `lsp` value.
+
+Some options are passed via `initialization_options` to the language server. These are for options which must be specified at language server startup and when changed will require restarting the language server.
+
+For example to pass the `check` option to `rust-analyzer`, use the following configuration:
 
 ```json
 "lsp": {
@@ -590,6 +595,20 @@ To override settings for a language, add an entry for that language server's nam
 }
 ```
 
+While other options may be changed at a runtime and should be placed under `settings`:
+
+```json
+"lsp": {
+  "yaml-language-server": {
+    "settings": {
+      "yaml": {
+        "keyOrdering": true // Enforces alphabetical ordering of keys in maps
+      }
+    }
+  }
+}
+```
+
 ## Format On Save
 
 - Description: Whether or not to perform a buffer format before saving.
diff --git a/docs/src/languages/typescript.md b/docs/src/languages/typescript.md
@@ -72,20 +72,20 @@ You can override these settings in your configuration file:
 
 ```json
 "lsp": {
-    "$LANGUAGE_SERVER_NAME": {
-        "initialization_options": {
-            "preferences": {
-              "includeInlayParameterNameHints": "all",
-              "includeInlayParameterNameHintsWhenArgumentMatchesName": true,
-              "includeInlayFunctionParameterTypeHints": true,
-              "includeInlayVariableTypeHints": true,
-              "includeInlayVariableTypeHintsWhenTypeMatchesName": true,
-              "includeInlayPropertyDeclarationTypeHints": true,
-              "includeInlayFunctionLikeReturnTypeHints": true,
-              "includeInlayEnumMemberValueHints": true,
-            }
-        }
+  "$LANGUAGE_SERVER_NAME": {
+    "initialization_options": {
+      "preferences": {
+      "includeInlayParameterNameHints": "all",
+        "includeInlayParameterNameHintsWhenArgumentMatchesName": true,
+        "includeInlayFunctionParameterTypeHints": true,
+        "includeInlayVariableTypeHints": true,
+        "includeInlayVariableTypeHintsWhenTypeMatchesName": true,
+        "includeInlayPropertyDeclarationTypeHints": true,
+        "includeInlayFunctionLikeReturnTypeHints": true,
+        "includeInlayEnumMemberValueHints": true,
+      }
     }
+  }
 }
 ```
 
diff --git a/docs/src/languages/yaml.md b/docs/src/languages/yaml.md
@@ -12,7 +12,7 @@ You can configure various [yaml-language-server settings](https://github.com/red
 ```json
   "lsp": {
     "yaml-language-server": {
-      "initialization_options": {
+      "settings": {
         "yaml": {
           "keyOrdering": true,
           "format": {
@@ -32,9 +32,9 @@ Note, settings keys must be nested, so `yaml.keyOrdering` becomes `{"yaml": { "k
 
 ## Schemas
 
-By default yaml-language-server will attempt to determine the correct schema for a given yaml file and retrieve the appropriate JSON Schema from [Json Schema Store].
+By default yaml-language-server will attempt to determine the correct schema for a given yaml file and retrieve the appropriate JSON Schema from [Json Schema Store](https://schemastore.org/).
 
-You can override this by [using an inlined schema] reference via a modeline comment at the top of your yaml file:
+You can override any auto-detected schema via the `schemas` settings key (demonstrated above) or by providing an [inlined schema](https://github.com/redhat-developer/yaml-language-server#using-inlined-schema) reference via a modeline comment at the top of your yaml file:
 
 ```yaml
 # yaml-language-server: $schema=https://json.schemastore.org/github-action.json
@@ -44,12 +44,12 @@ on:
     types: [oppened]
 ```
 
-You can disable this functionality entirely if desired:
+You can disable the automatic detection and retrieval of schemas from the JSON Schema if desired:
 
 ```json
   "lsp": {
     "yaml-language-server": {
-      "initialization_options": {
+      "settings": {
         "yaml": {
           "schemaStore": {
             "enable": false
@@ -59,3 +59,73 @@ You can disable this functionality entirely if desired:
     }
   }
 ```
+
+## Custom Tags
+
+Yaml-language-server supports [custom tags](https://github.com/redhat-developer/yaml-language-server#adding-custom-tags) which can be used to inject custom application functionality at runtime into your yaml files.
+
+For example Amazon CloudFormation YAML uses a number of custom tags, to support these you can add the following to your settings.json:
+
+```json
+  "lsp": {
+    "yaml-language-server": {
+      "settings": {
+        "yaml": {
+          "customTags": [
+            "!And scalar",
+            "!And mapping",
+            "!And sequence",
+            "!If scalar",
+            "!If mapping",
+            "!If sequence",
+            "!Not scalar",
+            "!Not mapping",
+            "!Not sequence",
+            "!Equals scalar",
+            "!Equals mapping",
+            "!Equals sequence",
+            "!Or scalar",
+            "!Or mapping",
+            "!Or sequence",
+            "!FindInMap scalar",
+            "!FindInMap mapping",
+            "!FindInMap sequence",
+            "!Base64 scalar",
+            "!Base64 mapping",
+            "!Base64 sequence",
+            "!Cidr scalar",
+            "!Cidr mapping",
+            "!Cidr sequence",
+            "!Ref scalar",
+            "!Ref mapping",
+            "!Ref sequence",
+            "!Sub scalar",
+            "!Sub mapping",
+            "!Sub sequence",
+            "!GetAtt scalar",
+            "!GetAtt mapping",
+            "!GetAtt sequence",
+            "!GetAZs scalar",
+            "!GetAZs mapping",
+            "!GetAZs sequence",
+            "!ImportValue scalar",
+            "!ImportValue mapping",
+            "!ImportValue sequence",
+            "!Select scalar",
+            "!Select mapping",
+            "!Select sequence",
+            "!Split scalar",
+            "!Split mapping",
+            "!Split sequence",
+            "!Join scalar",
+            "!Join mapping",
+            "!Join sequence",
+            "!Condition scalar",
+            "!Condition mapping",
+            "!Condition sequence"
+          ]
+        }
+      }
+    }
+  }
+```
