From c94873e785ea53a309d654e306340752eacda097 Mon Sep 17 00:00:00 2001 From: Folke Lemaitre Date: Sun, 23 Jun 2024 20:20:49 +0200 Subject: [PATCH] feat: more docs --- .github/workflows/deploy.yaml | 1 + README.footer.md | 0 README.header.md | 31 ++ README.md | 961 ++------------------------------- README.vim.md | 969 ++++++++++++++++++++++++++++++++++ lua/build.lua | 26 +- 6 files changed, 1053 insertions(+), 935 deletions(-) create mode 100644 README.footer.md create mode 100644 README.header.md create mode 100644 README.vim.md diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml index 80a7edd..4277381 100644 --- a/.github/workflows/deploy.yaml +++ b/.github/workflows/deploy.yaml @@ -32,6 +32,7 @@ jobs: vimdoc: lazy.nvim version: "Neovim >= 0.8.0" description: "A modern plugin manager for Neovim" + pandoc: "README.vim.md" demojify: false treesitter: true - name: Push changes diff --git a/README.footer.md b/README.footer.md new file mode 100644 index 0000000..e69de29 diff --git a/README.header.md b/README.header.md new file mode 100644 index 0000000..3abccc4 --- /dev/null +++ b/README.header.md @@ -0,0 +1,31 @@ +

+ Install + ยท + Configure + ยท + Docs +

+ +

+ + Latest release + + + Last commit + + + License + + + Stars + + + Issues + + + Repo Size + + + follow on Twitter + +

diff --git a/README.md b/README.md index 50fd0fe..ade77de 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,35 @@ +

+ Install + ยท + Configure + ยท + Docs +

+ +

+ + Latest release + + + Last commit + + + License + + + Stars + + + Issues + + + Repo Size + + + follow on Twitter + +

