Get started with my Neovim config

This is my personal Neovim configuration: file search, language servers, completion, debugging, and the shortcuts I use. It is a starting point you can read and change.

The configuration lives in BeepBoopBit/nvim-config on GitHub. These steps use Linux or macOS with Bash or Zsh, matching the repository’s setup script.

Prepare your tools

Install Neovim and Git, then install and activate mise in your shell. Check that they are available:

nvim --version
git --version
mise doctor

Use a Neovim version compatible with the plugins in the repository’s lazy-lock.json. The config includes native plugin builds, so it also needs a C/C++ compiler and make. On macOS, finish installing the Xcode command-line tools before running setup.

The included script can install native dependencies through apt, dnf, yum, pacman, or Homebrew. Linux package installation can ask for your sudo password. You also need a network connection to download runtimes, plugins, and language tools.

Clone a separate profile

Neovim supports separate configuration and data directories through NVIM_APPNAME. Use a profile named bbb-nvim to try this configuration alongside your current editor setup:

git clone https://github.com/BeepBoopBit/nvim-config.git "${XDG_CONFIG_HOME:-$HOME/.config}/bbb-nvim"

If that destination already exists, choose a different profile name and use it consistently in the commands below. Git will refuse to clone over an existing directory.

Review and run setup

Read the cloned setup.sh before running it. You can also read it on GitHub.

The script installs native tools such as ripgrep, fd, and fzf. It uses mise use --global to select Node.js LTS, Python, Rust, and Lua, and installs LuaRocks through your system package manager when needed. It also installs Node and Python providers, Tree-sitter CLI, and the locked Neovim plugins.

The separate profile keeps your Neovim files apart. The script’s system packages and global mise runtime selections also affect the rest of your shell environment. Review those choices first; you can prepare dependencies manually if you already manage your runtimes another way. The script itself requires mise.

When you are ready, run:

bbb_nvim_dir="${XDG_CONFIG_HOME:-$HOME/.config}/bbb-nvim"
NVIM_APPNAME=bbb-nvim bash "$bbb_nvim_dir/setup.sh"

Passing NVIM_APPNAME here makes the script’s headless Neovim command use this profile too. If setup stops with an error, fix the reported dependency and rerun it.

Open the editor

NVIM_APPNAME=bbb-nvim nvim

Keep this prefix whenever you want to use the profile. Running plain nvim still selects your usual configuration.

The config bootstraps lazy.nvim and configures Mason for Rust, C/C++, JavaScript/TypeScript, Python, and Lua language servers. Let any first-run downloads finish. Inside Neovim, inspect the setup with:

:Lazy
:Mason
:checkhealth

If a native plugin fails to build, check the compiler and make. If file search is missing, check rg, fd or fdfind, and the Telescope plugin’s install status. Provider and language-tool errors should appear in :checkhealth or :Mason.

Learn a few shortcuts

The leader key is Space. Press the following sequences in normal mode:

Keys	Action
Space f f	Find files with Telescope
Space f g	Search text in the project
Space f b	Find an open buffer
Space e f	Open the file explorer
Space h a	Add the current file to Harpoon
Space m a	Add a bookmark
Space l f	Format with the attached language server
Space d b	Toggle a debugger breakpoint
Space d c	Continue with the configured debugger
Shift h / Shift l	Move between buffers

Normal-mode arrow keys are mapped to reminders to use h, j, k, and l. Clipboard actions need a working clipboard provider, and debugger actions need the appropriate adapter and launch configuration.

Make it yours

Start with these files in the cloned profile:

• lua/BeepBoopBit/native/flags.lua for editor options.
• lua/BeepBoopBit/native/mapping.lua for general shortcuts.
• lua/BeepBoopBit/plugins/ for plugin settings and their own mappings.
• lazy-lock.json for the recorded plugin revisions.

Commit your changes or keep a backup before pulling updates. To fetch repository updates without creating a merge commit:

git -C "${XDG_CONFIG_HOME:-$HOME/.config}/bbb-nvim" pull --ff-only

Review incoming changes and the lockfile before updating installed plugins. For help with this particular configuration, open an issue in the repository with the relevant error and your Neovim version.