The Only Guide You Need to Get Started with Neovim

Neovim is like a souped-up version of the classic Vim text editor, but with a whole lot more power under the hood. It’s incredibly lightweight and customizable, letting you mold it to fit your exact coding style. It’s all about efficiency and speed, letting you edit code with a flow that feels almost like thought itself. With tons of plugins and a vibrant community, you can make Neovim a truly personalized coding sanctuary.

What is Kickstart?

Kickstart is a starting point, a template, for your Neovim configuration. It is not a distribution (a large bundle of plugins with added management layers). The goal is to have a single, well-documented file (less than 300 lines of code with about 400 lines of documentation) that guides you through every step, from basic configuration to advanced scripting and plugin customization.

Prerequisites

• Basic Lua Knowledge: If you’re unfamiliar with Lua, take a quick detour to learn the basics using resources like “Learn X in Y minutes”. Also, check out the Neovim Lua guide (:help lua-guide).
• Neovim Tutor: Run :tutor inside Neovim. This is essential for understanding basic navigation and commands.
• Neovim Help: Familiarize yourself with the help system by running :help. You can search within the help using space sh.

Key Concepts in Kickstart

Throughout the init.lua file, you’ll find bright green text notes that introduce important configuration concepts. Pay attention to these notes as you explore your configuration.

Leader Key

The leader key acts as a namespace for your custom key mappings. In Kickstart, the leader key is set to space. For example, space sh searches the help.

Options

Neovim is highly configurable via options. Kickstart sets some sensible defaults. You can modify these options using vim.opt. For example:

vim.opt.number = true -- Enables line numbers
vim.opt.number = false -- Disables line numbers

Keymaps

Keymaps are keyboard shortcuts to execute commands. They can be simple or complex sequences of keys. Kickstart provides examples of creating custom keymaps using vim.keymap.set. For example:

vim.keymap.set("n", "]d", vim.diagnostic.open_float, { desc = "Show diagnostic messages" })

Autocommands

Autocommands execute commands when specific events are triggered in Neovim. Kickstart uses autocommands for things like highlighting yanked text. They follow a general pattern: listen to an event, and execute a callback.

vim.api.nvim_create_autocmd("TextYankPost", {
    desc = "Highlight yanked text",
    group = vim.api.nvim_create_augroup("highlight_yank", {}),
    callback = function()
        -- Code to highlight yanked text
    end
})

Plugin Management with Lazy

Kickstart uses the lazy.nvim plugin manager. Lazy allows you to update, install, and manage plugins.

• :Lazy opens the lazy menu.
• lazy update updates plugins.
• Plugins are defined using a table containing the plugin’s repository or URL along with configuration options.

{ "tpope/vim-sleuth", }, -- Simple plugin install
{
    "folke/tokyonight.nvim",
    lazy = true, -- Load only when needed
    opts = { style = "night" }, -- Configuration options
},

• Plugins can also include Lua code for complex configuration.

Fuzzy Finding with Telescope

Telescope is a fuzzy finder used to search various elements like files, help, keymaps, symbols, and more.

• space sh searches help.
• ctrl / opens the preview window within Telescope.
• Kickstart includes keymaps for different telescope functions.
• Telescope can be customized using options like layout and current working directory.

-- Example of customizing telescope
vim.keymap.set("n", "<space>sn", function()
    require("telescope.builtin").find_files({ cwd = vim.fn.stdpath("config") })
end, { desc = "Search Neovim files" })

Language Server Protocol (LSP)

LSP provides code intelligence features. Kickstart sets up keymaps and autocommands to interact with LSP.

• Keymaps: gd (go to definition), gr (find references), space ds (document symbols), space ws (workspace symbols), and K (show documentation).
• Capabilities: Neovim informs the LSP of its capabilities, including supporting code completion and snippets.
• Servers: You can enable different LSPs for different languages by uncommenting lines in the servers table.
• Mason: Mason is used to install language servers.
• LSP Config: Connects the installed LSPs with Neovim.
• Conform: Used for formatting on save.

Autocompletion with Envim-cmp

Kickstart uses the nvim-cmp plugin for autocompletion.

• ctrl n and ctrl p: Move between next/previous completion item.
• ctrl y: Accept the completion.
• tab: Always inserts spaces for alignment
• enter: Always creates a new line
• nvim-cmp is a framework for multiple completion sources (LSP, path, buffer, etc).

Other notable plugins

• todo-comments.nvim: Highlights comments such as TODO:, FIXME:, and NOTE:.
• mini.nvim: A collection of small, independent plugins that provide enhanced editing capabilities. Includes features like text object manipulation, surround, and a status line.
• nvim-treesitter: Provides syntax highlighting, indenting, and other advanced features.

Customizing Kickstart

Kickstart is intended as a starting point. You can easily extend it with new plugins and configurations.

• You can include plugins directly into your init.lua or create a folder for custom plugins and use lazy.nvim’s import mechanism to include them.
• Example: The indent line plugin is included in the repo but commented out. You can uncomment this line to enable the plugin.
• Experiment and modify your configuration to suit your workflow.

Conclusion

Kickstart is a powerful template for learning and customizing Neovim. By understanding the concepts and configurations outlined in this guide (and in the init.lua file), you can build a Neovim setup that is both efficient and enjoyable to use. Don’t hesitate to explore, experiment, and make Neovim your own.