224 lines
5.3 KiB
Markdown
224 lines
5.3 KiB
Markdown
# ✔ **Neovim Migration Guide for AI Assistance**
|
|
|
|
## **Purpose**
|
|
|
|
I am transitioning from VS Code back to Neovim.
|
|
This document describes my goals, constraints, preferences, and what I expect from an AI assistant during this rebuild.
|
|
|
|
---
|
|
|
|
## **High-Level Goals**
|
|
|
|
* Create a clean, modern Neovim setup using Lua.
|
|
* Avoid bringing over legacy Vimscript or old config patterns.
|
|
* Keep the configuration minimal but powerful.
|
|
* Base plugins on **lazy.nvim**.
|
|
* Support my workflow: **multiple tabs, each with its own Neo-tree instance**, for working with WordPress plugin development and referencing external codebases (WooCommerce, WordPress core, etc).
|
|
* Use LSP, Treesitter, telescope, and modern UX plugins.
|
|
* Integrate GitHub Copilot into completion.
|
|
* Preserve colour scheme used but modernise it if needed.
|
|
|
|
---
|
|
|
|
## **Do NOT Include / Do NOT Recreate**
|
|
|
|
These are outdated patterns and I *do not* want them reintroduced:
|
|
|
|
* custom tabline or statusline implemented in Vimscript
|
|
* custom foldtext functions
|
|
* autocommands that toggle cursorline/cursorcolumn per window
|
|
* manual Redir/shell command buffer logic
|
|
* CoC or any CoC-specific configuration
|
|
* netrw settings (I will be using Neo-tree)
|
|
* ruby, perl, node providers (disable them unless a plugin needs them)
|
|
* template that reloads vimrc on write
|
|
* cursorcolumn
|
|
* old folding logic unrelated to UFO
|
|
* Vimscript-based UI hacks of any kind
|
|
|
|
If needed, suggest modern replacements instead.
|
|
|
|
---
|
|
|
|
## **Required Plugins (Modern Equivalents Only)**
|
|
|
|
I want help managing these categories using lazy.nvim:
|
|
|
|
### **Core**
|
|
|
|
* nvim-lspconfig
|
|
* nvim-cmp
|
|
* cmp-nvim-lsp
|
|
* cmp-buffer
|
|
* cmp-path
|
|
* LuaSnip
|
|
|
|
### **Navigation**
|
|
|
|
* neo-tree.nvim
|
|
* telescope.nvim
|
|
* telescope-fzf-native.nvim (optional)
|
|
|
|
### **Treesitter**
|
|
|
|
* nvim-treesitter
|
|
* nvim-treesitter-textobjects
|
|
* nvim-ts-autotag
|
|
|
|
### **UX / Editing**
|
|
|
|
* Comment.nvim
|
|
* surround.nvim
|
|
* nvim-autopairs
|
|
* indent-blankline.nvim
|
|
* leap.nvim or flash.nvim
|
|
* nvim-ufo (folding)
|
|
* undotree (optional)
|
|
|
|
### **Git**
|
|
|
|
* gitsigns.nvim
|
|
|
|
### **Markdown**
|
|
|
|
* render-markdown.nvim
|
|
|
|
### **Copilot**
|
|
|
|
* copilot.lua
|
|
* copilot-cmp
|
|
|
|
### **Formatting**
|
|
|
|
* none-ls.nvim
|
|
|
|
---
|
|
|
|
## **Behaviours From My Old Config That I Want to KEEP**
|
|
|
|
When helping me implement these, please use modern Lua (`vim.api.nvim_*`, `vim.keymap.set`, etc), **not Vimscript**.
|
|
|
|
### ✔ Keybindings to preserve
|
|
|
|
### ✔ Templates for new files
|
|
|
|
* Auto-populate `.sh` from templates
|
|
|
|
### ✔ Abbreviations
|
|
|
|
* adn → and
|
|
* waht → what
|
|
* tehn → then
|
|
* functin → function
|
|
* positin → position
|
|
|
|
### ✔ Whitespace highlighting (modern alternatives acceptable)
|
|
|
|
### ✔ Persistent folds (if not using UFO)
|
|
|
|
### ✔ Spell & text settings
|
|
|
|
* `spelllang=en_gb`
|
|
* custom listchars and showbreak
|
|
|
|
---
|
|
|
|
## **Agent Behaviour Expectations**
|
|
|
|
### ✔ The AI should:
|
|
|
|
* provide modern Neovim/Lua solutions
|
|
* avoid legacy Vimscript unless explicitly requested
|
|
* help translate old behaviours into clean Lua equivalents
|
|
* help structure the new config modularly
|
|
* help migrate step-by-step
|
|
* explain trade-offs briefly if necessary
|
|
* prioritise simplicity and maintainability
|
|
* ensure plugin configs are minimal and only include what is required
|
|
|
|
### ✘ The AI should **NOT**:
|
|
|
|
* reintroduce old Vimscript workarounds
|
|
* over-engineer or over-automate
|
|
* install any plugin not listed without explicit confirmation
|
|
* suggest plugin-heavy “mega-setups”
|
|
* attempt to recreate VS Code behaviour unless requested
|
|
* produce large complex boilerplate unless requested
|
|
|
|
---
|
|
|
|
## **Config Structure I Want**
|
|
|
|
I strongly prefer very modular config files.
|
|
Plugin specific settings should be kept in the plugin config files where possible.
|
|
|
|
```
|
|
~/.config/nvim/
|
|
│
|
|
├── init.lua → loads everything
|
|
│
|
|
├── lua/
|
|
│ ├── settings.lua → non-plugin options only
|
|
│ ├── keymaps.lua → non-plugin keymaps
|
|
│ ├── autocmds.lua → non-plugin autocommands
|
|
│ ├── utils.lua → helper fns if needed
|
|
│ │
|
|
│ ├── plugins/
|
|
│ │ ├── init.lua → optional, can load automatically
|
|
│ │ ├── neo-tree.lua
|
|
│ │ ├── telescope.lua
|
|
│ │ ├── treesitter.lua
|
|
│ │ ├── cmp.lua
|
|
│ │ ├── lsp.lua
|
|
│ │ ├── copilot.lua
|
|
│ │ ├── ufo.lua
|
|
│ │ ├── gitsigns.lua
|
|
│ │ ├── markdown.lua
|
|
│ │ └── …
|
|
```
|
|
|
|
Each plugin file returns one table:
|
|
|
|
```lua
|
|
return {
|
|
"nvim-telescope/telescope.nvim",
|
|
keys = { ... },
|
|
opts = { ... },
|
|
config = function(_, opts)
|
|
require("telescope").setup(opts)
|
|
end
|
|
}
|
|
```
|
|
|
|
The AI can help refine this structure but should keep it simple.
|
|
|
|
---
|
|
|
|
## **My Workflow Requirements**
|
|
|
|
* Tab-per-context workflow
|
|
* Each tab has its own Neo-tree root
|
|
- one keymap for floating Neo-tree
|
|
- one keymap neo-tree sidebar toggle
|
|
- i would like previews of files activated via keymap (not auto preview)
|
|
- i would like previewed files to not clutter the buffer list.
|
|
* Splits stay inside tabs
|
|
* Telescope + LSP jump for navigation
|
|
* Heavy HTML/PHP/JS/Markdown usage (WordPress plugin dev)
|
|
* Copilot for completion
|
|
* No LSP-overconfiguration
|
|
|
|
---
|
|
|
|
## **End Goal**
|
|
|
|
A clean Neovim setup with:
|
|
|
|
* fast startup
|
|
* minimal but powerful plugins
|
|
* strong WordPress/PHP workflow
|
|
* organised code navigation
|
|
* modern folding & UI
|
|
* no legacy cruft
|
|
* easy maintenance
|