diff options
| -rw-r--r-- | README.md | 26 | ||||
| -rw-r--r-- | doc/mason-lspconfig.txt | 140 | ||||
| -rw-r--r-- | doc/mason.txt | 2 |
3 files changed, 166 insertions, 2 deletions
@@ -24,6 +24,7 @@ - [Setup](#setup) - [Commands](#commands) - [Configuration](#configuration) +- [Extensions](#extensions) # Introduction @@ -80,6 +81,8 @@ Plug "williamboman/mason.nvim", { 'branch': 'alpha' } require("mason").setup {} ``` +Refer to [extensions](#extensions) for extra, opt-in, functionality! + Refer to the [Configuration](#configuration) section for information about which settings are available. # Commands @@ -92,7 +95,8 @@ Refer to the [Configuration](#configuration) section for information about which # Configuration -You may optionally configure certain behavior of `mason.nvim` when calling the `.setup()` function. +You may optionally configure certain behavior of `mason.nvim` when calling the `.setup()` function. Refer to the +[default configuration](#default-configuration) for a list of all available settings. Example: @@ -108,6 +112,8 @@ require("mason").setup({ }) ``` +## Default configuration + ```lua local DEFAULT_SETTINGS = { ui = { @@ -174,3 +180,21 @@ local DEFAULT_SETTINGS = { }, } ``` + +# Extensions + +## `mason-lspconfig` + +`mason-lspconfig` is a native extension to `mason.nvim` that ships with +`mason.nvim`. It bridges `mason.nvim` with the `lspconfig` plugin in order to +make it easier to use the both plugins together. + +It is recommended to use this extension if you use `lspconfig`. To use this extension, make sure to set it up after +`mason.nvim`, like so: + +```lua +require("mason").setup() +require("mason-lspconfig").setup() +``` + +For more documentation, see [`:h mason-lspconfig`](./doc/mason-lspconfig.txt). diff --git a/doc/mason-lspconfig.txt b/doc/mason-lspconfig.txt new file mode 100644 index 00000000..e200067a --- /dev/null +++ b/doc/mason-lspconfig.txt @@ -0,0 +1,140 @@ +*mason-lspconfig* + +Minimum version of neovim: 0.7.0 + +Author: William Boman + +============================================================================== +INTRODUCTION *mason-lspconfig-introduction* + +`mason-lspconfig` is a native extension to `mason.nvim` that ships with +`mason.nvim`. It bridges `mason.nvim` with the `lspconfig` plugin in order to +make it easier to use the both plugins together. + +It is recommended to use this extension if you use `lspconfig`. + +Among other things, it provides convenience APIs that allow you to use +mason.nvim as the main control for dynamically setting up installed servers on +an ad-hoc basis. It also provides extra commands such as `:LspInstall` that +for example allow you to install servers for the current 'filetype'. Lastly, +it also registers a setup hook with `lspconfig` that ensures servers installed +with `mason.nvim` are set up with the necessary extra configuration (however, +this only applies to a few select servers!). + +`lspconfig`: https://github.com/neovim/nvim-lspconfig + +============================================================================== +REQUIREMENTS *mason-lspconfig-requirements* + +`mason-lspconfig` requires `lspconfig` to be installed. Note that `lspconfig` +needs to be available when setting up `mason-lspconfig` - so if you lazy load +either plugin make sure `lspconfig` is not loaded after `mason-lspconfig`. + +Also, make sure not to set up any servers via `lspconfig` _before_ calling +`mason-lspconfig`'s setup function. + +============================================================================== +QUICK START *mason-lspconfig-quickstart* + +The only thing needed to enable the `mason-lspconfig` plugin is to make sure +to call the `setup()` function: + + require("mason").setup() + require("mason-lspconfig").setup() + +============================================================================== +COMMANDS *mason-lspconfig-commands* + + *:LspInstall* +:LspInstall [<server>...] + +Installs the provided servers. This command only accepts servers that have a +corresponding server configuration in `lspconfig`. + +You may also provide a language, like `:LspInstall typescript`. This will +prompt you with a selection of all available servers for that given language. + +When the command is ran without any arguments, the currently active buffer's +'filetype' will be used to identify relevant servers, and you will be prompted +with a selection of all suggested servers. + + *:LspUninstall* +:LspUninstall <server> ... + +Uninstalls the provided servers. + +============================================================================== +SETTINGS *mason-lspconfig-settings* + +You can configure certain behavior of `mason-lspconfig` when calling the +`.setup()` function. + +Refer to |mason-lspconfig-default-settings| for all available settings. + +Example: + + require("mason-lspconfig").setup({ + ensure_installed = { "rust_analyzer", "tsserver" } + }) + + *mason-lspconfig-default-settings* + + local DEFAULT_SETTINGS = { + -- A list of servers to automatically install if they're not already installed. Example: { "rust-analyzer@nightly", "sumneko_lua" } + -- This setting has no relation with the `automatic_installation` setting. + ensure_installed = {}, + + -- Whether servers that are set up (via lspconfig) should be automatically installed if they're not already installed. + -- This setting has no relation with the `ensure_installed` setting. + -- Can either be: + -- - false: Servers are not automatically installed. + -- - true: All servers set up via lspconfig are automatically installed. + -- - { exclude: string[] }: All servers set up via lspconfig, except the ones provided in the list, are automatically installed. + -- Example: automatic_installation = { exclude = { "rust_analyzer", "solargraph" } } + automatic_installation = false, + } + +============================================================================== +AUTOMATIC SERVER SETUP + *mason-lspconfig-automatic-server-setup* + +`mason-lspconfig` provides opt-in functionality that allow you to +automatically set up LSP servers installed with `mason.nvim`, without having +to edit your Neovim configuration for every single server you want to use. +This is also convenient if you want to use `mason.nvim` as the control for +which servers to set up. It also makes it possible to set up newly installed +servers without having to restart Neovim! + +Refer to |mason-lspconfig.setup_handlers()| for more information! + +============================================================================== +Lua module: mason-lspconfig + + *mason-lspconfig.setup()* +setup({config}) + Sets up mason with the provided {config} (see |mason-lspconfig-settings|). + + *mason-lspconfig.setup_handlers()* +setup_handlers({handlers}) + Registers the provided {handlers}, to be called by mason when a server is + ready to be set up. + + {handlers} is a table where all values is a function with the signature + `function (server_name: string)`. It has the following structure: + + require("mason-lspconfig").setup_handlers({ + function (server_name) -- default handler (optional) + -- The first entry (without a key) will be the default handler + -- and will be called for each installed server that doesn't have + -- a dedicated handler. + require("lspconfig")[server_name].setup {} + end, + -- Next, you can provide targeted overrides for specific servers. + -- For example, a handler override for the `rust_analyzer`: + ["rust_analyzer"] = function () + require("rust-tools").setup {} + end + }) + + + vim:tw=78:ft=help:norl:expandtab:sw=4 diff --git a/doc/mason.txt b/doc/mason.txt index 9ae43be1..3ddf08cf 100644 --- a/doc/mason.txt +++ b/doc/mason.txt @@ -241,6 +241,6 @@ Lua module: mason *mason.setup()* setup({config}) - Sets up mason with the provided {config} (see |mason-settings|). + Sets up mason with the provided {config} (see |mason-settings|). vim:tw=78:ft=help:norl:expandtab:sw=4 |