lua-nvim/README.md

Neovim Configuration

A modern, fast, and well-organized Neovim configuration built with Lua.

Requirements

• Neovim: 0.9+ (0.10+ recommended)
• Git: For plugin management
• Node.js: For LSP servers and tooling
• ripgrep (rg): For fast file searching
• Python 3: With pynvim package for Python support

Optional Dependencies

• Pandoc: For HTML to Markdown conversion
• Prettier: For code formatting
• Stylua: For Lua formatting

Installation

# Backup existing config (if any)
mv ~/.config/nvim ~/.config/nvim.bak

# Clone this configuration
git clone <your-repo-url> ~/.config/nvim

# Start Neovim (plugins will auto-install)
nvim

Structure

~/.config/nvim/
├── init.lua                 # Entry point
├── lua/cargdev/
│   ├── core/
│   │   ├── init.lua         # Core initialization
│   │   ├── options.lua      # Neovim options
│   │   ├── keymaps/         # Keymap modules
│   │   │   ├── init.lua     # Keymap loader
│   │   │   ├── general.lua  # General keymaps
│   │   │   ├── personal.lua # Personal workflow keymaps
│   │   │   ├── plugins.lua  # Plugin-specific keymaps
│   │   │   ├── window.lua   # Window management
│   │   │   ├── lsp.lua      # LSP keymaps
│   │   │   ├── copilot.lua  # Copilot keymaps
│   │   │   └── ...
│   │   └── function/        # Custom functions
│   ├── plugins/             # Plugin configurations
│   │   ├── lsp/             # LSP-related plugins
│   │   └── ...
│   └── lazy.lua             # Lazy.nvim setup
└── ftplugin/                # Filetype-specific settings

Key Features

• Colorscheme: cargdev-cyberpunk - Vibrant cyberpunk theme with neon colors and full TypeScript/LSP support
• Plugin Manager: lazy.nvim with auto-update notifications
• LSP: Full LSP support with Mason for easy server management
• Completion: nvim-cmp with multiple sources
• File Navigation: Snacks.nvim (modern) + Telescope (git features)
• File Explorer: nvim-tree
• Git Integration: LazyGit, Gitsigns
• AI Assistants: GitHub Copilot + Avante.nvim (local LLM support)
• Debugging: DAP with UI (Java, Node.js/NestJS, Python)
• Formatting: Conform.nvim with auto-format on save
• Diagnostics: Trouble.nvim for organized diagnostics view

Documentation

Document	Description
CHANGELOG.md	Version history and changes
keyboard_mappings.md	QMK keyboard configuration
NATIVE_AUTO_WRAPPER_GUIDE.md	Text wrapping configuration
TELESCOPE_TO_SNACKS_MIGRATION.md	Migration notes

Quick Reference - Essential Keymaps

Leader Key: <Space>

File Operations

Keymap	Description
<leader>w	Save file
<leader>q	Close file
<leader>xa	Save and close all
<leader>bd	Close buffer (safe)
<leader>bD	Force close buffer

Navigation

Keymap	Description
<leader>ff	Find files
<leader>fs	Live grep (search text)
<leader>fr	Recent files
<leader>fb	Find buffers
<leader>e	Toggle file explorer

Window Management

Keymap	Description
<leader>sv	Split vertical
<leader>sh	Split horizontal
<leader>se	Equal splits
<leader>sx	Close split
<C-h/j/k/l>	Resize splits

LSP

Keymap	Description
gd	Go to definition
gr	Show references
K	Hover documentation
<leader>ca	Code actions
<leader>rn	Rename symbol
<leader>f	Format buffer
<leader>mm	Format (conform)

Git

Keymap	Description
<leader>gg	LazyGit
<leader>gs	Git status
<leader>gb	Git blame

Diagnostics & Quickfix

Keymap	Description
<leader>xx	Toggle Trouble
<leader>xd	Document diagnostics
<leader>qn/qp	Next/prev quickfix
<leader>qo/qq	Open/close quickfix

Session

Keymap	Description
<leader>sS	Save session
<leader>sR	Restore session

Copilot

Keymap	Description
<Tab>	Accept suggestion
<leader>zc	Open Copilot Chat
<leader>ze	Explain code (visual)
<leader>zf	Fix code (visual)

Debugging (DAP)

Keymap	Description
<leader>dcr	Start/Continue Debugging
<leader>db	Toggle Breakpoint
<leader>dB	Conditional Breakpoint
<leader>do	Step Over
<leader>di	Step Into
<leader>dot	Step Out
<leader>du	Toggle DAP UI
<leader>dq	Stop Debugging
<leader>dr	Open REPL
<leader>dl	Run Last Debug
<leader>dcf	DAP Configurations
<leader>dcb	List Breakpoints
<leader>dco	DAP Commands

Java Debugging

Keymap	Description
<leader>jd	Debug Class (DAP)
<leader>jt	Test Class
<leader>jn	Test Nearest Method
<leader>jr	Run Java File
<leader>jm	Run Maven Project
<leader>jg	Run Gradle Project

Commands

Command	Description
:Lazy	Open plugin manager
:Mason	Open LSP server manager
:checkhealth	Run health checks
:CheckConfig	Run config validation
:FormatToggle	Toggle auto-format on save

Debugging Setup

This configuration includes full debugging support for multiple languages using DAP (Debug Adapter Protocol).

Supported Languages

Language	Debug Adapter	Configuration
Java	java-debug-adapter	Auto-configured via nvim-jdtls
Node.js/NestJS/TypeScript	js-debug-adapter (pwa-node)	Launch & Attach configurations
Python	debugpy	Django, FastAPI, Flask, and general Python

Debug Configurations

Node.js/NestJS/TypeScript

• Launch NestJS - Runs dist/main.js with source maps
• Launch Current File - Debug the current TypeScript/JavaScript file
• Launch with ts-node - Debug TypeScript directly without compilation
• Attach to NestJS - Attach to running process on port 9229
• Attach to Process - Pick from running Node.js processes

Python

• Launch File - Debug current Python file
• Launch with Arguments - Debug with custom arguments
• Attach Remote - Attach to debugpy server (port 5678)
• Django - Debug Django with manage.py runserver
• FastAPI - Debug FastAPI with uvicorn
• Flask - Debug Flask application

Java

• Auto-discovers main classes and test methods
• Hot code replacement enabled
• Use <leader>jd to debug the current class

Installation

Debug adapters are automatically installed via Mason. Run :Mason to verify:

• debugpy - Python debugger
• js-debug-adapter - Node.js/TypeScript debugger
• java-debug-adapter - Java debugger
• java-test - Java test runner

Troubleshooting

Check Configuration Health

:checkhealth
:CheckConfig

Common Issues

1. Plugins not loading: Run :Lazy sync
2. LSP not working: Run :Mason and install required servers
3. Formatting not working: Ensure formatters are installed (prettier, stylua, etc.)
4. Slow startup: Check :Lazy profile for slow plugins

License

MIT License - Feel free to use and modify as needed.