From 67cc8dc07ca2372922ffd5e5cf05f92872adacf7 Mon Sep 17 00:00:00 2001 From: Folke Lemaitre Date: Sat, 18 Mar 2023 08:57:20 +0100 Subject: [PATCH] docs: updated docs. Fixes #667 --- README.md | 100 ++++++++++++++++++++----------------------- lua/lazy/example.lua | 45 ++++++++----------- 2 files changed, 66 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 064e710..7292e4a 100644 --- a/README.md +++ b/README.md @@ -79,33 +79,34 @@ require("lazy").setup({ ## 🔌 Plugin Spec -| Property | Type | Description | -| ---------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `[1]` | `string?` | Short plugin url. Will be expanded using `config.git.url_format` | -| **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` | -| **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 | -| **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` | When `false`, or if the `function` returns false, then this plugin will not be loaded. Useful to disable some plugins in vscode, or firenvim for example. | -| **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. | -| **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("plugin").setup(opts)`. `"plugin"` will default to `name` if specified, otherwise `lazy.nvim` will do its best to guess the correct plugin name. See also `opts`. To use the default implementation without `opts` set `config` to `true`. | -| **build** | `fun(LazyPlugin)` or `string` or a list of build commands | `build` is executed when a plugin is installed or updated. If it's a string it will be ran as a shell command. When prefixed with `:` it is a Neovim command. You can also specify a list to executed multiple build commands | -| **branch** | `string?` | Branch of the repository | -| **tag** | `string?` | Tag of the repository | -| **commit** | `string?` | Commit of the repository | -| **version** | `string?` | 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` | -| **event** | `string?` or `string[]` or `fun(self:LazyPlugin, event: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 `LazyKeys[]` or `fun(self:LazyPlugin, keys:string[]):(string \| LazyKeys)[]` | Lazy-load on key mapping | -| **module** | `false?` | Do not automatically load this Lua module when it's required somewhere | -| **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. | +| Property | Type | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `[1]` | `string?` | Short plugin url. Will be expanded using `config.git.url_format` | +| **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` | +| **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 | +| **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` | When `false`, or if the `function` returns false, then this plugin will not be loaded. Useful to disable some plugins in vscode, or firenvim for example. | +| **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. | +| **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)`. 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. If it's a string it will be ran as a shell command. When prefixed with `:` it is a Neovim command. You can also specify a list to executed multiple build commands | +| **branch** | `string?` | Branch of the repository | +| **tag** | `string?` | Tag of the repository | +| **commit** | `string?` | Commit of the repository | +| **version** | `string?` | 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` | +| **event** | `string?` or `string[]` or `fun(self:LazyPlugin, event: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 `LazyKeys[]` or `fun(self:LazyPlugin, keys:string[]):(string \| LazyKeys)[]` | Lazy-load on key mapping | +| **module** | `false?` | Do not automatically load this Lua module when it's required somewhere | +| **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. | ### Lazy Loading @@ -213,30 +214,22 @@ return { "nvim-neorg/neorg", -- lazy-load on filetype ft = "norg", - -- custom config that will be executed when loading the plugin - config = function() - require("neorg").setup() - end, - }, - - -- the above could also be written as: - { - "nvim-neorg/neorg", - ft = "norg", - config = true, -- run require("neorg").setup() - }, - - -- or set custom options: - { - "nvim-neorg/neorg", - ft = "norg", - opts = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"}) + -- 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, }, { @@ -254,19 +247,20 @@ return { 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" }, { - "cshuaimin/ssr.nvim", - -- init is always executed during startup, but doesn't load the plugin yet. - init = function() - vim.keymap.set({ "n", "x" }, "cR", function() - -- this require will automatically load the plugin - require("ssr").open() - end, { desc = "Structural Replace" }) - end, + "Wansmer/treesj", + keys = { + { "J", "TSJToggle", desc = "Join Toggle" }, + }, + opts = { use_default_keymaps = false, max_join_length = 150 }, }, { diff --git a/lua/lazy/example.lua b/lua/lazy/example.lua index 18c1ca9..df52faf 100644 --- a/lua/lazy/example.lua +++ b/lua/lazy/example.lua @@ -18,30 +18,22 @@ return { "nvim-neorg/neorg", -- lazy-load on filetype ft = "norg", - -- custom config that will be executed when loading the plugin - config = function() - require("neorg").setup() - end, - }, - - -- the above could also be written as: - { - "nvim-neorg/neorg", - ft = "norg", - config = true, -- run require("neorg").setup() - }, - - -- or set custom options: - { - "nvim-neorg/neorg", - ft = "norg", - opts = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"}) + -- 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, }, { @@ -59,19 +51,20 @@ return { 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" }, { - "cshuaimin/ssr.nvim", - -- init is always executed during startup, but doesn't load the plugin yet. - init = function() - vim.keymap.set({ "n", "x" }, "cR", function() - -- this require will automatically load the plugin - require("ssr").open() - end, { desc = "Structural Replace" }) - end, + "Wansmer/treesj", + keys = { + { "J", "TSJToggle", desc = "Join Toggle" }, + }, + opts = { use_default_keymaps = false, max_join_length = 150 }, }, {