docs: readme

1 files changed, 13 insertions, 34 deletions

diff --git a/README.md b/README.md
index f79876f0..ed7a6401 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,10 @@ configurations for various LSP servers. View [all configs](doc/configs.md) or `:
 ## Important ⚠️
 
 * These configs are **best-effort and supported by the community (you).** See [contributions](#contributions).
+* The configs live in [`lsp/`](./lsp/).
+    * Upgrade to Nvim 0.11+ and use `vim.lsp.enable('…')` (not `require'…'.pyright.setup{}`) to enable a config.
+* The configs in `lua/lspconfig/` are *deprecated* and will be removed.
+    * Upgrade to Nvim 0.11+ and use `vim.lsp.enable('…')` (not `require'…'.pyright.setup{}`) to enable a config.
 * Ask questions on [GitHub Discussions](https://github.com/neovim/neovim/discussions), not the issue tracker.
 * If you found a bug in Nvim LSP (`:help lsp`), [report it to Neovim core](https://github.com/neovim/neovim/issues/new?assignees=&labels=bug%2Clsp&template=lsp_bug_report.yml).
     * **Do not** report it here. Only configuration data lives here.
@@ -50,36 +54,13 @@ For servers not on your `$PATH` (e.g., `jdtls`, `elixirls`), you must manually s
 
 ## Configuration
 
-Nvim sets some default options and mappings when a buffer attaches to LSP (see [`:help lsp-config`][lsp-config]). In particular:
+Nvim sets default options and mappings when LSP is active in a buffer:
+* [:help lsp-defaults](https://neovim.io/doc/user/lsp.html#lsp-defaults).
+* [:help diagnostic-defaults](https://neovim.io/doc/user/diagnostic.html#diagnostic-defaults)
 
-* [`'tagfunc'`][tagfunc]
-    - Enables "go to definition" capabilities using [`<C-]>`][tagjump] and other [tag commands][tag-commands].
-* [`'omnifunc'`][omnifunc]
-    - Enables (manual) omni mode completion with `<C-X><C-O>` in Insert mode.
-* [`'formatexpr'`][formatexpr]
-    - Enables LSP formatting with [`gq`][gq].
-* `K` maps to [`vim.lsp.buf.hover()`][vim.lsp.buf.hover] in Normal mode.
-* `[d` and `]d` map to `vim.diagnostic.jump()` with `{count=-1}` and
-  `vim.diagnostic.jump()` with `{count=1}`, respectively.
-* `<C-W>d` maps to `vim.diagnostic.open_float()`.
-
-[lsp-config]: https://neovim.io/doc/user/lsp.html#lsp-config
-[tagfunc]: https://neovim.io/doc/user/tagsrch.html#tag-function
-[omnifunc]: https://neovim.io/doc/user/options.html#'omnifunc'
-[formatexpr]: https://neovim.io/doc/user/options.html#'formatexpr'
-[gq]: https://neovim.io/doc/user/change.html#gq
-[vim.lsp.buf.hover]: https://neovim.io/doc/user/lsp.html#vim.lsp.buf.hover()
-[tagjump]: https://neovim.io/doc/user/tagsrch.html#CTRL-%5D
-[tag-commands]: https://neovim.io/doc/user/tagsrch.html#tag-commands
-
-Further customization can be achieved using the [`LspAttach`][LspAttach] autocommand event.
-The [`LspDetach`][LspAttach] autocommand event can be used to "cleanup" mappings if a buffer becomes detached from an LSP server.
-See [`:h LspAttach`][LspAttach] and [`:h LspDetach`][LspDetach] for details and examples.
-See [`:h lsp-buf`][lsp-buf] for details on other LSP functions.
-
-[LspAttach]: https://neovim.io/doc/user/lsp.html#LspAttach
-[LspDetach]: https://neovim.io/doc/user/lsp.html#LspDetach
-[lsp-buf]: https://neovim.io/doc/user/lsp.html#lsp-buf
+To customize, see:
+* [:help lsp-attach](https://neovim.io/doc/user/lsp.html#lsp-attach)
+* [`:h lsp-buf`][lsp-buf]
 
 Extra settings can be specified for each LSP server:
 
@@ -105,7 +86,8 @@ Extra settings can be specified for each LSP server:
 
 ## vim.lsp.config
 
-`nvim-lspconfig` includes configurations compatible with `vim.lsp` under [`lsp/`](./lsp/), so servers can be enabled (auto-activated when a filetype is opened) with:
+`nvim-lspconfig` configs live in [`lsp/`](./lsp/). Using Nvim 0.11 or newer, you can `enable()` a config: it will auto-activate when a filetype is opened.
+Example:
 
 ```lua
 vim.lsp.enable('pyright')
@@ -121,9 +103,6 @@ vim.lsp.config('pyright', {
 
 which extends the configuration under [`lsp/`](./lsp/). For further information see [`:help lsp-config`][lsp-config].
 
-> [!WARNING]
-> Some servers are [currently missing](https://github.com/neovim/nvim-lspconfig/issues/3705).
-
 ## Troubleshooting
 
 The most common reasons a language server does not start or attach are:
@@ -162,7 +141,7 @@ If a language server is missing from [configs.md](doc/configs.md), contributing
 a new configuration for it helps others, especially if the server requires special setup. Follow these steps:
 
 1. Read [CONTRIBUTING.md](CONTRIBUTING.md).
-2. Create a new file at `lsp/SERVER_NAME.lua`.
+2. Create a new file at `lsp/<server_name>.lua`.
     - Copy an [existing config](https://github.com/neovim/nvim-lspconfig/tree/master/lsp)
       to get started. Most configs are simple. For an extensive example see
       [texlab.lua](https://github.com/neovim/nvim-lspconfig/blob/master/lsp/texlab.lua).