Neovim configuration with Lua

A Neovim configuration using Lua, featuring a curated selection of plugins for an optimized programming workflow. It includes built-in LSP integration, autocompletion, fuzzy finding, git integration, formatting, and file exploration.

This README serves as a reference for setting up a new machine and quickly recalling key mappings.

---

Setting up

Neovim undergoes rapid development, so installing a recent version is recommended to ensure compatibility with modern plugins.

Linux

You can install Neovim using Snap:

# For stable versions
sudo snap install nvim --classic

# For nightly/development versions
sudo snap install --edge nvim --classic

MacOS

Using Homebrew, installing or updating Neovim is straightforward:

# For stable version
brew install neovim

# For nightly/HEAD version
brew install --HEAD neovim

# To update
brew upgrade neovim

Terminal Configuration for Alt/Option Mappings

Some plugins or navigation mappings rely on the Option/Alt key:

• iTerm2: Open Preferences -> Profiles -> Keys. Set the left Option key behavior to Esc+.
• Kitty: Add macos_option_as_alt left to your kitty configuration. Restart Kitty (Cmd + Q and reopen) for it to take effect.

External Dependencies

Since many language servers and plugins compile or install binaries locally, ensure your system has the following installed:

• npm (Node Package Manager) - required for JavaScript/TypeScript, Bash, and other language servers.
• python3 (with venv and pip) - required for Python tools and formatters.
• A C compiler (gcc or clang) and make - required to compile telescope-fzf-native.
• unzip and curl - used by Mason to download and extract packages.

---

Installing the configuration

Clone this repository into Neovim's standard configuration directory:

git clone https://github.com/miltonllera/neovim-lua-config ~/.config/nvim
cd ~/.config/nvim

Directory Structure

The configuration is organized under the standard Lua module layout:

.
├── init.lua                  # Configuration entrypoint
├── lazy-lock.json            # Lockfile generated by lazy.nvim
└── lua/
    ├── config/
    │   ├── commands.lua      # Custom user autocommands/commands
    │   ├── keymaps.lua       # Global, plugin-independent keymaps
    │   ├── lazy.lua          # lazy.nvim package manager bootstrap & setup
    │   ├── options.lua       # Neovim options and settings
    │   ├── plugins/          # Plugin specifications (automatically imported)
    │   │   ├── lsp/
    │   │   │   ├── lspconfig.lua # Native LSP configurations & keybinds
    │   │   │   └── mason.lua     # Mason manager (automatic LSP/tool installer)
    │   │   ├── bufferline.lua    # Buffer tabline UI
    │   │   ├── formatting.lua    # Formatting, LaTeX, and general text edit tools
    │   │   ├── git.lua           # Git fugitive, Trouble, and Gitsigns
    │   │   ├── lualine.lua       # Statusline UI
    │   │   ├── misc.lua          # Useless/fun animations
    │   │   ├── nvim-cmp.lua      # Autocomplete engine & sources
    │   │   ├── nvim-tree.lua     # File explorer configuration
    │   │   ├── startify.lua      # Start screen bookmarks/recent files
    │   │   ├── telescope.lua     # Fuzzy finder configuration
    │   │   ├── themes.lua        # Theme setup (e.g. Rose Pine)
    │   │   └── treesitter.lua    # Treesitter parser config
    │   └── themes.lua        # Theme loader hook
    └── utils.lua             # Helper keymap utility functions

Managing Plugins with lazy.nvim

Plugins are managed by lazy.nvim. The bootstrap configuration in lua/config/lazy.lua is set up to automatically import specs:

1. To configure an existing plugin, edit the corresponding file in lua/config/plugins/.
2. To install a new plugin, create a new .lua file inside lua/config/plugins/ that returns the plugin spec (or list of specs), or append it to one of the arrays in files like formatting.lua.

---

Core Plugins

Some of the most important plugins in this configuration are:

1. lazy.nvim: Fast and feature-rich plugin manager.
2. mason.nvim: Portable package manager for LSP servers, DAP servers, linters, and formatters.
3. nvim-lspconfig: Quickstart configurations for Neovim's built-in LSP client.
4. nvim-cmp: Completion engine that integrates with LSP and snippets.
5. nvim-treesitter: Provides advanced syntax highlighting, indenting, and code navigation.
6. nvim-tree.lua: Fast, customizable file explorer sidebar.
7. vim-fugitive: Git wrapper for command-line Git operations inside Neovim.
8. gitsigns.nvim: Git integration in the gutter (shows hunks, blames, and handles staging).
9. telescope.nvim: Highly extendable fuzzy finder over files, buffers, and grep.
10. lualine.nvim: Elegant and fast statusline.
11. bufferline.nvim: Snazzy tab/buffer header line.
12. trouble.nvim: Diagnostics window highlighting errors, warnings, and TODOs.
13. render-markdown.nvim: Elegant rendering of markdown headers, lists, codeblocks, and quotes.
14. glow.nvim: Markdown previewing directly inside a Neovim buffer.
15. fidget.nvim: Standalone UI for displaying LSP progress/messages.
16. vimtex: Full environment for writing LaTeX documents.

