add migration guide
This commit is contained in:
parent
b34147e8dd
commit
638ff2812f
|
|
@ -0,0 +1,223 @@
|
|||
# ✔ **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 certain useful behaviours from my old config (see below).
|
||||
|
||||
---
|
||||
|
||||
## **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
|
||||
* add plugins I did not ask for
|
||||
* 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
|
||||
Loading…
Reference in New Issue