KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #ai #dsh-plugin #ai-agent #mcp #deepseek-harness #windows

neovim-config

★ 69 Open GitHub ↗

A Neovim setup using Lua

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Neovim configuration with Lua

A [Neovim](https://github.com/neovim/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:
```bash
# For stable versions
sudo snap install nvim --classic

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

### MacOS

Using [Homebrew](https://brew.sh/), installing or updating Neovim is straightforward:
```bash
# 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:
```bash
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`**](https://github.com/folke/lazy.nvim). The bootstrap configuration in [lua/config/lazy.lua](file:///Users/mlle/Repos/configs/dotfiles/neovim/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](file:///Users/mlle/Repos/configs/dotfiles/neovim/lua/config/plugins/formatting.lua).

---

## Core Plugins

Some of the most important plugins in this configuration are:

1. [**`lazy.nvim`**](https://github.com/folke/lazy.nvim): Fast and feature-rich plugin manager.
2. [**`mason.nvim`**](https://github.com/williamboman/mason.nvim): Portable package manager for LSP servers, DAP servers, linters, and formatters.
3. [**`nvim-lspconfig`**](https://github.com/neovim/nvim-lspconfig): Quickstart configurations for Neovim's built-in LSP client.
4. [**`nvim-cmp`**](https://github.com/hrsh7th/nvim-cmp): Completion engine that integrates with LSP and snippets.
5. [**`nvim-treesitter`**](https://github.com/nvim-treesitter/nvim-treesitter): Provides advanced syntax highlighting, indenting, and code navigation.
6. [**`nvim-tree.lua`**](https://github.com/nvim-tree/nvim-tree.lua): Fast, customizable file explorer sidebar.
7. [**`vim-fugitive`**](https://github.com/tpope/vim-fugitive): Git wrapper for command-line Git operations inside Neovim.
8. [**`gitsigns.nvim`**](https://github.com/lewis6991/gitsigns.nvim): Git integration in the gutter (shows hunks, blames, and handles staging).
9. [**`telescope.nvim`**](https://github.com/nvim-telescope/telescope.nvim): Highly extendable fuzzy finder over files, buffers, and grep.
10. [**`lualine.nvim`**](https://github.com/nvim-lualine/lualine.nvim): Elegant and fast statusline.
11. [**`bufferline.nvim`**](https://github.com/akinsho/bufferline.nvim): Snazzy tab/buffer header line.
12. [**`trouble.nvim`**](https://github.com/folke/trouble.nvim): Diagnostics window highlighting errors, warnings, and TODOs.
13. [**`render-markdown.nvim`**](https://github.com/MeanderingProgrammer/render-markdown.nvim): Elegant rendering of markdown headers, lists, codeblocks, and quotes.
14. [**`glow.nvim`**](https://github.com/ellisonleao/glow.nvim): Markdown previewing directly inside a Neovim buffer.
15. [**`fidget.nvim`**](https://github.com/j-hui/fidget.nvim): Standalone UI for displaying LSP progress/messages.
16. [**`vimtex`**](https://github.com/lervag/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](file:///Users/mlle/Repos/configs/dotfiles/neovim/lua/config/plugins/lsp/lspconfig.lua):

```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](https://github.com/ryanoasis/nerd-fonts).

### Standard Installation
1. Download a font from the [Nerd Fonts Releases](https://github.com/ryanoasis/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.

neovim-config

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README