🌙 Neovim, but friendlier

A clean, well-documented Neovim configuration designed to be readable — whether you're a beginner learning how Neovim config works, or an experienced user looking for a solid base to fork.

Why this config? Because most Neovim configs are write-only. This one has comments that actually explain why, not just what.

✨ At a glance

• 🚀 Fast startup — lazy-loaded plugins via lazy.nvim
• 🧠 Smart completion — LSP-powered autocomplete with snippet support
• 🔍 Telescope everywhere — fuzzy-find files, symbols, git history, and more
• 🎨 Tokyo Night — the beloved dark colorscheme
• 📝 Format on demand — conform.nvim with formatters per language
• 🏗️ Drop-in LSP — add a .lua file to lsp/, it auto-wires itself
• 📚 Heavily commented — every file explains the concepts it uses

🎯 What you get

Category	Stack	What it does
Package manager	lazy.nvim	Install, update, and lazy-load plugins
Colorscheme	tokyonight.nvim	Dark theme, easy on the eyes
Completion	nvim-cmp + snippy	Intelligent autocomplete with snippet expansion
Fuzzy finder	telescope.nvim	Files, grep, symbols, git, diagnostics — one interface
File tree	neo-tree.nvim	Sidebar file explorer
Status line	lualine.nvim	Clean status and tab line
Syntax	nvim-treesitter	Better highlighting, indentation, and text objects
LSP	Builtin vim.lsp	Auto-discovered server configs for 10+ languages
Formatting	conform.nvim	Format code with a keypress
Motion	hop.nvim + mini.move	Jump anywhere on screen, move lines with Alt+hjkl
Terminal	FTerm.nvim	Floating terminal with lazygit, python, and btop shortcuts
Icons	nvim-web-devicons	File icons everywhere

Language support

Out of the box: Lua, C/C++, Python, Go, Kotlin, Dart, TypeScript/JavaScript, JSON, Markdown, TOML, CMake, XML

🚀 Quick start

# 1. Back up your existing config (if any)
mv ~/.config/nvim ~/.config/nvim.bak

# 2. Clone this repo
git clone https://github.com/AzarAI-TOP/nvim.git ~/.config/nvim

# 3. Launch Neovim — lazy.nvim installs itself, then all plugins
nvim

That's it. On first launch, lazy.nvim clones itself, then installs every plugin. Mason installs LSP servers and formatters automatically. Grab a coffee, it only happens once.

Prerequisites

• Neovim >= 0.11 (required for builtin vim.lsp.enable)
• A Nerd Font (for icons in the UI) — Nerd Fonts download
• Git (for lazy.nvim to clone plugins)
• Optional: lazygit, btop, fcitx5 (for the terminal shortcuts and IME switching)

⌨️ Key bindings

Everything is organized around <Space> as the leader key.

Finding things

Key	Action
<Space>ff	Find files
<Space>fg	Live grep (search file contents)
<Space>fh	Help tags
<Space>fk	Browse keymaps
<Space>fn	Browse notifications

LSP (language server)

Key	Action
K	Show hover info
<Space>la	Code actions (quick fix, import, etc.)
<Space>lf	Format document
<Space>lr	Rename symbol
<Space>lR	Find references
<Space>ld	Go to declaration
<Space>lD	Go to definition
<Space>ls	Document symbols
<Space>lS	Workspace symbols

Navigation

Key	Action
<Space>J	Hop anywhere on screen
<Space>j	Hop on current line
<M-hjkl>	Move selected lines/block
[b / ]b	Previous / next buffer
[d / ]d	Previous / next diagnostic
[t / ]t	Previous / next TODO comment

Buffers

Key	Action
<Space>bd	Delete buffer (safe — won't close window)
<Space>bD	Delete buffer (force)
<Space>bo	Delete all other buffers

Tools

Key	Action
<Space>e	Toggle file explorer
<Space>tl	Lazygit (floating terminal)
<Space>tp	Python REPL (floating terminal)
<Space>tb	Btop system monitor
<Space>tt	Default terminal
<F1>	Toggle terminal

Git & TODO

Key	Action
<Space>gc	Git commit history
<F5>	All TODOs in project
<F4>	TODOs in current file

🏗️ How it's organized

~/.config/nvim/
├── init.lua                  # Entry point — bootstraps lazy.nvim, loads modules
├── stylua.toml               # Formatter config (2 spaces, double quotes)
├── lua/
│   ├── config/
│   │   ├── options.lua       # Editor settings (indent, clipboard, etc.)
│   │   ├── autocmds.lua      # Event-driven hooks
│   │   ├── filetypes.lua     # Per-filetype overrides
│   │   ├── lazy_setup.lua    # Plugin manager configuration
│   │   ├── keymaps.lua       # All keybindings (organized by category)
│   │   ├── cmds.lua          # Custom Ex commands
│   │   ├── utils.lua         # Shared helper functions
│   │   └── lsp_setup.lua     # Auto-discovers LSP configs from lsp/
│   └── plugins/
│       ├── nvim-cmp.lua      # Completion engine
│       ├── mason.lua         # LSP & tool installer
│       ├── telescope.lua     # Fuzzy finder
│       ├── neo-tree.lua      # File explorer
│       ├── nvim-lualine.lua  # Status line
│       ├── nvim-treesitter.lua
│       ├── conform.lua       # Code formatter
│       ├── fterm.lua         # Floating terminal
│       ├── hop.lua           # Easy motion
│       ├── tokyonight.lua    # Colorscheme
│       └── ...               # And more
├── lsp/                      # One file per language server
│   ├── lua_ls.lua
│   ├── clangd.lua
│   ├── pyright.lua
│   ├── gopls.lua
│   └── ...
└── snippets/                 # Custom snippet files
    ├── lua.snippets
    ├── python.snippets
    └── ...

🎓 Great for learning

If you're new to Neovim configuration, start here:

1. lua/config/options.lua — the simplest file, just setting editor preferences
2. lua/config/keymaps.lua — see how keybindings are structured
3. lua/plugins/telescope.lua — a minimal plugin spec (just 3 lines!)
4. lua/plugins/nvim-cmp.lua — a complex plugin with detailed comments
5. lsp/lua_ls.lua — a straightforward LSP server config
6. lsp/clangd.lua — an advanced LSP config with custom commands

Every file has a header comment explaining what it does and the concepts involved.

🔧 Customizing

Fork it and make it yours:

• Add a language server — drop a .lua file into lsp/ returning a vim.lsp.Config table
• Add a plugin — create a file in lua/plugins/ returning a lazy.nvim spec
• Change the colorscheme — edit lua/plugins/tokyonight.lua and lazy_setup.lua
• Add keybindings — append to the relevant section in lua/config/keymaps.lua

📋 Requirements

Dependency	Purpose
Neovim >= 0.11	Required for builtin vim.lsp.enable()
Git	Plugin cloning
Nerd Font	Icons in UI
stylua	Lua formatting
clang-format	C/C++ formatting
black + isort	Python formatting
prettierd	JSON/Markdown formatting
taplo	TOML formatting
LSP servers	Installed automatically by Mason