dotfiles/term/.config/nvim/README.md

Neovim IDE Configuration

A feature-rich Neovim setup optimized for Python, JSON, and CSV development.

Features

LSP (Language Server Protocol)

• Python (pyright) - Autocomplete, type checking, goto definition, hover docs, rename
• JSON (jsonls) - Validation, formatting, schema support
• YAML (yamlls) - YAML file support
• HTML/CSS (html, cssls) - Web development
• Bash (bashls) - Shell script support
• Lua (lua_ls) - Neovim config development

Completion

• nvim-cmp - Smart autocomplete with LSP integration
• LuaSnip - Snippet support

Syntax Highlighting & Parsing

• Treesitter - Advanced syntax highlighting for Python, JSON, CSV, YAML, Markdown, and more
• CSV Support - Syntax highlighting for CSV files

File Management

• Neo-tree - File explorer with git integration
• Telescope - Fuzzy finder for files, text, and more

Git Integration

• Gitsigns - Git status in the gutter (added, modified, deleted lines)

Debugging

• nvim-dap - Debug Python code with breakpoints, step-through debugging
• dap-ui - Visual debugging interface

UI Enhancements

• Catppuccin - Beautiful dark color scheme (Mocha flavor)
• Lualine - Custom statusline showing mode, git branch, file, diagnostics

Formatting

• conform.nvim - Auto-format on save (ruff for Python, jq for JSON, etc.)

Utilities

• nvim-comment - Easy commenting (toggle comments with gcc)

---

Installation

1. Install Neovim (version 0.10+ recommended)

2. Link this config:

   ln -s ~/.dotfiles/nvim ~/.config/nvim
   

3. Open Neovim - plugins will install automatically

4. Install debugpy for Python debugging:

   pip install debugpy
   

5. Install formatters (optional):

   pip install ruff black
   

---

Keymaps

General

Keymap	Action
<leader>w	Save file
<leader>q	Quit Neovim
<Esc>	Exit insert mode
u	Undo
<C-r>	Redo
dd	Delete line
yy	Yank (copy) line
p	Paste

Navigation

Keymap	Action
h/j/k/l	Move left/down/up/right
w/b	Jump forward/back by word
0/$	Jump to start/end of line
gg	Jump to beginning of file
G	Jump to end of file
<C-d>/<C-u>	Jump down/up half page
<C-f>/<C-b>	Jump forward/back page

File Explorer (Neo-tree)

Keymap	Action
<C-n>	Toggle file explorer
Enter	Open file/folder
h	Close folder
l	Open folder
a	Add file
d	Delete file
r	Rename file
y/x	Copy/Cut file
p	Paste

Fuzzy Finder (Telescope)

Keymap	Action
<C-p>	Find files
<leader>fg	Grep (search text in files)

LSP (Language Server)

Keymap	Action
gd	Go to definition
gD	Go to declaration
gi	Go to implementation
gr	Show references
K	Show hover documentation
<leader>rn	Rename symbol
<leader>ca	Code actions / quick fixes
<leader>e	Show diagnostic error
[d / ]d	Previous/next diagnostic

Formatting

Keymap	Action
<leader>f	Format file

Git (Gitsigns)

Keymap	Action
]c / [c	Next/previous hunk (change)
<leader>hs	Stage current hunk
<leader>hr	Reset current hunk
<leader>hp	Preview hunk changes
<leader>hb	Blame line

Debugging (DAP)

Keymap	Action
<F5>	Continue / Start debugger
<F9>	Toggle breakpoint
<F10>	Step over
<F11>	Step into
<S-F11>	Step out
<leader>du	Toggle debugger UI

Commenting

Keymap	Action
gcc	Toggle line comment
gc (visual)	Toggle selection comment

Folding

Keymap	Action
zc	Close (fold) current block
zo	Open (unfold) current block
za	Toggle fold at cursor
zM	Close all folds
zR	Open all folds
zC	Close folds recursively
zO	Open folds recursively
zE	Eliminate all folds
zv	Open folds enough to see cursor

---

File Type Specifics

Python (.py)

• LSP: Full autocompletion, type checking, goto definition
• Formatting: ruff format (fast), black (backup)
• Debugging: Set breakpoints with F9, run with F5
• Indentation: 4 spaces (Python convention)

JSON (.json)

• LSP: Validation, schema support
• Formatting: jq
• Indentation: 2 spaces
• Folding: JSON objects/arrays are foldable (za to toggle, zM to close all)

CSV (.csv)

• Treesitter: Syntax highlighting
• No wrap: Full row visibility
• Navigation: Standard motions (j/k, /, etc.)
• Tip: Use set nowrap for viewing wide CSV files without line wrapping

YAML (.yaml/.yml)

• LSP: Validation, schema support
• Folding: Nested structures are foldable

Python (.py)

• Folding: Functions, classes, and code blocks are foldable
• Tip: Use za to toggle a fold at cursor, zM to close all folds

---

Troubleshooting

LSP not working

1. Ensure the language server is installed
2. Run :LspInfo to check status
3. Try :LspRestart

Debugging not working

1. Install debugpy: pip install debugpy
2. Place breakpoint with F9
3. Start with F5

Colors wrong

The config uses Catppuccin Mocha theme. If you see color issues, run:

:colorscheme catppuccin

---

Adding New Plugins

Plugins are defined in lua/plugins/. Each .lua file is a plugin spec that returns a table.

Example (lua/plugins/myplugin.lua):

return {
    "username/repo-name",
    config = function()
        require("myplugin").setup()
    end,
}

---

Credits

• lazy.nvim - Plugin manager
• nvim-lspconfig - LSP configuration
• nvim-cmp - Completion
• Telescope - Fuzzy finder
• Neo-tree - File explorer
• Catppuccin - Colorscheme
• Gitsigns - Git integration
• nvim-dap - Debugging