kickstart-nvim/AGENTS.md

AGENTS.md - Neovim Configuration Guide

Overview

This is a kickstart.nvim fork - a modular Neovim configuration written in Lua. Code is organized in:

• /init.lua - Main entry point (kept concise for learning)
• /lua/custom/ - User custom configurations and plugins
• /lua/kickstart/ - Core plugin configurations

Code Style Guidelines

Lua Formatting

• Formatter: Stylua (enforced via CI)
• Config: .stylua.toml (column_width=160, indent=2 spaces, auto quote style)
• Command: stylua . to format all files, stylua --check . to verify

Code Conventions

• Imports: Use require() to load modules; prefer relative paths from /lua/
• Comments: Use -- for single-line, --[[ for block comments; include URLs for plugins
• Naming: snake_case for variables/functions, PascalCase for classes
• Lua tables: Preferred data structure; use clear key names
• Error handling: Use pcall() for risky operations; fail gracefully with fallbacks

Plugin Structure

• Each plugin is a separate file returning a table with name, dependencies, config
• Use event, cmd, ft keys for lazy-loading optimization
• Config functions should be self-contained and well-commented

Build/Lint/Test Commands

Format & Lint

# Format all Lua files
stylua .

# Check formatting without changing files
stylua --check .

# Format specific file
stylua path/to/file.lua

No traditional tests

This is a configuration repo, not a testable library. Validation is manual:

• Start Neovim: nvim
• Check :Lazy status for plugin errors
• Review :checkhealth for configuration issues
• Test manually in editor to verify keymaps/features work

Linting

• Neovim's built-in Lua LSP provides type checking (integrated via plugin)
• The GitHub Actions workflow runs stylua --check on PRs

Key Notes

• Language: Lua 5.1+ (Neovim's version)
• No external build process: Configuration is interpreted at runtime
• Plugin manager: Lazy.nvim (auto-installs missing plugins on startup)
• Target: Latest Neovim stable + nightly versions