Skip to content

Seandagan/astrocore

 
 

Repository files navigation

🧰 AstroCore

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.

✨ Features

  • 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 cd features
  • Session management with resession.nvim

⚡️ Requirements

📦 Installation

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 = {},
  },
}

⚙️ Configuration

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("astrocore.buffer").nav(vim.v.count1) end,
        desc = "Next buffer",
      },
      H = {
        function() require("astrocore.buffer").nav(-vim.v.count1) 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
    },
  },
}

📦 API

AstroCore provides a Lua API with utility functions. This can be viewed with :h astrocore or in the repository at doc/api.md

🚀 Contributing

If you plan to contribute, please check the contribution guidelines first.

About

Core AstroNvim configuration engine

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Lua 100.0%