From 8b5d48a199c02658e399f5b43ff8d06df1ede7fb Mon Sep 17 00:00:00 2001 From: TJ DeVries Date: Mon, 26 Feb 2024 10:03:53 -0500 Subject: 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 ------------------------------------------------------------------------------- ``` --- README.md | 158 +++++++++++++++++++++----------------------------------------- 1 file changed, 53 insertions(+), 105 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index b7fe337..c9b9d84 100644 --- a/README.md +++ b/README.md @@ -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 + +**NOT** a Neovim distribution, but instead a starting point for your configuration. -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. +## 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 Neovim -Distribution Alternatives: -- [LazyVim](https://www.lazyvim.org/): A delightful distribution maintained by @folke (the author of lazy.nvim, the package manager used here) +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 +### 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 +
Linux and Mac + ```sh git clone https://github.com/nvim-lua/kickstart.nvim.git "${XDG_CONFIG_HOME:-$HOME/.config}"/nvim ``` -- on Windows (cmd) +
+ +
Windows + +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\ ``` +
### 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//kickstart.nvim.git` -### Configuration And Extension - -* 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. +#### Examples of adding popularly requested plugins -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. +
+ Adding autopairs -#### 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 { } ``` +
+
+ Adding a file tree 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). - -#### 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. +
### 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 ". - -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! :) -- cgit v1.2.3