From 9eaedb864cdadc29c6eb7d761a6c0d8aee26c91b Mon Sep 17 00:00:00 2001 From: William Boman Date: Tue, 20 May 2025 12:26:06 +0200 Subject: docs: rework Installation & Setup sections, and other minor adjustments (#1951) --- README.md | 138 +++++++++++++++++++++++++++++----------------------------- doc/mason.txt | 2 +- 2 files changed, 71 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index ed3a3ff4..559ff830 100644 --- a/README.md +++ b/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) -mason.nvim +

+ mason.nvim +

Portable package manager for Neovim that runs everywhere Neovim runs.
@@ -17,19 +19,18 @@ Latest version: v2.0.0

-# 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 . -## Screenshots +## Installation & Usage -| | | | -| :----------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------: | -| Main window | | Language filter | -| LSP server configuration schema | Checking for new versions | Help window | +> [`: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 + +| | | | +| :----------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------: | +| Main window | Language search | Language filter | +| Package information | New package versions | Help window | + +## 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 help docs :help mason.nvim! -[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 diff --git a/doc/mason.txt b/doc/mason.txt index 034463bf..091982a2 100644 --- a/doc/mason.txt +++ b/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. -- cgit v1.2.3-70-g09d2