From 9c5238d40531d9230ebf52e224bba788f3ac5ffe Mon Sep 17 00:00:00 2001 From: Glenn Waters Date: Tue, 20 Feb 2024 14:10:23 -0500 Subject: [PATCH] feat(v4_migration): add first draft of the v4 migration guide (#138) * First draft on new migration guide and added getting started. * Edits. * More edits. * More edits. * More edits. * More edits. * More edits. * migration getting started information to getting started guide and plugin configuration page * Changes on v4 branch Was on detached head branch. Hopefull this brings it all back to working git goodness! * Added plugin changes section. * Add comment about which plugins can be disabled. * rename "Custom Plugins" page to "Customizing Plugins" * fix: remove unnecessary title * chore: copy edits and fix some bugs in the formatting * Remove todo. * add more details to the migration guide regarding plugin changes as well as various edits * fix: add missing configuration options in migration guide * chore: simplify table entries * chore: more table simplification for formatting * chore: add link when referencing other section * fix: add missing link * feat: add placeholder for session management recipes * feat(sessions): add recipes to sessions management page * feat(customizing_plugins): add walkthrough for how `opts` overriding works * chore: reorder migration guide * feat(v4_migration): add utility function migration information * chore: remove unnecessary todo --------- Co-authored-by: Micah Halter --- .../docs/configuration/custom_plugins.md | 154 -------- .../docs/configuration/customizing_plugins.md | 355 ++++++++++++++++++ .../docs/configuration/lua_completion.md | 2 +- .../docs/configuration/v4_migration.md | 272 +++++++++----- src/content/docs/faq.md | 2 +- src/content/docs/index.mdx | 106 ++++-- src/content/docs/recipes/colorscheme.md | 2 +- src/content/docs/recipes/sessions.md | 156 ++++++++ src/content/docs/reference/uninstall.mdx | 4 +- 9 files changed, 770 insertions(+), 283 deletions(-) delete mode 100644 src/content/docs/configuration/custom_plugins.md create mode 100644 src/content/docs/configuration/customizing_plugins.md create mode 100644 src/content/docs/recipes/sessions.md diff --git a/src/content/docs/configuration/custom_plugins.md b/src/content/docs/configuration/custom_plugins.md deleted file mode 100644 index fb4160065..000000000 --- a/src/content/docs/configuration/custom_plugins.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -id: custom_plugins -title: Custom Plugins ---- - -Plugins in AstroNvim are configured the same as using `lazy.nvim` in a configuration built from scratch. To see all available options for defining plugins in Lazy.nvim please refer to the [Lazy.nvim Plugin Spec](https://github.com/folke/lazy.nvim#-plugin-spec). Here we will go over examples of defining new plugins, overriding plugins, and disabling plugins. - -## Defining Plugins - -Plugins can be added in your Neovim configuration inside of your `lua/plugins/` folder. You can create any number of Lua files in this folder that return `lazy.nvim` plugin specifications and they will automatically be loaded. - -Here is an example that adds `lsp_signature.nvim`: - -```lua title="lua/plugins/lsp_signature.lua" -return { - -- add lsp_signature - { - "ray-x/lsp_signature.nvim", - event = "BufRead", - opts = { - -- configuration options go here... - }, - config = function(plugin, opts) - require("lsp_signature").setup(opts) - end, - }, -} -``` - -## Overriding Plugins - -Overriding plugins are as simple as adding a plugin specification for that plugin and add modifications to the plugin specification that you want. Lazy.nvim supports extending many keys (`cmd`, `event`, `ft`, `keys`, `opts`, and `dependencies`) while other keys in the plugin specification will fully overwrite the defaults. - -Here are some examples of overwriting some plugins: - -```lua title="lua/plugins/overrided.lua" {5-10} {17-23} -return { - { - "AstroNvim/AstroLSP", - ---@type AstroLSPOpts - opts = { -- extend the plugin options - diagnostics = { - -- disable diagnostics virtual text - virtual_text = false, - }, - }, - }, - -- customize cmp mappings - { - "hrsh7th/nvim-cmp", - -- override the options table that is used - -- in the `require("cmp").setup()` call - opts = function(_, opts) - -- opts parameter is the default options table - -- the function is lazy loaded so cmp is able to be required - local cmp = require("cmp") - -- modify the mapping part of the table - opts.mapping[""] = cmp.mapping.select_next_item() - end, - }, -} -``` - -### Extending Core Plugin Config Functions - -Many of our core plugins have additional code that runs during setup which you might want to extend. For this reason we have included our own modules in `require("astronvim.plugins.configs.X")` (replacing `X` with the plugin `require` string) that returns the AstroNvim default config function in each plugin specification that has a `config` function which can be easily called if you want to extend a plugin configuration. This is particularly useful if you want to do something like add rules to `nvim-autopairs`, add user snippets to `luasnip`, or add more extensions to `telescope` without having to rewrite our entire configuration function. Here is an example of adding the `media_files` Telescope extension: - -:::note - -Not all plugins have custom `config` functions and will not have an `astronvim.plugins.configs.X` module. The Lua language server provides autocompletion that is useful for identifying which plugins have a core `config` function. - -::: - -```lua title="lua/plugins/extended_config.lua" {10-11} -return { - { - "nvim-telescope/telescope.nvim", - dependencies = { -- add a new dependency to telescope that is our new plugin - "nvim-telescope/telescope-media-files.nvim", - }, - -- the first parameter is the plugin specification - -- the second is the table of options as set up in Lazy with the `opts` key - config = function(plugin, opts) - -- run the core AstroNvim configuration function with the options table - require("astronvim.plugins.configs.telescope")(plugin, opts) - - -- require telescope and load extensions as necessary - require("telescope").load_extension("media_files") - end, - }, -} -``` - -## Disabling Plugins - -Plugins can be easily disabled by simply setting the `enabled` option to `false`. Here is an example of disabling the core dashboard plugin, `alpha`: - -```lua title="lua/plugins/disabled.lua" "enabled = false" -return { - { "goolord/alpha-nvim", enabled = false }, -} -``` - -## Lazy Loading - -Lazy loading can be used to delay plugin loading to speed up start up time. There are a few basic methods of lazy loading that can be easily added. The main keys here are `lazy`, `cmd`, `ft`, `keys`, and `event`. More details of these and more options can be found in the [Lazy Documentation](https://github.com/folke/lazy.nvim#-plugin-spec). Here are a few examples: - -```lua title="lua/plugins/lazy_loaded.lua" /((lazy|event|cmd|ft|keys) = (\S+|{.*}))/ -return { - -- by enabling the lazy option, the plugin will automatically be lazy loaded - -- until it's module is called for example require("tokyonight") - { "folke/tokyonight.nvim", lazy = true }, - - -- this plugin will be loaded on the autocmd event "UIEnter" - { "rcarriga/nvim-notify", event = "UIEnter" }, - - -- this plugin will be loaded when using `:ZenMode` - { "folke/zen-mode.nvim", cmd = "ZenMode" }, - - -- this plugin will be loaded when using `:ZenMode` - { "folke/zen-mode.nvim", cmd = "ZenMode" }, - - -- this plugin will be loaded when opening a "markdown" file - { "lukas-reineke/headlines.nvim", ft = "markdown" }, -} -``` - -### Lazy Load File Related Plugins - -AstroNvim has many plugins that we load on the first real file that is open. This is used internally for plugins like Treesitter, LSP related plugins, and other various plugins related to interacting with files. We achieve this by creating a custom `User` `autocmd` event called `AstroFile`. This can also be used by users for lazy loading plugins on the first real file that is opened: - -```lua title="lua/plugins/nvim-colorizer.lua" {4} -return { - { - "NvChad/nvim-colorizer.lua", - event = "User AstroFile", - }, -} -``` - -This will tell AstroNvim that this plugin should be loaded whenever the `User` autocmd event `AstroFile` is fired. - -### Lazy Load Git Plugins - -Similar to the file related plugins described above, we also have a similar hook for git related plugins. These shouldn't be loaded until a file is open that is in a git repository folder. We use this for stuff like the `gitsigns` plugin. This will check when a file is opened if it is in a git tracked folder and then load the plugin. This `User` `autocmd` event is `AstroGitFile`. **This does require access to the `git` command in your `PATH`.** - -```lua title="lua/plugins/gitsigns.lua" {4} -return { - { - "lewis6991/gitsigns.nvim", - event = "User AstroGitFile", - }, -} -``` diff --git a/src/content/docs/configuration/customizing_plugins.md b/src/content/docs/configuration/customizing_plugins.md new file mode 100644 index 000000000..7499caf8d --- /dev/null +++ b/src/content/docs/configuration/customizing_plugins.md @@ -0,0 +1,355 @@ +--- +id: customizing_plugins +title: Customizing Plugins +--- + +`lazy.nvim` (referred to as just _Lazy_ from now on) is a plugin manager. A plugin manager helps to manage the installation and configuration of plugins. AstroNvim is built around plugins, and hence around Lazy. + +The power of AstroNvim is that it selects the "best" plugins that help to make `nvim` a great environment for editing, and, more importantly configures those plugins with "reasonable" defaults. + +Many people find great value in having the plugins selected and configured for them. AstroNvim: + +- Encapsulates the complexity of plugin configuration +- Takes care of the interactions among plugins +- Takes care of the interactions with `nvim` +- Provides "sane" defaults for plugins + +Another win is that you are not locked in to the plugins that are part of AstroNvim. Except for the `AstroNvim/*` plugins, all of the plugins can be disabled if they are not to your liking. Additional plugins can be added if they suit your needs better. Finally, all of the plugins can have their configuration tuned to your liking. + +Lazy is particularly feature rich in that it helps with plugin life cycle management. A few of the life cycle features are: + +- Installation of plugins from different sources, such as from GitHub or from a local directory. +- Uninstalling plugins when they are no longer referenced in your configuration. +- Lazily loading plugins meaning that plugins can be loaded only when needed, such as on some editor event happening, benefiting `nvim` startup time. +- Compiles plugin `lua` code into native code for your system, helping with execution speed of plugin code. + +To see all available options for defining plugins in Lazy.nvim please refer to the [Lazy.nvim Plugin Spec](https://github.com/folke/lazy.nvim#-plugin-spec). Here we will go over examples of defining new plugins, overriding plugins, and disabling plugins. + +## Defining Plugins + +To install and configure a plugin, a _plugin specification_ is required. Here is an example of a specification for the `catppuccin` theme: + +```lua title="lua/plugins/catppuccin.lua" +return { + { + "catppuccin/nvim", + name = "catppuccin", + opts = { + dim_inactive = { enabled = true, percentage = 0.25 }, + highlight_overrides = { + mocha = function(c) + return { + Normal = { bg = c.mantle }, + Comment = { fg = "#7687a0" }, + ["@tag.attribute"] = { style = {} }, + } + end, + }, + }, + }, +} +``` + +The code above resides in a file. The name of the file can be any valid filename, as long as the file's extension is `.lua`. By convention, many people name the file after the plugin that is being installed. So, in the example above, the file would be called `catppuccin.lua` and if you are following the AstroNvim template then the file would be located in the `lua/plugins` directory. + +The `return` statement is returning a table of tables. The outer table is a list of _plugin specifications_. Each entry in the list is a single plugin specification. + +The first entry in the plugin specification is the name of the plugin to load, specified in short URL form. The next two entries in the table, `name` and `opts` are Lazy recognized keys that direct Lazy on how to configure this plugin. `opts` can be a table or a function (`opts` is a table in the example above) that contains the configuration for the plugin. The structure of what is inside of `opts` is up to each plugin. + +To learn more about plugin specifications, see the [Lazy documentation](https://github.com/folke/lazy.nvim#-plugin-spec). + +That's it! When `nvim` is started, the `catppuccin` plugin will be downloaded from GitHub, installed, configured, and loaded. + +## Configure AstroNvim Plugins + +Overriding plugins are as simple as adding a plugin specification for that plugin and add modifications to the plugin specification that you want. Lazy.nvim supports extending many keys (`cmd`, `event`, `ft`, `keys`, `opts`, and `dependencies`) while other keys in the plugin specification will fully overwrite the defaults. + +Here are some examples of overwriting some plugins: + +```lua title="lua/plugins/overridden.lua" {5-10} {17-23} +return { + { + "AstroNvim/AstroLSP", + ---@type AstroLSPOpts + opts = { -- extend the plugin options + diagnostics = { + -- disable diagnostics virtual text + virtual_text = false, + }, + }, + }, + -- customize cmp mappings + { + "hrsh7th/nvim-cmp", + -- override the options table that is used + -- in the `require("cmp").setup()` call + opts = function(_, opts) + -- opts parameter is the default options table + -- the function is lazy loaded so cmp is able to be required + local cmp = require("cmp") + -- modify the mapping part of the table + opts.mapping[""] = cmp.mapping.select_next_item() + end, + }, + -- customize treesitter parsers + { + "nvim-treesitter/nvim-treesitter", + opts = function(_, opts) + -- list like portions of a table cannot be merged naturally and require the user to merge it manually + -- check to make sure the key exists + if not opts.ensure_installed then + opts.ensure_installed = {} + end + vim.list_extend(opts.ensure_installed, { + "lua", + "vim", + -- add more arguments for adding more treesitter parsers + }) + end, + }, +} +``` + +Here is a link to all of the AstroNvim [plugin configuration files.](https://github.com/AstroNvim/AstroNvim/tree/v4/lua%2Fastronvim%2Fplugins). This is useful to see all the plugins installed by AstroNvim and see their default configuration. + +### How `opts` Overriding Works + +When configuring plugins the main configuration point is modifying a plugin's setup options through the `opts` key. As plugin specs are loaded in by `lazy.nvim` this field (along with others) is merged with previous settings that `lazy.nvim` has already setup. There are 2 main formats that this `opts` field can be set to. The first is a simple `table` which is directly merged using `vim.tbl_deep_extend` and the second is by using a Lua `function` that gives you complete control over the table itself. + +The `table` notation is the simplest method for configuration but does not cover all of the cases that users will experience which makes the `function` notation necessary in some situations. Understanding when to use each can make life much easier when doing advanced configuration. Here are a few cases in which the `table` notation may not do what you want: + +- When passing a `table` in Lua it is resolved immediately. This can break lazy loading and try to access modules before they are available. When passing a `function` in Lua the contents are only resolved when it is executed. This allows for safe accessing of modules when they should be available. +- When using the `table` notation for overriding, merging works great for dictionary-like entries with a key/value pair, but does not do any actual "merging" for list-like tables. Instead the list-like table will be replaced completely. This can be resolved in the `function` notation by manually doing the list merging that you want either with something like the Lua function `table.insert` or provided Neovim functions like `vim.list_extend`. + +Let's take a closer look at these two notations with an example using [`nvim-treesitter`](https://github.com/nvim-treesitter/nvim-treesitter). Let's assume the default configuration for `nvim-treesitter` is: + +```lua +return { + "nvim-treesitter/nvim-treesitter", + opts = { + ensure_installed = { "lua", "vim" }, + highlight = { + enable = true, + }, + }, +} +``` + +With this specification the current `opts` would resolve to the table: + +```lua +opts = { + ensure_installed = { "lua", "vim" }, + highlight = { + enable = true, + }, +} +``` + +If you use the table notation to override these fields in your configuration like this: + +```lua +return { + "nvim-treesitter/nvim-treesitter", + opts = { + ensure_installed = { "python" }, + highlight = { + enable = false, + }, + indent = { + enable = false, + }, + }, +} +``` + +You would end up with the `opts` resolving to: + +```lua +opts = { + ensure_installed = { "python" }, + highlight = { + enable = false, + }, + indent = { + enable = false, + }, +} +``` + +The `highlight.enabled` and `indent.enabled` fields work as expected, but the `ensure_installed` table does not actually extend the list and instead simply overwrites it. This is a limitation of the table merging. To resolve this we can rewrite our `opts` as a function where the first parameter is the resolve plugin specification (this is rarely used but may be useful in very advanced cases) and the second parameter which is the current `opts` table: + +```lua +return { + "nvim-treesitter/nvim-treesitter", + opts = function(plugin, opts) + table.insert(opts.ensure_installed, "python") + end, +} +``` + +You would end up with the `opts` resolving to: + +```lua +opts = { + ensure_installed = { "lua", "vim", "python" }, + highlight = { + enable = true, + }, +} +``` + +One thing to be careful for that the `table` merging handles that the function notation will not is the automatic creation of nested/parent keys. For example, if we want to set `indent.enable = true` in our `opts` with the function notation, it would look something like this: + +```lua +return { + "nvim-treesitter/nvim-treesitter", + opts = function(plugin, opts) + -- check if an `indent` table exists, if not, create it + if not opts.indent then + opts.indent = {} + end + -- once we know it is created, we can set the sub-keys + opts.indent.enable = true + end, +} +``` + +You would end up with the `opts` resolving to: + +```lua +opts = { + ensure_installed = { "lua", "vim", "python" }, + highlight = { + enable = true, + }, +} +``` + +Notice how we didn't return anything from this function. In Lua, tables are passed by reference to functions which means if we modify the table directly then that will automatically apply to the plugin. We can however decide to return the table we want which will take full precedence over the `opts` table that was passed in. For example, if we wanted to completely clear the options: + +```lua +return { + "nvim-treesitter/nvim-treesitter", + opts = function(plugin, opts) + return {} + end, +} +``` + +You would end up with the `opts` resolving to: + +```lua +opts = {} +``` + +The last thing that this function notation provides is the ability to `require` modules safely even with lazy loading. `nvim-treesitter` isn't a great example of this, so here is a simple example with `nvim-cmp`. `nvim-cmp` allows the configuration of mappings and provides helper functions to make setting these mappings easy. Because `nvim-cmp` is lazy loaded, the function notation is required in this situation so that we don't break the lazy loading: + +```lua +return { + "hrsh7th/nvim-cmp", + opts = function(plugin, opts) + -- opts parameter is the default options table + -- the function is lazy loaded so cmp is able to be required + local cmp = require("cmp") + -- make sure there is a `mapping` table in the `opts` + if not opts.mapping then + opts.mapping = {} + end + -- modify the mapping part of the table + opts.mapping[""] = cmp.mapping.select_next_item() + end, +} +``` + +### Extending Core Plugin Config Functions + +Many of our core plugins have additional code that runs during setup which you might want to extend. For this reason we have included our own modules in `require("astronvim.plugins.configs.X")` (replacing `X` with the plugin `require` string) that returns the AstroNvim default config function in each plugin specification that has a `config` function which can be easily called if you want to extend a plugin configuration. This is particularly useful if you want to do something like add rules to `nvim-autopairs`, add user snippets to `luasnip`, or add more extensions to `telescope` without having to rewrite our entire configuration function. Here is an example of adding the `media_files` Telescope extension: + +:::note + +Not all plugins have custom `config` functions and will not have an `astronvim.plugins.configs.X` module. The Lua language server provides autocompletion that is useful for identifying which plugins have a core `config` function. + +::: + +```lua title="lua/plugins/extended_config.lua" {10-11} +return { + { + "nvim-telescope/telescope.nvim", + dependencies = { -- add a new dependency to telescope that is our new plugin + "nvim-telescope/telescope-media-files.nvim", + }, + -- the first parameter is the plugin specification + -- the second is the table of options as set up in Lazy with the `opts` key + config = function(plugin, opts) + -- run the core AstroNvim configuration function with the options table + require("astronvim.plugins.configs.telescope")(plugin, opts) + + -- require telescope and load extensions as necessary + require("telescope").load_extension("media_files") + end, + }, +} +``` + +## Disabling Plugins + +Plugins can be easily disabled by simply setting the `enabled` option to `false`. Here is an example of disabling the core dashboard plugin, `alpha`: + +```lua title="lua/plugins/disabled.lua" "enabled = false" +return { + { "goolord/alpha-nvim", enabled = false }, +} +``` + +## Lazy Loading + +Lazy loading can be used to delay plugin loading to speed up start up time. There are a few basic methods of lazy loading that can be easily added. The main keys here are `lazy`, `cmd`, `ft`, `keys`, and `event`. More details of these and more options can be found in the [Lazy Documentation](https://github.com/folke/lazy.nvim#-plugin-spec). Here are a few examples: + +```lua title="lua/plugins/lazy_loaded.lua" /((lazy|event|cmd|ft|keys) = (\S+|{.*}))/ +return { + -- by enabling the lazy option, the plugin will automatically be lazy loaded + -- until it's module is called for example require("tokyonight") + { "folke/tokyonight.nvim", lazy = true }, + + -- this plugin will be loaded on the autocmd event "UIEnter" + { "rcarriga/nvim-notify", event = "UIEnter" }, + + -- this plugin will be loaded when using `:ZenMode` + { "folke/zen-mode.nvim", cmd = "ZenMode" }, + + -- this plugin will be loaded when using `:ZenMode` + { "folke/zen-mode.nvim", cmd = "ZenMode" }, + + -- this plugin will be loaded when opening a "markdown" file + { "lukas-reineke/headlines.nvim", ft = "markdown" }, +} +``` + +### Lazy Load File Related Plugins + +AstroNvim has many plugins that we load on the first real file that is open. This is used internally for plugins like Treesitter, LSP related plugins, and other various plugins related to interacting with files. We achieve this by creating a custom `User` `autocmd` event called `AstroFile`. This can also be used by users for lazy loading plugins on the first real file that is opened: + +```lua title="lua/plugins/nvim-colorizer.lua" {4} +return { + { + "NvChad/nvim-colorizer.lua", + event = "User AstroFile", + }, +} +``` + +This will tell AstroNvim that this plugin should be loaded whenever the `User` autocmd event `AstroFile` is fired. + +### Lazy Load Git Plugins + +Similar to the file related plugins described above, we also have a similar hook for git related plugins. These shouldn't be loaded until a file is open that is in a git repository folder. We use this for stuff like the `gitsigns` plugin. This will check when a file is opened if it is in a git tracked folder and then load the plugin. This `User` `autocmd` event is `AstroGitFile`. **This does require access to the `git` command in your `PATH`.** + +```lua title="lua/plugins/gitsigns.lua" {4} +return { + { + "lewis6991/gitsigns.nvim", + event = "User AstroGitFile", + }, +} +``` diff --git a/src/content/docs/configuration/lua_completion.md b/src/content/docs/configuration/lua_completion.md index 0d6f8eaff..0309b3e8e 100644 --- a/src/content/docs/configuration/lua_completion.md +++ b/src/content/docs/configuration/lua_completion.md @@ -11,7 +11,7 @@ Each of the core AstroNvim plugins have full integration with the Lua Language S | AstroUI | `AstroUIOpts` | | AstroLSP | `AstroLSPOpts` | -In `lazy.nvim` there are a couple formats that the `opts` can be specified in, either a Lua table or a Lua Function. Here is the notation to specify the typing in each situation. For more information on how plugins are customized, check out the [Custom Plugins page](/configuration/custom_plugins). +In `lazy.nvim` there are a couple formats that the `opts` can be specified in, either a Lua table or a Lua Function. Here is the notation to specify the typing in each situation. For more information on how plugins are customized, check out the [Customizing Plugins page](/configuration/customizing_plugins). ### `opts` Table diff --git a/src/content/docs/configuration/v4_migration.md b/src/content/docs/configuration/v4_migration.md index e669a43c1..5a540e65d 100644 --- a/src/content/docs/configuration/v4_migration.md +++ b/src/content/docs/configuration/v4_migration.md @@ -3,132 +3,222 @@ id: v4_migration title: Migration to v4.0 --- -The largest change between AstroNvim v3 and v4 is the transition towards shipping AstroNvim as a pack of plugins which can be distributed, updated, and configured entirely through the [`lazy.nvim` plugin manager](https://github.com/folke/lazy.nvim). Rather than cloning AstroNvim and then configuring everything through a `user/` folder inside a configuration you download, you simply set up your own Neovim configuration with `lazy.nvim`, add AstroNvim, and then import it's plugins. Nearly all of the configuration after that is done through the configuration of plugins with `lazy.nvim`. This page will help guide you through migrating your user configuration from your previous `user/` folder to your own neovim configuration that utilizes AstroNvim v4. +While there are many small improvements to AstroNvim in version 4, the major update is a move to use the [`lazy.nvim`](https://github.com/folke/lazy.nvim) plugin manager for much more of the configuration. + +The first major change is that the installation of AstroNvim itself is through `lazy.nvim`. Rather than cloning AstroNvim, as was done in previous versions, AstroNvim is "just another" plugin and it is installed using `lazy.nvim`. + +The second major change is that AstroNvim configuration has been split among a number of plugins, each with their own configuration. While the [AstroNvim](https://github.com/AstroNvim/AstroNvim/tree/v4) plugin is still the main plugin, it has very limited configuration options. + +The new plugins are: + +- [AstroCore](https://github.com/AstroNvim/astrocore) - Provides a configuration interface for "core" AstroNvim functions, such as key mappings, auto commands, etc. The [configuration here](https://github.com/AstroNvim/astrocore#%EF%B8%8F-configuration) provides an example and `:help astrocore` provides help within Neovim. AstroCore also has an API for utility functions that help with managing and updating your configuration. +- [AstroLSP](https://github.com/AstroNvim/astrolsp) - Provides a configuration interface for Language Server Protocol (LSP) functions. The [configuration here](https://github.com/AstroNvim/astrolsp#%EF%B8%8F-configuration) provides an example and `:help astrolsp` provides help within Neovim. +- [AstroUI](https://github.com/AstroNvim/astroui) - Provides a configuration interface for User Interface (UI) functions, such as setting the colorscheme, highlights, icons, etc. The [configuration here](https://github.com/AstroNvim/astroui#%EF%B8%8F-configuration) provides and example and `:help astroui` provides help within Neovim. + +All AstroNvim configuration is coordinated through those plugins above. + +:::note + +Before getting started it is recommended to review the [Getting Started](/) guide. The guide explains how AstroNvim uses `lazy.nvim` and it also explains the AstroNvim configuration template, which is the recommended way to migrate from the previous version. + +::: ## Setting Up a Migration Environment -With upgrading requiring dealing with breaking changes to your text editor configuration, we recommend setting up an isolated environment to safely migrate over your configuration at whatever pace you need. On the Alternative Installation reference page we have a section for setting up an [Isolated Installation](/reference/alt_install/#isolated-installation) which we would highly recommend using to do the migration from AstroNvim v3 to v4 so it does not interrupt your editor workflow and allows you to take your time. Here are some example steps to get started with a migration: +Breaking your working editor configuration when migrating to v4 will make it difficult to edit your new configuration. As such, we **recommend following the process** below so that your existing editor keeps working while migrating to the v4 configuration. This workflow makes use of an [Isolated Installation](/reference/alt_install/#isolated-installation) environment. -1. Clone the new AstroNvim v4 template to a new configuration location: +1. Clone the AstroNvim v4 configuration template to a new location (`astronvim_v4` is used as the example): ```sh git clone https://github.com/AstroNvim/template ~/.config/astronvim_v4 rm -rf ~/.config/astronvim_v4/.git ``` -2. Run the new environment: +2. Start `nvim` in the new environment. `nvim` should start, bootstrap itself by installing and loading `lazy.nvim`. Lazy will load all of the plugins specified by AstroNvim. ```sh NVIM_APPNAME=astronvim_v4 nvim ``` -3. Migrate your AstroNvim v3 configuration to your new AstroNvim v4 environment at `~/.config/astronvim_v4`. You can use your AstroNvim v3 setup to do the editing and then continue running the command in Step 2 to test the new installation. +3. Migrate your AstroNvim v3 configuration to your new AstroNvim v4 environment at `~/.config/astronvim_v4` using the guide below. You can use your previous AstroNvim setup to do the editing and then continue running the command in Step 2 to test the new installation. -4. Once you have your configuration set up how you like it, simply move it over to the default neovim configuration location: +4. Once you have your configuration set up how you like it, move it over to the default neovim configuration location `~/.config/nvim`: ```sh mv ~/.config/nvim ~/.config/nvim.bak # backup old config mv ~/.config/astronvim_v4 ~/.config/nvim # move new config ``` -5. Run your new v4 environment simply with `nvim` +5. Run your new v4 environment simply with `nvim` 🎉 ## Migration Guide -:::danger - -Currently this is the old v3 migration guide, this should be updated to migrating to v4 - -::: - -## Old Configuration Options - -These need to be converted into mappings from v3 to their locations in AstroCore/AstroUI/AstroLSP - -| `user/init.lua` table key | Expected Format | Use Case | Alternate File Path (in `user/` folder) | -| -------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -| `colorscheme` | `string` | The colorscheme to be set | `colorscheme.lua` | -| `diagnostics` | `table`, `function(table)` | Modify the default vim diagnostics options | `diagnostics.lua` | -| `heirline.attributes` | `table`, `function(table)` | Modify the section highlight attributes used by Heirline | `heirline/attributes.lua` | -| `heirline.colors` | `table`, `function(table)` | Modify the section colors used by Heirline | `heirline/colors.lua` | -| `heirline.icon_highlights` | `table`, `function(table)` | Modify which components should do dynamic icon highlighting Heirline | `heirline/icon_highlights.lua` | -| `heirline.separators` | `table`, `function(table)` | Modify the section separators used by Heirline | `heirline/separators.lua` | -| `highlights.init` | `table`, `function(table)` | Custom highlight groups for the all colorschemes | `highlights/init.lua` | -| `highlights.` | `table`, `function(table)` | Custom highlight groups for the specified theme, replace `` with colorscheme name | `highlights/.lua` | -| `icons` | `table`, `function(table)` | Customize the icons used in the user interface | `icons.lua` | -| `lazy` | `table`, `function(table)` | Modify the default lazy.nvim `setup` configuration table | `lazy.lua` | -| `lsp.capabilities` | `table`, `function(table)` | Modify the default LSP `capabilities` table | `lsp/capabilities.lua` | -| `lsp.config.` | `table`, `function(table)` | Modify the LSP server settings, replace `` with server name | `lsp/config/.lua` | -| `lsp.flags` | `table`, `function(table)` | Modify the default LSP `flags` table | `lsp/flags.lua` | -| `lsp.formatting` | `table`, `function(table)` | Modify the formatting options described in the [LSP Configuration Page](../../recipes/advanced_lsp#controlling-formatting) | `lsp/formatting.lua` | -| `lsp.mappings` | `table`, `function(table)` | Modify the buffer mappings that are set when a language server attaches | `lsp/mappings.lua` | -| `lsp.on_attach` | `function(client, bufnr)` | Modify the default LSP `on_attach` function | `lsp/on_attach.lua` | -| `lsp.servers` | `table`, `function(table)` | List of language servers to be set up that are already installed without `mason` | `lsp/servers.lua` | -| `lsp.setup_handlers` | `table`, `function(table)` | Modify the `lspconfig` setup handler for a given language server, each key in the table should be a language server | `lsp/setup_handlers.lua` | -| `lsp.skip_setup` | `table`, `function(table)` | List of language servers to guarantee the `lspconfig` setup is never called on automatically | `lsp/skip_setup.lua` | -| `mappings` | `table`, `function(table)` | Modify the mappings table | `mappings.lua` | -| `options` | `table`, `function(table)` | The `vim.x.y` variables to be set | `options.lua` | -| `plugins` | `table` | Modify the `lazy.nvim` plugin specifications | `plugins/.lua` | -| `polish` | `function()` | Lua function to be run last. Good place for setting vim options and adding mappings | `polish.lua` | -| `text_icons` | `table`, `function(table)` | Customize the text based icons used in the user interface when `vim.g.icons_enabled = false` | `text_icons.lua` | -| `updater` | `table`, `function(table)` | The configuration for the AstroNvim updater | `updater.lua` | - -## Migrating User Configuration +### Configuration Option Changes -- **Plugin Manager Change:** With v3 we have moved away from Packer and to the new [lazy.nvim](https://github.com/folke/lazy.nvim). The options for lazy can be configured with the `lazy` user option. We have also removed all abstraction away from the plugin specifications. So the lazy.nvim docs can be referred to for the format of adding new plugins. You can also check the updated [Customizing Plugins Documentation](../custom_plugins) for defining new plugins as well as overriding core plugins. +:::caution - - Lazy also handles overriding options and setup functions automatically so we have removed all of the `plugins.X` user options for overriding the setup tables for the core provided plugins. These can be set up, extended, and configured similar to any other plugin that you are adding. - - **Note:** The default options for lazy sets `lazy = true` for each plugin. This means plugins should either be configured appropriately for lazy loading or use `lazy = false` if you do not want a plugin to be lazy loaded - - The `user/plugins/` folder is added to the Lazy plugin specifications to be imported. This allows you to add lists of plugins to any files in the `user/plugins/` folder and they will be used appropriately. This will allow you to organize your plugins in any way you would prefer. +This is a work in progress. This guide is taking shape and covers much of the migration. There are holes though! If you see something missing drop a note on the Discord `#v4_testing` channel or open a pull request on GitHub. -- `astronvim.file_plugins` and `astronvim.git_plugins` tables have been removed in favor of a `User` `autocmd` model. Wherever you are using `astronvim.file_plugins` or `astronvim.git_plugins` to lazy load your plugins, please switch to lazy loading on the user events `User AstroFile` and `User AstroGitFile`. More details for these can be found in the updated [Customizing Plugins Documentation](../custom_plugins). - -- A large restructuring of our internal utilities has taken place. - - - Our `core` module has been renamed to `astronvim` so anywhere you use `require("core...")` will need to be replaced with `require("astronvim...")` - - Most utility functions in the global `astronvim` variable have been separated into specific modules and can be accessed with require such as: `require("astronvim.utils")`. Commonly used changes are: `astronvim.lsp` is now `require("astronvim.utils.lsp")`, `astronvim.status` is now `require("astronvim.utils.status")`, and most of the various utilities are now just in `require("astronvim.utils")`. Please check out the updated API documentation here for specific details and finding specific functions: [api.astronvim.com](https://api.astronvim.com). - -- We have removed Bufferline and are now using Heirline and `astronvim.utils.status` (previously was in `astronvim.status` but is now accessed with `require("astronvim.utils.status")`) for our own performant and custom tabline. - -- `:AstroReload` has been removed. There are a couple reasons for this, it was never very reliable and hard to maintain and lazy.nvim strictly does not support hot reloading neovim configurations. - -- The `require("astronvim.utils.status").component.macro_recording` status component has been removed. Please use the improved `require("astronvim.utils.status").component.cmd_info` component. - -- `lsp.server-settings` has been renamed to `lsp.config`. If you have the `["server-settings"]` table in your `user/init.lua` file, just rename it to `config`. If you have the folder `user/lsp/server-settings`, just rename the folder to `user/lsp/config`. - -- `luasnip` options table has been removed. Please see the updated [Custom Snippets Documentation](../../recipes/snippets) for the new way to extend the default configuration of LuaSnip to add new loaders. - -- `which-key` options table has been removed. Which-key menu titles can now be easily added into the `mappings` table by setting a binding to a table with the `name` property set and it will be passed to `which-key`. For example, you can add the following to the `mappings` table: `["b"] = { name = "Buffer" }`. - -- `nvim-autopairs` options table has been removed. Please see the updated [Customize Autopairs Documentation](../../recipes/autopairs) for the new way to extend the default configuration of autopairs and adding more rules. - -- `cmp` options table has been removed. Please see the updated [Customize cmp Completion Documentation](../../recipes/cmp) for the new way to extend the default configuration of cmp and running more `cmp` setup functions. - -- `mason-lspconfig`, `mason-null-ls`, and `mason-nvim-dap` options tables have been removed, please use the new plugin notation for extending these options like adding custom setup handlers. This is described in the [Extending Core Plugin Config Functions Documentation](../custom_plugins#extending-core-plugin-config-functions). - -- `default_theme` has been migrated to a dedicated plugin that can be used outside of AstroNvim as well at [AstroNvim/astrotheme](https://github.com/AstroNvim/astrotheme). This can be customized and configured the same as any other plugin, check the README for details on the `setup` function. - -- The bindings in `cmp` to scroll the preview window for a completion item have moved to `` and `` +::: -- `p` mappings for package and plugin management have been cleaned up to follow a common format amongst each other. `ps` is now for checking Plugin Status and `pS` is for syncing plugins. Mason mappings have been moved to `pm` and `pM` for Mason Status and Mason Update respectively. +Each "Migrating" section below has an link to documentation and/or an example configuration. Each example configuration file shows the structure for configuring that plugin. The comments in each example configuration describes the configuration keys. -- The dashboard mapping has been changed from `d` to `h` for the "Home Screen" +:::note -- The debugging menu has been moved from `D` to `d` for quicker and more comfortable usage. +**Recommended reading**: for each plugin there is a link to example configuration. These configurations are full of documentation and can help guide your migration! -- `H` and `L` have been changed to `[b` and `]b` respectively for changing tabs in the UI. This is for both switching buffers as well as neo-tree sources in the explorer. This can be changed in the your user configuration by adding the following entries to your `mappings.n` table (This uses an internal `astronvim.utils.buffer` function that follows the tab positioning and also allows for using a number to move by multiple tabs at once): +::: -```lua - L = { function() require("astronvim.utils.buffer").nav(vim.v.count > 0 and vim.v.count or 1) end, desc = "Next buffer" }, - H = { function() require("astronvim.utils.buffer").nav(-(vim.v.count > 0 and vim.v.count or 1)) end, desc = "Previous buffer" }, -``` +The [plugin configuration files.](https://github.com/AstroNvim/AstroNvim/tree/v4/lua%2Fastronvim%2Fplugins) in the AstroNvim codebase itself are also a good reference to learn how to configure. + +**Please also read the [Other Changes section](./#other-changes)** - there are a number of changes that are not just "move some config from one place to another". For example, in key mapping `` is no longer recognized. + +If you get stuck, people on the [Discord](https://discord.astronvim.com/) forum are active and friendly! Like all humans, sometimes they are grumpy, so be nice to them! The best place to post is most likely the `#help-forum`, but poke around a few of the other channels, you never know what you will find that is useful. + +v3 configuration options in `user/init.lua` and their new location in the core AstroNvim plugin configuration `opts`: + +| v3 `user/init.lua` table key | v4 `AstroNvim/` plugin | v4 plugin `opt` key | +| ---------------------------- | ---------------------- | --------------------------- | +| `colorscheme` | `astroui` | `colorscheme` | +| `diagnostics` | `astrolsp` | `diagnostics` | +| `heirline.attributes` | `astroui` | `status.attributes` | +| `heirline.colors` | `astroui` | `status.colors` | +| `heirline.icon_highlights` | `astroui` | `status.icon_highlights` | +| `heirline.separators` | `astroui` | `status.separators` | +| `highlights.init` | `astroui` | `highlights.init` | +| `highlights.` | `astroui` | `highlights.` | +| `icons` | `astroui` | `icons` | +| `lsp.capabilities` | `astrolsp` | `capabilities` | +| `lsp.config.` | `astrolsp` | `config.` | +| `lsp.flags` | `astrolsp` | `flags` | +| `lsp.formatting` | `astrolsp` | `formatting` | +| `lsp.mappings` | `astrolsp` | `mappings` | +| `lsp.on_attach` | `astrolsp` | `on_attach` | +| `lsp.servers` | `astrolsp` | `servers` | +| `lsp.setup_handlers` | `astrolsp` | `handlers` | +| `lsp.skip_setup` | `astrolsp` | Set `handler. = false` | +| `mappings` | `astrocore` | `mappings` | +| `options` | `astrocore` | `options` | +| `text_icons` | `astroui` | `text_icons` | + +v3 keys which are now handled entirely by the user in their configuration. Here are examples for where the configuration goes in the provided starter template: + +| `user/init.lua` table key | Starter Template Migration | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `lazy` | `lazy` is bootstrapped through `init.lua` and configured using `lua/lazy_setup.lua` | +| `plugins` | Plugins are in the directory `lua/plugins/.lua` | +| `polish` | `polish` is in the file `lua/polish.lua` | +| `updater` | Updating uses `lazy` update features and is configured in `init.lua` using `lazy` `branch` and `version` plugin spec options. | + +A few options were configured through global (`vim.g`) variables. These have also been moved to our core configuration plugins: + +| v3 `vim.g` variable | v4 `AstroNvim/` plugin | v4 plugin `opt` key | +| -------------------------- | ---------------------- | ----------------------------------- | +| `autoformat_enabled` | `astrolsp` | `formatting.format_on_save.enabled` | +| `autopairs_enabled` | `astrocore` | `features.autopairs` | +| `cmp_enabled` | `astrocore` | `features.cmp` | +| `codelens_enabled` | `astrolsp` | `features.codelens` | +| `diagnostic_mode` | `astrolsp` | `features.diagnostics_mode` | +| `git_worktrees` | `astrocore` | `git_worktrees` | +| `highlighturl_enabled` | `astrocore` | `features.highlighturl` | +| `icons_enabled` | `AstroNvim` | `icons_enabled` | +| `inlay_hints_enabled` | `astrolsp` | `features.inlay_hints` | +| `lsp_handlers_enabled` | `astrolsp` | `features.lsp_handlers` | +| `max_file` | `astrocore` | `features.large_buf` | +| `semantic_tokens_enabled` | `astrolsp` | `features.semantic_tokens` | +| `ui_notifications_enabled` | `astrocore` | `features.notifications` | +| `resession_enabled` | N/A | Resession is now the default | + +The following keys are introduced in v4 and have no equivalent in v3. This configuration was done through user configuration (for example in `polish.lua): + +| New key | v4 `AstroNvim/` plugin | Description | +| ---------- | ---------------------- | ---------------------------------------------------------------------------- | +| `autocmds` | `astrocore` | Configure global auto commands | +| `commands` | `astrocore` | Configure global commands | +| `on_keys` | `astrocore` | Configure functions on key press | +| `rooter` | `astrocore` | Configure project root detection | +| `sessions` | `astrocore` | Configure Resession session management | +| `autocmds` | `astrolsp` | Configure buffer local auto commands to add when attaching a language server | +| `commands` | `astrolsp` | Configure buffer local user commands to add when attaching a language server | + +### Module Changes + +AstroNvim v3 also has many utility functions in `astronvim.utils` modules which users may be using in their user configuration These utility functions have been moved to the various AstroNvim core plugins. Here are the updated modules names which can be used to update `require` statements throughout the user configuration: + +| v3 module | v4 module | +| ---------------------------------- | ----------------------------------------- | +| `astronvim.utils` | `astrocore` | +| `astronvim.utils.buffer` | `astrocore.buffer` | +| `astronvim.utils.git` | N/A - no longer providing a Git Lua API | +| `astronvim.utils.lsp` | `astrolsp` | +| `astronvim.utils.mason` | `astrocore.mason` | +| `astronvim.utils.status` | `astroui.status` | +| `astronvim.utils.status.component` | `astroui.status.component` | +| `astronvim.utils.status.condition` | `astroui.status.condition` | +| `astronvim.utils.status.env` | `astroui.config.status` | +| `astronvim.utils.status.heirline` | `astroui.status.heirline` | +| `astronvim.utils.status.hl` | `astroui.status.hl` | +| `astronvim.utils.status.init` | `astroui.status.init` | +| `astronvim.utils.status.provider` | `astroui.status.provider` | +| `astronvim.utils.status.utils` | `astroui.status.utils` | +| `astronvim.utils.ui` | `astrocore.toggles` | +| `astronvim.utils.updater` | N/A - no longer providing our own updater | + +This table captures most of the changes, here are a few changes that don't exactly follow the above and need to be mentioned specifically: + +- A few `astronvim.util` functions were moved to `astroui` rather than `astrocore`: + - `get_hlgroup` → `require("astroui").get_hlgroup` + - `get_icon` → `require("astroui").get_icon` + - `get_spinner` → `require("astroui").get_spinner` + +### Plugin Changes + +Along with the new core AstroNvim plugins, we have made some other changes to our plugin list that user's should keep in mind while performing the migration. + +- Added: + - [`AstroNvim/AstroNvim`](https://github.com/AstroNvim/AstroNvim) + - AstroNvim is now formatted as a plugin that provides plugin specifications to `lazy.nvim` through `import`. + - [`AstroNvim/astrocore`](https://github.com/AstroNvim/astrocore) + - The core configuration mechanism for AstroNvim for configuring things such as auto commands, mappings, vim options, session management, etc. + - [`AstroNvim/astrolsp`](https://github.com/AstroNvim/astrolsp) + - The core LSP configuration mechanism for AstroNvim which provides a single place of configuration that interfaces between the various LSP plugins. + - [`AstroNvim/astroui`](https://github.com/AstroNvim/astroui) + - The UI configuration mechanism for providing a unified interface such as icon and highlight configuration as well as our extensive `status` Lua API for building our `statusline`, `tabline`, `winbar`, and `statuscolumn` + - [`RRethy/vim-illuminate`](https://github.com/RRethy/vim-illuminate) + - provides more general and performant highlighting of the word under the cursor. If you were previously removing the `augroup` `lsp_document_highlight`, we are no longer creating that `augroup` and instead you should just disable (or configure) this plugin. + - [`folke/todo-comments.nvim`](https://github.com/folke/todo-comments.nvim) + - provides highlighting of known comment strings like `TODO:`. +- Changed: + - [`jose-elias-alvarez/null-ls.nvim`](https://github.com/jose-elias-alvarez/null-ls.nvim) → [`nvimtools/none-ls.nvim`](https://github.com/nvimtools/none-ls.nvim) + - `null-ls` was archived by the author and `none-ls` is a maintainer fork. All `require`s are the same, but if you are configuring `null-ls` in your plugins anywhere be sure to update the repository to `nvimtools/none-ls.nvim`. + - [`Shatur/neovim-session-manager`](https://github.com/Shatur/neovim-session-manager) → [`stevearc/resession.nvim`](https://github.com/stevearc/resession.nvim) + - `resession.nvim` provides a deeper and more configurable Lua API for building up our session management. This allows us to take into account our tab-local buffers when saving and restoring sessions. Similar to how `heirline` provides a framework for building statuslines, `resession` provides a framework for session management. We have added a few easy to configure options in AstroCore under the `sessions` table in the configuration opts for easily configuring auto saving of sessions and rules for ignoring buffers when saving. For advanced configuration please check out the extensive [Ressesion Documentation](https://github.com/stevearc/resession.nvim/) and our [Session Management Recipes](/recipes/sessions). +- Removed: + - [`b0o/SchemaStore.nvim`](https://github.com/b0o/SchemaStore.nvim) + - We are no longer providing `SchemaStore.nvim` out of the box. This will be provided as needed in the AstroCommunity language packs. + +### Other Changes + +:::caution + +`mapleader` and `maplocalleader` must be configured either before the `lazy.setup` call or in the `AstroNvim/AstroNvim` `opts` (This is in the `lua/lazy_setup.lua` file in the official template). This is required due to the way that `lazy.nvim` plugin manager works and how Neovim creates mappings with the leaders. -- `header` option has been removed in favor of decreasing abstractions. Check the updated [Dashboard Customizations Documentation](../../recipes/alpha) +::: -- `s` has been unified with the `f` menu rather than spreading the Telescope mappings out across two menus. Please check the new mappings by pressing `f` or in the updated [Mappings Documentation](/mappings) +- Key codes in the keys for the mappings for AstroNvim are now normalized to match the casing in the official vimdocs. For example in v3 our mappings used ``, but this is now changed to ``. +- `mapleader` and `maplocalleader` must be set in the `AstroNvim/AstroNvim` configuration spec `opts` or before the `require("lazy").setup` call in your Neovim configuration. +- `MasonUpdate` and `MasonUpdateAll` commands have been renamed to `AstroMasonUpdate` and `AstroMasonUpdateAll` to avoid conflicting with core Mason commands +- `u` mappings have been modified to align buffer-local and global commands to a common standard +- The `file_info` component in the `status` API default options have been changed. If you are using `file_info` in your configuration, please refer to the new defaults in the [AstroUI Repository](https://github.com/AstroNvim/astroui/blob/main/lua/astroui/status/component.lua#L34-L57). +- `signs` is no longer used for configuring diagnostic signs. This is now configured in the `diagnostics` table under the `signs` key. If you are modifying the diagnostic signs in your configuration, please refer to the [AstroLSP configuration in AstroNvim](https://github.com/AstroNvim/AstroNvim/blob/v4/lua/astronvim/plugins/_astrolsp.lua#L45-L54) +- The `signs` table is now a dictionary format rather than a list to more closely align with the core Neovim Lua API as well as make it easier for the user to modify. If you are customizing signs in your user configuration, the field that was previously `name` in the list is now the key in a dictionary like table. +- The "loop" text object configured in `nvim-treesitter-text-objects` has been changed from `l` to `o` to avoid collisions with the common text object for line -- Heirline has moved to a more sustainable configuration format for their `setup` call. Before it was configured with `require("heirline").setup(statusline, winbar, tabline)`, this has moved to a new format with a single table like `require("heirline").setup({ statusline = statusline, winbar = winbar, tabline = tabline, statuscolumn = statuscolumn })`. If you have a custom Heirline configuration please check out the updated [Customizing Statusline Documentation](../../recipes/status) as well as the updated [Heirline Documentation](https://github.com/rebelot/heirline.nvim/blob/master/cookbook.md). (_Note:_ also that along with all of the other core plugin setups, the abstractions have been removed and you will need to update to the new Lazy syntax described in the [Custom Plugins Documentation](../custom_plugins#overriding-core-plugins)) +### New Features -- `lsp.skip_setup` option has been removed as the new and improved `lsp.setup_handlers` option makes this easy. If you are using this option for LSP specific plugins, check up the updated [Advanced LSP Setup Documentation](../../recipes/advanced_lsp#lsp-specific-plugins). This page also includes the new format for setting these plugins up with Lazy.nvim. +Some changes have been made that do not necessarily require any user intervention during the migration, but are just new features! Here are a few icon_highlights -- The `default_tbl(override_tbl, default_tbl)` internal function has been removed and replaced with `extend_tbl(default_tbl, override_tbl)`. If you use the original function anywhere in your config, remember to rename it and change the order of the parameters. Also note that this now lives in `astronvim.utils` rather than the global `astronvim` table. This can be accessed with `require("astronvim.utils").extend_tbl(default_tbl, override_tbl)`. +- `shift+enter` in Neo-Tree will now open the file under the cursor with the system. This is useful for opening images or other files that are not supported natively by Neovim. +- Heirline now has a virtual environment component that is in the default configuration. If a virtual environment is activated, it will be shown in the statusline. +- AstroNvim now has a built-in project rooting utility that can be used to update the current working directory to an automatically detected project root. `:AstroRootInfo` can be used to see the current information from the rooter and `:AstroRoot` will update the current working directory to the detected root. This can be configured in AstroCore in the `rooter` settings to update the root automatically as well as changing how the root detection works. +- Large buffer detection has been greatly improved to make working with large files much faster. We have also added a user auto command event (`AstroLargeBuf`) which can be used to disable more things when a large buffer is detected. diff --git a/src/content/docs/faq.md b/src/content/docs/faq.md index 2e31b21a1..541faf7f7 100644 --- a/src/content/docs/faq.md +++ b/src/content/docs/faq.md @@ -13,7 +13,7 @@ If a plugin is missing feel free to contribute it using a pull request. Please j ## How do I customize AstroNvim? -AstroNvim offers the addition of plugin specs with zero abstraction thanks to the [`lazy.nvim`](https://www.github.com/folke/lazy.nvim) plugin manager. Please go through the entire `README.md` for `lazy.nvim` as this will help to build a general understanding for the configuration mechanisms, the available properties, and how to lazily load plugins. More details on customizing plugins in AstroNvim can be found on the [Custom Plugins page](/configuration/custom_plugins). +AstroNvim offers the addition of plugin specs with zero abstraction thanks to the [`lazy.nvim`](https://www.github.com/folke/lazy.nvim) plugin manager. Please go through the entire `README.md` for `lazy.nvim` as this will help to build a general understanding for the configuration mechanisms, the available properties, and how to lazily load plugins. More details on customizing plugins in AstroNvim can be found on the [Customizing Plugins page](/configuration/customizing_plugins). You can get a template configuration from [here!](https://github.com/AstroNvim/template) This should provide a solid starting point on which you can build your customized environment. Check out the pages for [Using these docs](/using_the_docs) and [Manageing User Configuration](/configuration/manage_user_config). diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 4c65f2610..ab0ebbcf4 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -1,8 +1,6 @@ --- id: intro title: Getting Started -tableOfContents: - maxHeadingLevel: 2 --- import { Tabs, TabItem } from "@astrojs/starlight/components"; @@ -54,17 +52,19 @@ color support. ## 🛠️ Installation +[Our configuration template](https://github.com/AstroNvim/template) is an easy way to going with AstroNvim. The template provides a directory structure with the required files in place. Within the files some indication, through commented out code, of how to configure the feature. Here are the instructions for installing this template: + -### Make a backup of your current nvim folder +1. **Make a backup of your current nvim folder** ```sh mv ~/.config/nvim ~/.config/nvim.bak ``` -#### Clean neovim folders (Optional but recommended) +2. **Clean neovim folders** _(Optional but recommended)_ ```sh mv ~/.local/share/nvim ~/.local/share/nvim.bak @@ -72,7 +72,7 @@ mv ~/.local/state/nvim ~/.local/state/nvim.bak mv ~/.cache/nvim ~/.cache/nvim.bak ``` -### Clone the repository +3. **Clone the repository** ```sh git clone --depth 1 https://github.com/AstroNvim/template ~/.config/nvim @@ -85,19 +85,19 @@ nvim -### Make a backup of your current nvim folder +1. **Make a backup of your current nvim folder** ```powershell Move-Item $env:LOCALAPPDATA\nvim $env:LOCALAPPDATA\nvim.bak ``` -### Clean old plugins (Optional but recommended) +2. **Clean neovim folders** _(Optional but recommended)_ ```powershell Move-Item $env:LOCALAPPDATA\nvim-data $env:LOCALAPPDATA\nvim-data.bak ``` -### Clone the repository +3. **Clone the repository** ```powershell git clone --depth 1 https://github.com/AstroNvim/template $env:LOCALAPPDATA\nvim @@ -127,41 +127,38 @@ docker run -w /root -it --rm alpine:edge sh -uelic ' ## 📦 Setup -### Install LSP - -Enter `:LspInstall` followed by the name of the server you want to install - -> Example: `:LspInstall pyright` +- **Install LSP** -### Install language parser + Enter `:LspInstall` followed by the name of the server you want to install -Enter `:TSInstall` followed by the name of the language you want to install + > Example: `:LspInstall pyright` -> Example: `:TSInstall python` +- **Install language parser** -### Install Debugger + Enter `:TSInstall` followed by the name of the language you want to install -Enter `:DapInstall` followed by the name of the debugger you want to install + > Example: `:TSInstall python` -> Example: `:DapInstall python` +- **Install Debugger** -### Manage plugins + Enter `:DapInstall` followed by the name of the debugger you want to install -Run `:Lazy check` (`pu`) to check for plugin updates + > Example: `:DapInstall python` -Run `:Lazy update` (`pU`) to apply any pending plugin updates +- **Manage plugins** -Run `:Lazy sync` (`pS`) to update and clean plugins + - Run `:Lazy check` (`pu`) to check for plugin updates + - Run `:Lazy update` (`pU`) to apply any pending plugin updates + - Run `:Lazy sync` (`pS`) to update and clean plugins + - Run `:Lazy clean` to remove any disabled or unused plugins -Run `:Lazy clean` to remove any disabled or unused plugins +- **Update Mason packages and plugins** -### Update Mason packages and plugins + Run `:AstroUpdatePackages` (`pa`) to update both Neovim plugins and Mason packages -Run `:AstroUpdatePackages` (`pa`) to update both Neovim plugins and Mason packages +- **Reload AstroNvim** (_EXPERIMENTAL_) -### Reload AstroNvim (_EXPERIMENTAL_) - -Run `:AstroReload` to reload the AstroNvim configuration and any new user configuration changes without restarting. This is currently an experimental feature and may lead to instability until the next restart. + Run `:AstroReload` to reload the AstroNvim configuration and any new user configuration changes without restarting. This is currently an experimental feature and may lead to instability until the next restart. ## ✨ Features @@ -182,13 +179,56 @@ Run `:AstroReload` to reload the AstroNvim configuration and any new user config To begin making customizations simply treat your `nvim` folder as your own Neovim configuration! This can be synced to a git repository to backup as well. AstroNvim is simply a plugin managed by the Lazy package manager that provides it's own collection of plugins and their configurations. -## 📦 Community Plugin Configurations +### 🚀 The Starter Template + +If you followed the instructions in this guide for installation, you are probably starting out with our template configuration. This comes with the following basic structure: + +```txt +~/.config/nvim/ +├── README.md +├── init.lua +└── lua/ + ├── community.lua + ├── lazy_setup.lua + ├── plugins/ + │   ├── astrocore.lua + │   ├── astrolsp.lua + │   ├── astroui.lua + │   ├── mason.lua + │   ├── none-ls.lua + │   ├── treesitter.lua + │   ├── user.lua + │   └── vim-sandwich.lua + └── polish.lua +``` + +:::note + +The list of files in the template may change over time as we fine tune what user's want in the template, so the files above may be slightly different from the actual template. + +::: -To avoid duplication of effort, you can use community-provided setups from the [AstroCommunity repository](https://github.com/AstroNvim/astrocommunity). For example, to enable language tools (LSP and DAP etc.) for Rust and Python, your `plugins/community.lua` file can look like the following. +At the top level is `init.lua`. This code bootstraps the configuration by installing [`lazy.nvim`](https://github.com/folke/lazy.nvim) if it is not already installed and then calling `lua/lazy_setup.lua` to install and configure the AstroNvim and user plugins. -**Disclaimer: These setups might not always work. Think of them as VSCode extensions or AUR build scripts, separate from the main AstroNvim project. Report any issues to the [AstroCommunity](https://github.com/AstroNvim/astrocommunity) maintainers, not the AstroNvim maintainers.** +Looking a bit deeper, the `plugins` directory is where all plugins, except AstroNvim and AstroCommunity imports, are setup. The first three plugins are for the AstroNvim configuration. The next four plugins modify the configuration of a plugin that is part of AstroNvim (e.g.: `treesitter.lua`). The last file is not a part of the template. `vim-sandwich` specifies the installation and configuration a plugin of a user specified (i.e.: one that is not a part of AstroNvim distribution). + +Each file in the plugins directory can specify the installation and configuration of one or more plugins. The template generally installs and configures a single plugin per `lua` file. Further, the name of the file generally matches the name of the plugin. The one exception is `user.lua` which has multiple plugins in it - but they could be split into separate files if you wish! + +Be sure to check out the [Configuration/Customizing Plugins page](/configuration/customizing_plugins) and the [Lazy.nvim Documentation](https://github.com/folke/lazy.nvim?tab=readme-ov-file#-plugin-spec) for more details in how to define and configure plugins using `lazy.nvim`. + +There is nothing special about the template! It's merely a quick way to get started, and, well, recommended to get you up and running quicker. Once you have a working configuration that may be the time when you start to move things around. + +### 📦 AstroCommunity + +[AstroCommunity](https://github.com/AstroNvim/astrocommunity) is a plugin specification repository on GitHub. The specifications found there are configurations for many popular plugins that can be used to augment your configuration. There are also "language packs" that are specifications for many programming lanaguages. These are a good way to get setup with a set of tools for the languages that you are using. + +:::caution + +These setups might not always work. Think of them as VSCode extensions or AUR build scripts, separate from the main AstroNvim project. Report any issues to the [AstroCommunity](https://github.com/AstroNvim/astrocommunity) maintainers, not the AstroNvim maintainers. + +::: -```lua +```lua title="lua/community.lua" return { -- Add the community repository of plugin specifications "AstroNvim/astrocommunity", diff --git a/src/content/docs/recipes/colorscheme.md b/src/content/docs/recipes/colorscheme.md index 0e34837ac..12348860e 100644 --- a/src/content/docs/recipes/colorscheme.md +++ b/src/content/docs/recipes/colorscheme.md @@ -14,7 +14,7 @@ There are only 2 simple steps to change colorscheme of your editor: ### Step 1 - Adding a plugin -You can either add a colorscheme plugin directly to your `plugins` as described in the [Custom Plugins Page](/configuration/custom_plugins), for example if you wanted to add [Catppuccin](https://github.com/catppuccin/nvim) you would add the following to your `plugins`: +You can either add a colorscheme plugin directly to your `plugins` as described in the [Customizing Plugins Page](/configuration/customizing_plugins), for example if you wanted to add [Catppuccin](https://github.com/catppuccin/nvim) you would add the following to your `plugins`: ```lua title="lua/plugins/catppuccin.lua" return { diff --git a/src/content/docs/recipes/sessions.md b/src/content/docs/recipes/sessions.md new file mode 100644 index 000000000..8cb816c71 --- /dev/null +++ b/src/content/docs/recipes/sessions.md @@ -0,0 +1,156 @@ +--- +id: sessions +title: Customize Session Management +--- + +Since AstroNvim v4, we have begun using [resession.nvim](https://github.com/stevearc/resession.nvim) for powering session management. This plugins provides an extensive Lua API for building out the features we want when saving and restoring sessions. This allows us to handle things such as our tab-local buffer management. This is a very powerful Lua API but can take some learning to configure the way you want. This page provides a few common recipes that user's want that can be easily added to your user configuration. + +## AstroNvim Defaults + +To ease the use of resession we have built a few features into AstroNvim which can be configured. By default AstroNvim is set up to save the previous session as well as the last session for each working directory on exit and has the ability to configure buffers which the user wants to ignore when saving sessions. These options are configured through the `AstroNvim/astrocore` plugin and has the following defaults: + +```lua title="lua/plugins/astrocore_sessions.lua" +return { + "AstroNvim/astrocore", + ---@type AstroCoreOpts + opts = { + -- Configuration table of session options for AstroNvim's session management powered by Resession + sessions = { + -- Configure auto saving + autosave = { + last = true, -- auto save last session + cwd = true, -- auto save session for each working directory + }, + -- Patterns to ignore when saving sessions + ignore = { + dirs = {}, -- working directories to ignore sessions in + filetypes = { "gitcommit", "gitrebase" }, -- filetypes to ignore sessions + buftypes = {}, -- buffer types to ignore sessions + }, + }, + }, +} +``` + +## Automatically Restore Previous Session + +Some users may want to automatically restore their previous session for a given directory when opening Neovim with no arguments. This can be achieved by setting up an auto command on the `VimEnter` event: + +```lua title="lua/plugins/auto_restore_sessions.lua" +return { + "AstroNvim/astrocore", + ---@type AstroCoreOpts + opts = { + autocmds = { + -- disable alpha autostart + alpha_autostart = false, + restore_session = { + { + event = "VimEnter", + desc = "Restore previous directory session if neovim opened with no arguments", + callback = function() + -- Only load the session if nvim was started with no args + if vim.fn.argc(-1) == 0 then + -- try to load a directory session using the current working directory + require("resession").load( + vim.fn.getcwd(), + { dir = "dirsession", silence_errors = true } + ) + -- trigger buffer read auto commands on each opened buffer after load + vim.tbl_map(vim.cmd.doautoall, { "BufReadPre", "BufReadPost" }) + end + end, + }, + }, + }, + }, +} +``` + +## Git Branch Specific Directory Sessions + +Some users may want to save sessions not only specific to their directory, but also the current branch checked out in `git` if applicable. This can also be easily configurable. + +```lua title="lua/plugins/git_branch_sessions.lua" +-- function for calculating the current session name +local get_session_name = function() + local name = vim.fn.getcwd() + local branch = vim.fn.system("git branch --show-current") + if vim.v.shell_error == 0 then + return name .. vim.trim(branch --[[@as string]]) + else + return name + end +end + +return { + "AstroNvim/astrocore", + ---@type AstroCoreOpts + opts = { + sessions = { + -- disable the auto-saving of directory sessions + autosave = { cwd = false }, + }, + mappings = { + n = { + -- update save dirsession mapping to get the correct session name + ["SS"] = { + function() + require("resession").save( + get_session_name(), + { dir = "dirsession" } + ) + end, + desc = "Save this dirsession", + }, + -- update load dirsession mapping to get the correct session name + ["S."] = { + function() + require("resession").load( + get_session_name(), + { dir = "dirsession" } + ) + end, + desc = "Load current dirsession", + }, + }, + }, + autocmds = { + -- disable alpha autostart + alpha_autostart = false, + git_branch_sessions = { + -- auto save directory sessions on leaving + { + event = "VimLeavePre", + desc = "Save git branch directory sessions on close", + callback = vim.schedule_wrap(function() + if require("astrocore.buffer").is_valid_session() then + require("resession").save( + get_session_name(), + { dir = "dirsession", notify = false } + ) + end + end), + }, + -- auto restore previous previous directory session, remove if necessary + { + event = "VimEnter", + desc = "Restore previous directory session if neovim opened with no arguments", + callback = function() + -- Only load the session if nvim was started with no args + if vim.fn.argc(-1) == 0 then + -- try to load a directory session using the current working directory + require("resession").load( + get_session_name(), + { dir = "dirsession", silence_errors = true } + ) + -- trigger buffer read auto commands on each opened buffer after load + vim.tbl_map(vim.cmd.doautoall, { "BufReadPre", "BufReadPost" }) + end + end, + }, + }, + }, + }, +} +``` diff --git a/src/content/docs/reference/uninstall.mdx b/src/content/docs/reference/uninstall.mdx index 81f9ebcee..d5b0365a9 100644 --- a/src/content/docs/reference/uninstall.mdx +++ b/src/content/docs/reference/uninstall.mdx @@ -1,8 +1,6 @@ --- id: uninstall title: Uninstall AstroNvim -tableOfContents: - maxHeadingLevel: 2 --- import { Tabs, TabItem } from "@astrojs/starlight/components"; @@ -13,6 +11,8 @@ configuration directory. The important next step is that you also remove the state and cache folders so that there are no lingering files from AstroNvim that Neovim might still try to load. +## Commands +