docs(volar): add Take Over Mode & smart global TS fallback docs (#1448)

Co-authored-by: Artur Tagisow <artur@tagisow.dev>

1 files changed, 55 insertions, 6 deletions

diff --git a/lua/lspconfig/volar.lua b/lua/lspconfig/volar.lua
index 542b8817..7c3aee24 100644
--- a/lua/lspconfig/volar.lua
+++ b/lua/lspconfig/volar.lua
@@ -71,18 +71,67 @@ configs[server_name] = {
 https://github.com/johnsoncodehk/volar/tree/master/packages/server
 
 Volar language server for Vue
-Volar can be installed via npm
+
+Volar can be installed via npm:
+
 ```sh
 npm install -g @volar/server
 ```
 
-With Vue 3 projects - it works out of the box.
+Volar by default supports Vue 3 projects. Vue 2 projects need [additional configuration](https://github.com/johnsoncodehk/volar/blob/master/extensions/vscode-vue-language-features/README.md?plain=1#L28-L63).
+
+**Take Over Mode**
+Volar can serve as a language server for both Vue and TypeScript via [Take Over Mode](https://github.com/johnsoncodehk/volar/discussions/471).
+
+To enable Take Over Mode, override the default filetypes in `setup{}` as follows:
+
+```lua
+require'lspconfig'.volar.setup{
+  filetypes = {'typescript', 'javascript', 'javascriptreact', 'typescriptreact', 'vue', 'json'}
+}
+```
+
+**Overriding the default TypeScript Server used by Volar**
+The default config looks for TS in the local node_modules. The alternatives are:
+
+- use a global TypeScript Server installation
 
-With Vue 2 projects - requires [additional configuration](https://github.com/johnsoncodehk/volar#using)
+```lua
+require'lspconfig'.volar.setup{
+  init_options = {
+    typescript = {
+      serverPath = '/path/to/.npm/lib/node_modules/typescript/lib/tsserverlib.js'
+    }
+  }
+}
+```
 
-Do not run `vuels` and `volar` at the same time.
+- use a global TypeScript Server installation if a local server is not found
 
-To check which language servers are running, open a `.vue` file and run the `:LspInfo` command.
-]],
+```lua
+local util = require 'lspconfig/util'
+
+local function get_typescript_server_path(root_dir)
+  local project_root = util.find_node_modules_ancestor(root_dir)
+
+  local local_tsserverlib = project_root ~= nil and util.path.join(project_root, 'node_modules', 'typescript', 'lib', 'tsserverlibrary.js')
+  local global_tsserverlib = '/home/[yourusernamehere]/.npm/lib/node_modules/typescript/lib/tsserverlibrary.js'
+
+  if local_tsserverlib and util.path.exists(local_tsserverlib) then
+    return local_tsserverlib
+  else
+    return global_tsserverlib
+  end
+end
+
+require'lspconfig'.volar.setup{
+  config = {
+    on_new_config = function(new_config, new_root_dir)
+      new_config.init_options.typescript.serverPath = get_typescript_server_path(new_root_dir)
+    end,
+  }
+}
+```
+    ]],
   },
 }