diff options
Diffstat (limited to 'docs/README.md')
| -rw-r--r-- | docs/README.md | 100 |
1 files changed, 53 insertions, 47 deletions
diff --git a/docs/README.md b/docs/README.md index 39e54bb..62e091d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,9 +2,44 @@ This doc summarizes how to install and use this configuration in detail. # Pre-requisite +## Terminal emulators + +Which [terminal emulator](https://en.wikipedia.org/wiki/Terminal_emulator) we choose to use greatly affects the appearance and features of Nvim. +Since Nvim supports true colors, terminals that support true colors are preferred. +For a list of terminals that support true colors, see [here](https://github.com/termstandard/colors). + +For macOS, we can use [kitty](https://sw.kovidgoyal.net/kitty/), [iterm2](https://www.iterm2.com/), [wezterm](https://wezfurlong.org/wezterm/) or [Alacritty](https://github.com/jwilm/alacritty). + +If you ssh to Linux server on Windows, I recommend [wsltty](https://github.com/mintty/wsltty) and [Cygwin](https://www.cygwin.com/), +both of them use [mintty](https://github.com/mintty/mintty) as the terminal emulator. +For the latest version of Windows 10, you can also try [Windows Terminal](https://github.com/microsoft/terminal). + +## Patched Fonts + +Since statusline or file explorer plugins often use Unicode symbols not available in normal font, +we need to install a patched font from the [nerd-fonts](https://github.com/ryanoasis/nerd-fonts) project. + +# Automatic installation + +## Automatic Installation for Linux + +To set up a workable Nvim environment on Linux, +I use [a bash script](nvim_setup_linux.sh) to automatically install necessary dependencies, Nvim itself and configs. + +Note that the variable `PYTHON_INSTALLED`, `SYSTEM_PYTHON` and `ADD_TO_SYSTEM_PATH` in the script +should be set properly based on your environment. + +## Automatic installation for Windows + +Run script [nvim_setup_windows.ps1](nvim_setup_windows.ps1) under PowerShell. + +# Manual install + There are a few dependencies if we want to use Nvim for efficient editing and development work. -## Python +## Dependencies + +### Python A lot of Nvim plugins are mainly written in Python, so we must install Python 3. The easiest way to install is via [Anaconda](https://docs.anaconda.com/anaconda/install/index.html) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html). @@ -12,7 +47,7 @@ The easiest way to install is via [Anaconda](https://docs.anaconda.com/anaconda/ After installation, make sure that you can run `python --version`, and that the output should be Python 3.x. -## Pynvim +### Pynvim Nvim relies on [pynvim](https://github.com/neovim/pynvim) to communicate with plugins that utilize its Python binding. Pynvim is required by plugins such as [wilder.nvim](https://github.com/gelguy/wilder.nvim). @@ -21,7 +56,7 @@ Pynvim is required by plugins such as [wilder.nvim](https://github.com/gelguy/wi pip install -U pynvim ``` -## python-lsp-server +### python-lsp-server [python-lsp-server (pylsp)](https://github.com/python-lsp/python-lsp-server) is a Python [Language Server](https://microsoft.github.io/language-server-protocol/) for completion, linting, go to definition, etc. @@ -33,7 +68,7 @@ Note the executable for pylsp is also named `pylsp`. You need to set its PATH co If you use pip from Anaconda, the executable path may be something like `$CONDA_ROOT/bin/pylsp`. For native python, the path for pylsp may be like `$HOME/.local/bin/pylsp` -## Node +### Node We need to install node.js from [here](https://nodejs.org/en/download/). For Linux, you can use the following script: @@ -60,7 +95,7 @@ source ~/.bash_profile # source ~/.zshrc ``` -## vim-language-server +### vim-language-server [vim-language-server](https://github.com/iamcco/vim-language-server) provides completion for vim script. We can install vim-language-server globally: @@ -70,7 +105,7 @@ npm install -g vim-language-server vim-language-server is installed in the same directory as the node executable. -## Git +### Git Git is required by plugin manager [packer.nvim](https://github.com/wbthomason/packer.nvim) and other git-related plugins. @@ -79,7 +114,7 @@ The version of Git on the Linux system may be too old so that plugins may break. Check [here](https://jdhao.github.io/2021/03/27/upgrade_git_on_linux/) on how to install and set up the latest version of Git. For Windows, install [Git for Windows](https://git-scm.com/download/win) and make sure you can run `git` from command line. -## ctags +### ctags In order to use tags related plugins such as [vista.vim](https://github.com/liuchengxu/vista.vim), we need to install a ctags distribution. Universal-ctags is preferred. @@ -102,7 +137,7 @@ choco install universal-ctags Set its PATH properly and make sure you can run `ctags` from command line. -## Ripgrep +### Ripgrep [Ripgrep](https://github.com/BurntSushi/ripgrep), aka, `rg`, is a fast grepping tool available for both Linux, Windows and macOS. It is used by several searching plugins. @@ -112,7 +147,7 @@ For Linux, we can download the [binary release](https://github.com/BurntSushi/ri Set its PATH properly and make sure you can run `rg` from command line. -## Linters +### 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. @@ -122,35 +157,18 @@ Based on the programming languages we use, we may need to install various linter Set their PATH properly and make sure you can run `pylint`, `flake8` and `vint` from command line. -## Terminal emulators - -Which [terminal emulator](https://en.wikipedia.org/wiki/Terminal_emulator) we choose to use greatly affects the appearance and features of Nvim. -Since Nvim supports true colors, terminals that support true colors are preferred. -For a list of terminals that support true colors, see [here](https://github.com/termstandard/colors). - -For macOS, we can use [kitty](https://sw.kovidgoyal.net/kitty/), [iterm2](https://www.iterm2.com/), [wezterm](https://wezfurlong.org/wezterm/) or [Alacritty](https://github.com/jwilm/alacritty). - -If you ssh to Linux server on Windows, I recommend [wsltty](https://github.com/mintty/wsltty) and [Cygwin](https://www.cygwin.com/), -both of them use [mintty](https://github.com/mintty/mintty) as the terminal emulator. -For the latest version of Windows 10, you can also try [Windows Terminal](https://github.com/microsoft/terminal). - -## Patched Fonts - -Since statusline or file explorer plugins often use Unicode symbols not available in normal font, -we need to install a patched font from the [nerd-fonts](https://github.com/ryanoasis/nerd-fonts) project. - -# Install Nvim +## Install Nvim There are various ways to install Nvim depending on your system. This config is only maintained for [the latest nvim stable release](https://github.com/neovim/neovim/releases/tag/stable). -## Linux +### Linux You can directly download the binary release from [here](https://github.com/neovim/neovim/releases/download/stable/nvim-linux64.tar.gz). You can also use the system package manager to install nvim, but that is not reliable since the latest version may not be available. -## Windows +### Windows You may download from [nvim release](https://github.com/neovim/neovim/releases/download/stable/nvim-win64.zip) from GitHub and manually extract it. @@ -164,7 +182,7 @@ choco install neovim # scoop install neovim ``` -## macOS +### macOS It is recommended to install neovim via [Homebrew](https://brew.sh/) on macOS. Simply run the following command: @@ -175,9 +193,11 @@ brew install neovim After installing Nvim, we need to set the path to nvim correctly. **Make sure that you can run `nvim` from the command line after all these setups**. -# Setting up Nvim +## Setting up Nvim + +After installing nvim and all the dependencies, we will install plugin managers and set up this config. -## Install plugin manager packer.nvim +### Install plugin manager packer.nvim I use packer.nvim to manage my plugins. We need to install packer.nvim on our system first. @@ -193,7 +213,7 @@ For macOS and Linux, run the following command: git clone --depth=1 https://github.com/wbthomason/packer.nvim ~/.local/share/nvim/site/pack/packer/opt/packer.nvim ``` -## How to install this configuration +### How to install this configuration On Linux and macOS, the directory is `~/.config/nvim`. On Windows, the config directory is `$HOME/AppData/Local/nvim`[^1]. @@ -207,18 +227,4 @@ git clone --depth=1 https://github.com/jdhao/nvim-config.git . After that, when we first open nvim, run command `:PackerSync` 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. -# Automatic installation - -## Automatic Installation for Linux # - -To set up a workable Nvim environment on Linux, -I use [a bash script](nvim_setup_linux.sh) to automatically install necessary dependencies, Nvim itself and configs. - -Note that the variable `PYTHON_INSTALLED`, `SYSTEM_PYTHON` and `ADD_TO_SYSTEM_PATH` in the script -should be set properly based on your environment. - -## Automatic installation for Windows - -Run script [nvim_setup_windows.ps1](nvim_setup_windows.ps1) under PowerShell. - [^1]: Use `echo %userprofile%` to see where your `$HOME` is. |