docs: readme

- improve overview for newcomers
- call out plan for upstreaming "framework" parts to Nvim core
- guide bug reports to neovim core
- remove most mentions of wiki

fix #3202

README.md

@@ -1,24 +1,30 @@
 # nvim-lspconfig
 
-[Configs](doc/server_configurations.md) for the [Nvim LSP client](https://neovim.io/doc/user/lsp.html) (`:help lsp`).
+nvim-lspconfig is a "data only" repo, providing basic, default [Nvim LSP client](https://neovim.io/doc/user/lsp.html)
+configurations for various LSP servers.
 
-* **Do not file Nvim LSP client issues here.** The Nvim LSP client does not live here. This is only a collection of LSP configs.
-* If you found a bug in the Nvim LSP client, [report it at the Nvim core repo](https://github.com/neovim/neovim/issues/new?assignees=&labels=bug%2Clsp&template=lsp_bug_report.yml).
-* These configs are **best-effort and supported by the community.** See [contributions](#contributions).
+View the [documentation for all configs](doc/server_configurations.md) or `:help lspconfig-all` from Nvim.
+
+## Important ⚠️
 
-See also `:help lspconfig`.
+* If you found a bug in the Nvim LSP functionality (`: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.
+* These configs are **best-effort and supported by the community.** See [contributions](#contributions).
+* **Note:** This repo only provides *configurations*. Its programmatic API is deprecated and should not be used externally.
+    * [Work is planned](https://github.com/neovim/neovim/issues/28479) to selectively upstream the
+      "framework" parts (*not* the configs) of nvim-lspconfig, to Nvim core, and deprecate them in
+      nvim-lspconfig.
 
 ## Install
 
 [![LuaRocks](https://img.shields.io/luarocks/v/neovim/nvim-lspconfig?logo=lua&color=purple)](https://luarocks.org/modules/neovim/nvim-lspconfig)
 
-* Requires neovim version 0.8 above. Update Nvim and nvim-lspconfig before reporting an issue.
-
-* Install nvim-lspconfig using builtin packages:
-
-      git clone https://github.com/neovim/nvim-lspconfig ~/.config/nvim/pack/nvim/start/nvim-lspconfig
-
-* Alternatively, nvim-lspconfig can be installed using a 3rd party plugin manager (consult the documentation for your plugin manager for details).
+* Requires Nvim 0.10 above. Update Nvim and nvim-lspconfig before reporting an issue.
+* Install nvim-lspconfig using Vim's "packages" feature:
+  ```
+  git clone https://github.com/neovim/nvim-lspconfig ~/.config/nvim/pack/nvim/start/nvim-lspconfig
+  ```
+* Or use a 3rd-party plugin manager (consult the documentation for your plugin manager).
 
 ## Quickstart
 
@@ -36,25 +42,22 @@ See also `:help lspconfig`.
    ```
 4. Run `:checkhealth lsp` to see the status or to troubleshoot.
 
-See [server_configurations.md](doc/server_configurations.md) (`:help lspconfig-all` from Nvim) for the full list of configs, including installation instructions and additional, optional, customization suggestions for each language server. For servers that are not on your system path (e.g., `jdtls`, `elixirls`), you must manually add `cmd` to the `setup` parameter. Most language servers can be installed in less than a minute.
+Read `:help lspconfig` for details. Read `:help lspconfig-all` for the full list of server-specific details.
+For servers not on your `$PATH` (e.g., `jdtls`, `elixirls`), you must manually set the `cmd` parameter when calling `setup()`.
 
 ## Configuration
 
-Nvim sets some default options whenever a buffer attaches to an LSP client. See [`:h lsp-config`][lsp-config] for more details. In particular, the following options are set:
+Nvim sets some default options and mappings when a buffer attaches to LSP (see [`:help lsp-config`][lsp-config]). In particular:
 
 * [`'tagfunc'`][tagfunc]
-  - Enables "go to definition" capabilities using [`<C-]>`][tagjump] and other [tag commands][tag-commands].
+    - 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. For *auto*completion, an [autocompletion plugin](https://github.com/neovim/nvim-lspconfig/wiki/Autocompletion) is required.
+    - Enables (manual) omni mode completion with `<C-X><C-O>` in Insert mode. For *auto*completion, an [autocompletion plugin](https://github.com/neovim/nvim-lspconfig/wiki/Autocompletion) is required.
 * [`'formatexpr'`][formatexpr]
-  - Enables LSP formatting with [`gq`][gq].
-
-Nvim also maps `K` to [`vim.lsp.buf.hover()`][vim.lsp.buf.hover] in Normal mode.
-
-Nvim 0.10 and newer creates the following default maps unconditionally:
-
-* `[d` and `]d` map to `vim.diagnostic.goto_prev()` and `vim.diagnostic.goto_next()` (respectively)
-* `<C-W>d` maps to `vim.diagnostic.open_float()`
+    - 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.goto_prev()` and `vim.diagnostic.goto_next()`, 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
@@ -88,16 +91,18 @@ lspconfig.rust_analyzer.setup {
 
 ## Troubleshooting
 
-If you have an issue, the first step is to reproduce with a [minimal configuration](https://github.com/neovim/nvim-lspconfig/blob/master/test/minimal_init.lua).
-
 The most common reasons a language server does not start or attach are:
 
-1. The language server is not installed. nvim-lspconfig does not install language servers for you. You should be able to run the `cmd` defined in each server's Lua module from the command line and see that the language server starts. If the `cmd` is an executable name instead of an absolute path to the executable, ensure it is on your path.
+1. Language server is not installed. nvim-lspconfig does not install language servers for you. You should be able to run the `cmd` defined in each server's Lua module from the command line and see that the language server starts. If the `cmd` is an executable name instead of an absolute path to the executable, ensure it is on your path.
 2. Missing filetype plugins. Certain languages are not detecting by vim/neovim because they have not yet been added to the filetype detection system. Ensure `:set ft?` shows the filetype and not an empty value.
 3. Not triggering root detection. **Some** language servers will only start if it is opened in a directory, or child directory, containing a file which signals the *root* of the project. Most of the time, this is a `.git` folder, but each server defines the root config in the lua file. See [server_configurations.md](doc/server_configurations.md) or the source for the list of root directories.
 4. You must pass `capabilities` for **each** `setup {}` if you want these to take effect.
 5. **Do not call `setup {}` twice for the same server**. The second call to `setup {}` will overwrite the first.
 
+## Bug reports
+
+If you found a bug with LSP functionality, [report it to Neovim core](https://github.com/neovim/neovim/issues/new?assignees=&labels=bug%2Clsp&template=lsp_bug_report.yml).
+
 Before reporting a bug, check your logs and the output of `:LspInfo`. Add the following to your init.vim to enable logging:
 
 ```lua
@@ -118,18 +123,9 @@ Most of the time, the reason for failure is present in the logs.
 * `:LspStop <client_id>` Defaults to stopping all buffer clients.
 * `:LspRestart <client_id>` Defaults to restarting all buffer clients.
 
-## Wiki
-
-See the [wiki](https://github.com/neovim/nvim-lspconfig/wiki) for additional topics, including:
-
-* [Automatic server installation](https://github.com/neovim/nvim-lspconfig/wiki/Installing-language-servers#automatically)
-* [Snippets support](https://github.com/neovim/nvim-lspconfig/wiki/Snippets)
-* [Project local settings](https://github.com/neovim/nvim-lspconfig/wiki/Project-local-settings)
-* [Recommended plugins for enhanced language server features](https://github.com/neovim/nvim-lspconfig/wiki/Language-specific-plugins)
-
 ## Contributions
 
-If you are missing a language server on the list in [server_configurations.md](doc/server_configurations.md), contributing
+If a language server is missing from [server_configurations.md](doc/server_configurations.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).