Skip to main content
This page walks you through the development environment, project structure, and how to make common types of changes.

​
Development environment

Aquavium.nvim is developed in the following environment (as of 2026/03/11):
ToolVersion
Windows11 (Build 26200)
Microsoft Visual Studio Community2026
Neovim0.11.6
WezTermNightly
If you use the maintainer’s dotfiles, clone the repository to ~\source\repos\Aquavium.nvim so the paths resolve correctly.

​
Project structure

Aquavium.nvim/
├── colors/
│   └── Aquavium.lua              # Entry point — calls require("Aquavium").setup()
└── lua/
    ├── Aquavium/
    │   ├── init.lua              # Main module — defines M.setup()
    │   ├── colors.lua            # Color palette definitions
    │   ├── highlights.lua        # Neovim highlight group assignments
    │   ├── utils.lua             # Utility functions (apply_hl)
    │   └── integrations/
    │       ├── init.lua          # Loads and runs all integration modules
    │       ├── bufferline.lua
    │       ├── dashboard.lua
    │       ├── lazy-nvim.lua
    │       ├── markview.lua
    │       ├── nvim-notify.lua
    │       ├── telescope-nvim.lua
    │       └── treesitter_context.lua
    └── lualine/
        └── themes/
            └── Aquavium.lua      # Lualine theme definition

​
Key files

This is the file Neovim loads when you run colorscheme Aquavium. It simply calls require("Aquavium").setup() to delegate all work to the main module.
Defines M.setup(user_options), which merges user options with defaults, clears existing highlights, loads the color palette, applies highlight groups, and triggers integrations. The default options are:
local default_options = {
    bold = true,
    italic = true,
    transparent = true
}
Defines the full color palette as a Lua table. When transparent = true is set, bg1 is replaced with "NONE" so the terminal background shows through.
local palette = {
    bg1 =       "#000e1e",
    fg =        "#cdd5e5",
    red =       "#cc0047",
    green =     "#73bf5e",
    blue =      "#004584",
    lightblue = "#4fbee3",
    cyan =      "#63deff",
    sky =       "#699ee0",
    orange =    "#fdba8a",
    yellow =    "#e8dfad",
    purple =    "#938af8",
    pink =      "#eeb6c7",
    rose =      "#da9197",
    gray =      "#7b92ae",
}
Defines all core Neovim highlight groups using the color palette. Calls utils.apply_hl(hl) to apply them. This is where you add or modify highlight groups for built-in Neovim syntax.
Exports apply_hl(groups), a helper that iterates over a table of highlight group definitions and calls vim.api.nvim_set_hl for each one.
Each file handles highlight groups for a specific plugin. integrations/init.lua iterates over the registered module names and calls mod.apply(colors, opts) on each one automatically.

​
Testing changes locally

1

Clone the repository

Clone Aquavium.nvim into your Neovim configuration’s plugin directory, or point your plugin manager at your local clone.
git clone https://github.com/T-b-t-nchos/Aquavium.nvim
2

Load via lazy.nvim in development mode

In your lazy.nvim plugin spec, use the dir key to point at your local clone instead of fetching from GitHub:
{
    dir = "~/path/to/Aquavium.nvim",
    lazy = false,
    priority = 1000,
    config = function()
        require("Aquavium").setup({})
        vim.cmd("colorscheme Aquavium")
    end,
}
3

Reload Neovim to apply changes

After editing any Lua file, restart Neovim (or run :luafile % on the changed file) to pick up your changes. Verify the highlight groups look correct in your terminal.

​
Adding or modifying highlight groups

To change how a built-in syntax element looks, edit lua/Aquavium/highlights.lua. Add your group to the hl table inside M.apply: 
function M.apply(c, opts)
    local hl = {
        -- existing groups ...
        YourNewGroup = { fg = c.cyan, bold = opts.bold },
    }

    utils.apply_hl(hl)
end
Use the color names from colors.lua (for example, c.cyan, c.purple, c.rose) to keep the palette consistent.

​
Adding a new integration

1

Create a new file in lua/Aquavium/integrations/

Name the file after the plugin, for example my-plugin.lua.
2

Implement the M.apply function

Your file must export a M.apply(colors, opts) function. Use utils.apply_hl to apply the highlight table:
local utils = require("Aquavium.utils")
local M = {}

function M.apply(c, opts)
    local hl = {
        -- Map plugin highlight groups to palette colors.
        -- Example from nvim-notify:
        NotifyERRORBody   = { fg = c.rose },
        NotifyERRORBorder = { link = "NotifyERRORBody" },
        NotifyERRORTitle  = { link = "NotifyERRORBody" },
        NotifyERRORIcon   = { link = "NotifyERRORBody" },

        NotifyINFOBody    = { fg = c.lightblue },
        NotifyINFOBorder  = { link = "NotifyINFOBody" },
        NotifyINFOTitle   = { link = "NotifyINFOBody" },
        NotifyINFOIcon    = { link = "NotifyINFOBody" },
    }

    utils.apply_hl(hl)
end

return M
3

Register the module in integrations/init.lua

Add the filename (without .lua) to the modules table in lua/Aquavium/integrations/init.lua:
local modules = {
    "bufferline",
    "dashboard",
    "lazy-nvim",
    "markview",
    "nvim-notify",
    "telescope-nvim",
    "treesitter_context",
    "my-plugin",   -- add your new integration here
}
integrations/init.lua automatically calls mod.apply(colors, opts) on every module in this list.

Build docs developers (and LLMs) love

Get started for freeTalk to us