Neovim

Neovim — Complete Developer Guide

AstroNvim v6 + lazy.nvim + Nix-provided LSP tools. Inspired by mic92’s dotfiles. Catppuccin Mocha theme.

Architecture

Nix provides:     neovim (bare, no Ruby) + 50+ LSP/formatter/linter packages
Config link:      config/nvim/ → ~/.config/nvim/ (via home.configFile, recursive symlink)
Plugin manager:   lazy.nvim (downloads to ~/.local/share/nvim/lazy/)
Framework:        AstroNvim v6 (keybindings, UI, LSP integration, completion)
Theme:            catppuccin-mocha (via astrocommunity)

Key files:

config/nvim/
  init.lua                 Bootstrap lazy.nvim + AstroNvim
  lazy-lock.json           63 pinned plugin versions
  treesitter-rev           Pinned treesitter commit (Nix grammar compat)
  lua/plugins/
    astrolsp.lua           LSP server config (13 servers)
    astroui.lua            Theme (catppuccin-mocha)
    community.lua          14 language packs + editing support
    gitsigns.lua           Inline git blame
    hunk.lua               Visual diff editor
    icon-picker.lua        Emoji/icon picker
    languages.lua          Custom filetype mappings (Snakemake, Nextflow, Zsh)
    luasnip.lua            Snippet engine
    mappings.lua           Custom keybindings
    mason.lua              Mason (disabled — all tools from Nix)
    neo-tree.lua           File explorer
    none-ls.lua            Formatters/linters (stylua, prettier, golangci-lint, shfmt)
    spaceless.lua          Strip trailing whitespace
    treesitter.lua         Syntax highlighting (auto-install grammars)

First Launch

After hey sync, open nvim for the first time:

1. lazy.nvim clones itself from GitHub
2. All 63 plugins are installed automatically
3. Treesitter grammars compile from source (C compiler wrapped via Nix)
4. LSP servers are already on PATH (installed by Nix)

No manual steps required. If a plugin fails to install, run :Lazy and press I to retry.

Modes (Vim Basics)

Mode Transitions

Normal ──► Insert:   i (cursor), a (after), o (new line below), O (above), I (line start), A (line end)
Insert ──► Normal:   Esc or Ctrl+c
Normal ──► Visual:   v (char), V (line), Ctrl+v (block)
Visual ──► Normal:   Esc
Normal ──► Command:  : (type command, Enter to execute)

File Operations

Open Files

Save & Close

Buffer Navigation

Window Management

Splits

Navigate Windows

Resize Windows

Code Intelligence (LSP)

All LSP servers are installed by Nix and available on PATH. AstroNvim’s astrolsp module auto-attaches them to the right filetypes.

Navigation

Editing

Diagnostics

LSP Servers Installed

Completion

AstroNvim uses blink.cmp (fast Rust-based completion engine).

Completion Behavior

Completion Sources (priority order)

1. LSP — code intelligence (definitions, methods, properties)
2. Copilot — AI suggestions
3. Snippets — LuaSnip + friendly-snippets
4. Buffer — words from open buffers
5. Path — file paths
6. Tmux — words from other tmux panes

Copilot

• Accept suggestion: Tab (when no completion menu visible)
• Dismiss: Esc
• Enabled for all filetypes including gitcommit

File Explorer (Neo-tree)

Inside Neo-tree

Search & Find

AstroNvim uses snacks.nvim for fuzzy finding (replaces Telescope).

File & Text Search

Inside Picker (snacks)

Git Integration

Gitsigns (inline)

Hunk (visual diff editor)

:DiffEditor    " Open visual diff/conflict resolution

Lazy-loaded — only available when invoked.

Debugging (DAP)

Debug Adapter Protocol

Supported Languages

Terminal Integration

ToggleTerm

Inside Terminal

Plugin Management (lazy.nvim)

Commands

Inside lazy.nvim UI

Adding a New Plugin

1. Create a new file in config/nvim/lua/plugins/ (e.g., my-plugin.lua):

   return {
       "author/plugin-name",
       opts = {
           -- plugin options
       },
   }

2. Reopen Neovim — lazy.nvim auto-installs it
3. Commit the updated lazy-lock.json

Pinning a Plugin Version

In the plugin spec:

return {
    "author/plugin-name",
    commit = "abc123",    -- pin to specific commit
    -- or
    tag = "v1.0.0",       -- pin to tag
    -- or
    version = "1.*",       -- semver range
}

Treesitter (Syntax Highlighting)

