Configuration Structure¶

This document explains the organization of the configuration files.

Directory Layout¶

~/dotfiles/nvim/
├── init.lua                      # Main entry point
├── lua/                          # Lua configuration
│   ├── autocmds.lua             # Autocommands and event handlers
│   ├── settings.lua             # Basic editor settings (tabs, indentation, etc.)
│   ├── statusline.lua           # Custom status line
│   ├── lsp/                     # Language Server Protocol
│   │   ├── init.lua             # LSP initialization
│   │   └── lsp.lua              # Zuban LSP configuration
│   ├── plugin/                  # Plugin configurations
│   │   ├── ayu.lua              # Ayu colorscheme
│   │   ├── fzf-lua.lua          # FZF fuzzy finder
│   │   ├── gitsigns.lua         # Git decorations
│   │   ├── indent_blankline.lua # Indentation guides
│   │   ├── leap.lua             # Fast movement
│   │   ├── treesitter.lua       # Treesitter highlighting
│   │   └── which-key.lua        # Keybinding menu
│   ├── disable_plugins.lua      # Disables default plugins
│   └── utils/                   # Utility functions
│       ├── core.lua             # Core utilities
│       ├── python.lua           # Python-specific utilities
│       └── treesitter.lua       # Treesitter helpers
├── install.py                    # Automated setup script
├── pyproject.toml               # Python dependencies
├── README.md                    # Main documentation
└── docs/                        # Sphinx documentation (this folder)

init.lua - Main Entry Point¶

The init.lua file is the main configuration file. It:

Loads basic settings
Initializes the LSP
Configures plugins
Sets up keybindings

Never edit init.lua directly - instead, modify the specific files it requires.

lua/settings.lua - Editor Settings¶

Basic Neovim settings:

Tab width and indentation
Line numbering
Search settings
Split behavior
Clipboard configuration

To modify: Edit lua/settings.lua and reload Neovim.

lua/statusline.lua - Custom Status Line¶

A custom status line showing:

Current file name
Cursor position
Git branch (if in repo)
LSP status
Diagnostic count

The status line is lightweight and fast - no plugin needed.

To customize: Edit this file and reload Neovim. The file is well-commented.

lua/autocmds.lua - Autocommands¶

Automatically triggered actions:

Format on save
Update diagnostics
Auto-save certain file types
Custom event handlers

To add new autocommand: Add to this file following the existing patterns.

lua/lsp/ - Language Server Configuration¶

init.lua: Initializes LSP capabilities.

lsp.lua: Configures Zuban for Python:

Server settings
Diagnostic configuration
Completion setup
Hover behavior

To add another language server: Edit lsp.lua and add configuration for that language.

Example:

-- In lua/lsp/lsp.lua
lsp.go:setup({})  -- Add Go language server

lua/plugin/ - Plugin Configurations¶

Each plugin has its own file:

ayu.lua - Colorscheme

Sets the color scheme
Customizes highlight groups
Adjusts colors for readability

fzf-lua.lua - Fuzzy Finder

Configures FZF behavior
Sets search paths
Customizes preview window
Maps FZF commands

gitsigns.lua - Git Integration

Shows git changes in line numbers
Marks added/modified/deleted lines
Provides git hunks navigation

indent_blankline.lua - Indentation Guides

Shows vertical lines for indentation levels
Helps visualize code structure

leap.lua - Fast Movement

Quick motion to any location
Type target characters to jump

treesitter.lua - Syntax Highlighting

Configures Treesitter parsers
Sets highlighting rules
Manages parser installation

which-key.lua - Keybinding Menu

Organizes all keybindings
Shows menu on <leader> press
Most important file for customization

lua/utils/ - Utility Functions¶

Reusable code shared across the config.

core.lua - Core Utilities

Helper functions
Common patterns
Utility functions used by other modules

python.lua - Python Utilities

Python-specific helpers
Test running
Code formatting utilities

treesitter.lua - Treesitter Helpers

Parser detection
Language-specific utilities

lua/disable_plugins.lua - Disable Built-ins¶

Disables Neovim’s built-in plugins:

netrw - File browser (we use FZF instead)
Other defaults we don’t use

This keeps Neovim lean and fast.

install.py - Setup Script¶

Automated installation:

Downloads Neovim
Sets up Python environment
Installs dependencies
Creates symlinks
Installs plugins

Run once: python3 install.py

pyproject.toml - Python Dependencies¶

Python packages required in the virtual environment:

pynvim - Python bindings for Neovim
zuban - Python Language Server
ruff - Linter
darker - Code formatter

See Python Dependencies for details.

How Files Work Together¶

Startup sequence:

Neovim launches
Loads init.lua
init.lua requires all other configuration files
Settings, LSP, plugins, keybindings all activate
You can start editing

When you edit a file:

Autocommands trigger
LSP analyzes code
Treesitter highlights syntax
Status line updates
Diagnostics appear

When you press a keybinding:

Which-key menu shows (if you press <leader>)
Plugin command executes
LSP action happens (if LSP-related)
Result appears in editor

Understanding Dependencies¶

Some files depend on others:

All files depend on settings.lua (basic setup)
LSP files depend on each other
Plugin files are somewhat independent
Utilities are used by multiple files

If you remove a file: Other files may break. For example:

Removing utils/core.lua breaks any plugin using it
Removing lsp/lsp.lua disables all language features
Removing plugin/which-key.lua disables keybindings

Adding New Plugins¶

To add a new plugin:

Create lua/plugin/my_plugin.lua
Require it in init.lua
Configure the plugin in the new file
Add keybindings to which-key.lua

Example:

-- In lua/plugin/my_plugin.lua
require('my_plugin').setup({
    -- configuration
})

-- In init.lua, add:
require('lua/plugin/my_plugin')

Adding New Settings¶

Edit lua/settings.lua to add:

Indentation rules
Line width
Search options
Behavior settings

Example:

vim.opt.textwidth = 88  -- Line width for formatting

Modifying Keybindings¶

Edit lua/plugin/which-key.lua:

wk.add({
  { "<leader>x", "<cmd>MyCommand<cr>", desc = "My command" }
})

See Customization for detailed examples.

File Naming Conventions¶

lua/*.lua - Top-level configuration
lua/lsp/*.lua - LSP-related
lua/plugin/*.lua - Plugin configuration
lua/utils/*.lua - Utility functions

Following these conventions keeps the project organized.

Performance Considerations¶

The configuration is optimized for:

Fast startup - Minimal lazy loading, quick initialization
Responsive editing - LSP operations don’t block
Efficient plugins - Carefully selected, minimal overhead

To keep performance good:

Avoid heavy plugins
Don’t load plugins unless needed
Use FZF instead of plugin file browsers
Disable unused language servers

Extending the Configuration¶

Best practices:

Create new files in appropriate directories
Follow existing code patterns
Document your changes
Test with :checkhealth
Keep files focused (one plugin per file)

Common extensions:

Add language server in lua/lsp/lsp.lua
Add plugin config in lua/plugin/
Add utilities in lua/utils/
Add keybindings in lua/plugin/which-key.lua

See Customization for detailed examples.

Backup and Version Control¶

Using git:

cd ~/dotfiles/nvim
git add .
git commit -m "My customizations"

Before major changes:

git branch backup-$(date +%Y%m%d)

Debugging Configuration¶

If something doesn’t work:

Check for errors: :checkhealth
Look in error log: :messages
Check file for syntax errors
Verify dependencies are installed

Most issues come from:

Missing plugins
Wrong Python environment
Syntax errors in Lua
Missing dependencies

See Troubleshooting for detailed solutions.