docs: rework Installation & Setup sections, and other minor adjustments (#1951)

Author: williamboman

README.md

@@ -4,7 +4,9 @@
 [![GitHub CI](https://github.com/mason-org/mason.nvim/workflows/Tests/badge.svg)](https://github.com/mason-org/mason.nvim/actions?query=workflow%3ATests+branch%3Amain+event%3Apush)
 [![Sponsors](https://img.shields.io/github/sponsors/williamboman)](https://github.com/sponsors/williamboman)
 
-<img src="https://user-images.githubusercontent.com/6705160/177613416-0c0354d2-f431-40d8-87f0-21310f0bba0e.png" alt="mason.nvim" />
+<h1>
+    <img src="https://user-images.githubusercontent.com/6705160/177613416-0c0354d2-f431-40d8-87f0-21310f0bba0e.png" alt="mason.nvim" />
+</h1>
 
 <p align="center">
     Portable package manager for Neovim that runs everywhere Neovim runs.<br />
@@ -17,19 +19,18 @@
     <sup>Latest version: v2.0.0</sup> <!-- x-release-please-version -->
 </p>
 
-# Table of Contents
+## Table of Contents
 
 -   [Introduction](#introduction)
--   [Screenshots](#screenshots)
+-   [Installation & Usage](#installation--usage)
+    - [Recommended setup for `lazy.nvim`](#recommended-setup-for-lazynvim)
 -   [Requirements](#requirements)
--   [Installation](#installation)
--   [Setup](#setup)
-    -   [Extensions](#extensions)
 -   [Commands](#commands)
 -   [Registries](#registries)
+-   [Screenshots](#screenshots)
 -   [Configuration](#configuration)
 
-# Introduction
+## Introduction
 
 > [`:h mason-introduction`][help-mason-introduction]
 
@@ -39,18 +40,38 @@ with only a small set of [external requirements](#requirements) needed.
 
 Packages are installed in Neovim's data directory ([`:h standard-path`][help-standard-path]) by default. Executables are
 linked to a single `bin/` directory, which `mason.nvim` will add to Neovim's PATH during setup, allowing seamless access
-from Neovim builtins (shell, terminal, etc.) as well as other 3rd party plugins.
+from Neovim builtins (LSP client, shell, terminal, etc.) as well as other 3rd party plugins.
 
 For a list of all available packages, see <https://mason-registry.dev/registry/list>.
 
-## Screenshots
+## Installation & Usage
 
-|                                                                                                                                                        |                                                                                                                                                  |                                                                                                                                        |
-| :----------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------: |
-|           <img alt="Main window" src="https://user-images.githubusercontent.com/6705160/177617680-d62caf26-f253-4ace-ab57-4b590595adca.png">           |                 <img src="https://user-images.githubusercontent.com/6705160/177617684-6bb4c13f-1235-4ac9-829e-120b06f7437b.png">                 | <img alt="Language filter" src="https://user-images.githubusercontent.com/6705160/177617688-8f9ba225-00c8-495c-9c4c-b74240d6f280.png"> |
-| <img alt="LSP server configuration schema" src="https://user-images.githubusercontent.com/6705160/177617692-02c6ddde-a97e-42b4-bca4-4f4caf45d569.png"> | <img alt="Checking for new versions" src="https://user-images.githubusercontent.com/6705160/180648183-69077d10-8795-4da6-ba4d-57ecf0cb25c9.png"> |   <img alt="Help window" src="https://user-images.githubusercontent.com/6705160/180648292-136a0888-0fb6-4226-aa29-53bd3ffed400.png">   |
+> [`:h mason-quickstart`][help-mason-quickstart]
+
+Install using your plugin manager of choice. **Setup is required**:
+
+```lua
+require("mason").setup()
+```
+
+`mason.nvim` is optimized to load as little as possible during setup. Lazy-loading the plugin, or somehow deferring the
+setup, is not recommended.
+
+Refer to the [Configuration](#configuration) section for information about which settings are available.
+
+### Recommended setup for `lazy.nvim`
 
-# Requirements
+The following is the recommended setup when using `lazy.nvim`. It will set up the plugin for you, meaning **you don't have
+to call `require("mason").setup()` yourself**.
+
+```lua
+{
+    "mason-org/mason.nvim",
+    opts = {}
+}
+```
+
+## Requirements
 
 > [`:h mason-requirements`][help-mason-requirements]
 
@@ -85,50 +106,7 @@ your personal usage, some of these will also need to be installed. Refer to `:ch
 [winzip]: https://www.winzip.com/
 [winrar]: https://www.win-rar.com/
 
-# Installation
-
-## [Packer](https://github.com/wbthomason/packer.nvim)
-
-```lua
-use {
-    "mason-org/mason.nvim"
-}
-```
-
-## [lazy.nvim](https://github.com/folke/lazy.nvim)
-
-```lua
-{
-    "mason-org/mason.nvim"
-}
-```
-
-## [vim-plug](https://github.com/junegunn/vim-plug)
-
-```vim
-Plug 'mason-org/mason.nvim'
-```
-
-# Setup
-
-> [`:h mason-quickstart`][help-mason-quickstart]
-
-```lua
-require("mason").setup()
-```
-
-`mason.nvim` is optimized to load as little as possible during setup. Lazy-loading the plugin, or somehow deferring the
-setup, is not recommended.
-
-Refer to the [Configuration](#configuration) section for information about which settings are available.
-
-## Extensions
-
-Refer to the [Wiki](https://github.com/mason-org/mason.nvim/wiki/Extensions) for a list of 3rd party extensions.
-
--   [`mason-lspconfig.nvim`](https://github.com/mason-org/mason-lspconfig.nvim) - recommended for usage with `lspconfig`
-
-# Commands
+## Commands
 
 > [`:h mason-commands`][help-mason-commands]
 
@@ -139,17 +117,24 @@ Refer to the [Wiki](https://github.com/mason-org/mason.nvim/wiki/Extensions) for
 -   `:MasonUninstallAll` - uninstalls all packages
 -   `:MasonLog` - opens the `mason.nvim` log file in a new tab window
 
-# Registries
+## Registries
 
 Mason's core package registry is located at [mason-org/mason-registry](https://github.com/mason-org/mason-registry).
 Before any packages can be used, the registry needs to be downloaded. This is done automatically for you when using the
 different Mason commands (e.g. `:MasonInstall`), but can also be done manually by using the `:MasonUpdate` command.
 
 If you're utilizing Mason's Lua APIs to access packages, it's recommended to use the
-[`:h mason-registry.refresh()`][help-mason-registry-refresh] and/or [`:h mason-registry.update()`][help-mason-registry-update]
+[`:h mason-registry.refresh()`][help-mason-registry-refresh] or [`:h mason-registry.update()`][help-mason-registry-update]
 functions to ensure you have the latest package information before retrieving packages.
 
-# Configuration
+## Screenshots
+
+|                                                                                                                                                        |                                                                                                                                                  |                                                                                                                                        |
+| :----------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------: |
+|           <img alt="Main window" src="https://github.com/user-attachments/assets/b9a57d21-f551-45ad-a1e5-a9fd66291510">           |                 <img alt="Language search" src="https://github.com/user-attachments/assets/3d24fb7b-2c57-4948-923b-0a42bb627cbe">                 | <img alt="Language filter" src="https://github.com/user-attachments/assets/c0ca5818-3c74-4071-bc41-427a2cd1056d"> |
+| <img alt="Package information" src="https://github.com/user-attachments/assets/6f9f6819-ac97-483d-a77c-8f6c6131ac85"> | <img alt="New package versions" src="https://github.com/user-attachments/assets/ff1adc4d-2fcc-46df-ab4c-291c891efa50"> |   <img alt="Help window" src="https://github.com/user-attachments/assets/1fbe75e4-fe69-4417-83e3-82329e1c236e">   |
+
+## Configuration
 
 > [`:h mason-settings`][help-mason-settings]
 
@@ -170,7 +155,24 @@ require("mason").setup({
 })
 ```
 
-## Default configuration
+### Configuration using `lazy.nvim`
+
+```lua
+{
+    "mason-org/mason.nvim",
+    opts = {
+        ui = {
+            icons = {
+                package_installed = "✓",
+                package_pending = "➜",
+                package_uninstalled = "✗"
+            }
+        }
+    }
+}
+```
+
+### Default configuration
 
 ```lua
 ---@class MasonSettings
@@ -322,11 +324,11 @@ local DEFAULT_SETTINGS = {
 👋 didn't find what you were looking for? Try looking in the <a href="./doc/mason.txt">help docs</a> <code>:help mason.nvim</code>!
 </sup>
 
-[help-mason-commands]: ./doc/mason.txt#L178
+[help-mason-commands]: ./doc/mason.txt#L140
 [help-mason-introduction]: ./doc/mason.txt#L11
-[help-mason-quickstart]: ./doc/mason.txt#L67
-[help-mason-registry-refresh]: ./doc/mason.txt#L549
-[help-mason-registry-update]: ./doc/mason.txt#L542
-[help-mason-requirements]: ./doc/mason.txt#L50
-[help-mason-settings]: ./doc/mason.txt#L238
+[help-mason-quickstart]: ./doc/mason.txt#L42
+[help-mason-registry-refresh]: ./doc/mason.txt#L520
+[help-mason-registry-update]: ./doc/mason.txt#L513
+[help-mason-requirements]: ./doc/mason.txt#L25
+[help-mason-settings]: ./doc/mason.txt#L200
 [help-standard-path]: https://neovim.io/doc/user/starting.html#standard-path

doc/mason.txt

@@ -50,7 +50,7 @@ function:
     require("mason").setup()
 <
 Mason will do the following during setup:
-    1) enhance the Neovim session's PATH environment
+    1) add Mason's `bin/` directory to the Neovim session's PATH
     2) register commands (|mason-commands|)
 
 Refer to |mason-settings| for all available settings.