---

Key Mappings Reference

This configuration defines a set of handy keyboard shortcuts. The leader key is configured to Space.

General Editor Mappings

Key	Mode	Description
kj	Insert	Escape to Normal Mode
<C-u>	Normal	Page up (and center cursor zz)
<C-d>	Normal	Page down (and center cursor zz)
<C-s>	Normal	Save file (:w)
<C-c>	Normal	Close current window (:q)
<C-h> / j / k / l	Normal	Navigate to Left / Down / Up / Right window splits
<TAB>	Normal	Go to next buffer (via bufferline.nvim)
<S-TAB>	Normal	Go to previous buffer (via bufferline.nvim)
<A-w>	Normal	Delete current buffer (:bd)
<leader>ws	Normal	Horizontal split
<leader>vs	Normal	Vertical split
<leader>s	Normal/Visual	Populate buffer search/substitution command
<leader>S	Normal/Visual	Populate project-wide substitution command
<leader>y	Normal/Visual	Yank selected text to system clipboard
<leader>P	Normal/Visual	Paste text from system clipboard
<leader>p	Visual	Paste without overwriting default register
<leader>nh	Normal/Visual	Clear search highlights (:nohlsearch)
<leader>e	Normal	Toggle File Explorer (NvimTree)

Fuzzy Finder (Telescope)

Key	Mode	Description
<leader>o	Normal	Find files in project
<leader>H	Normal	Find files (including hidden files)
<leader>b	Normal	Find open buffers
<leader>lg	Normal	Live grep search project
<leader>pr	Normal	Find recently opened files

Git Mappings (Fugitive & Gitsigns)

Key	Mode	Description
<leader>G	Normal	Open Git Fugitive Status (:G)
<leader>gl	Normal	Open Git commit log (:Gclog)
]c	Normal	Jump to next git change hunk
[c	Normal	Jump to previous git change hunk
<leader>hs	Normal/Visual	Stage the hunk under the cursor
<leader>hr	Normal/Visual	Reset the hunk under the cursor
<leader>hS	Normal	Stage all changes in current buffer
<leader>hu	Normal	Undo last staged hunk
<leader>hR	Normal	Reset all changes in current buffer
<leader>hp	Normal	Preview the hunk under the cursor
<leader>hb	Normal	Toggle blame line overlay details
<leader>tb	Normal	Toggle virtual text current-line blame
<leader>hd	Normal	Diff changes against index

LSP & Code Mappings

These mappings are active when an LSP client attaches to the buffer:

Key	Mode	Description
gD	Normal	Go to declaration
gd	Normal	Go to definition
gi	Normal	Go to implementation
gr	Normal	Show references (via Telescope)
gt	Normal	Show type definitions (via Telescope)
<leader>vca	Normal/Visual	Open code actions
<leader>R	Normal	Rename symbol under cursor
K	Normal	Show hover documentation under cursor
<C-h>	Insert	Show signature help
<leader>rs	Normal	Restart LSP
<leader>d	Normal	Show line diagnostics in float window
<leader>D	Normal	Show buffer diagnostics (via Telescope)
<leader>i	Normal	Show line diagnostic details
<leader>I	Normal	Open buffer diagnostics in Trouble

---

Language Servers & Tools

LSP servers, linters, and formatters are automatically installed and managed by mason.nvim, mason-lspconfig.nvim, and mason-tool-installer.nvim.

Managed Servers (LSP)

The following servers are configured for automatic installation and hook into the completion/LSP client:

• basedpyright: Advanced Python type checking and code analysis.
• lua_ls: Lua language server.
• ts_ls: TypeScript/JavaScript language server.
• bashls: Bash/shell script language server.
• julials: Julia language server.
• texlab: LaTeX language server.
• marksman: Markdown language server.

Managed Tools & Linters

• pylint: Python code linter.
• clangd: C/C++ language server and development tool.

Diagnostics Notes

By default, inline error messages (virtual text diagnostics) are disabled in the current configuration to prevent clutter. To enable them, update the vim.diagnostic.config setup (around line 57) in lua/config/plugins/lsp/lspconfig.lua:

vim.diagnostic.config({
  virtual_text = true, -- Change false to true to enable inline errors
  -- ...
})

---

Web-dev Icons

To display folder/file icons and UI separators properly, install a Nerd Font.

Standard Installation

1. Download a font from the Nerd Fonts Releases. (e.g., Roboto Mono Nerd Font).
2. Copy the .ttf / .otf file to:
   • Linux: ~/.local/share/fonts/
   • MacOS: /Library/Fonts/
3. Configure your terminal emulator settings to use the installed font.

Nerd Fonts with Kitty

Kitty handles font fallback rendering automatically:

1. Download and install the font (e.g. Symbols Nerd Font) into your system font folder.
2. In your kitty.conf, configure the symbol mapping if symbols aren't rendered by default, then refresh your kitty font cache.

---

Attributions

Acknowledge of code snippets and configuration designs sourced from plugin documentations and other Neovim community configurations.