5.3 KiB

Raw Permalink Blame History

✔ 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

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:

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

5.3 KiB Raw Permalink Blame History