Introduction

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

中文版的更新可能有延迟，请以英文版为主。

• Prerequisites
  • Install stable version in Arch Linux
• Fork before pull
• Installation
• How to get update
• Clean up
• Check health
• Docker

Prerequisites

• 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.

Installation

# NO WINDOWS SUPPORT NOW
git clone https://github.com/YOUR_USER_NAME/nvim ~/.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.

:checkhealth

Docker

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 'https://github.com/Avimitin/nvim' ~/.config/nvim
      nvim -c "autocmd User PackerComplete quitall"
      nvim /root/.config/nvim/README.md
  '

Next Step

See key mappings

Keymap

Leader key

leader key is set to ;.

Navigation

Basic movement

   ^
   k
<h   l>
   j
   V

Cursor move in insert mode

Windows Navigation

Windows resize

Search

Copy and Paste

Text move

Save and Quit

Scrolling

Others

Next Step

concept

How to use this config

Edit simple file

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

Coding

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/xxx.md 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.

Extra

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

Customize

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.

Details

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 = {
    "fish",
    "html",
    "json",
    "toml",
    { "go", "gopls" },
    { { "javascript", "typescript", "javascriptreact", "typescriptreact" }, "eslint" },
    {
      "python",
      "pyright",
      {
        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

Fields

Current supported options:

langs

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

autocmd_enable

Per language configuration snippets

c/cpp

• 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.

$ cmake -H. -BDebug -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=YES
$ 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

• Clangd official site: https://clangd.llvm.org/
• CMake official site: https://cmake.org/

JavaScript/TypeScript

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

langs = {
  "html",
  "css",
  "json",
  { { "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.

rust

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

See https://github.com/simrat39/rust-tools.nvim/ 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: https://rust-analyzer.github.io/manual.html#configuration

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

Versioning

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.

Benchmark

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

perl ./fixtures/benchmark.pl

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

RELEASE.md

If any of the commits contains API compatibility changes, we must write them into RELEASE.md 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 https://git.suckless.org/surf
cd surf
sudo make clean install

安装

# 目前没有 Windows 支持
git clone https://github.com/YOUR_USER_NAME/nvim ~/.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

打开你的neovim，并输入以下命令，检查依赖是否已经全部安装。

:checkhealth

Docker

只是想尝试一下，但不想把你的本地环境搞得一团糟？我为你准备了docker脚本!

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

颜色方案

本节描述了我是如何管理颜色方案的。

配置文件

lua/colors.lua

更改颜色方案

你可以在 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 {
  'somebody/nord',
  cond = function()
    return require("colors").theme == "nord"
  end,
  config = function()
    require("colors").nord_setup()
  end
}

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

2. 在 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
  set_color("nord")
end

键位设置

Leader key

leader key 设置到了空格键上。

移动

  ^
  k
<h l>
  j

搜索

标签页

Copy and Paste

Text move

Save and Quit

Others

nvim-tree.lua

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

键位设置

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