ContextQMD
Back to Astronvim

🚀 Getting Started

src/content/docs/index.mdx

latest10.7 KB
Original Source

import { Tabs, TabItem, FileTree, Steps } from "@astrojs/starlight/components";

:::tip

When getting started, please be sure to check out the Frequently Asked Questions!

:::

AstroNvim is an aesthetically pleasing and feature-rich neovim config that is extensible and easy to use with a great set of plugins

âš¡ Requirements

  • Nerd Fonts (Optional with manual intervention: See Recipes/Customizing Icons) <sup>[1]</sup>
  • Neovim v0.10+ (Not including nightly)
  • Tree-sitter CLI (Note: This is only necessary if you want to use auto_install feature with Treesitter)
  • A clipboard tool is necessary for the integration with the system clipboard (see :help clipboard-tool for supported solutions)
  • Terminal with true color support (for the default theme, otherwise it is dependent on the theme you are using) <sup>[2]</sup>
  • Optional Requirements:
    • ripgrep - live grep file search (<Leader>fw)
    • lazygit - git ui toggle terminal (<Leader>tl or <Leader>gg)
    • go DiskUsage() - disk usage toggle terminal (<Leader>tu)
    • bottom - process viewer toggle terminal (<Leader>tt)
    • Python - python repl toggle terminal (<Leader>tp)
    • Node - Node is needed for a lot of the LSPs, and for the node repl toggle terminal (<Leader>tn)

:::note

<sup id="1">[1]</sup> All downloadable Nerd Fonts contain icons which are used by AstroNvim. Install the Nerd Font of your choice to your system and in your terminal emulator settings, set its font face to that Nerd Font. If you are using AstroNvim on a remote system via SSH, you do not need to install the font on the remote system.

:::

:::note

<sup id="2">[2]</sup> When using default theme: The default MacOS terminal does not support true colors until Tahoe 26. On older versions, use Ghostty, iTerm2, Kitty, WezTerm, or another terminal emulator that has true color support.

:::

🧰 Installation

Our configuration 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:

<Tabs> <TabItem value="nix" label="Linux/Mac OS" icon="linux" default> <Steps>

  1. Make a backup of your current nvim config (if exists)

    sh
    mv ~/.config/nvim ~/.config/nvim.bak

  2. Clean neovim folders (Optional but recommended)

    sh
    mv ~/.local/share/nvim ~/.local/share/nvim.bak
mv ~/.local/state/nvim ~/.local/state/nvim.bak
mv ~/.cache/nvim ~/.cache/nvim.bak

  3. Clone the repository

    sh
    git clone --depth 1 https://github.com/AstroNvim/template ~/.config/nvim
# remove template's git connection to set up your own later
rm -rf ~/.config/nvim/.git
nvim
</Steps> </TabItem> <TabItem value="windoze" label="Windows (PowerShell)" icon="seti:windows"> <Steps>

  1. Make a backup of your current nvim config (if exists)

    powershell
    Move-Item $env:LOCALAPPDATA\nvim $env:LOCALAPPDATA\nvim.bak

  2. Clean neovim folders (Optional but recommended)

    powershell
    Move-Item $env:LOCALAPPDATA\nvim-data $env:LOCALAPPDATA\nvim-data.bak

  3. Clone the repository

    powershell
    git clone --depth 1 https://github.com/AstroNvim/template $env:LOCALAPPDATA\nvim
# remove template's git connection to set up your own later
Remove-Item $env:LOCALAPPDATA\nvim\.git -Recurse -Force
nvim
</Steps> </TabItem> <TabItem value="docker" label="Docker" icon="seti:docker">

If you want to try AstroNvim before installing you can use the following Docker command to open a test instance without touching your current Neovim configuration. This also allows you to use :TSInstall and :LspInstall to load and evaluate language servers and treesitter parsers as well.

sh
docker run -w /root -it --rm alpine:edge sh -uelic '
  apk add bash curl git lua nodejs npm lazygit bottom python3 go neovim ripgrep alpine-sdk --update
  # Replace with your own configuration repository to load a user configuration
  git clone --depth 1 https://github.com/AstroNvim/template ~/.config/nvim
  nvim
'
</TabItem> </Tabs>

📦 Setup

  • Install LSP

    Enter :LspInstall followed by the name of the server you want to install

    Example: :LspInstall pyright

  • Install language parser

    Enter :TSInstall followed by the name of the language you want to install

    Example: :TSInstall python

  • Install Debugger

    Enter :DapInstall followed by the name of the debugger you want to install

    Example: :DapInstall python

  • Manage plugins

    • Run :Lazy check (<Leader>pu) to check for plugin updates
    • Run :Lazy update (<Leader>pU) to apply any pending plugin updates
    • Run :Lazy sync (<Leader>pS) to update and clean plugins
    • Run :Lazy clean to remove any disabled or unused plugins

  • Update Mason packages and plugins

    Run :AstroUpdate (<Leader>pa) to update both Neovim plugins and Mason packages

  • Check AstroNvim version

    Run :AstroVersion to display the currently installed AstroNvim version

  • 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.

✨ Features

🔧 Configuration

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.

🚀 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:

<FileTree>
  • ~/.config/nvim/
    • README.md
    • init.lua bootstrap the lazy plugin manager
    • lua/
      • community.lua import AstroCommunity plugin specs
      • lazy_setup.lua configure and setup lazy.nvim
      • plugins/ configure plugins
        • astrocore.lua
        • astrolsp.lua
        • astroui.lua
        • mason.lua
        • none-ls.lua
        • treesitter.lua
        • user.lua
        • ... add more files here as needed
      • polish.lua file executed last with arbitrary Lua
</FileTree>

:::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.

:::

At the top level is init.lua. This code bootstraps the configuration by installing lazy.nvim if it is not already installed and then calling lua/lazy_setup.lua to install and configure the AstroNvim and user plugins.

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).

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 and the Lazy.nvim Documentation 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 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 languages. 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 maintainers, not the AstroNvim maintainers.

:::

lua
return {
  -- Add the community repository of plugin specifications
  "AstroNvim/astrocommunity",
  -- example of importing a plugin
  -- available plugins can be found at https://github.com/AstroNvim/astrocommunity
  { import = "astrocommunity.colorscheme.catppuccin" },
  { import = "astrocommunity.pack.rust" },
  { import = "astrocommunity.pack.python" },
}