From 3182811b8daa83db4786a5921328252a56f4d1fd Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Tue, 27 Jan 2026 11:45:35 +0300
Subject: [PATCH] docs/manual: describe registring custom LSPs in the language
 section

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I776aa1283b0d89016a4eb0de2b67e2f86a6a6964
---
 docs/manual/configuring/languages/lsp.md | 40 ++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/manual/configuring/languages/lsp.md b/docs/manual/configuring/languages/lsp.md
index 2ddc08b5..847924aa 100644
--- a/docs/manual/configuring/languages/lsp.md
+++ b/docs/manual/configuring/languages/lsp.md
@@ -21,3 +21,43 @@ vim.languages.java = {
   };
 }
 ```
+
+## Custom LSP Servers {#ch-custom-lsp-servers}
+
+Neovim 0.11, in an effort to improve the out-of-the-box experience of Neovim,
+has introduced a new `vim.lsp` API that can be used to register custom LSP
+servers with ease. In **nvf**, this translates to the custom `vim.lsp` API that
+can be used to register servers that are not present in existing language
+modules.
+
+The {option}`vim.lsp.servers` submodule can be used to modify existing LSP
+definitions OR register your own custom LSPs respectively. For example, if you'd
+like to avoid having NVF pull the LSP packages you may modify the start command
+to use a string, which will cause the LSP API to discover LSP servers from
+{env}`PATH`. For example:
+
+```nix
+{lib, ...}: { 
+  vim.lsp.servers = {
+    # Get `basedpyright-langserver` from PATH, e.g., a dev shell.
+    basedpyright.cmd = lib.mkForce ["basedpyright-langserver" "--stdio"];
+
+    # Define a custom LSP entry using `vim.lsp.servers`:
+    ty = {
+      cmd = lib.mkDefault [(lib.getExe pkgs.ty) "server"];
+      filetypes = ["python"];
+      root_markers = [
+        ".git"
+        "pyproject.toml"
+        "setup.cfg"
+        "requirements.txt"
+        "Pipfile"
+        "pyrightconfig.json"
+      ];
+
+    # If your LSP accepts custom settings. See `:help lsp-config` for more details
+    # on available fields. This is a freeform field.
+    settings.ty = { /* ... */ };
+  };
+}
+```