AstroCore provides the core Lua API that powers AstroNvim. It provides an interface for configuration auto commands, user commands, on_key functions, key mappings, and more as well as a Lua API of common utility functions.
- Unified interface for configuring auto commands, user commands, key maps, on key functions
- Easy toggles of UI/UX elements and features
- Universal interface for setting up git worktrees
- Tab local buffer management for a clean
tabline - Project root detection with automatic
cdfeatures - Session management with resession.nvim
- Neovim >= 0.9
- lazy.nvim
- resession.nvim (optional)
Install the plugin with the lazy plugin manager:
return {
"AstroNvim/astrocore",
lazy = false, -- disable lazy loading
priority = 10000, -- load AstroCore first
opts = {
-- set configuration options as described below
},
}💡 If you want to enable session management with resession.nvim, enable it in the setup:
require("resession").setup {
extensions = {
astrocore = {},
},
}AstroCore comes with no defaults, but can be configured fully through the opts table in lazy. Here are descriptions of the options and some example usages:
---@type AstroCoreConfig
local opts = {
-- easily configure auto commands
autocmds = {
-- first key is the `augroup` (:h augroup)
highlighturl = {
-- list of auto commands to set
{
-- events to trigger
event = { "VimEnter", "FileType", "BufEnter", "WinEnter" },
-- the rest of the autocmd options (:h nvim_create_autocmd)
desc = "URL Highlighting",
callback = function() require("astrocore").set_url_match() end,
},
},
},
-- easily configure user commands
commands = {
-- key is the command name
AstroReload = {
-- first element with no key is the command (string or function)
function() require("astrocore").reload() end,
-- the rest are options for creating user commands (:h nvim_create_user_command)
desc = "Reload AstroNvim (Experimental)",
},
},
-- Configure diagnostics options (`:h vim.diagnostic.config()`)
diagnostics = {
update_in_insert = false,
},
-- passed to `vim.filetype.add`
filetypes = {
-- see `:h vim.filetype.add` for usage
extension = {
foo = "fooscript",
},
filename = {
[".foorc"] = "fooscript",
},
pattern = {
[".*/etc/foo/.*"] = "fooscript",
},
},
-- Configuration of vim mappings to create
mappings = {
-- map mode (:h map-modes)
n = {
-- use vimscript strings for mappings
["<C-s>"] = { ":w!<cr>", desc = "Save File" },
-- navigate buffer tabs with `H` and `L`
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",
},
-- tables with just a `desc` key will be registered with which-key if it's installed
-- this is useful for naming menus
["<leader>b"] = { desc = "Buffers" },
},
},
-- easily configure functions on key press
on_keys = {
-- first key is the namespace
auto_hlsearch = {
-- list of functions to execute on key press (:h vim.on_key)
function(char) -- example automatically disables `hlsearch` when not actively searching
if vim.fn.mode() == "n" then
local new_hlsearch = vim.tbl_contains({ "<CR>", "n", "N", "*", "#", "?", "/" }, vim.fn.keytrans(char))
if vim.opt.hlsearch:get() ~= new_hlsearch then vim.opt.hlsearch = new_hlsearch end
end
end,
},
},
-- easily configure vim options
options = {
-- first key is the type of option `vim.<first_key>`
opt = {
relativenumber = true, -- sets `vim.opt.relativenumber`
signcolumn = "auto", -- sets `vim.opt.relativenumber`
},
g = {
-- set global `vim.g` settings here
},
},
-- configure AstroNvim features
features = {
autopairs = true, -- enable or disable autopairs on start
cmp = true, -- enable or disable cmp on start
diagnostics_mode = 3, -- diagnostic mode on start (0 = off, 1 = no signs/virtual text, 2 = no virtual text, 3 = off)
highlighturl = true, -- enable or disable highlighting of urls on start
-- table for defining the size of the max file for all features, above these limits we disable features like treesitter.
large_buf = { size = 1024 * 100, lines = 10000 },
notifications = true, -- enable or disable notifications on start
},
-- Enable git integration for detached worktrees
git_worktrees = {
{ toplevel = vim.env.HOME, gitdir = vim.env.HOME .. "/.dotfiles" },
},
-- Configure project root detection, check status with `:AstroRootInfo`
rooter = {
-- list of detectors in order of prevalence, elements can be:
-- "lsp" : lsp detection
-- string[] : a list of directory patterns to look for
-- fun(bufnr: integer): string|string[] : a function that takes a buffer number and outputs detected roots
detector = {
"lsp", -- highest priority is getting workspace from running language servers
{ ".git", "_darcs", ".hg", ".bzr", ".svn" }, -- next check for a version controlled parent directory
{ "lua", "MakeFile", "package.json" }, -- lastly check for known project root files
},
-- ignore things from root detection
ignore = {
servers = {}, -- list of language server names to ignore (Ex. { "efm" })
dirs = {}, -- list of directory patterns (Ex. { "~/.cargo/*" })
},
-- automatically update working directory (update manually with `:AstroRoot`)
autochdir = false,
-- scope of working directory to change ("global"|"tab"|"win")
scope = "global",
-- show notification on every working directory change
notify = false,
},
-- 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
},
},
}AstroCore provides a Lua API with utility functions. This can be viewed with :h astrocore or in the repository at doc/api.md
If you plan to contribute, please check the contribution guidelines first.