summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md114
1 files changed, 80 insertions, 34 deletions
diff --git a/README.md b/README.md
index 4cc00b1..32f58df 100644
--- a/README.md
+++ b/README.md
@@ -1,64 +1,91 @@
+# kickstart.nvim
+
### Introduction
A starting point for Neovim that is:
-* Small (<500 lines)
-* Single-file
+* Small
+* Single-file (with examples of moving to multi-file)
* Documented
* Modular
-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.
+This repo is meant to be used as by **YOU** to begin your Neovim journey; remove the things you don't use and add what you miss.
-This repo is meant to be used as a starting point for a user's own configuration; remove the things you don't use and add what you miss. Please refrain from leaving comments about enabling / disabling particular languages out of the box.
+Distribution Alternatives:
+- [LazyVim](https://www.lazyvim.org/): A delightful distribution maintained by @folke (the author of lazy.nvim, the package manager used here)
### 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.
+
* Backup your previous configuration
-* Copy and paste the kickstart.nvim `init.lua` into `$HOME/.config/nvim/init.lua` (Linux) or `~/AppData/Local/nvim/init.lua` (Windows)
-* Start Neovim (`nvim`) and run `:PackerInstall` - ignore any error message about missing plugins, `:PackerInstall` will fix that shortly
+* (Recommended) Fork this repo (so that you have your own copy that you can modify).
+* Clone the kickstart repo into `$HOME/.config/nvim/` (Linux/Mac) or `~/AppData/Local/nvim/` (Windows)
+ * If you don't want to include it as a git repo, you can just clone it and then move the files to this location
+* Start Neovim (`nvim`) and allow `lazy.nvim` to complete installation.
* Restart Neovim
+* **You're ready to go!**
+Additional system 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 as well [Windows Installation](#Windows-Installation)
-If there are languages that you don't want to use, remove their configuration and notes from your `init.lua` after copy and pasting (for example, in the mason configuration).
+### Configuration And Extension
-### Windows Installation
-
-Installation may require installing build tools, and updating the run command for `telescope-fzf-native`
+* Inside of your fork, feel free to modify any file you like! It's your fork!
+* Then there are two primary configuration options available:
+ * Include the `lua/kickstart/plugins/*` files in your configuration.
+ * Add new configuration in `lua/custom/plugins/*` files, which will be auto sourced using `lazy.nvim`
+ * NOTE: To enable this, you need to uncomment `{ import = 'custom.plugins' }` in your `init.lua`
-See `telescope-fzf-native` documention for [more details](https://github.com/nvim-telescope/telescope-fzf-native.nvim#installation)
+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
-This requires:
+#### Example: Adding an autopairs plugin
-- Install CMake, and the Microsoft C++ Build Tools on Windows
+In the file: `lua/custom/plugins/autopairs.lua`, add:
```lua
-use {'nvim-telescope/telescope-fzf-native.nvim', run = 'cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release && cmake --build build --config Release && cmake --install build --prefix build' }
+-- File: lua/custom/plugins/autopairs.lua
+
+return {
+ "windwp/nvim-autopairs",
+ config = function()
+ require("nvim-autopairs").setup {}
+ end,
+}
```
-### Configuration
-You could directly modify the `init.lua` file with your personal customizations. This option is the most straightforward, but if you update your config from this repo, you may need to reapply your changes.
+This will automatically install `nvim-autopairs` and enable it on startup. For more information, see documentation for [lazy.nvim](https://github.com/folke/lazy.nvim).
-An alternative approach is to create a separate `custom.plugins` module to register your own plugins. In addition, you can handle further customizations in the `/after/plugin/` directory (see `:help load-plugins`). See the following examples for more information. Leveraging this technique should make upgrading to a newer version of this repo easier.
+#### Example: Adding a file tree plugin
-#### Example `plugins.lua`
-
-The following is an example of a `plugins.lua` module (located at `$HOME/.config/nvim/lua/custom/plugins.lua`) where you can register your own plugins.
+In the file: `lua/custom/plugins/filetree.lua`, add:
```lua
-return function(use)
- use({
- "folke/which-key.nvim",
- config = function()
- require("which-key").setup({})
- end
- })
-end
+return {
+ "nvim-neo-tree/neo-tree.nvim",
+ version = "*",
+ dependencies = {
+ "nvim-lua/plenary.nvim",
+ "nvim-tree/nvim-web-devicons", -- not strictly required, but recommended
+ "MunifTanjim/nui.nvim",
+ },
+ config = function ()
+ -- Unless you are still migrating, remove the deprecated commands from v1.x
+ vim.cmd([[ let g:neo_tree_remove_legacy_commands = 1 ]])
+
+ require('neo-tree').setup {}
+ end,
+}
```
-#### Example `defaults.lua`
+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.
+
+#### Example: Adding a file to change default options
-For further customizations, you can add a file in the `/after/plugin/` folder (see `:help load-plugins`) to include your own options, keymaps, autogroups, and more. The following is an example `defaults.lua` file (located at `$HOME/.config/nvim/after/plugin/defaults.lua`).
+To change default options, you can add a file in the `/after/plugin/` folder (see `:help load-plugins`) to include your own options, keymaps, autogroups, and more. The following is an example `defaults.lua` file (located at `$HOME/.config/nvim/after/plugin/defaults.lua`).
```lua
vim.opt.relativenumber = true
@@ -72,13 +99,32 @@ Pull-requests are welcome. The goal of this repo is not to create a Neovim confi
* Custom language server configuration (null-ls templates)
* Theming beyond a default colorscheme necessary for LSP highlight groups
-* Lazy-loading. Kickstart.nvim should start within 40 ms on modern hardware. Please profile and contribute to upstream plugins to optimize startup time instead.
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/`
+* 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)
+* What if I want to "uninstall" this configuration:
+ * See [lazy.nvim uninstall](https://github.com/folke/lazy.nvim#-uninstalling) information
+* Are there any cool videos about this plugin?
+ * Current iteration of kickstart (coming soon)
+ * Here is one about the previous iteration of kickstart: [video introduction to Kickstart.nvim](https://youtu.be/stqUbv-5u2s).
+
+### Windows Installation
+
+Installation may require installing build tools, and updating the run command for `telescope-fzf-native`
+
+See `telescope-fzf-native` documention for [more details](https://github.com/nvim-telescope/telescope-fzf-native.nvim#installation)
+
+This requires:
+
+- Install CMake, and the Microsoft C++ Build Tools on Windows
+
+```lua
+use {'nvim-telescope/telescope-fzf-native.nvim', run = 'cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release && cmake --build build --config Release && cmake --install build --prefix build' }
+```