nvim/PLUGIN_STRUCTURE.md

AstroNvim Plugin Structure

This document describes the complete plugin structure for your AstroNvim configuration.

📁 Directory Structure

lua/plugins/
├── README.md                      # Documentation and guide
├── astrocore.lua                  # Core settings, keymaps, autocmds (23KB)
├── astrolsp.lua                   # LSP, formatting, linting (23KB)
├── astroui.lua                    # UI configuration (8.3KB)
├── buildtools.lua                 # Build tools & dev environment (6.5KB)
├── bufferline.lua                 # Buffer/tab management (2.1KB)
├── claude.lua                     # Claude Code integration (1.3KB)
├── neotree.lua                    # File explorer (15KB)
├── _template-custom.lua           # Template for custom plugins (disabled)
├── _template-filetype.lua         # Template for filetype plugins (disabled)
├── _template-mason.lua            # Template for Mason tools (disabled)
├── _template-treesitter.lua       # Template for Treesitter (disabled)
└── _template-ui.lua               # Template for UI plugins (disabled)

🎯 Active Plugin Files

Core Configuration (3 files)

1. astrocore.lua - Core AstroNvim functionality

   • Session management
   • Root detection (lsp, git)
   • Features configuration
   • Options (vim settings)
   • Keymappings (extensive custom bindings)
   • UI toggles (<leader>u prefix)

2. astrolsp.lua - Comprehensive LSP & Tooling (CONSOLIDATED)

   • LSP configurations (Go, TypeScript, Tailwind, HTML, CSS, Protobuf, JSON, YAML, Lua, Volar)
   • Formatting (Conform.nvim with oxfmt, stylua, rustfmt, taplo)
   • Linting (nvim-lint with oxlint, stylelint, markdownlint)
   • Treesitter configuration
   • TypeScript tooling (typescript-tools, autotag)
   • Mason auto-installation
   • Package management (package-info, crates.nvim)
   • Diagnostics UI (Trouble, lsp_lines, nvim-bqf)

3. astroui.lua - UI/UX Configuration

   • Colorscheme (cyberdream)
   • Icons
   • Statusline (Heirline)
   • Status components

Feature Plugin Files (4 files)

4. buildtools.lua - Development Tools

   • Treesitter (TOML, YAML, JSON parsers)
   • SchemaStore (JSON/YAML schemas)
   • Overseer (task runner for bun, vite)
   • Trouble (diagnostics)
   • Gitsigns (git integration)
   • EditorConfig
   • DevContainer support

5. bufferline.lua - Buffer Management

   • Enhanced bufferline with diagnostics
   • Custom close handlers
   • Buffer groups support
   • Icon integration

6. claude.lua - AI Assistant

   • Claude Code integration
   • Git root detection
   • Custom commands and keybindings
   • File explorer integration

7. neotree.lua - File Explorer

   • Dynamic pattern filtering
   • LSP file operations integration
   • Snacks.rename integration (NEW)
   • Custom keybindings for git, terminals, docker
   • Custom commands (format, mason)

8. template.lua - Code Templates (NEW)

   • Snacks picker integration
   • 14 essential templates for Cosmos SDK, Protobuf, and Vite+Cloudflare
   • Smart variable substitution
   • Filetype-aware template filtering

📝 Template Files (5 files - disabled by default)

These files are prefixed with _template- and disabled with if true then return {} end. Remove the first line to activate them.

1. _template-custom.lua - Examples for adding custom plugins
2. _template-filetype.lua - Filetype-specific configurations (Markdown, Rust, Python, Go, LaTeX)
3. _template-mason.lua - Mason tool installer customization
4. _template-treesitter.lua - Treesitter parser configuration
5. _template-ui.lua - UI plugins and colorscheme examples

✅ Recent Changes

Consolidated Files

• ✅ tsx.lua → Merged into astrolsp.lua
• ✅ linting.lua → Merged into astrolsp.lua

Added Features

• ✅ Snacks.rename integration in neotree.lua
• ✅ Snacks.toggle keymaps in astrocore.lua (<leader>u prefix)
• ✅ Proper ---@type LazySpec annotations on all files
• ✅ Comprehensive documentation (README.md)
• ✅ Template files for common customizations

New Toggle Keybindings (<leader>u)

• <leader>ud - Toggle diagnostics
• <leader>un - Toggle line numbers
• <leader>ur - Toggle relative numbers
• <leader>uw - Toggle line wrap
• <leader>us - Toggle spelling
• <leader>ui - Toggle inlay hints
• <leader>ut - Toggle treesitter
• <leader>uc - Toggle conceal
• <leader>uI - Toggle indent guides
• <leader>uz - Toggle zen mode
• <leader>uZ - Toggle zoom
• <leader>ua - Toggle animations
• <leader>uS - Toggle smooth scroll
• <leader>up - Toggle profiler
• <leader>uh - Toggle profiler highlights
• <leader>ux - Toggle dim inactive
• <leader>uf - Toggle format on save
• <leader>ul - Toggle LSP lines

Template Keybindings

• <C-a><C-t> - Open template picker (Snacks integration)

📚 Documentation

All plugin files now include:

• ✅ Module documentation headers
• ✅ ---@type LazySpec annotations
• ✅ Detailed inline comments
• ✅ Proper lazy loading strategies

🎓 Quick Reference

Adding a New Plugin

1. Create a new .lua file in lua/plugins/
2. Add module documentation and ---@type LazySpec
3. Return a table with plugin specifications
4. Configure lazy loading (event, cmd, ft, keys)

Modifying Existing Config

• Core settings → astrocore.lua
• LSP/formatting/linting → astrolsp.lua
• UI/statusline → astroui.lua
• Keymaps → astrocore.lua (mappings section)

Template Usage

1. Copy a template file (remove _template- prefix)
2. Remove if true then return {} end line
3. Customize the configuration
4. Save and restart Neovim

🔧 Useful Commands

• :Lazy - Plugin manager
• :Mason - LSP/tool installer
• :AstroReload - Reload config
• :ConformInfo - Format status
• :FormatToggle - Toggle format on save
• :LspLinesToggle - Toggle inline diagnostics
• :checkhealth - Health check

📖 Resources

• AstroNvim Docs
• lazy.nvim
• AstroCore
• AstroLSP
• Snacks.nvim