136 lines
5.3 KiB
Markdown
136 lines
5.3 KiB
Markdown
# 🌌 Whipsmart.nvim
|
|
|
|
Whipsmart.nvim is a modular, native-first Neovim configuration built on top of the Neovim 0.12+ `vim.pack` system. It evolved from [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim) into a modular, machine-aware "Grand Unified" configuration.
|
|
|
|
## ✨ Features
|
|
|
|
- **Modular Architecture**: Plugin configurations are isolated in `lua/plugins/*.lua`.
|
|
- **Native-First**: Leverages Neovim 0.12's built-in `vim.pack` for plugin management and native LSP/Autocomplete improvements.
|
|
- **Ergonomic Dashboard**: Includes `pack-manager.nvim` to provide a polished, Lazy-like UI on top of native primitives.
|
|
- **Machine Awareness**: Built-in hostname detection in `init.lua` for machine-specific overrides.
|
|
- **Version Pinning**: Uses `nvim-pack-lock.json` for reproducible environments across all your hardware.
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### 1. Prerequisites
|
|
|
|
Ensure you are running **Neovim 0.12+** (nightly or latest stable). You will also need:
|
|
- `git`, `make`, `unzip`, `gcc`
|
|
- [ripgrep](https://github.com/BurntSushi/ripgrep) and [fd](https://github.com/sharkdp/fd)
|
|
- A [Nerd Font](https://www.nerdfonts.com/) (recommended)
|
|
|
|
### 2. Installation
|
|
|
|
```sh
|
|
# Clone your fork (replace <your_username> with your GitHub handle)
|
|
git clone https://github.com/<your_username>/whipsmart.nvim.git ~/.config/nvim
|
|
|
|
# Start Neovim — plugins install automatically on first launch
|
|
nvim
|
|
```
|
|
|
|
On first launch, Mason will install the default LSP servers and formatters. Once complete, verify your environment:
|
|
|
|
```vim
|
|
:checkhealth whipsmart
|
|
```
|
|
|
|
## 🛠️ Package Management
|
|
|
|
Whipsmart provides two ways to manage your plugins:
|
|
|
|
### The "Lazy" Way (High-Level UI)
|
|
Press **`<leader>pm`** to open the **Package Manager Menu**. This dashboard allows you to:
|
|
- Check for updates
|
|
- Install new plugins
|
|
- Disable/Enable existing plugins
|
|
- Clean up unused packages
|
|
|
|
### The "Native" Way (Low-Level Access)
|
|
Whipsmart also exposes the raw `vim.pack` primitives:
|
|
- **`<leader>ps`**: **Sync** (Triggers `vim.pack.update()` to fetch new metadata).
|
|
- **`<leader>pi`**: **Inspect** (View current plugin status offline).
|
|
- **`:w`**: Inside the update buffer, write to disk to apply changes.
|
|
|
|
## 🏗️ Project Layout
|
|
|
|
```text
|
|
~/.config/nvim/
|
|
├── init.lua # Core options, keymaps, and plugin loader
|
|
├── UNIFIED.md # The Grand Unified roadmap and local instructions
|
|
├── nvim-pack-lock.json # Plugin lockfile (Tracked in Git)
|
|
└── lua/
|
|
├── plugins/ # Core plugin modules (explicit load order in init.lua)
|
|
│ ├── pack_manager.lua # pack-manager.nvim UI setup
|
|
│ ├── core_ui.lua # Which-key, Colorscheme, Oil, Mini.nvim
|
|
│ ├── telescope.lua # Fuzzy Finding
|
|
│ ├── lsp.lua # LSP, Mason, and Tooling
|
|
│ ├── cmp.lua # Autocompletion and Snippets
|
|
│ ├── treesitter.lua # Syntax Highlighting
|
|
│ └── format.lua # Conform.nvim Formatting
|
|
├── whipsmart/ # Opt-in extras (not loaded by default)
|
|
│ ├── health.lua # :checkhealth whipsmart
|
|
│ └── plugins/ # autopairs, debug, gitsigns+, indent, lint, neo-tree
|
|
└── custom/
|
|
└── plugins/ # Your personal plugins — no merge conflicts here
|
|
```
|
|
|
|
## 💻 Customization
|
|
|
|
### Adding a Personal Plugin
|
|
Drop a `.lua` file in `lua/custom/plugins/` — it is loaded automatically on startup and will never conflict with upstream changes.
|
|
|
|
Example `lua/custom/plugins/harpoon.lua`:
|
|
```lua
|
|
vim.pack.add { 'https://github.com/ThePrimeagen/harpoon' }
|
|
require('harpoon').setup {}
|
|
```
|
|
|
|
### Adding a Core Plugin
|
|
To add a plugin to the core `lua/plugins/` layer, create the file and then register it in the explicit loader list in `init.lua` (Section 2):
|
|
|
|
```lua
|
|
for _, mod in ipairs {
|
|
...
|
|
'plugins.my_new_plugin', -- add here
|
|
} do
|
|
```
|
|
|
|
### Adding LSP Servers
|
|
LSP configuration lives in `lua/plugins/lsp.lua` and has two separate lists that must both be updated:
|
|
|
|
1. **`servers`** — uses **lspconfig names** (passed to `vim.lsp.config` / `vim.lsp.enable`):
|
|
```lua
|
|
local servers = {
|
|
lua_ls = { ... }, -- lspconfig name
|
|
pyright = {}, -- lspconfig name
|
|
}
|
|
```
|
|
|
|
2. **`mason_tools`** — uses **Mason registry names** (passed to `mason-tool-installer`):
|
|
```lua
|
|
local mason_tools = {
|
|
'lua-language-server', -- Mason name for lua_ls
|
|
'pyright', -- Mason name (happens to match here)
|
|
'stylua', -- formatter, Mason name
|
|
}
|
|
```
|
|
|
|
> **Note:** lspconfig names and Mason names often differ. Look up the correct Mason name at [mason-registry](https://mason-registry.dev/registry/list) and the lspconfig name in the [lspconfig server list](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md).
|
|
|
|
### Enabling Format-on-Save
|
|
In `lua/plugins/format.lua`, add filetypes to `fmt_on_save_fts`:
|
|
|
|
```lua
|
|
local fmt_on_save_fts = {
|
|
lua = true,
|
|
go = true,
|
|
}
|
|
```
|
|
|
|
### Machine-Specific Settings
|
|
Whipsmart uses hostname detection. Open `init.lua` and locate the **Machine Specific Setup** section to add overrides for your specific hardware.
|
|
|
|
## 📜 Credits
|
|
Whipsmart started as a fork of [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim) and maintains its spirit of being a starting point rather than a distribution.
|