+ # ๐Ÿš€ Getting Started **lazy.nvim** is a modern plugin manager for Neovim. @@ -28,931 +60,4 @@ - Neovim >= **0.8.0** (needs to be built with **LuaJIT**) - Git >= **2.19.0** (for partial clones support) -- a [Nerd Font](https://www.nerdfonts.com/) **_(optional)_** -# ๐Ÿ› ๏ธ Installation - -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; - -There are multiple ways to install **lazy.nvim**. -The **Structured Setup** is the recommended way, but you can also use the **Single File Setup** -if you prefer to keep everything in your `init.lua`. - -Please refer to the [Configuration](/configuration) section for an overview of all available options. - -:::tip - -It is recommended to run `:checkhealth lazy` after installation. - -::: - -:::note - -In what follows `~/.config/nvim` is your Neovim configuration directory. -On Windows, this is usually `~\AppData\Local\nvim`. -To know the correct path for your system, run `:echo stdpath('config')`. - -::: - -## Structured Setup - -```lua -require("config.lazy") -``` - -```lua --- Bootstrap lazy.nvim -local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim" -if not (vim.uv or vim.loop).fs_stat(lazypath) then - local lazyrepo = "https://github.com/folke/lazy.nvim.git" - vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath }) -end -vim.opt.rtp:prepend(lazypath) - --- Make sure to setup `mapleader` and `maplocalleader` before --- loading lazy.nvim so that mappings are correct. --- This is also a good place to setup other settings (vim.opt) -vim.g.mapleader = " " -vim.g.maplocalleader = "\\" - --- Setup lazy.nvim -require("lazy").setup({ - -- highlight-start - spec = { - -- import your plugins - { import = "plugins" }, - }, - -- highlight-end - -- Configure any other settings here. See the documentation for more details. - -- colorscheme that will be used when installing plugins. - install = { colorscheme = { "habamax" } }, - -- automatically check for plugin updates - checker = { enabled = true }, -}) -``` - -You can then create your plugin specs in `~/.config/nvim/lua/plugins/`. -Each file should return a table with the plugins you want to install. - -For more info see [Structuring Your Plugins](/usage/structuring) - -
-~/.config/nvim
-โ”œโ”€โ”€ lua
-โ”‚ย ย  โ”œโ”€โ”€ config
-โ”‚ย ย  โ”‚ย ย  โ””โ”€โ”€ lazy.lua
-โ”‚ย ย  โ””โ”€โ”€ plugins
-โ”‚ย ย      โ”œโ”€โ”€ spec1.lua
-โ”‚ย ย      โ”œโ”€โ”€ **
-โ”‚ย ย      โ””โ”€โ”€ spec2.lua
-โ””โ”€โ”€ init.lua
-
- -## Single File Setup - -```lua --- Bootstrap lazy.nvim -local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim" -if not (vim.uv or vim.loop).fs_stat(lazypath) then - local lazyrepo = "https://github.com/folke/lazy.nvim.git" - vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath }) -end -vim.opt.rtp:prepend(lazypath) - --- Make sure to setup `mapleader` and `maplocalleader` before --- loading lazy.nvim so that mappings are correct. --- This is also a good place to setup other settings (vim.opt) -vim.g.mapleader = " " -vim.g.maplocalleader = "\\" - --- Setup lazy.nvim -require("lazy").setup({ - -- highlight-start - spec = { - -- add your plugins here - }, - -- highlight-end - -- Configure any other settings here. See the documentation for more details. - -- colorscheme that will be used when installing plugins. - install = { colorscheme = { "habamax" } }, - -- automatically check for plugin updates - checker = { enabled = true }, -}) -``` -# ๐Ÿ”Œ Plugin Spec - -## Source - -| Property | Type | Description | -| --------- | ---------- | -------------------------------------------------------------------------------------------------------------------- | -| **\[1\]** | `string?` | Short plugin url. Will be expanded using [`config.git.url_format`](../configuration/). Can also be a `url` or `dir`. | -| **dir** | `string?` | A directory pointing to a local plugin | -| **url** | `string?` | A custom git url where the plugin is hosted | -| **name** | `string?` | A custom name for the plugin used for the local plugin directory and as the display name | -| **dev** | `boolean?` | When `true`, a local plugin directory will be used instead. See [`config.dev`](../configuration/) | - -A valid spec should define one of `[1]`, `dir` or `url`. - -## Loading - -| Property | Type | Description | -| ---------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **dependencies** | `LazySpec[]` | A list of plugin names or plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise. When specifying a name, make sure the plugin spec has been defined somewhere else. | -| **enabled** | `boolean?` or `fun():boolean` | When `false`, or if the `function` returns false, then this plugin will not be included in the spec | -| **cond** | `boolean?` or `fun(LazyPlugin):boolean` | Behaves the same as `enabled`, but won't uninstall the plugin when the condition is `false`. Useful to disable some plugins in vscode, or firenvim for example. | -| **priority** | `number?` | Only useful for **start** plugins (`lazy=false`) to force loading certain plugins first. Default priority is `50`. It's recommended to set this to a high number for colorschemes. | - -## Setup - -| Property | Type | Description | -| ---------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **init** | `fun(LazyPlugin)` | `init` functions are always executed during startup | -| **opts** | `table` or `fun(LazyPlugin, opts:table)` | `opts` should be a table (will be merged with parent specs), return a table (replaces parent specs) or should change a table. The table will be passed to the `Plugin.config()` function. Setting this value will imply `Plugin.config()` | -| **config** | `fun(LazyPlugin, opts:table)` or `true` | `config` is executed when the plugin loads. The default implementation will automatically run `require(MAIN).setup(opts)` if `opts` or `config = true` is set. Lazy uses several heuristics to determine the plugin's `MAIN` module automatically based on the plugin's **name**. See also `opts`. To use the default implementation without `opts` set `config` to `true`. | -| **main** | `string?` | You can specify the `main` module to use for `config()` and `opts()`, in case it can not be determined automatically. See `config()` | -| **build** | `fun(LazyPlugin)` or `string` or a list of build commands | `build` is executed when a plugin is installed or updated. Before running `build`, a plugin is first loaded. If it's a string it will be run as a shell command. When prefixed with `:` it is a Neovim command. You can also specify a list to executed multiple build commands. Some plugins provide their own `build.lua` which is automatically used by lazy. So no need to specify a build step for those plugins. | -| **rocks** | `string[]?` | Add any [luarocks](https://luarocks.org/) dependencies. | - -## Lazy Loading - -| Property | Type | Description | -| --------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **lazy** | `boolean?` | When `true`, the plugin will only be loaded when needed. Lazy-loaded plugins are automatically loaded when their Lua modules are `required`, or when one of the lazy-loading handlers triggers | -| **event** | `string?` or `string[]` or `fun(self:LazyPlugin, event:string[]):string[]` or `{event:string[]\|string, pattern?:string[]\|string}` | Lazy-load on event. Events can be specified as `BufEnter` or with a pattern like `BufEnter *.lua` | -| **cmd** | `string?` or `string[]` or `fun(self:LazyPlugin, cmd:string[]):string[]` | Lazy-load on command | -| **ft** | `string?` or `string[]` or `fun(self:LazyPlugin, ft:string[]):string[]` | Lazy-load on filetype | -| **keys** | `string?` or `string[]` or `LazyKeysSpec[]` or `fun(self:LazyPlugin, keys:string[]):(string \| LazyKeysSpec)[]` | Lazy-load on [key mapping](/spec/lazy_loading#%EF%B8%8F-lazy-key-mappings) | - -Refer to the [Lazy Loading](./lazy_loading.md) section for more information. - -## Versioning - -| Property | Type | Description | -| -------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| **branch** | `string?` | Branch of the repository | -| **tag** | `string?` | Tag of the repository | -| **commit** | `string?` | Commit of the repository | -| **version** | `string?` or `false` to override the default | Version to use from the repository. Full [Semver](https://devhints.io/semver) ranges are supported | -| **pin** | `boolean?` | When `true`, this plugin will not be included in updates | -| **submodules** | `boolean?` | When false, git submodules will not be fetched. Defaults to `true` | - -Refer to the [Versioning](./versioning.md) section for more information. - -## Advanced - -| Property | Type | Description | -| ------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **optional** | `boolean?` | When a spec is tagged optional, it will only be included in the final spec, when the same plugin has been specified at least once somewhere else without `optional`. This is mainly useful for Neovim distros, to allow setting options on plugins that may/may not be part of the user's plugins. | -| **specs** | `LazySpec` | A list of plugin specs defined in the scope of the plugin. This is mainly useful for Neovim distros, to allow setting options on plugins that may/may not be part of the user's plugins. When the plugin is disabled, none of the scoped specs will be included in the final spec. Similar to `dependencies` without the automatic loading of the specs. | -| **module** | `false?` | Do not automatically load this Lua module when it's required somewhere | -| **import** | `string?` | Import the given spec module. | -## Examples - -```lua -return { - -- the colorscheme should be available when starting Neovim - { - "folke/tokyonight.nvim", - lazy = false, -- make sure we load this during startup if it is your main colorscheme - priority = 1000, -- make sure to load this before all the other start plugins - config = function() - -- load the colorscheme here - vim.cmd([[colorscheme tokyonight]]) - end, - }, - - -- I have a separate config.mappings file where I require which-key. - -- With lazy the plugin will be automatically loaded when it is required somewhere - { "folke/which-key.nvim", lazy = true }, - - { - "nvim-neorg/neorg", - -- lazy-load on filetype - ft = "norg", - -- options for neorg. This will automatically call `require("neorg").setup(opts)` - opts = { - load = { - ["core.defaults"] = {}, - }, - }, - }, - - { - "dstein64/vim-startuptime", - -- lazy-load on a command - cmd = "StartupTime", - -- init is called during startup. Configuration for vim plugins typically should be set in an init function - init = function() - vim.g.startuptime_tries = 10 - end, - }, - - { - "hrsh7th/nvim-cmp", - -- load cmp on InsertEnter - event = "InsertEnter", - -- these dependencies will only be loaded when cmp loads - -- dependencies are always lazy-loaded unless specified otherwise - dependencies = { - "hrsh7th/cmp-nvim-lsp", - "hrsh7th/cmp-buffer", - }, - config = function() - -- ... - end, - }, - - -- if some code requires a module from an unloaded plugin, it will be automatically loaded. - -- So for api plugins like devicons, we can always set lazy=true - { "nvim-tree/nvim-web-devicons", lazy = true }, - - -- you can use the VeryLazy event for things that can - -- load later and are not important for the initial UI - { "stevearc/dressing.nvim", event = "VeryLazy" }, - - { - "Wansmer/treesj", - keys = { - { "J", "TSJToggle", desc = "Join Toggle" }, - }, - opts = { use_default_keymaps = false, max_join_length = 150 }, - }, - - { - "monaqa/dial.nvim", - -- lazy-load on keys - -- mode is `n` by default. For more advanced options, check the section on key mappings - keys = { "", { "", mode = "n" } }, - }, - - -- local plugins need to be explicitly configured with dir - { dir = "~/projects/secret.nvim" }, - - -- you can use a custom url to fetch a plugin - { url = "git@github.com:folke/noice.nvim.git" }, - - -- local plugins can also be configured with the dev option. - -- This will use {config.dev.path}/noice.nvim/ instead of fetching it from GitHub - -- With the dev option, you can easily switch between the local and installed version of a plugin - { "folke/noice.nvim", dev = true }, -} -``` -## Lazy Loading - -**lazy.nvim** automagically lazy-loads Lua modules. This means that if -you have a plugin `A` that is lazy-loaded and a plugin `B` that requires a -module of plugin `A`, then plugin `A` will be loaded on demand as expected. - -:::tip - -You can configure **lazy.nvim** to lazy-load all plugins by default with `config.defaults.lazy = true`. -Make sure you've configured lazy-loading, for your plugins to avoid unexpected behavior. -Only do this if you know what you are doing, as it can lead to unexpected behavior. - -::: - -Additionally, you can also lazy-load on **events**, **commands**, -**file types** and **key mappings**. - -Plugins will be lazy-loaded when one of the following is `true`: - -- The plugin only exists as a dependency in your spec -- It has an `event`, `cmd`, `ft` or `keys` key -- `config.defaults.lazy == true` - -### ๐ŸŒˆ Colorschemes - -Colorscheme plugins can be configured with `lazy=true`. The plugin will automagically load -when doing `colorscheme foobar`. - -:::warning - -since **start** plugins can possibly change existing highlight groups, -it's important to make sure that your main **colorscheme** is loaded first. -To ensure this you can use the `priority=1000` field. **_(see the [examples](./examples.md))_** - -::: - -### โŒจ๏ธ Lazy Key Mappings - -The `keys` property can be a `string` or `string[]` for simple normal-mode mappings, or it -can be a `LazyKeysSpec` table with the following key-value pairs: - -- **[1]**: (`string`) lhs **_(required)_** -- **[2]**: (`string|fun()`) rhs **_(optional)_** -- **mode**: (`string|string[]`) mode **_(optional, defaults to `"n"`)_** -- **ft**: (`string|string[]`) `filetype` for buffer-local keymaps **_(optional)_** -- any other option valid for `vim.keymap.set` - -Key mappings will load the plugin the first time they get executed. - -When `[2]` is `nil`, then the real mapping has to be created by the `config()` function. - -```lua --- Example for neo-tree.nvim -{ - "nvim-neo-tree/neo-tree.nvim", - keys = { - { "ft", "Neotree toggle", desc = "NeoTree" }, - }, - config = function() - require("neo-tree").setup() - end, -} -``` -## Versioning - -If you want to install a specific revision of a plugin, you can use `commit`, -`tag`, `branch`, `version`. - -The `version` property supports [Semver](https://semver.org/) ranges. - -:::tip - -You can set `config.defaults.version = "*"` to install the latest stable -version of plugins that support Semver. - -::: - -### Examples - -- `*`: latest stable version (this excludes pre-release versions) -- `1.2.x`: any version that starts with `1.2`, such as `1.2.0`, `1.2.3`, etc. -- `^1.2.3`: any version that is compatible with `1.2.3`, such as `1.3.0`, `1.4.5`, etc., but not `2.0.0`. -- `~1.2.3`: any version that is compatible with `1.2.3`, such as `1.2.4`, `1.2.5`, but not `1.3.0`. -- `>1.2.3`: any version that is greater than `1.2.3`, such as `1.3.0`, `1.4.5`, etc. -- `>=1.2.3`: any version that is greater than or equal to `1.2.3`, such as `1.2.3`, `1.3.0`, `1.4.5`, etc. -- `<1.2.3`: any version that is less than `1.2.3`, such as `1.1.0`, `1.0.5`, etc. -- `<=1.2.3`: any version that is less than or equal to `1.2.3`, such as `1.2.3`, `1.1.0`, `1.0.5`, etc -# ๐Ÿ“ฆ Packages - -**lazy.nvim** supports three ways for plugins to define their dependencies and configuration. - -- **Lazy**: `lazy.lua` file -- **Rockspec**: [luarocks](https://luarocks.org/) `*-scm-1.rockspec` [file](https://github.com/luarocks/luarocks/wiki/Rockspec-format) -- **Packspec**: `pkg.json` (experimental, since the [format](https://github.com/neovim/packspec/issues/41) is not quite there yet) - -You can enable/disable package sources with [`config.pkg.sources`](/configuration). -The order of sources is important, as the first source that finds a package will be used. - -:::info - -Package specs are always loaded in the scope of the plugin (using [specs](/spec#advanced)), -so that when the plugin is disabled, none of the specs are loaded. - -::: - -## Lazy - -Using a `lazy.lua` file is the recommended way to define your plugin dependencies and configuration. -Syntax is the same as any plugin spec. - -## Rockspec - -When a plugin contains a `*-scm-1.rockspec` file, **lazy.nvim** will automatically load its [`rocks`](/spec#setup) dependencies. - -## Packspec - -Supports the [pkg.json](https://github.com/nvim-lua/nvim-package-specification/issues/41) format, -with a lazy extension in `lazy`. -`lazy` can contain any valid lazy spec fields. They will be added to the plugin's spec. -# โš™๏ธ Configuration - -**lazy.nvim** comes with the following defaults: - -```lua -{ - root = vim.fn.stdpath("data") .. "/lazy", -- directory where plugins will be installed - defaults = { - -- By default, only LazyVim plugins will be lazy-loaded. Your custom plugins will load during startup. - -- If you know what you're doing, you can set this to `true` to have all your custom plugins lazy-loaded by default. - lazy = false, -- should plugins be lazy-loaded? - -- It's recommended to leave version=false for now, since a lot the plugin that support versioning, - -- have outdated releases, which may break your Neovim install. - version = nil, -- always use the latest git commit - -- version = "*", -- try installing the latest stable version for plugins that support semver - -- default `cond` you can use to globally disable a lot of plugins - -- when running inside vscode for example - cond = nil, ---@type boolean|fun(self:LazyPlugin):boolean|nil - -- version = "*", -- enable this to try installing the latest stable versions of plugins - }, - -- leave nil when passing the spec as the first argument to setup() - spec = nil, ---@type LazySpec - local_spec = true, -- load project specific .lazy.lua spec files. They will be added at the end of the spec. - lockfile = vim.fn.stdpath("config") .. "/lazy-lock.json", -- lockfile generated after running update. - ---@type number? limit the maximum amount of concurrent tasks - concurrency = jit.os:find("Windows") and (vim.uv.available_parallelism() * 2) or nil, - git = { - -- defaults for the `Lazy log` command - -- log = { "--since=3 days ago" }, -- show commits from the last 3 days - log = { "-8" }, -- show the last 8 commits - timeout = 120, -- kill processes that take more than 2 minutes - url_format = "https://github.com/%s.git", - -- lazy.nvim requires git >=2.19.0. If you really want to use lazy with an older version, - -- then set the below to false. This should work, but is NOT supported and will - -- increase downloads a lot. - filter = true, - }, - pkg = { - enabled = true, - cache = vim.fn.stdpath("state") .. "/lazy/pkg-cache.lua", - versions = true, -- Honor versions in pkg sources - -- the first package source that is found for a plugin will be used. - sources = { - "lazy", - "rockspec", - "packspec", - }, - }, - rocks = { - root = vim.fn.stdpath("data") .. "/lazy-rocks", - server = "https://nvim-neorocks.github.io/rocks-binaries/", - }, - dev = { - ---@type string | fun(plugin: LazyPlugin): string directory where you store your local plugin projects - path = "~/projects", - ---@type string[] plugins that match these patterns will use your local versions instead of being fetched from GitHub - patterns = {}, -- For example {"folke"} - fallback = false, -- Fallback to git when local plugin doesn't exist - }, - install = { - -- install missing plugins on startup. This doesn't increase startup time. - missing = true, - -- try to load one of these colorschemes when starting an installation during startup - colorscheme = { "habamax" }, - }, - ui = { - -- a number <1 is a percentage., >1 is a fixed size - size = { width = 0.8, height = 0.8 }, - wrap = true, -- wrap the lines in the ui - -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|. - border = "none", - -- The backdrop opacity. 0 is fully opaque, 100 is fully transparent. - backdrop = 60, - title = nil, ---@type string only works when border is not "none" - title_pos = "center", ---@type "center" | "left" | "right" - -- Show pills on top of the Lazy window - pills = true, ---@type boolean - icons = { - cmd = "๎ฏ‡ ", - config = "๏€“", - event = "๎ช† ", - favorite = "๏€… ", - ft = "๏€– ", - init = "๏€“ ", - import = "๎‰ฝ ", - keys = "๏„œ ", - lazy = "๓ฐ’ฒ ", - loaded = "โ—", - not_loaded = "โ—‹", - plugin = "๏’‡ ", - runtime = "๎Ÿ… ", - require = "๓ฐขฑ ", - source = "๏„ก ", - start = "๎ซ“ ", - task = "โœ” ", - list = { - "โ—", - "โžœ", - "โ˜…", - "โ€’", - }, - }, - -- leave nil, to automatically select a browser depending on your OS. - -- If you want to use a specific browser, you can define it here - browser = nil, ---@type string? - throttle = 20, -- how frequently should the ui process render events - custom_keys = { - -- You can define custom key maps here. If present, the description will - -- be shown in the help menu. - -- To disable one of the defaults, set it to false. - - ["l"] = { - function(plugin) - require("lazy.util").float_term({ "lazygit", "log" }, { - cwd = plugin.dir, - }) - end, - desc = "Open lazygit log", - }, - - ["t"] = { - function(plugin) - require("lazy.util").float_term(nil, { - cwd = plugin.dir, - }) - end, - desc = "Open terminal in plugin dir", - }, - }, - }, - diff = { - -- diff command can be one of: - -- * browser: opens the github compare view. Note that this is always mapped to as well, - -- so you can have a different command for diff - -- * git: will run git diff and open a buffer with filetype git - -- * terminal_git: will open a pseudo terminal with git diff - -- * diffview.nvim: will open Diffview to show the diff - cmd = "git", - }, - checker = { - -- automatically check for plugin updates - enabled = false, - concurrency = nil, ---@type number? set to 1 to check for updates very slowly - notify = true, -- get a notification when new updates are found - frequency = 3600, -- check for updates every hour - check_pinned = false, -- check for pinned packages that can't be updated - }, - change_detection = { - -- automatically check for config file changes and reload the ui - enabled = true, - notify = true, -- get a notification when changes are found - }, - performance = { - cache = { - enabled = true, - }, - reset_packpath = true, -- reset the package path to improve startup time - rtp = { - reset = true, -- reset the runtime path to $VIMRUNTIME and your config directory - ---@type string[] - paths = {}, -- add any custom paths here that you want to includes in the rtp - ---@type string[] list any plugins you want to disable here - disabled_plugins = { - -- "gzip", - -- "matchit", - -- "matchparen", - -- "netrwPlugin", - -- "tarPlugin", - -- "tohtml", - -- "tutor", - -- "zipPlugin", - }, - }, - }, - -- lazy can generate helptags from the headings in markdown readme files, - -- so :help works even for plugins that don't have vim docs. - -- when the readme opens with :help it will be correctly displayed as markdown - readme = { - enabled = true, - root = vim.fn.stdpath("state") .. "/lazy/readme", - files = { "README.md", "lua/**/README.md" }, - -- only generate markdown helptags for plugins that dont have docs - skip_if_doc_exists = true, - }, - state = vim.fn.stdpath("state") .. "/lazy/state.json", -- state info for checker and other things - build = { - -- Plugins can provide a `build.lua` file that will be executed when the plugin is installed - -- or updated. When the plugin spec also has a `build` command, the plugin's `build.lua` not be - -- executed. In this case, a warning message will be shown. - warn_on_override = true, - }, - -- Enable profiling of lazy.nvim. This will add some overhead, - -- so only enable this when you are debugging lazy.nvim - profiling = { - -- Enables extra stats on the debug tab related to the loader cache. - -- Additionally gathers stats about all package.loaders - loader = false, - -- Track each new require in the Lazy profiling tab - require = false, - }, -} -``` - -
-If you don't want to use a Nerd Font, you can replace the icons with Unicode symbols. - -```lua -{ - ui = { - icons = { - cmd = "โŒ˜", - config = "๐Ÿ› ", - event = "๐Ÿ“…", - ft = "๐Ÿ“‚", - init = "โš™", - keys = "๐Ÿ—", - plugin = "๐Ÿ”Œ", - runtime = "๐Ÿ’ป", - require = "๐ŸŒ™", - source = "๐Ÿ“„", - start = "๐Ÿš€", - task = "๐Ÿ“Œ", - lazy = "๐Ÿ’ค ", - }, - }, -} -``` - -
-## ๐ŸŒˆ Highlight Groups - -| Highlight Group | Default Group | Description | -| --- | --- | --- | -| **LazyButton** | ***CursorLine*** | | -| **LazyButtonActive** | ***Visual*** | | -| **LazyComment** | ***Comment*** | | -| **LazyCommit** | ***@variable.builtin*** | commit ref | -| **LazyCommitIssue** | ***Number*** | | -| **LazyCommitScope** | ***Italic*** | conventional commit scope | -| **LazyCommitType** | ***Title*** | conventional commit type | -| **LazyDimmed** | ***Conceal*** | property | -| **LazyDir** | ***@markup.link*** | directory | -| **LazyH1** | ***IncSearch*** | home button | -| **LazyH2** | ***Bold*** | titles | -| **LazyLocal** | ***Constant*** | | -| **LazyNoCond** | ***DiagnosticWarn*** | unloaded icon for a plugin where `cond()` was false | -| **LazyNormal** | ***NormalFloat*** | | -| **LazyProgressDone** | ***Constant*** | progress bar done | -| **LazyProgressTodo** | ***LineNr*** | progress bar todo | -| **LazyProp** | ***Conceal*** | property | -| **LazyReasonCmd** | ***Operator*** | | -| **LazyReasonEvent** | ***Constant*** | | -| **LazyReasonFt** | ***Character*** | | -| **LazyReasonImport** | ***Identifier*** | | -| **LazyReasonKeys** | ***Statement*** | | -| **LazyReasonPlugin** | ***Special*** | | -| **LazyReasonRequire** | ***@variable.parameter*** | | -| **LazyReasonRuntime** | ***@macro*** | | -| **LazyReasonSource** | ***Character*** | | -| **LazyReasonStart** | ***@variable.member*** | | -| **LazySpecial** | ***@punctuation.special*** | | -| **LazyTaskError** | ***ErrorMsg*** | task errors | -| **LazyTaskOutput** | ***MsgArea*** | task output | -| **LazyUrl** | ***@markup.link*** | url | -| **LazyValue** | ***@string*** | value of a property | -# ๐Ÿš€ Usage - -## โ–ถ๏ธ Startup Sequence - -**lazy.nvim** does **NOT** use Neovim packages and even disables plugin loading -completely (`vim.go.loadplugins = false`). It takes over the complete -startup sequence for more flexibility and better performance. - -In practice this means that step 10 of [Neovim Initialization](https://neovim.io/doc/user/starting.html#initialization) is done by Lazy: - -1. All the plugins' `init()` functions are executed -2. All plugins with `lazy=false` are loaded. This includes sourcing `/plugin` and `/ftdetect` files. (`/after` will not be sourced yet) -3. All files from `/plugin` and `/ftdetect` directories in your rtp are sourced (excluding `/after`) -4. All `/after/plugin` files are sourced (this includes `/after` from plugins) - -Files from runtime directories are always sourced in alphabetical order. - -## ๐Ÿš€ Commands - -Plugins are managed with the `:Lazy` command. -Open the help with `` to see all the key mappings. - -You can press `` on a plugin to show its details. Most properties -can be hovered with `` to open links, help files, readmes, -git commits and git issues. - -Lazy can automatically check for updates in the background. This feature -can be enabled with `config.checker.enabled = true`. - -Any operation can be started from the UI, with a sub command or an API function: - -| Command | Lua | Description | -| --- | --- | --- | -| `:Lazy build {plugins}` | `require("lazy").build(opts)` | Rebuild a plugin | -| `:Lazy check [plugins]` | `require("lazy").check(opts?)` | Check for updates and show the log (git fetch) | -| `:Lazy clean [plugins]` | `require("lazy").clean(opts?)` | Clean plugins that are no longer needed | -| `:Lazy clear` | `require("lazy").clear()` | Clear finished tasks | -| `:Lazy debug` | `require("lazy").debug()` | Show debug information | -| `:Lazy health` | `require("lazy").health()` | Run `:checkhealth lazy` | -| `:Lazy help` | `require("lazy").help()` | Toggle this help page | -| `:Lazy home` | `require("lazy").home()` | Go back to plugin list | -| `:Lazy install [plugins]` | `require("lazy").install(opts?)` | Install missing plugins | -| `:Lazy load {plugins}` | `require("lazy").load(opts)` | Load a plugin that has not been loaded yet. Similar to `:packadd`. Like `:Lazy load foo.nvim`. Use `:Lazy! load` to skip `cond` checks. | -| `:Lazy log [plugins]` | `require("lazy").log(opts?)` | Show recent updates | -| `:Lazy profile` | `require("lazy").profile()` | Show detailed profiling | -| `:Lazy reload {plugins}` | `require("lazy").reload(opts)` | Reload a plugin (experimental!!) | -| `:Lazy restore [plugins]` | `require("lazy").restore(opts?)` | Updates all plugins to the state in the lockfile. For a single plugin: restore it to the state in the lockfile or to a given commit under the cursor | -| `:Lazy sync [plugins]` | `require("lazy").sync(opts?)` | Run install, clean and update | -| `:Lazy update [plugins]` | `require("lazy").update(opts?)` | Update plugins. This will also update the lockfile | - -Any command can have a **bang** to make the command wait till it finished. For example, -if you want to sync lazy from the cmdline, you can use: - -```shell -nvim --headless "+Lazy! sync" +qa -``` - -`opts` is a table with the following key-values: - -- **wait**: when true, then the call will wait till the operation completed -- **show**: when false, the UI will not be shown -- **plugins**: a list of plugin names to run the operation on -- **concurrency**: limit the `number` of concurrently running tasks - -Stats API (`require("lazy").stats()`): - -```lua -{ - -- startuptime in milliseconds till UIEnter - startuptime = 0, - -- when true, startuptime is the accurate cputime for the Neovim process. (Linux & macOS) - -- this is more accurate than `nvim --startuptime`, and as such will be slightly higher - -- when false, startuptime is calculated based on a delta with a timestamp when lazy started. - real_cputime = false, - count = 0, -- total number of plugins - loaded = 0, -- number of loaded plugins - ---@type table - times = {}, -} -``` - -**lazy.nvim** provides a statusline component that you can use to show the number of pending updates. -Make sure to enable `config.checker.enabled = true` to make this work. - -
-Example of configuring lualine.nvim - -```lua -require("lualine").setup({ - sections = { - lualine_x = { - { - require("lazy.status").updates, - cond = require("lazy.status").has_updates, - color = { fg = "#ff9e64" }, - }, - }, - }, -}) - -``` - -
- -## ๐Ÿ“† User Events - -The following user events will be triggered: - -- **LazyDone**: when lazy has finished starting up and loaded your config -- **LazySync**: after running sync -- **LazyInstall**: after an install -- **LazyUpdate**: after an update -- **LazyClean**: after a clean -- **LazyCheck**: after checking for updates -- **LazyLog**: after running log -- **LazyLoad**: after loading a plugin. The `data` attribute will contain the plugin name. -- **LazySyncPre**: before running sync -- **LazyInstallPre**: before an install -- **LazyUpdatePre**: before an update -- **LazyCleanPre**: before a clean -- **LazyCheckPre**: before checking for updates -- **LazyLogPre**: before running log -- **LazyReload**: triggered by change detection after reloading plugin specs -- **VeryLazy**: triggered after `LazyDone` and processing `VimEnter` auto commands -- **LazyVimStarted**: triggered after `UIEnter` when `require("lazy").stats().startuptime` has been calculated. - Useful to update the startuptime on your dashboard. - -## โŒ Uninstalling - -To uninstall **lazy.nvim**, you need to remove the following files and directories: - -- **data**: `~/.local/share/nvim/lazy` -- **state**: `~/.local/state/nvim/lazy` -- **lockfile**: `~/.config/nvim/lazy-lock.json` - -> Paths can differ if you changed `XDG` environment variables. -## ๐Ÿ”’ Lockfile - -After every **update**, the local lockfile (`lazy-lock.json`) is updated with the installed revisions. -It is recommended to have this file under version control. - -If you use your Neovim config on multiple machines, using the lockfile, you can -ensure that the same version of every plugin is installed. - -If you are on another machine, you can do `:Lazy restore`, to update all your plugins to -the version from the lockfile. -## ๐Ÿ“ฆ Migration Guide - -### [packer.nvim](https://github.com/wbthomason/packer.nvim) - -- `setup` โžก๏ธ `init` -- `requires` โžก๏ธ `dependencies` -- `as` โžก๏ธ `name` -- `opt` โžก๏ธ `lazy` -- `run` โžก๏ธ `build` -- `lock` โžก๏ธ `pin` -- `disable=true` โžก๏ธ `enabled = false` -- `tag='*'` โžก๏ธ `version="*"` -- `after` is **_not needed_** for most use-cases. Use `dependencies` otherwise. -- `wants` is **_not needed_** for most use-cases. Use `dependencies` otherwise. -- `config` don't support string type, use `fun(LazyPlugin)` instead. -- `module` is auto-loaded. No need to specify -- `keys` spec is [different](#%EF%B8%8F-lazy-key-mappings) -- `rtp` can be accomplished with: - -```lua -config = function(plugin) - vim.opt.rtp:append(plugin.dir .. "/custom-rtp") -end -``` - -With packer `wants`, `requires` and `after` can be used to manage dependencies. -With lazy, this isn't needed for most of the Lua dependencies. They can be installed just like normal plugins -(even with `lazy=true`) and will be loaded when other plugins need them. -The `dependencies` key can be used to group those required plugins with the one that requires them. -The plugins which are added as `dependencies` will always be lazy-loaded and loaded when the plugin is loaded. - -### [paq-nvim](https://github.com/savq/paq-nvim) - -- `as` โžก๏ธ `name` -- `opt` โžก๏ธ `lazy` -- `run` โžก๏ธ `build` -## โšก Profiling & Debug - -Great care has been taken to make the startup code (`lazy.core`) as efficient as possible. -During startup, all Lua files used before `VimEnter` or `BufReadPre` are byte-compiled and cached, -similar to what [impatient.nvim](https://github.com/lewis6991/impatient.nvim) does. - -My config for example loads in about `11ms` with `93` plugins. I do a lot of lazy-loading though :) - -**lazy.nvim** comes with an advanced profiler `:Lazy profile` to help you improve performance. -The profiling view shows you why and how long it took to load your plugins. - -![image](https://user-images.githubusercontent.com/292349/208301766-5c400561-83c3-4811-9667-1ec4bb3c43b8.png) - -### ๐Ÿ› Debug - -See an overview of active lazy-loading handlers and what's in the module cache. - -![image](https://user-images.githubusercontent.com/292349/208301790-7eedbfa5-d202-4e70-852e-de68aa47233b.png) -## ๐Ÿ“‚ Structuring Your Plugins - -Some users may want to split their plugin specs in multiple files. -Instead of passing a spec table to `setup()`, you can use a Lua module. -The specs from the **module** and any top-level **sub-modules** will be merged together in the final spec, -so it is not needed to add `require` calls in your main plugin file to the other files. - -The benefits of using this approach: - -- Simple to **add** new plugin specs. Just create a new file in your plugins module. -- Allows for **caching** of all your plugin specs. This becomes important if you have a lot of smaller plugin specs. -- Spec changes will automatically be **reloaded** when they're updated, so the `:Lazy` UI is always up to date. - -Example: - -- `~/.config/nvim/init.lua` - -```lua -require("lazy").setup("plugins") -``` - -- `~/.config/nvim/lua/plugins.lua` or `~/.config/nvim/lua/plugins/init.lua` **_(this file is optional)_** - -```lua -return { - "folke/neodev.nvim", - "folke/which-key.nvim", - { "folke/neoconf.nvim", cmd = "Neoconf" }, -} -``` - -- Any lua file in `~/.config/nvim/lua/plugins/*.lua` will be automatically merged in the main plugin spec - -For a real-life example, you can check [LazyVim](https://github.com/LazyVim/LazyVim) and more specifically: - -- [lazyvim.plugins](https://github.com/LazyVim/LazyVim/tree/main/lua/lazyvim/plugins) contains all the plugin specs that will be loaded - -#### โ†ฉ๏ธ Importing Specs, `config` & `opts` - -As part of a spec, you can add `import` statements to import additional plugin modules. -Both of the `setup()` calls are equivalent: - -```lua -require("lazy").setup("plugins") - --- Same as: -require("lazy").setup({{import = "plugins"}}) -``` - -To import multiple modules from a plugin, add additional specs for each import. -For example, to import LazyVim core plugins and an optional plugin: - -```lua -require("lazy").setup({ - spec = { - { "LazyVim/LazyVim", import = "lazyvim.plugins" }, - { import = "lazyvim.plugins.extras.coding.copilot" }, - } -}) -``` - -When you import specs, you can override them by simply adding a spec for the same plugin to your local -specs, adding any keys you want to override / merge. - -`opts`, `dependencies`, `cmd`, `event`, `ft` and `keys` are always merged with the parent spec. -Any other property will override the property from the parent spec. -# ๐Ÿ“š Plugin Developers - -To make it easier for users to install your plugin, you can include a [package spec](/packages) in your repo. - -If your plugin needs a build step, you can specify this in your **package file**, -or create a file `build.lua` or `build/init.lua` in the root of your repo. -This file will be loaded when the plugin is installed or updated. - -This makes it easier for users, as they no longer need to specify a `build` command. \ No newline at end of file +- a [Nerd Font](https://www.nerdfonts.com/) **_(optional)_** \ No newline at end of file diff --git a/README.vim.md b/README.vim.md new file mode 100644 index 0000000..5c2d114 --- /dev/null +++ b/README.vim.md @@ -0,0 +1,969 @@ +# ๐Ÿš€ Getting Started + +**lazy.nvim** is a modern plugin manager for Neovim. + +![image](https://user-images.githubusercontent.com/292349/208301737-68fb279c-ba70-43ef-a369-8c3e8367d6b1.png) + +## โœจ Features + +- ๐Ÿ“ฆ Manage all your Neovim plugins with a powerful UI +- ๐Ÿš€ Fast startup times thanks to automatic caching and bytecode compilation of Lua modules +- ๐Ÿ’พ Partial clones instead of shallow clones +- ๐Ÿ”Œ Automatic lazy-loading of Lua modules and lazy-loading on events, commands, filetypes, and key mappings +- โณ Automatically install missing plugins before starting up Neovim, allowing you to start using it right away +- ๐Ÿ’ช Async execution for improved performance +- ๐Ÿ› ๏ธ No need to manually compile plugins +- ๐Ÿงช Correct sequencing of dependencies +- ๐Ÿ“ Configurable in multiple files +- ๐Ÿ“š Generates helptags of the headings in `README.md` files for plugins that don't have vimdocs +- ๐Ÿ’ป Dev options and patterns for using local plugins +- ๐Ÿ“Š Profiling tools to optimize performance +- ๐Ÿ”’ Lockfile `lazy-lock.json` to keep track of installed plugins +- ๐Ÿ”Ž Automatically check for updates +- ๐Ÿ“‹ Commit, branch, tag, version, and full [Semver](https://devhints.io/semver) support +- ๐Ÿ“ˆ Statusline component to see the number of pending updates +- ๐ŸŽจ Automatically lazy-loads colorschemes + +## โšก๏ธ Requirements + +- Neovim >= **0.8.0** (needs to be built with **LuaJIT**) +- Git >= **2.19.0** (for partial clones support) +- a [Nerd Font](https://www.nerdfonts.com/) **_(optional)_** + +# ๐Ÿ› ๏ธ Installation + +There are multiple ways to install **lazy.nvim**. +The **Structured Setup** is the recommended way, but you can also use the **Single File Setup** +if you prefer to keep everything in your `init.lua`. + +Please refer to the [Configuration](/configuration) section for an overview of all available options. + +:::tip + +It is recommended to run `:checkhealth lazy` after installation. + +::: + +:::note + +In what follows `~/.config/nvim` is your Neovim configuration directory. +On Windows, this is usually `~\AppData\Local\nvim`. +To know the correct path for your system, run `:echo stdpath('config')`. + +::: + +## Structured Setup + +```lua +require("config.lazy") +``` + +```lua +-- Bootstrap lazy.nvim +local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim" +if not (vim.uv or vim.loop).fs_stat(lazypath) then + local lazyrepo = "https://github.com/folke/lazy.nvim.git" + vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath }) +end +vim.opt.rtp:prepend(lazypath) + +-- Make sure to setup `mapleader` and `maplocalleader` before +-- loading lazy.nvim so that mappings are correct. +-- This is also a good place to setup other settings (vim.opt) +vim.g.mapleader = " " +vim.g.maplocalleader = "\\" + +-- Setup lazy.nvim +require("lazy").setup({ + -- highlight-start + spec = { + -- import your plugins + { import = "plugins" }, + }, + -- highlight-end + -- Configure any other settings here. See the documentation for more details. + -- colorscheme that will be used when installing plugins. + install = { colorscheme = { "habamax" } }, + -- automatically check for plugin updates + checker = { enabled = true }, +}) +``` + +You can then create your plugin specs in `~/.config/nvim/lua/plugins/`. +Each file should return a table with the plugins you want to install. + +For more info see [Structuring Your Plugins](/usage/structuring) + +
+~/.config/nvim
+โ”œโ”€โ”€ lua
+โ”‚ย ย  โ”œโ”€โ”€ config
+โ”‚ย ย  โ”‚ย ย  โ””โ”€โ”€ lazy.lua
+โ”‚ย ย  โ””โ”€โ”€ plugins
+โ”‚ย ย      โ”œโ”€โ”€ spec1.lua
+โ”‚ย ย      โ”œโ”€โ”€ **
+โ”‚ย ย      โ””โ”€โ”€ spec2.lua
+โ””โ”€โ”€ init.lua
+
+ +## Single File Setup + +```lua +-- Bootstrap lazy.nvim +local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim" +if not (vim.uv or vim.loop).fs_stat(lazypath) then + local lazyrepo = "https://github.com/folke/lazy.nvim.git" + vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath }) +end +vim.opt.rtp:prepend(lazypath) + +-- Make sure to setup `mapleader` and `maplocalleader` before +-- loading lazy.nvim so that mappings are correct. +-- This is also a good place to setup other settings (vim.opt) +vim.g.mapleader = " " +vim.g.maplocalleader = "\\" + +-- Setup lazy.nvim +require("lazy").setup({ + -- highlight-start + spec = { + -- add your plugins here + }, + -- highlight-end + -- Configure any other settings here. See the documentation for more details. + -- colorscheme that will be used when installing plugins. + install = { colorscheme = { "habamax" } }, + -- automatically check for plugin updates + checker = { enabled = true }, +}) +``` + +# ๐Ÿ”Œ Plugin Spec + +## Source + +| Property | Type | Description | +| --------- | ---------- | -------------------------------------------------------------------------------------------------------------------- | +| **\[1\]** | `string?` | Short plugin url. Will be expanded using [`config.git.url_format`](../configuration/). Can also be a `url` or `dir`. | +| **dir** | `string?` | A directory pointing to a local plugin | +| **url** | `string?` | A custom git url where the plugin is hosted | +| **name** | `string?` | A custom name for the plugin used for the local plugin directory and as the display name | +| **dev** | `boolean?` | When `true`, a local plugin directory will be used instead. See [`config.dev`](../configuration/) | + +A valid spec should define one of `[1]`, `dir` or `url`. + +## Loading + +| Property | Type | Description | +| ---------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **dependencies** | `LazySpec[]` | A list of plugin names or plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise. When specifying a name, make sure the plugin spec has been defined somewhere else. | +| **enabled** | `boolean?` or `fun():boolean` | When `false`, or if the `function` returns false, then this plugin will not be included in the spec | +| **cond** | `boolean?` or `fun(LazyPlugin):boolean` | Behaves the same as `enabled`, but won't uninstall the plugin when the condition is `false`. Useful to disable some plugins in vscode, or firenvim for example. | +| **priority** | `number?` | Only useful for **start** plugins (`lazy=false`) to force loading certain plugins first. Default priority is `50`. It's recommended to set this to a high number for colorschemes. | + +## Setup + +| Property | Type | Description | +| ---------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **init** | `fun(LazyPlugin)` | `init` functions are always executed during startup | +| **opts** | `table` or `fun(LazyPlugin, opts:table)` | `opts` should be a table (will be merged with parent specs), return a table (replaces parent specs) or should change a table. The table will be passed to the `Plugin.config()` function. Setting this value will imply `Plugin.config()` | +| **config** | `fun(LazyPlugin, opts:table)` or `true` | `config` is executed when the plugin loads. The default implementation will automatically run `require(MAIN).setup(opts)` if `opts` or `config = true` is set. Lazy uses several heuristics to determine the plugin's `MAIN` module automatically based on the plugin's **name**. See also `opts`. To use the default implementation without `opts` set `config` to `true`. | +| **main** | `string?` | You can specify the `main` module to use for `config()` and `opts()`, in case it can not be determined automatically. See `config()` | +| **build** | `fun(LazyPlugin)` or `string` or a list of build commands | `build` is executed when a plugin is installed or updated. Before running `build`, a plugin is first loaded. If it's a string it will be run as a shell command. When prefixed with `:` it is a Neovim command. You can also specify a list to executed multiple build commands. Some plugins provide their own `build.lua` which is automatically used by lazy. So no need to specify a build step for those plugins. | +| **rocks** | `string[]?` | Add any [luarocks](https://luarocks.org/) dependencies. | + +## Lazy Loading + +| Property | Type | Description | +| --------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **lazy** | `boolean?` | When `true`, the plugin will only be loaded when needed. Lazy-loaded plugins are automatically loaded when their Lua modules are `required`, or when one of the lazy-loading handlers triggers | +| **event** | `string?` or `string[]` or `fun(self:LazyPlugin, event:string[]):string[]` or `{event:string[]\|string, pattern?:string[]\|string}` | Lazy-load on event. Events can be specified as `BufEnter` or with a pattern like `BufEnter *.lua` | +| **cmd** | `string?` or `string[]` or `fun(self:LazyPlugin, cmd:string[]):string[]` | Lazy-load on command | +| **ft** | `string?` or `string[]` or `fun(self:LazyPlugin, ft:string[]):string[]` | Lazy-load on filetype | +| **keys** | `string?` or `string[]` or `LazyKeysSpec[]` or `fun(self:LazyPlugin, keys:string[]):(string \| LazyKeysSpec)[]` | Lazy-load on [key mapping](/spec/lazy_loading#%EF%B8%8F-lazy-key-mappings) | + +Refer to the [Lazy Loading](./lazy_loading.md) section for more information. + +## Versioning + +| Property | Type | Description | +| -------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| **branch** | `string?` | Branch of the repository | +| **tag** | `string?` | Tag of the repository | +| **commit** | `string?` | Commit of the repository | +| **version** | `string?` or `false` to override the default | Version to use from the repository. Full [Semver](https://devhints.io/semver) ranges are supported | +| **pin** | `boolean?` | When `true`, this plugin will not be included in updates | +| **submodules** | `boolean?` | When false, git submodules will not be fetched. Defaults to `true` | + +Refer to the [Versioning](./versioning.md) section for more information. + +## Advanced + +| Property | Type | Description | +| ------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **optional** | `boolean?` | When a spec is tagged optional, it will only be included in the final spec, when the same plugin has been specified at least once somewhere else without `optional`. This is mainly useful for Neovim distros, to allow setting options on plugins that may/may not be part of the user's plugins. | +| **specs** | `LazySpec` | A list of plugin specs defined in the scope of the plugin. This is mainly useful for Neovim distros, to allow setting options on plugins that may/may not be part of the user's plugins. When the plugin is disabled, none of the scoped specs will be included in the final spec. Similar to `dependencies` without the automatic loading of the specs. | +| **module** | `false?` | Do not automatically load this Lua module when it's required somewhere | +| **import** | `string?` | Import the given spec module. | + +## Examples + +```lua +return { + -- the colorscheme should be available when starting Neovim + { + "folke/tokyonight.nvim", + lazy = false, -- make sure we load this during startup if it is your main colorscheme + priority = 1000, -- make sure to load this before all the other start plugins + config = function() + -- load the colorscheme here + vim.cmd([[colorscheme tokyonight]]) + end, + }, + + -- I have a separate config.mappings file where I require which-key. + -- With lazy the plugin will be automatically loaded when it is required somewhere + { "folke/which-key.nvim", lazy = true }, + + { + "nvim-neorg/neorg", + -- lazy-load on filetype + ft = "norg", + -- options for neorg. This will automatically call `require("neorg").setup(opts)` + opts = { + load = { + ["core.defaults"] = {}, + }, + }, + }, + + { + "dstein64/vim-startuptime", + -- lazy-load on a command + cmd = "StartupTime", + -- init is called during startup. Configuration for vim plugins typically should be set in an init function + init = function() + vim.g.startuptime_tries = 10 + end, + }, + + { + "hrsh7th/nvim-cmp", + -- load cmp on InsertEnter + event = "InsertEnter", + -- these dependencies will only be loaded when cmp loads + -- dependencies are always lazy-loaded unless specified otherwise + dependencies = { + "hrsh7th/cmp-nvim-lsp", + "hrsh7th/cmp-buffer", + }, + config = function() + -- ... + end, + }, + + -- if some code requires a module from an unloaded plugin, it will be automatically loaded. + -- So for api plugins like devicons, we can always set lazy=true + { "nvim-tree/nvim-web-devicons", lazy = true }, + + -- you can use the VeryLazy event for things that can + -- load later and are not important for the initial UI + { "stevearc/dressing.nvim", event = "VeryLazy" }, + + { + "Wansmer/treesj", + keys = { + { "J", "TSJToggle", desc = "Join Toggle" }, + }, + opts = { use_default_keymaps = false, max_join_length = 150 }, + }, + + { + "monaqa/dial.nvim", + -- lazy-load on keys + -- mode is `n` by default. For more advanced options, check the section on key mappings + keys = { "", { "", mode = "n" } }, + }, + + -- local plugins need to be explicitly configured with dir + { dir = "~/projects/secret.nvim" }, + + -- you can use a custom url to fetch a plugin + { url = "git@github.com:folke/noice.nvim.git" }, + + -- local plugins can also be configured with the dev option. + -- This will use {config.dev.path}/noice.nvim/ instead of fetching it from GitHub + -- With the dev option, you can easily switch between the local and installed version of a plugin + { "folke/noice.nvim", dev = true }, +} +``` + +## Lazy Loading + +**lazy.nvim** automagically lazy-loads Lua modules. This means that if +you have a plugin `A` that is lazy-loaded and a plugin `B` that requires a +module of plugin `A`, then plugin `A` will be loaded on demand as expected. + +:::tip + +You can configure **lazy.nvim** to lazy-load all plugins by default with `config.defaults.lazy = true`. +Make sure you've configured lazy-loading, for your plugins to avoid unexpected behavior. +Only do this if you know what you are doing, as it can lead to unexpected behavior. + +::: + +Additionally, you can also lazy-load on **events**, **commands**, +**file types** and **key mappings**. + +Plugins will be lazy-loaded when one of the following is `true`: + +- The plugin only exists as a dependency in your spec +- It has an `event`, `cmd`, `ft` or `keys` key +- `config.defaults.lazy == true` + +### ๐ŸŒˆ Colorschemes + +Colorscheme plugins can be configured with `lazy=true`. The plugin will automagically load +when doing `colorscheme foobar`. + +:::warning + +since **start** plugins can possibly change existing highlight groups, +it's important to make sure that your main **colorscheme** is loaded first. +To ensure this you can use the `priority=1000` field. **_(see the [examples](./examples.md))_** + +::: + +### โŒจ๏ธ Lazy Key Mappings + +The `keys` property can be a `string` or `string[]` for simple normal-mode mappings, or it +can be a `LazyKeysSpec` table with the following key-value pairs: + +- **[1]**: (`string`) lhs **_(required)_** +- **[2]**: (`string|fun()`) rhs **_(optional)_** +- **mode**: (`string|string[]`) mode **_(optional, defaults to `"n"`)_** +- **ft**: (`string|string[]`) `filetype` for buffer-local keymaps **_(optional)_** +- any other option valid for `vim.keymap.set` + +Key mappings will load the plugin the first time they get executed. + +When `[2]` is `nil`, then the real mapping has to be created by the `config()` function. + +```lua +-- Example for neo-tree.nvim +{ + "nvim-neo-tree/neo-tree.nvim", + keys = { + { "ft", "Neotree toggle", desc = "NeoTree" }, + }, + config = function() + require("neo-tree").setup() + end, +} +``` + +## Versioning + +If you want to install a specific revision of a plugin, you can use `commit`, +`tag`, `branch`, `version`. + +The `version` property supports [Semver](https://semver.org/) ranges. + +:::tip + +You can set `config.defaults.version = "*"` to install the latest stable +version of plugins that support Semver. + +::: + +### Examples + +- `*`: latest stable version (this excludes pre-release versions) +- `1.2.x`: any version that starts with `1.2`, such as `1.2.0`, `1.2.3`, etc. +- `^1.2.3`: any version that is compatible with `1.2.3`, such as `1.3.0`, `1.4.5`, etc., but not `2.0.0`. +- `~1.2.3`: any version that is compatible with `1.2.3`, such as `1.2.4`, `1.2.5`, but not `1.3.0`. +- `>1.2.3`: any version that is greater than `1.2.3`, such as `1.3.0`, `1.4.5`, etc. +- `>=1.2.3`: any version that is greater than or equal to `1.2.3`, such as `1.2.3`, `1.3.0`, `1.4.5`, etc. +- `<1.2.3`: any version that is less than `1.2.3`, such as `1.1.0`, `1.0.5`, etc. +- `<=1.2.3`: any version that is less than or equal to `1.2.3`, such as `1.2.3`, `1.1.0`, `1.0.5`, etc + +# ๐Ÿ“ฆ Packages + +**lazy.nvim** supports three ways for plugins to define their dependencies and configuration. + +- **Lazy**: `lazy.lua` file +- **Rockspec**: [luarocks](https://luarocks.org/) `*-scm-1.rockspec` [file](https://github.com/luarocks/luarocks/wiki/Rockspec-format) +- **Packspec**: `pkg.json` (experimental, since the [format](https://github.com/neovim/packspec/issues/41) is not quite there yet) + +You can enable/disable package sources with [`config.pkg.sources`](/configuration). +The order of sources is important, as the first source that finds a package will be used. + +:::info + +Package specs are always loaded in the scope of the plugin (using [specs](/spec#advanced)), +so that when the plugin is disabled, none of the specs are loaded. + +::: + +## Lazy + +Using a `lazy.lua` file is the recommended way to define your plugin dependencies and configuration. +Syntax is the same as any plugin spec. + +## Rockspec + +When a plugin contains a `*-scm-1.rockspec` file, **lazy.nvim** will automatically load its [`rocks`](/spec#setup) dependencies. + +## Packspec + +Supports the [pkg.json](https://github.com/nvim-lua/nvim-package-specification/issues/41) format, +with a lazy extension in `lazy`. +`lazy` can contain any valid lazy spec fields. They will be added to the plugin's spec. + +# โš™๏ธ Configuration + +**lazy.nvim** comes with the following defaults: + +```lua +{ + root = vim.fn.stdpath("data") .. "/lazy", -- directory where plugins will be installed + defaults = { + -- By default, only LazyVim plugins will be lazy-loaded. Your custom plugins will load during startup. + -- If you know what you're doing, you can set this to `true` to have all your custom plugins lazy-loaded by default. + lazy = false, -- should plugins be lazy-loaded? + -- It's recommended to leave version=false for now, since a lot the plugin that support versioning, + -- have outdated releases, which may break your Neovim install. + version = nil, -- always use the latest git commit + -- version = "*", -- try installing the latest stable version for plugins that support semver + -- default `cond` you can use to globally disable a lot of plugins + -- when running inside vscode for example + cond = nil, ---@type boolean|fun(self:LazyPlugin):boolean|nil + -- version = "*", -- enable this to try installing the latest stable versions of plugins + }, + -- leave nil when passing the spec as the first argument to setup() + spec = nil, ---@type LazySpec + local_spec = true, -- load project specific .lazy.lua spec files. They will be added at the end of the spec. + lockfile = vim.fn.stdpath("config") .. "/lazy-lock.json", -- lockfile generated after running update. + ---@type number? limit the maximum amount of concurrent tasks + concurrency = jit.os:find("Windows") and (vim.uv.available_parallelism() * 2) or nil, + git = { + -- defaults for the `Lazy log` command + -- log = { "--since=3 days ago" }, -- show commits from the last 3 days + log = { "-8" }, -- show the last 8 commits + timeout = 120, -- kill processes that take more than 2 minutes + url_format = "https://github.com/%s.git", + -- lazy.nvim requires git >=2.19.0. If you really want to use lazy with an older version, + -- then set the below to false. This should work, but is NOT supported and will + -- increase downloads a lot. + filter = true, + }, + pkg = { + enabled = true, + cache = vim.fn.stdpath("state") .. "/lazy/pkg-cache.lua", + versions = true, -- Honor versions in pkg sources + -- the first package source that is found for a plugin will be used. + sources = { + "lazy", + "rockspec", + "packspec", + }, + }, + rocks = { + root = vim.fn.stdpath("data") .. "/lazy-rocks", + server = "https://nvim-neorocks.github.io/rocks-binaries/", + }, + dev = { + ---@type string | fun(plugin: LazyPlugin): string directory where you store your local plugin projects + path = "~/projects", + ---@type string[] plugins that match these patterns will use your local versions instead of being fetched from GitHub + patterns = {}, -- For example {"folke"} + fallback = false, -- Fallback to git when local plugin doesn't exist + }, + install = { + -- install missing plugins on startup. This doesn't increase startup time. + missing = true, + -- try to load one of these colorschemes when starting an installation during startup + colorscheme = { "habamax" }, + }, + ui = { + -- a number <1 is a percentage., >1 is a fixed size + size = { width = 0.8, height = 0.8 }, + wrap = true, -- wrap the lines in the ui + -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|. + border = "none", + -- The backdrop opacity. 0 is fully opaque, 100 is fully transparent. + backdrop = 60, + title = nil, ---@type string only works when border is not "none" + title_pos = "center", ---@type "center" | "left" | "right" + -- Show pills on top of the Lazy window + pills = true, ---@type boolean + icons = { + cmd = "๎ฏ‡ ", + config = "๏€“", + event = "๎ช† ", + favorite = "๏€… ", + ft = "๏€– ", + init = "๏€“ ", + import = "๎‰ฝ ", + keys = "๏„œ ", + lazy = "๓ฐ’ฒ ", + loaded = "โ—", + not_loaded = "โ—‹", + plugin = "๏’‡ ", + runtime = "๎Ÿ… ", + require = "๓ฐขฑ ", + source = "๏„ก ", + start = "๎ซ“ ", + task = "โœ” ", + list = { + "โ—", + "โžœ", + "โ˜…", + "โ€’", + }, + }, + -- leave nil, to automatically select a browser depending on your OS. + -- If you want to use a specific browser, you can define it here + browser = nil, ---@type string? + throttle = 20, -- how frequently should the ui process render events + custom_keys = { + -- You can define custom key maps here. If present, the description will + -- be shown in the help menu. + -- To disable one of the defaults, set it to false. + + ["l"] = { + function(plugin) + require("lazy.util").float_term({ "lazygit", "log" }, { + cwd = plugin.dir, + }) + end, + desc = "Open lazygit log", + }, + + ["t"] = { + function(plugin) + require("lazy.util").float_term(nil, { + cwd = plugin.dir, + }) + end, + desc = "Open terminal in plugin dir", + }, + }, + }, + diff = { + -- diff command can be one of: + -- * browser: opens the github compare view. Note that this is always mapped to as well, + -- so you can have a different command for diff + -- * git: will run git diff and open a buffer with filetype git + -- * terminal_git: will open a pseudo terminal with git diff + -- * diffview.nvim: will open Diffview to show the diff + cmd = "git", + }, + checker = { + -- automatically check for plugin updates + enabled = false, + concurrency = nil, ---@type number? set to 1 to check for updates very slowly + notify = true, -- get a notification when new updates are found + frequency = 3600, -- check for updates every hour + check_pinned = false, -- check for pinned packages that can't be updated + }, + change_detection = { + -- automatically check for config file changes and reload the ui + enabled = true, + notify = true, -- get a notification when changes are found + }, + performance = { + cache = { + enabled = true, + }, + reset_packpath = true, -- reset the package path to improve startup time + rtp = { + reset = true, -- reset the runtime path to $VIMRUNTIME and your config directory + ---@type string[] + paths = {}, -- add any custom paths here that you want to includes in the rtp + ---@type string[] list any plugins you want to disable here + disabled_plugins = { + -- "gzip", + -- "matchit", + -- "matchparen", + -- "netrwPlugin", + -- "tarPlugin", + -- "tohtml", + -- "tutor", + -- "zipPlugin", + }, + }, + }, + -- lazy can generate helptags from the headings in markdown readme files, + -- so :help works even for plugins that don't have vim docs. + -- when the readme opens with :help it will be correctly displayed as markdown + readme = { + enabled = true, + root = vim.fn.stdpath("state") .. "/lazy/readme", + files = { "README.md", "lua/**/README.md" }, + -- only generate markdown helptags for plugins that dont have docs + skip_if_doc_exists = true, + }, + state = vim.fn.stdpath("state") .. "/lazy/state.json", -- state info for checker and other things + build = { + -- Plugins can provide a `build.lua` file that will be executed when the plugin is installed + -- or updated. When the plugin spec also has a `build` command, the plugin's `build.lua` not be + -- executed. In this case, a warning message will be shown. + warn_on_override = true, + }, + -- Enable profiling of lazy.nvim. This will add some overhead, + -- so only enable this when you are debugging lazy.nvim + profiling = { + -- Enables extra stats on the debug tab related to the loader cache. + -- Additionally gathers stats about all package.loaders + loader = false, + -- Track each new require in the Lazy profiling tab + require = false, + }, +} +``` + +
+If you don't want to use a Nerd Font, you can replace the icons with Unicode symbols. + +```lua +{ + ui = { + icons = { + cmd = "โŒ˜", + config = "๐Ÿ› ", + event = "๐Ÿ“…", + ft = "๐Ÿ“‚", + init = "โš™", + keys = "๐Ÿ—", + plugin = "๐Ÿ”Œ", + runtime = "๐Ÿ’ป", + require = "๐ŸŒ™", + source = "๐Ÿ“„", + start = "๐Ÿš€", + task = "๐Ÿ“Œ", + lazy = "๐Ÿ’ค ", + }, + }, +} +``` + +
+ +## ๐ŸŒˆ Highlight Groups + +| Highlight Group | Default Group | Description | +| --- | --- | --- | +| **LazyButton** | ***CursorLine*** | | +| **LazyButtonActive** | ***Visual*** | | +| **LazyComment** | ***Comment*** | | +| **LazyCommit** | ***@variable.builtin*** | commit ref | +| **LazyCommitIssue** | ***Number*** | | +| **LazyCommitScope** | ***Italic*** | conventional commit scope | +| **LazyCommitType** | ***Title*** | conventional commit type | +| **LazyDimmed** | ***Conceal*** | property | +| **LazyDir** | ***@markup.link*** | directory | +| **LazyH1** | ***IncSearch*** | home button | +| **LazyH2** | ***Bold*** | titles | +| **LazyLocal** | ***Constant*** | | +| **LazyNoCond** | ***DiagnosticWarn*** | unloaded icon for a plugin where `cond()` was false | +| **LazyNormal** | ***NormalFloat*** | | +| **LazyProgressDone** | ***Constant*** | progress bar done | +| **LazyProgressTodo** | ***LineNr*** | progress bar todo | +| **LazyProp** | ***Conceal*** | property | +| **LazyReasonCmd** | ***Operator*** | | +| **LazyReasonEvent** | ***Constant*** | | +| **LazyReasonFt** | ***Character*** | | +| **LazyReasonImport** | ***Identifier*** | | +| **LazyReasonKeys** | ***Statement*** | | +| **LazyReasonPlugin** | ***Special*** | | +| **LazyReasonRequire** | ***@variable.parameter*** | | +| **LazyReasonRuntime** | ***@macro*** | | +| **LazyReasonSource** | ***Character*** | | +| **LazyReasonStart** | ***@variable.member*** | | +| **LazySpecial** | ***@punctuation.special*** | | +| **LazyTaskError** | ***ErrorMsg*** | task errors | +| **LazyTaskOutput** | ***MsgArea*** | task output | +| **LazyUrl** | ***@markup.link*** | url | +| **LazyValue** | ***@string*** | value of a property | + +# ๐Ÿš€ Usage + +## โ–ถ๏ธ Startup Sequence + +**lazy.nvim** does **NOT** use Neovim packages and even disables plugin loading +completely (`vim.go.loadplugins = false`). It takes over the complete +startup sequence for more flexibility and better performance. + +In practice this means that step 10 of [Neovim Initialization](https://neovim.io/doc/user/starting.html#initialization) is done by Lazy: + +1. All the plugins' `init()` functions are executed +2. All plugins with `lazy=false` are loaded. This includes sourcing `/plugin` and `/ftdetect` files. (`/after` will not be sourced yet) +3. All files from `/plugin` and `/ftdetect` directories in your rtp are sourced (excluding `/after`) +4. All `/after/plugin` files are sourced (this includes `/after` from plugins) + +Files from runtime directories are always sourced in alphabetical order. + +## ๐Ÿš€ Commands + +Plugins are managed with the `:Lazy` command. +Open the help with `` to see all the key mappings. + +You can press `` on a plugin to show its details. Most properties +can be hovered with `` to open links, help files, readmes, +git commits and git issues. + +Lazy can automatically check for updates in the background. This feature +can be enabled with `config.checker.enabled = true`. + +Any operation can be started from the UI, with a sub command or an API function: + +| Command | Lua | Description | +| --- | --- | --- | +| `:Lazy build {plugins}` | `require("lazy").build(opts)` | Rebuild a plugin | +| `:Lazy check [plugins]` | `require("lazy").check(opts?)` | Check for updates and show the log (git fetch) | +| `:Lazy clean [plugins]` | `require("lazy").clean(opts?)` | Clean plugins that are no longer needed | +| `:Lazy clear` | `require("lazy").clear()` | Clear finished tasks | +| `:Lazy debug` | `require("lazy").debug()` | Show debug information | +| `:Lazy health` | `require("lazy").health()` | Run `:checkhealth lazy` | +| `:Lazy help` | `require("lazy").help()` | Toggle this help page | +| `:Lazy home` | `require("lazy").home()` | Go back to plugin list | +| `:Lazy install [plugins]` | `require("lazy").install(opts?)` | Install missing plugins | +| `:Lazy load {plugins}` | `require("lazy").load(opts)` | Load a plugin that has not been loaded yet. Similar to `:packadd`. Like `:Lazy load foo.nvim`. Use `:Lazy! load` to skip `cond` checks. | +| `:Lazy log [plugins]` | `require("lazy").log(opts?)` | Show recent updates | +| `:Lazy profile` | `require("lazy").profile()` | Show detailed profiling | +| `:Lazy reload {plugins}` | `require("lazy").reload(opts)` | Reload a plugin (experimental!!) | +| `:Lazy restore [plugins]` | `require("lazy").restore(opts?)` | Updates all plugins to the state in the lockfile. For a single plugin: restore it to the state in the lockfile or to a given commit under the cursor | +| `:Lazy sync [plugins]` | `require("lazy").sync(opts?)` | Run install, clean and update | +| `:Lazy update [plugins]` | `require("lazy").update(opts?)` | Update plugins. This will also update the lockfile | + +Any command can have a **bang** to make the command wait till it finished. For example, +if you want to sync lazy from the cmdline, you can use: + +```shell +nvim --headless "+Lazy! sync" +qa +``` + +`opts` is a table with the following key-values: + +- **wait**: when true, then the call will wait till the operation completed +- **show**: when false, the UI will not be shown +- **plugins**: a list of plugin names to run the operation on +- **concurrency**: limit the `number` of concurrently running tasks + +Stats API (`require("lazy").stats()`): + +```lua +{ + -- startuptime in milliseconds till UIEnter + startuptime = 0, + -- when true, startuptime is the accurate cputime for the Neovim process. (Linux & macOS) + -- this is more accurate than `nvim --startuptime`, and as such will be slightly higher + -- when false, startuptime is calculated based on a delta with a timestamp when lazy started. + real_cputime = false, + count = 0, -- total number of plugins + loaded = 0, -- number of loaded plugins + ---@type table + times = {}, +} +``` + +**lazy.nvim** provides a statusline component that you can use to show the number of pending updates. +Make sure to enable `config.checker.enabled = true` to make this work. + +
+Example of configuring lualine.nvim + +```lua +require("lualine").setup({ + sections = { + lualine_x = { + { + require("lazy.status").updates, + cond = require("lazy.status").has_updates, + color = { fg = "#ff9e64" }, + }, + }, + }, +}) + +``` + +
+ +## ๐Ÿ“† User Events + +The following user events will be triggered: + +- **LazyDone**: when lazy has finished starting up and loaded your config +- **LazySync**: after running sync +- **LazyInstall**: after an install +- **LazyUpdate**: after an update +- **LazyClean**: after a clean +- **LazyCheck**: after checking for updates +- **LazyLog**: after running log +- **LazyLoad**: after loading a plugin. The `data` attribute will contain the plugin name. +- **LazySyncPre**: before running sync +- **LazyInstallPre**: before an install +- **LazyUpdatePre**: before an update +- **LazyCleanPre**: before a clean +- **LazyCheckPre**: before checking for updates +- **LazyLogPre**: before running log +- **LazyReload**: triggered by change detection after reloading plugin specs +- **VeryLazy**: triggered after `LazyDone` and processing `VimEnter` auto commands +- **LazyVimStarted**: triggered after `UIEnter` when `require("lazy").stats().startuptime` has been calculated. + Useful to update the startuptime on your dashboard. + +## โŒ Uninstalling + +To uninstall **lazy.nvim**, you need to remove the following files and directories: + +- **data**: `~/.local/share/nvim/lazy` +- **state**: `~/.local/state/nvim/lazy` +- **lockfile**: `~/.config/nvim/lazy-lock.json` + +> Paths can differ if you changed `XDG` environment variables. + +## ๐Ÿ”’ Lockfile + +After every **update**, the local lockfile (`lazy-lock.json`) is updated with the installed revisions. +It is recommended to have this file under version control. + +If you use your Neovim config on multiple machines, using the lockfile, you can +ensure that the same version of every plugin is installed. + +If you are on another machine, you can do `:Lazy restore`, to update all your plugins to +the version from the lockfile. + +## ๐Ÿ“ฆ Migration Guide + +### [packer.nvim](https://github.com/wbthomason/packer.nvim) + +- `setup` โžก๏ธ `init` +- `requires` โžก๏ธ `dependencies` +- `as` โžก๏ธ `name` +- `opt` โžก๏ธ `lazy` +- `run` โžก๏ธ `build` +- `lock` โžก๏ธ `pin` +- `disable=true` โžก๏ธ `enabled = false` +- `tag='*'` โžก๏ธ `version="*"` +- `after` is **_not needed_** for most use-cases. Use `dependencies` otherwise. +- `wants` is **_not needed_** for most use-cases. Use `dependencies` otherwise. +- `config` don't support string type, use `fun(LazyPlugin)` instead. +- `module` is auto-loaded. No need to specify +- `keys` spec is [different](#%EF%B8%8F-lazy-key-mappings) +- `rtp` can be accomplished with: + +```lua +config = function(plugin) + vim.opt.rtp:append(plugin.dir .. "/custom-rtp") +end +``` + +With packer `wants`, `requires` and `after` can be used to manage dependencies. +With lazy, this isn't needed for most of the Lua dependencies. They can be installed just like normal plugins +(even with `lazy=true`) and will be loaded when other plugins need them. +The `dependencies` key can be used to group those required plugins with the one that requires them. +The plugins which are added as `dependencies` will always be lazy-loaded and loaded when the plugin is loaded. + +### [paq-nvim](https://github.com/savq/paq-nvim) + +- `as` โžก๏ธ `name` +- `opt` โžก๏ธ `lazy` +- `run` โžก๏ธ `build` + +## โšก Profiling & Debug + +Great care has been taken to make the startup code (`lazy.core`) as efficient as possible. +During startup, all Lua files used before `VimEnter` or `BufReadPre` are byte-compiled and cached, +similar to what [impatient.nvim](https://github.com/lewis6991/impatient.nvim) does. + +My config for example loads in about `11ms` with `93` plugins. I do a lot of lazy-loading though :) + +**lazy.nvim** comes with an advanced profiler `:Lazy profile` to help you improve performance. +The profiling view shows you why and how long it took to load your plugins. + +![image](https://user-images.githubusercontent.com/292349/208301766-5c400561-83c3-4811-9667-1ec4bb3c43b8.png) + +### ๐Ÿ› Debug + +See an overview of active lazy-loading handlers and what's in the module cache. + +![image](https://user-images.githubusercontent.com/292349/208301790-7eedbfa5-d202-4e70-852e-de68aa47233b.png) + +## ๐Ÿ“‚ Structuring Your Plugins + +Some users may want to split their plugin specs in multiple files. +Instead of passing a spec table to `setup()`, you can use a Lua module. +The specs from the **module** and any top-level **sub-modules** will be merged together in the final spec, +so it is not needed to add `require` calls in your main plugin file to the other files. + +The benefits of using this approach: + +- Simple to **add** new plugin specs. Just create a new file in your plugins module. +- Allows for **caching** of all your plugin specs. This becomes important if you have a lot of smaller plugin specs. +- Spec changes will automatically be **reloaded** when they're updated, so the `:Lazy` UI is always up to date. + +Example: + +- `~/.config/nvim/init.lua` + +```lua +require("lazy").setup("plugins") +``` + +- `~/.config/nvim/lua/plugins.lua` or `~/.config/nvim/lua/plugins/init.lua` **_(this file is optional)_** + +```lua +return { + "folke/neodev.nvim", + "folke/which-key.nvim", + { "folke/neoconf.nvim", cmd = "Neoconf" }, +} +``` + +- Any lua file in `~/.config/nvim/lua/plugins/*.lua` will be automatically merged in the main plugin spec + +For a real-life example, you can check [LazyVim](https://github.com/LazyVim/LazyVim) and more specifically: + +- [lazyvim.plugins](https://github.com/LazyVim/LazyVim/tree/main/lua/lazyvim/plugins) contains all the plugin specs that will be loaded + +#### โ†ฉ๏ธ Importing Specs, `config` & `opts` + +As part of a spec, you can add `import` statements to import additional plugin modules. +Both of the `setup()` calls are equivalent: + +```lua +require("lazy").setup("plugins") + +-- Same as: +require("lazy").setup({{import = "plugins"}}) +``` + +To import multiple modules from a plugin, add additional specs for each import. +For example, to import LazyVim core plugins and an optional plugin: + +```lua +require("lazy").setup({ + spec = { + { "LazyVim/LazyVim", import = "lazyvim.plugins" }, + { import = "lazyvim.plugins.extras.coding.copilot" }, + } +}) +``` + +When you import specs, you can override them by simply adding a spec for the same plugin to your local +specs, adding any keys you want to override / merge. + +`opts`, `dependencies`, `cmd`, `event`, `ft` and `keys` are always merged with the parent spec. +Any other property will override the property from the parent spec. + +# ๐Ÿ“š Plugin Developers + +To make it easier for users to install your plugin, you can include a [package spec](/packages) in your repo. + +If your plugin needs a build step, you can specify this in your **package file**, +or create a file `build.lua` or `build/init.lua` in the root of your repo. +This file will be loaded when the plugin is installed or updated. + +This makes it easier for users, as they no longer need to specify a `build` command. \ No newline at end of file diff --git a/lua/build.lua b/lua/build.lua index 4aef5b6..300a939 100644 --- a/lua/build.lua +++ b/lua/build.lua @@ -84,10 +84,14 @@ function M._old() }) end -function M.readme() - local mds = vim.fs.find(function(name, path) - return name:match(".*%.mdx?$") - end, { limit = math.huge, type = "file", path = "docs" }) +---@param readme? string +---@param mds? string[] +function M.readme(readme, mds) + readme = readme or "README.md" + mds = mds + or vim.fs.find(function(name, path) + return name:match(".*%.mdx?$") + end, { limit = math.huge, type = "file", path = "docs" }) local sorters = { "intro", "installation", @@ -138,18 +142,26 @@ function M.readme() -- t = t:gsub('[ \t]*', "## %2") t = t:gsub("", "") + t = t:gsub("\nimport .-\n", "\n") + t = t:gsub("\nimport .-\n", "\n") t = t:gsub("\n%s*\n", "\n\n") t = "\n" .. t -- fix headings t = t:gsub("\n#", "\n" .. ("#"):rep(level + 1)) - text = text .. "\n" .. vim.trim(t) + text = text .. "\n\n" .. vim.trim(t) end text = vim.trim(text) - Util.write_file("README.md", text) + Util.write_file(readme, text) end function M.update() - M.readme() + M.readme("README.vim.md") + M.readme("README.md", { + "README.header.md", + "docs/intro.md", + -- "docs/installation.mdx", + "README.footer.md", + }) M.themes() M.docs() vim.cmd.checktime()