From 7c72929f0ba3ade5fde3e7b090dcd2685ae243e3 Mon Sep 17 00:00:00 2001
From: Kartik Vashistha <kartikv.work@gmail.com>
Date: Tue, 5 Nov 2024 18:57:15 +0000
Subject: [PATCH] docs: Add Ansible language documentation (#20087)

Co-authored-by: Peter Tripp <peter@zed.dev>
---
 docs/src/SUMMARY.md           |  1 +
 docs/src/languages.md         |  1 +
 docs/src/languages/ansible.md | 75 +++++++++++++++++++++++++++++++++++
 3 files changed, 77 insertions(+)
 create mode 100644 docs/src/languages/ansible.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 8383e990d982d..bc7ba52869306 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -56,6 +56,7 @@
 # Language Support
 
 - [All Languages](./languages.md)
+- [Ansible](./languages/ansible.md)
 - [AsciiDoc](./languages/asciidoc.md)
 - [Astro](./languages/astro.md)
 - [Bash](./languages/bash.md)
diff --git a/docs/src/languages.md b/docs/src/languages.md
index 2e29898f2d580..befa2aded0346 100644
--- a/docs/src/languages.md
+++ b/docs/src/languages.md
@@ -4,6 +4,7 @@ Zed supports hundreds of programming languages and text formats. Some work out-o
 
 ## Languages with Documentation
 
+- [Ansible](./languages/ansible.md)
 - [AsciiDoc](./languages/asciidoc.md)
 - [Astro](./languages/astro.md)
 - [Bash](./languages/bash.md)
diff --git a/docs/src/languages/ansible.md b/docs/src/languages/ansible.md
new file mode 100644
index 0000000000000..259b4f8f731d4
--- /dev/null
+++ b/docs/src/languages/ansible.md
@@ -0,0 +1,75 @@
+# Ansible
+
+Support for Ansible in Zed is provided via a community-maintained [Ansible extension](https://github.com/kartikvashistha/zed-ansible).
+
+- Tree-sitter: [zed-industries/tree-sitter-yaml](https://github.com/zed-industries/tree-sitter-yaml)
+- Language Server: [ansible/vscode-ansible](https://github.com/ansible/vscode-ansible/tree/main/packages/ansible-language-server)
+
+## Setup
+
+### File detection
+
+By default, to avoid mishandling non-Ansible YAML files, the Ansible Language is not associated with any file extensions by default. To change this behavior you can add a `"file_types"` section to the Zed settings inside your project (`.zed/setttings.json`) or your Zed user settings (`~/.config/zed/settings.json`) to match your folder/naming conventions. For example:
+
+```json
+"file_types": {
+    "Ansible": [
+      "**.ansible.yml",
+      "**.ansible.yaml",
+      "**/defaults/*.yml",
+      "**/defaults/*.yaml",
+      "**/meta/*.yml",
+      "**/meta/*.yaml",
+      "**/tasks/*.yml",
+      "**/tasks/*.yml",
+      "**/tasks/*.yaml",
+      "**/handlers/*.yml",
+      "**/handlers/*.yaml",
+      "**/group_vars/*.yml",
+      "**/group_vars/*.yaml",
+      "**/playbooks/*.yaml",
+      "**/playbooks/*.yml",
+      "**playbook*.yaml",
+      "**playbook*.yml"
+    ]
+  }
+```
+
+Feel free to modify this list as per your needs.
+
+### LSP Configuration
+
+LSP options for this extension can be configured under Zed's settings file. To get the best experience, add the following configuration under the `"lsp"` section in your `~/.zed/settings.json`:
+
+```json
+"lsp": {
+  // Note, the Zed Ansible extension prefixes all settings with `ansible`
+  // so instead of using `ansible.ansible.path` use `ansible.path`.
+  "ansible-language-server": {
+    "settings": {
+      "ansible": {
+        "path": "ansible"
+      },
+      "executionEnvironment": {
+        "enabled": false
+      },
+      "python": {
+        "interpreterPath": "python3"
+      },
+      "validation": {
+        "enabled": true,
+        // To enable linting, manually install ansible-lint and make sure it is your PATH
+        "lint": {
+          "enabled": true,
+          "path": "ansible-lint"
+        }
+      }
+    }
+  }
+}
+```
+
+This config was conveniently adopted from [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/blob/ad32182cc4a03c8826a64e9ced68046c575fdb7d/lua/lspconfig/server_configurations/ansiblels.lua#L6-L23).
+
+A full list of options/settings, that can be passed to the server, can be found at the project's page [here](https://github.com/ansible/vscode-ansible/blob/5a89836d66d470fb9d20e7ea8aa2af96f12f61fb/docs/als/settings.md).
+Feel free to modify option values as needed.