rewrite: slimmer, trimmer and more lazy kickstart.nvim (#635)

We've removed over 1/3 of the code that was in kickstart previously,
and more than doubled the amount of comments explaining every line
of code (to the best of my ability).

kickstart now properly uses many of the lazy.nvim config and loading
idioms, which should be really helpful for people moving both to
modular configs, as well as extending the kickstart config in one file.

Additional features:
- Beautiful ascii art
- Added some documentation that explains what is an LSP, what is telescope, etc
- There is now a `:checkhealth` for kickstart, which checks some basic information
  and adds useful information for maintainers (for people cloning the repo).
- Improved LSP configuration and tool installation, for easier first time startup
- Changed init.lua ordering, so that it moves from simple options to complicated config

```
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Lua                              1            108            404            298
-------------------------------------------------------------------------------
```
This commit is contained in:
TJ DeVries 2024-02-26 10:03:53 -05:00 committed by GitHub
parent 7af594fd31
commit 8b5d48a199
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 844 additions and 781 deletions

3
.gitignore vendored
View File

@ -2,3 +2,6 @@ tags
test.sh
.luarc.json
nvim
spell/
lazy-lock.json

158
README.md
View File

@ -1,59 +1,73 @@
# kickstart.nvim
https://github.com/kdheepak/kickstart.nvim/assets/1813121/f3ff9a2b-c31f-44df-a4fa-8a0d7b17cf7b
### Introduction
## Introduction
A starting point for Neovim that is:
* Small
* Single-file (with examples of moving to multi-file)
* Documented
* Modular
* Single-file
* Completely Documented
This repo is meant to be used by **YOU** to begin your Neovim journey; remove the things you don't use and add what you miss.
**NOT** a Neovim distribution, but instead a starting point for your configuration.
Kickstart.nvim targets *only* the latest ['stable'](https://github.com/neovim/neovim/releases/tag/stable) and latest ['nightly'](https://github.com/neovim/neovim/releases/tag/nightly) of Neovim. If you are experiencing issues, please make sure you have the latest versions.
## Installation
Distribution Alternatives:
- [LazyVim](https://www.lazyvim.org/): A delightful distribution maintained by @folke (the author of lazy.nvim, the package manager used here)
### Install Neovim
### Installation
Kickstart.nvim targets *only* the latest
['stable'](https://github.com/neovim/neovim/releases/tag/stable) and latest
['nightly'](https://github.com/neovim/neovim/releases/tag/nightly) of Neovim.
If you are experiencing issues, please make sure you have the latest versions.
### Install External Dependencies
> **NOTE**
> [Backup](#FAQ) your previous configuration (if any exists)
Requirements:
* Make sure to review the readmes of the plugins if you are experiencing errors. In particular:
* [ripgrep](https://github.com/BurntSushi/ripgrep#installation) is required for multiple [telescope](https://github.com/nvim-telescope/telescope.nvim#suggested-dependencies) pickers.
* See [Windows Installation](#Windows-Installation) if you have trouble with `telescope-fzf-native`
External Requirements:
- Basic utils: `git`, `make`, `unzip`, C Compiler (`gcc`)
- [ripgrep](https://github.com/BurntSushi/ripgrep#installation)
- Language Setup:
- If want to write Typescript, you need `npm`
- If want to write Golang, you will need `go`
- etc.
> **NOTE**
> See [Windows Installation](#Windows-Installation) to double check any additional Windows notes
Neovim's configurations are located under the following paths, depending on your OS:
| OS | PATH |
| :- | :--- |
| Linux | `$XDG_CONFIG_HOME/nvim`, `~/.config/nvim` |
| MacOS | `$XDG_CONFIG_HOME/nvim`, `~/.config/nvim` |
| Linux, MacOS | `$XDG_CONFIG_HOME/nvim`, `~/.config/nvim` |
| Windows (cmd)| `%userprofile%\AppData\Local\nvim\` |
| Windows (powershell)| `$env:USERPROFILE\AppData\Local\nvim\` |
Clone kickstart.nvim:
- on Linux and Mac
<details><summary> Linux and Mac </summary>
```sh
git clone https://github.com/nvim-lua/kickstart.nvim.git "${XDG_CONFIG_HOME:-$HOME/.config}"/nvim
```
- on Windows (cmd)
</details>
<details><summary> Windows </summary>
If you're using `cmd.exe`:
```
git clone https://github.com/nvim-lua/kickstart.nvim.git %userprofile%\AppData\Local\nvim\
```
- on Windows (powershell)
If you're using `powershell.exe`
```
git clone https://github.com/nvim-lua/kickstart.nvim.git $env:USERPROFILE\AppData\Local\nvim\
```
</details>
### Post Installation
@ -63,37 +77,33 @@ Start Neovim
nvim
```
The `Lazy` plugin manager will start automatically on the first run and install the configured plugins - as can be seen in the introduction video. After the installation is complete you can press `q` to close the `Lazy` UI and **you are ready to go**! Next time you run nvim `Lazy` will no longer show up.
That's it! Lazy will install all the plugins you have. Use `:Lazy` to view
current plugin status.
If you would prefer to hide this step and run the plugin sync from the command line, you can use:
```sh
nvim --headless "+Lazy! sync" +qa
```
Read through the `init.lua` file in your configuration folder for more
information about extending and exploring Neovim.
### Getting Started
See [Effective Neovim: Instant IDE](https://youtu.be/stqUbv-5u2s), covering the previous version. Note: The install via init.lua is outdated, please follow the install instructions in this file instead. An updated video is coming soon.
See [Effective Neovim: Instant IDE](https://youtu.be/stqUbv-5u2s), covering the
previous version. Note: The install via init.lua is outdated, please follow the
install instructions in this file instead. An updated video is coming soon.
### Recommended Steps
[Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) this repo (so that you have your own copy that you can modify) and then installing you can install to your machine using the methods above.
[Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) this repo
(so that you have your own copy that you can modify) and then installing you
can install to your machine using the methods above.
> **NOTE**
> Your fork's url will be something like this: `https://github.com/<your_github_username>/kickstart.nvim.git`
### Configuration And Extension
#### Examples of adding popularly requested plugins
* Inside of your copy, feel free to modify any file you like! It's your copy!
* Feel free to change any of the default options in `init.lua` to better suit your needs.
* For adding plugins, there are 3 primary options:
* Add new configuration in `lua/custom/plugins/*` files, which will be auto sourced using `lazy.nvim` (uncomment the line importing the `custom/plugins` directory in the `init.lua` file to enable this)
* Modify `init.lua` with additional plugins.
* Include the `lua/kickstart/plugins/*` files in your configuration.
<details>
<summary>Adding autopairs</summary>
You can also merge updates/changes from the repo back into your fork, to keep up-to-date with any changes for the default configuration.
#### Example: Adding an autopairs plugin
This will automatically install [windwp/nvim-autopairs](https://github.com/windwp/nvim-autopairs) and enable it on startup. For more information, see documentation for [lazy.nvim](https://github.com/folke/lazy.nvim).
In the file: `lua/custom/plugins/autopairs.lua`, add:
@ -117,10 +127,11 @@ return {
}
```
</details>
<details>
<summary>Adding a file tree plugin</summary>
This will automatically install [windwp/nvim-autopairs](https://github.com/windwp/nvim-autopairs) and enable it on startup. For more information, see documentation for [lazy.nvim](https://github.com/folke/lazy.nvim).
#### Example: Adding a file tree plugin
This will install the tree plugin and add the command `:Neotree` for you. You can explore the documentation at [neo-tree.nvim](https://github.com/nvim-neo-tree/neo-tree.nvim) for more information.
In the file: `lua/custom/plugins/filetree.lua`, add:
@ -142,23 +153,13 @@ return {
}
```
This will install the tree plugin and add the command `:Neotree` for you. You can explore the documentation at [neo-tree.nvim](https://github.com/nvim-neo-tree/neo-tree.nvim) for more information.
### Contribution
Pull-requests are welcome. The goal of this repo is not to create a Neovim configuration framework, but to offer a starting template that shows, by example, available features in Neovim. Some things that will not be included:
* Custom language server configuration (null-ls templates)
* Theming beyond a default colorscheme necessary for LSP highlight groups
Each PR, especially those which increase the line count, should have a description as to why the PR is necessary.
</details>
### FAQ
* What should I do if I already have a pre-existing neovim configuration?
* You should back it up, then delete all files associated with it.
* This includes your existing init.lua and the neovim files in `~/.local` which can be deleted with `rm -rf ~/.local/share/nvim/`
* You may also want to look at the [migration guide for lazy.nvim](https://github.com/folke/lazy.nvim#-migration-guide)
* Can I keep my existing configuration in parallel to kickstart?
* Yes! You can use [NVIM_APPNAME](https://neovim.io/doc/user/starting.html#%24NVIM_APPNAME)`=nvim-NAME` to maintain multiple configurations. For example you can install the kickstart configuration in `~/.config/nvim-kickstart` and create an alias:
```
@ -191,56 +192,3 @@ This requires:
```lua
{'nvim-telescope/telescope-fzf-native.nvim', build = 'cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release && cmake --build build --config Release && cmake --install build --prefix build' }
```
### Hints And Tips For New Neovimmers
Neovim is a very rich and powerful environment, but it can also feel a bit
intimidating for new users trying to find their way around, especially if
they're coming from other environments like Visual Studio Code or a traditional
IDE.
There's no way this README can provide you with everything you need to know, but
here are a few tips so you can learn how to learn.
### Use The Help, Luke!
Neovim's help system is incredibly thorough and extensive. You should really
take a moment to get comfortable navigating through help topics, going back and
forth, navigating the menus, etc. This won't just help you read the help, it
will empower you in the rest of your Neovim journey.
You can double click on a topic to drill down, and hit Ctrl-o (Hold down the
Control key and the 'o' key) to go back.
Read the first page you get when you run :help carefully. it will serve you
well.
You can also get help on a particular thing by typing ":help <topic>".
Like, let's say we want to learn more about folding, just type ":help folding".
### To The Telescope!
One of the more powerful features you get by installing this project is the
brilliant Telescope plugin co-written by @tjdevries.
Take a minute to browse through ":help telescope" and get a sense for all the
amazing superpowers you've gained.
In particular, there are two Telescope features that are incredible for helping
you understand how to do a particular thing or how to configure a particular
feature.
If you're not sure what to look for, try ":Telescope help_tags". Let's say we
want to configure Neovim to automatically word wrap. We might type ":Telescope
help_tags" and then type w, r, a, p. Notice how the list of results changes with
each new letter you type? When you're done you've got a screen full of topics
involving word wrap.
Another common question is "What keys do I hit to make a thing happen?". To get
an answer, one way is to use ":Telescope keymaps". You'll get the same list of
results that changes to adapt with each new key you press.
With these hints in mind you should be in good shape to get learning. Remember,
you are on a journey of discovery here, adapting your programming environment to
your needs. It will take effort, but the rewards are worth it! :)

1330
init.lua

File diff suppressed because it is too large Load Diff

51
lua/kickstart/health.lua Normal file
View File

@ -0,0 +1,51 @@
--[[
--
-- This file is not required for your own configuration,
-- but helps people determine if their system is setup correctly.
--
--]]
local check_version = function()
if not vim.version.cmp then
vim.health.error(string.format("Neovim out of date: '%s'. Upgrade to latest stable or nightly", tostring(vim.version())))
return
end
if vim.version.cmp(vim.version(), { 0, 9, 4 }) >= 0 then
vim.health.ok(string.format("Neovim version is: '%s'", tostring(vim.version())))
else
vim.health.error(string.format("Neovim out of date: '%s'. Upgrade to latest stable or nightly", tostring(vim.version())))
end
end
local check_external_reqs = function()
-- Basic utils: `git`, `make`, `unzip`
for _, exe in ipairs { 'git', 'make', 'unzip', 'rg' } do
local is_executable = vim.fn.executable(exe) == 1
if is_executable then
vim.health.ok(string.format("Found executable: '%s'", exe))
else
vim.health.warn(string.format("Could not find executable: '%s'", exe))
end
end
return true
end
return {
check = function()
vim.health.start 'kickstart.nvim'
vim.health.info [[NOTE: Not every warning is a 'must-fix' in `:checkhealth`
Fix only warnings for plugins and languages you intend to use.
Mason will give warnings for languages that are not installed.
You do not need to install, unless you want to use those languages!]]
local uv = vim.uv or vim.loop
vim.health.info('System Information: ' .. vim.inspect(uv.os_uname()))
check_version()
check_external_reqs()
end,
}

View File

@ -1,74 +0,0 @@
-- autoformat.lua
--
-- Use your language server to automatically format your code on save.
-- Adds additional commands as well to manage the behavior
return {
'neovim/nvim-lspconfig',
config = function()
-- Switch for controlling whether you want autoformatting.
-- Use :KickstartFormatToggle to toggle autoformatting on or off
local format_is_enabled = true
vim.api.nvim_create_user_command('KickstartFormatToggle', function()
format_is_enabled = not format_is_enabled
print('Setting autoformatting to: ' .. tostring(format_is_enabled))
end, {})
-- Create an augroup that is used for managing our formatting autocmds.
-- We need one augroup per client to make sure that multiple clients
-- can attach to the same buffer without interfering with each other.
local _augroups = {}
local get_augroup = function(client)
if not _augroups[client.id] then
local group_name = 'kickstart-lsp-format-' .. client.name
local id = vim.api.nvim_create_augroup(group_name, { clear = true })
_augroups[client.id] = id
end
return _augroups[client.id]
end
-- Whenever an LSP attaches to a buffer, we will run this function.
--
-- See `:help LspAttach` for more information about this autocmd event.
vim.api.nvim_create_autocmd('LspAttach', {
group = vim.api.nvim_create_augroup('kickstart-lsp-attach-format', { clear = true }),
-- This is where we attach the autoformatting for reasonable clients
callback = function(args)
local client_id = args.data.client_id
local client = vim.lsp.get_client_by_id(client_id)
local bufnr = args.buf
-- Only attach to clients that support document formatting
if not client.server_capabilities.documentFormattingProvider then
return
end
-- Tsserver usually works poorly. Sorry you work with bad languages
-- You can remove this line if you know what you're doing :)
if client.name == 'tsserver' then
return
end
-- Create an autocmd that will run *before* we save the buffer.
-- Run the formatting command for the LSP that has just attached.
vim.api.nvim_create_autocmd('BufWritePre', {
group = get_augroup(client),
buffer = bufnr,
callback = function()
if not format_is_enabled then
return
end
vim.lsp.buf.format {
async = false,
filter = function(c)
return c.id == client.id
end,
}
end,
})
end,
})
end,
}

View File

@ -0,0 +1,9 @@
return {
{ -- Add indentation guides even on blank lines
'lukas-reineke/indent-blankline.nvim',
-- Enable `lukas-reineke/indent-blankline.nvim`
-- See `:help ibl`
main = 'ibl',
opts = {},
},
}