Treesitter provides structural syntax highlighting, indentation, and text objects.

Installed Language Packs (via astrocommunity)

Go, Bash, HTML, CSS, C++, Lua, Markdown, Nix, Python, Rust, TOML, YAML, Zig

Additional Grammars

Auto-installed by treesitter when you open a file. Compiled from source (Nix provides the C compiler).

Text Objects (treesitter-based)

Editing Features

Surround (nvim-surround)

Auto-pairs

Automatically pairs (, [, {, ", ', `. Press Enter to split pairs:

before: {|}     (| is cursor)
press Enter:
{
  |
}

Comment (Comment.nvim)

Indentation

Whitespace

• spaceless.nvim automatically strips trailing whitespace on save
• indent-blankline shows indent guides

Workflow: Snakemake & Nextflow

Snakemake

Files *.smk, *.snakefile, Snakefile are treated as Python:

• Treesitter Python highlighting
• basedpyright + ruff LSP
• black + isort formatting

Nextflow

Files *.nf, nextflow.config are treated as Groovy:

• Treesitter Groovy highlighting (auto-installed)
• No dedicated LSP (limited ecosystem)

Customization

Changing Theme

Edit config/nvim/lua/plugins/astroui.lua:

return {
    "AstroNvim/astroui",
    opts = {
        colorscheme = "catppuccin-mocha",  -- change here
    },
}

Available catppuccin flavors: catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, catppuccin-mocha

Adding Custom Keybindings

Edit config/nvim/lua/plugins/mappings.lua:

mappings = {
    n = {
        ["<leader>xx"] = { "<cmd>echo 'hello'<cr>", desc = "Say hello" },
    },
},

Adding LSP Servers

Edit config/nvim/lua/plugins/astrolsp.lua:

vim.list_extend(opts.servers, {
    "bashls", "clangd", -- ... existing servers
    "new_server",        -- add here
})

Also add the Nix package to modules/editors/vim.nix under nvim-lsp-packages.

Adding Formatters/Linters

Edit config/nvim/lua/plugins/none-ls.lua:

config.sources = astrocore.list_insert_unique(config.sources, {
    null_ls.builtins.formatting.new_formatter,
    null_ls.builtins.diagnostics.new_linter,
})

Quick Reference Card

NAVIGATION                          LSP
  <Space><Space>  Find files          gd    Go to definition
  <Space>fw       Grep text           gr    Find references
  <Space>*        Grep cursor word    K     Hover docs
  <Space>e        File explorer       <Space>rn  Rename
  <Space>o        Focus explorer      <Space>ca  Code action
  Tab / S-Tab     Next/prev buffer    ]d / [d    Next/prev diagnostic

EDITING                             GIT
  gcc             Comment line        ]c / [c    Next/prev hunk
  ys{m}{c}        Add surround        <Space>gs  Stage hunk
  ds{c}           Delete surround     <Space>gp  Preview hunk
  >> / <<         Indent/unindent     <Space>gb  Blame line

WINDOWS                             DEBUG
  Ctrl+w v        Vertical split      F5        Continue
  Ctrl+w s        Horizontal split    F10       Step over
  Ctrl+w h/j/k/l  Navigate            F11       Step into
  Ctrl+w c        Close window        <Space>b  Breakpoint

SEARCH                              TERMINAL
  <Space>fw       Live grep           <Space>tt  Toggle terminal
  <Space>fb       Buffers             <Space>tl  Lazygit
  <Space>fh       Help tags           Ctrl+\ Ctrl+n  Exit term mode

PLUGIN MANAGEMENT
  :Lazy           Open UI
  I / U / X       Install / Update / Clean
  R               Restore lockfile

Troubleshooting

LSP not attaching

1. Check :LspInfo — shows which servers are attached
2. Check :checkhealth lsp — diagnostic info
3. Verify the server is on PATH: which gopls etc.

Treesitter grammar not found

1. Run :TSInstall <language> to manually install
2. Or restart nvim — auto-install should trigger

Plugin not loading

1. Run :Lazy — check plugin status
2. Run :checkhealth lazy — check lazy.nvim health
3. Delete ~/.local/share/nvim/lazy/ and restart for clean install

Slow startup

1. Run :Lazy profile — shows load times per plugin
2. Check for conflicting plugins
3. Verify treesitter grammars are compiled (not downloading)

Copilot not working

1. Run :Copilot setup — authenticate with GitHub
2. Check :Copilot status — verify connection
3. Requires nodejs on PATH (provided by Nix)

Related Docs