Here is a simple guidance, please read the detail document in the source code.



  • Neovim (MUST)

This configuration is compatible with neovim version v0.7.0-v0.8.0 only.

You can follow neovim installation for the installation guidance.

Install stable version in Arch Linux

If you are Arch Linux user, and you found that there are some bug in the latest version , you can download PKGBUILD file with your aur helper, and then add a prepare script to build stable version:

# Assuming that you are using paru
paru -G neovim-git

Then edit the PKGBUILD file and this lines before the build() function:

+prepare() {
+  cd "${pkgname}"
+  git checkout stable

Finally, run the makepkg -si to install the neovim.

  • Nerdfont (MUST)

Most of my setting are based on nerd font. It’s highly recommended to install nerdfont for impressive icon support.

  • ripgrep (MUST)

The telescope, nvim-cmp, and anyjump plugin are configured to use ripgrep as the search program. It is an faster grep RIIR alternative.

See its readme for more.

Fork before pull

I recommend you use my configuration as a base and build your configuration.

This neovim config is biased and was not created for generic use. The reason I build this configuration is that I don't want to use the same neovim as the community. And it is really tired to always make compatibility for an editor configuration. It will gradually expand the size of the configuration, amount of the bug, and uninteresting of the maintenance.

And I know that someone like me want to build their own configurationt too, but it is hard to start from empty. So you can use my configuration as a base to build yours.


git clone ~/.config/nvim

# Enable configuration for the configuration
mv ~/.config/nvim/lua/custom.example.lua ~/.config/nvim/lua/custom.lua

Open your neovim by command nvim and wait for all plugins installed. The plugins will be installed automatically. Please quit and reopen the neovim to load all the plugins.

If the neovim don’t install plugins automatically, use the command :PackerSync to install those plugins manually. And please open a issue to notify me about the error.

NOTE: Markdown preview plugin is installed in another thread, please wait for it until it response message of installation success. Otherwise, you will find that you can’t activate it.

How to get update

You can rename the default branch to upstream and switch to a new master branch:

# rename master to upstream. Not necessary to be upstream, you can pick whatever you like as branch name.
git branch -m master upstream

# create new branch with name "master". Not necessary to be master too.
git branch master

Working with two different branches, you can always pull or pick new bugfix or feature from my configuration without messing up your configuration.

I will always write changes into CHANGELOG and release a new version after changes are made. Please read the changelog each time you pull new changes. And if you are not satisfied with the changes, you can git checkout the old version. You are also welcome to open an issue to discuss with me. This config is considered as MY personal configuration, and I can't guarantee I will stabilize it as the community do.

Clean up

You need to clean the below directory to do a fresh install.

# plugins directory
rm -rf ~/.local/share/nvim

# neovim cache file
rm -r ~/.cache/nvim

# neovim plugins load sequence
rm -r ~/.config/nvim/plugin

Check health

Open your neovim and input following command to check if the dependence is all installed or not.



Just wanna have a try but do not want to mess up your local environment? I have docker script for you!

docker run -w /root -it --rm alpine:edge sh -uelic '
      apk add git neovim ripgrep alpine-sdk --update
      git clone '' ~/.config/nvim
      nvim -c "autocmd User PackerComplete quitall"
      nvim /root/.config/nvim/

Next Step

See key mappings


Leader key

leader key is set to ;.

Basic movement

<h   l>
h/j/k/lMove around
HGo to the first character of the line
LGo to the last character of the line
JGo down 5 lines
KGo up 5 lines
WGo 5 words forward
BGo 5 words backward

Cursor move in insert mode

Ctrl aAct like Home
Ctrl eAct like End
Ctrl fAct like w in normal mode
Ctrl bAct like b in normal mode

Windows Navigation

;kGo to the window above
;jGo to the window below
;hGo to the right window
;lGo to the left window

Windows resize

Alt UpResize the top border of window
Alt DownResize the bottom border of the window
Alt LeftResize the left border of the window
Alt RightResize the right border of the window
/Forward search
?Backward search
*Search word under cursor
NGo to the before matches
nGo to the following matches
ESCClose the search highlight

Copy and Paste

yCopy to system clipboard
pPaste from the editor register
Ctrl-pPaste from the clipboardIn normal and insert mode

Text move

<Reduce one indent levelIn normal and selection mode
>Increse one indent levelIn normal and selection mode

Save and Quit

;qQuit buffer (Auto quit nvim when last buffer is deleted)
:qQuit neovim, window, tabs
Alt;Leave the insert mode (Same as ESC)Only in insert mode


Ctrl jScroll down
Ctrl kScroll up
Ctrl fLike "PgDown" key, scroll down half a page
Ctrl bLike "PgUp" key, scroll up half a page
Ctrl yScroll up, but cursor will not move
Ctrl eScroll down, but curson will not move


Ctrl-zReverse changes

Next Step


How to use this config

Edit simple file

You can just use command nvim /path/to/file to edit the file.


See customize to learn how to setup the LSP. Then go into your project directory and use command nvim /path/to/source code to open and edit the code.

Write Markdown

Use command nvim /path/to/ to open the markdown file. And their are some commands can enhance your writing experience:

  • :TableModeToggle: Trigger the table edit mode.
  • :MarkdownPreview: Preview the rendered markdown content in your favourite browser. See customize for details.
  • :GenTocGFM: Generate a GitHub favor TOC.


Each folder under lua/ directory has a file to indicate what it is and what plugin it has. You can learn more from there.


You might not want git to track some frequently changed values. Like color scheme or some other settings. Those settings can all define in an optional Lua module.


Rename the lua/custom.example.lua file to lua/custom.lua, then make your modification. The .gitignore file contains the custom.lua file already.

Create a new configuration table and return it at the end.

-- example
local my_config = {
  theme = "kanagawa",

  langs = {
    { "go", "gopls" },
    { { "javascript", "typescript", "javascriptreact", "typescriptreact" }, "eslint" },
        python = {
          analysis = {
            autoSearchPaths = true,
            diagnosticMode = "workspace",
            useLibraryCodeForTypes = true,

  -- configuration for null-ls lsp injection
  null_ls = {
    enable_stylua_fmt = false, -- require stylua executable

  autocmd_enable = {
    fcitx5 = false, -- require fcitx5-remote
    lastline = true,
    diff_on_commit = false, -- might mess up your window

  markdown = {
    -- must be executable
    preview_browser = "chrome",

return my_config -- <- Don't forget to return this table, or the config will not acceive what you configured


Current supported options:

themecolorscheme, read colors for tips and tricks
autocmd_enableList of auto commands that you want to toggle on or off
langsAn array of language layers for nvim-treesitter and lspconfig
markdownMarkdown options


This fields contains an array of language layer definitions.

  • Single string or an array with item tells the editor to load nvim-treesitter only for this languages.

  • An array with two items tells the editor to load both of the nvim-treesitter and lspconfig plugins. And the second items for the multi-items array should be lsp server that you want to enabled.

  • If the array contains three items, the third item will be considered as server configuration and will be transfer to the lsp server.

  • Available Lsp Servers

  • Supported Languages for treesitter

  • Lsp Server Configuration


fcitx5Enable fcitx5 auto toggle when switching insert and normal mode
lastlineEnable auto command that jump to last edit line when you open neovim
diff_on_commitEnable auto command that open diff window when you commiting

Per language configuration snippets


  • Config

C/CPP can be configured to use clangd as default LSP server.

{ { "c", "cpp" }, "clangd" },
  • project setup

The clangd respect your cmake settings. You will need to provide the compile_commands.json file for clangd to identify your project correctly.

$ ln -s Debug/compile_commands.json .
  • Makefile

If you are writing C and using the Makefile, you can use the :Dispatch or :Make command to easily build and debug your code.

  • Resources


Add the below script into lua/custom.lua file.

langs = {
  { { "javascript", "typescript", "javascriptreact", "typescriptreact" }, "tsserver" },

Inject eslint into tsserver by enable the null-ls option:

null_ls = {
  enable_eslint = true, -- require eslint, useful to combine use with tsserver
  enable_prettier = true, -- require prettier, useful when you want format in js/ts{x}

Trouble Shooting

  • Neovim notify that their is no executable in $PATH

Please make sure that you have configured node.js/deno PATH correctly. If you are using node version manager like nvm or other stuff, please make sure you have enabled correct version before you start the neovim.


The plugin rust-tools.nvim has already set up LSP, format, and debug utilities.

See for what it can do.

This plugin will setup lspconfig itself, please don't write lspconfig manually.

  • Inlay hint

The rust-tools.nvim setting is located in lua/plugins/coding/config/rust-tools.lua. And inlay hint is set up automatically after you open rust file.

But it will not prompt up by default due to some unknown bug. It will only show up after you save the buffer. So you need to manually run command :w when you first open the rust code.

  • Code action

You can use the keymap LEADER ra or keymap gx set by LSP to view and select the action for Rust code. Also you can press LEADER rr to run test or function.

  • Code format

You can use gf to run the LSP built in format API. It will called the rustfmt program.

  • Debug

You need to install lldb-vscode. Then run :RustDebuggables, it will open the debug panel automatically.

  • Rust Analyzer Settings

You might want to make some specific rust-analyzer settings for your project. You can create a file with name .rust-analyzer.json in the same directory with the Cargo.toml file. Then put all the configuration you want into it.

Configuration reference:

For example, if you want to enable all feature when editing the code:

# cd to the root directory of your project
echo '{
  "cargo": {
    "allFeatures": true
}' > .rust-analyzer.json
  • Gallery

Please read demo.

Development specifications


This configuration is not gonna follow semver, instead, it use calendar versioning and release new version in each weekend. Version will be released in cvYYYY.0M.0D format.


I've write a Perl script to handle the benchmark.

perl ./fixtures/

It will write result into the ./fixtures/benchmark.txt file.

If any of the commits contains API compatibility changes, we must write them into file for the next version release.


  • Neovim (必要)

目前我使用 v0.7.0-dev+920-g7e2ce35e3。 如果你遇到了任何错误,请检查你的版本。

你可以按照 neovim 安装方式 构建最新版本的 neovim。

如果你是 ArchLinux 用户,你可以运行: yay -S neovim-git

  • Nerdfont (必要)

我的大部分设置都是基于 nerd font 的。强烈建议你安装 nerdfont 来取得很棒的图标支持。

  • ripgrep (必要)

我使用 ripgrep 作为插件 telescope, nvim-cmp, anyjump 的搜索程序。ripgrep 是一个性能更好的grep 替代。

在此查看更多有关信息 readme

  • Surf (可选)

我使用 Surf 作为 Markdown 预览器。用 Firefox 预览 markdown 太重了。如果你有兴趣,可以按照官方说明来更改。没有的话,你也可以使用下列命令简单的替换。

sed -i 's/surf/firefox/g' ./lua/config/mkdp.lua
  • 如何构建surf
# Arch linux 包含了许多有用的库
# 其他发行版需要自己去查看文档
git clone
cd surf
sudo make clean install


# 目前没有 Windows 支持
git clone ~/.config/nvim

使用nvim命令打开你的 neovim,等待所有插件安装完成。当安装完成后,请退出并重新打开以加载所有的插件。

如果 neovim 没有自动安装插件,请使用命令:PackerSync来手动安装这些插件。并请打开一个 issue 来通知我这个错误。

NOTE: Markdown 预览插件已在另一个线程中安装,请等待安装成功的消息。否则插件无法激活。



# 插件目录
rm -rf ~/.local/share/nvim

# neovim 缓存目录
rm -r ~/.cache/nvim

# 重置插件加载顺序
rm -r ~/.config/nvim/plugin

Check health





docker run -w /root -it --rm alpine:edge sh -uelic '
      apk add git neovim ripgrep alpine-sdk --update
      git clone '' ~/.config/nvim
      nvim -c "autocmd User PackerComplete quitall"
      nvim /root/.config/nvim/






你可以在 colors.lua 文件中修改变量 M.theme。 目前,我们有:

  • deus
M.theme = "deus"


  • kanagawa
M.theme = "kanagawa"


  • everforest
M.theme = "everforest"


  • ayu
M.theme = "ayu"


  • gruvbox
M.theme = "gruvbox"




  1. 添加主题插件到 plug.lua。

假设你想要添加的主题名称叫 "nord"。

use {
  cond = function()
    return require("colors").theme == "nord"
  config = function()

你可以阅读 lua/plugins.lua 文件为例。

  1. 在 color.lua 中添加配置
-- select the theme
M.theme = "nord"

M.nord_setup = function()
  -- leave it blank here if you don't have any config
  vim.g.background = "dark"

  -- And don't forget this step, it is the final step to load the theme


Leader key

leader key 设置到了空格键上。


<h l>
J向下移动 5 行
K向上移动 5 行
W向前跳转 5 个单词
B向后跳转 5 个单词




Ctrl-t h跳转到前一个标签页
Ctrl-t l跳转到下一个标签页
Ctrl-t n创建新的标签页

Copy and Paste

y复制到 register
p粘贴到 register

Text move


Save and Quit

; w保存
Alt q关掉缓存页
Alt ;离开插入模式只在插入模式有效


;等同于 ":"


nvim-tree 是一个小窗文件管理器,可以以树形态展示文件。


  • 使用 tt 来启用/关闭 nvim-tree
  • 使用 tr 来刷新 nvim-tree 的文件