jdhao-nvim-config/docs

Pre-requisite

There are a few dependencies if we want to use Neovim for efficient editing and development work.

Python

A lot of Neovim plugins are mainly written in Python. To use auto-completion and other features, we must install Python 3. The easiest way to install is via Anaconda or Miniconda. Make sure that the output of python --version shows that Python 3.x is installed.

Pynvim

Neovim relies on pynvim to communicate with plugins that utilize its Python binding. Pynvim is required by plugins such as Deoplete and Semshi.

pip install -U pynvim

python-lsp-server

python-lsp-server is the community-fork of pyls, and it is a Python Language Server for completion, linting, go to definition, etc.

pip install 'python-lsp-server[all]' pylsp-mypy pyls-isort

Node

We need to install node.js from here:

# Ref: https://johnpapa.net/node-and-npm-without-sudo/
wget https://nodejs.org/dist/v14.15.4/node-v14.15.4-linux-x64.tar.xz

mkdir -p $HOME/tools
# extract node to a custom directory, the directory should exist.
tar xvf node-v14.15.4-linux-x64.tar.xz --directory=$HOME/tools

Then add the following config to .bash_profile or .zshrc

export PATH="$HOME/tools/node-v14.15.4-linux-x64/bin:$PATH"

Source the file:

source ~/.bash_profile
# source ~/.zshrc

vim-language-server

vim-language-server provides completion for vim script. We can install vim-language-server globally and set its path:

npm install -g vim-language-server

export PATH="$HOME/.npm-packages/bin:$PATH"

Git

Git is used by the plugin manager packer.nvim to download plugins from GitHub or other Git repositories.

Since Git is usually pre-installed on Linux and macOS, we do not need to worry if we are on these two platforms. For Windows, install Git for Windows and make sure you can call git from the command line.

ctags

In order to use tags related plugins such as tagbar and gutentags, we need to install a ctags distribution. Universal-ctags is preferred.

To install ctags on macOS, use Homebrew:

brew install ctags

To install it Windows, use chocolatey:

choco install universal-ctags

To install it on Linux, we need to build it from source. See here for the details.

Set its PATH properly and make sure you can call ctags from command line.

Ripgrep

Ripgrep, aka, rg, is a fast greping tool available for both Linux, Windows and macOS. It is used by several searching plugins.

For Windows and macOS, we can install it via chocolatey and homebrew respectively. For Linux, we can download the executable file from its release page and install it.

Linters

A linter is a tool to check the source code for possible style and syntax issues. Based on the programming languages we use, we may need to install various linters.

• Python: pylint and flake8.
• Vim script: vint.

For other linters, please consult the plugin documentation. For ALE (which is the linting plugin I currently use), a list of linters for different languages is listed here.

Terminal emulators

Which terminal emulator we choose to use greatly affects the appearance and functionalities of Neovim. Since Neovim supports true colors, terminals that support true colors are preferred. For a list of terminals that support true colors, see here.

For macOS, we can use iterm2, kitty or Alacritty. If you connect to Linux server on Windows, I recommend wsltty and Cygwin, both of them use mintty as the terminal emulator.

Font

Since Vim-airline uses several Unicode symbols not available in normal font, we need to install fonts here to make vim-airline look pretty. I am using Hack, and it looks great. Another great resource for programming font is the nerd-font project.

Install Neovim

There are various ways to install Neovim based on your system. Note that some of plugins I use require Nvim master. It is recommended to use the nightly version of nvim.

Linux

We can directly download the binary release from here.

Windows

The easiest way to install Neovim on Windows is via chocolatey. First, install chocolatey. Then we can install neovim easily using the following command:

# install the latest version of neovim
# choco install neovim --pre

choco install neovim

The Neovim that chocolatey installs may not be up to date. To use the cutting-edge features of Neovim, you may download the nightly release from GitHub and manually extract it.

macOS

It is recommended to install neovim via Homebrew on macOS. Simply run the following command:

brew install neovim
# If you want to install the latest version of neovim, use the following
# command instead.
# brew install --HEAD neovim

After installing Neovim, we need to add the directory where the Neovim executable (nvim on Linux and macOS, nvim.exe on Windows) resides to the system PATH.

Make sure that you can call nvim from the command line after all these setups.

Setting up Nvim

Install plugin manager packer.nvim

I use packer.nvim to manage my plugins. We need to install packer.nvim on our system first.

For Windows, if curl is installed, use the following command (on Powershell):

git clone --depth=1 https://github.com/wbthomason/packer.nvim "$env:LOCALAPPDATA\nvim-data\site\pack\packer\start\packer.nvim"

For macOS and Linux, use the following command:

git clone --depth=1 https://github.com/wbthomason/packer.nvim ~/.local/share/nvim/site/pack/packer/start/packer.nvim

How to install this configuration

On Windows, the config directory is $HOME/AppData/Local/nvim¹. On Linux and macOS, the directory is ~/.config/nvim. First, we need to remove all the files under the config directory (including dot files), then go to this directory, and run the following command to install this configuration:

git clone --depth=1 https://github.com/jdhao/nvim-config.git .

After that, when we first open nvim, use :PackerInstall to install all the plugins. Since I use quite a lot of plugins (more than 60), it may take some time to install all of them, depending on your network condition.

Automatic Installation for Linux

To set up a workable Neovim environment in Linux, I use the bash script Nvim_setup.sh to automatically install necessary dependencies, Neovim itself and Nvim configs in this repo.

Note that the variable PYTHON_INSTALLED, SYSTEM_PYTHON and ADD_TO_SYSTEM_PATH in the script should be set properly based on your environment.

---

1. Use echo %userprofile% to see where your $HOME is. ↩︎