My user config prefs
hyperreal.bsky.moonshadow.dev
1# kickstart.nvim
2
3## Introduction
4
5A starting point for Neovim that is:
6
7* Small
8* Single-file
9* Completely Documented
10
11**NOT** a Neovim distribution, but instead a starting point for your configuration.
12
13## Installation
14
15### Install Neovim
16
17Kickstart.nvim targets *only* the latest
18['stable'](https://github.com/neovim/neovim/releases/tag/stable) and latest
19['nightly'](https://github.com/neovim/neovim/releases/tag/nightly) of Neovim.
20If you are experiencing issues, please make sure you have the latest versions.
21
22### Install External Dependencies
23
24External Requirements:
25- Basic utils: `git`, `make`, `unzip`, C Compiler (`gcc`)
26- [ripgrep](https://github.com/BurntSushi/ripgrep#installation)
27- Clipboard tool (xclip/xsel/win32yank or other depending on the platform)
28- A [Nerd Font](https://www.nerdfonts.com/): optional, provides various icons
29 - if you have it set `vim.g.have_nerd_font` in `init.lua` to true
30- Emoji fonts (Ubuntu only, and only if you want emoji!) `sudo apt install fonts-noto-color-emoji`
31- Language Setup:
32 - If you want to write Typescript, you need `npm`
33 - If you want to write Golang, you will need `go`
34 - etc.
35
36> **NOTE**
37> See [Install Recipes](#Install-Recipes) for additional Windows and Linux specific notes
38> and quick install snippets
39
40### Install Kickstart
41
42> **NOTE**
43> [Backup](#FAQ) your previous configuration (if any exists)
44
45Neovim's configurations are located under the following paths, depending on your OS:
46
47| OS | PATH |
48| :- | :--- |
49| Linux, MacOS | `$XDG_CONFIG_HOME/nvim`, `~/.config/nvim` |
50| Windows (cmd)| `%localappdata%\nvim\` |
51| Windows (powershell)| `$env:LOCALAPPDATA\nvim\` |
52
53#### Recommended Step
54
55[Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) this repo
56so that you have your own copy that you can modify, then install by cloning the
57fork to your machine using one of the commands below, depending on your OS.
58
59> **NOTE**
60> Your fork's URL will be something like this:
61> `https://github.com/<your_github_username>/kickstart.nvim.git`
62
63You likely want to remove `lazy-lock.json` from your fork's `.gitignore` file
64too - it's ignored in the kickstart repo to make maintenance easier, but it's
65[recommended to track it in version control](https://lazy.folke.io/usage/lockfile).
66
67#### Clone kickstart.nvim
68> **NOTE**
69> If following the recommended step above (i.e., forking the repo), replace
70> `nvim-lua` with `<your_github_username>` in the commands below
71
72<details><summary> Linux and Mac </summary>
73
74```sh
75git clone https://github.com/nvim-lua/kickstart.nvim.git "${XDG_CONFIG_HOME:-$HOME/.config}"/nvim
76```
77
78</details>
79
80<details><summary> Windows </summary>
81
82If you're using `cmd.exe`:
83
84```
85git clone https://github.com/nvim-lua/kickstart.nvim.git "%localappdata%\nvim"
86```
87
88If you're using `powershell.exe`
89
90```
91git clone https://github.com/nvim-lua/kickstart.nvim.git "${env:LOCALAPPDATA}\nvim"
92```
93
94</details>
95
96### Post Installation
97
98Start Neovim
99
100```sh
101nvim
102```
103
104That's it! Lazy will install all the plugins you have. Use `:Lazy` to view
105the current plugin status. Hit `q` to close the window.
106
107#### Read The Friendly Documentation
108
109Read through the `init.lua` file in your configuration folder for more
110information about extending and exploring Neovim. That also includes
111examples of adding popularly requested plugins.
112
113> [!NOTE]
114> For more information about a particular plugin check its repository's documentation.
115
116
117### Getting Started
118
119[The Only Video You Need to Get Started with Neovim](https://youtu.be/m8C0Cq9Uv9o)
120
121### FAQ
122
123* What should I do if I already have a pre-existing Neovim configuration?
124 * You should back it up and then delete all associated files.
125 * This includes your existing init.lua and the Neovim files in `~/.local`
126 which can be deleted with `rm -rf ~/.local/share/nvim/`
127* Can I keep my existing configuration in parallel to kickstart?
128 * Yes! You can use [NVIM_APPNAME](https://neovim.io/doc/user/starting.html#%24NVIM_APPNAME)`=nvim-NAME`
129 to maintain multiple configurations. For example, you can install the kickstart
130 configuration in `~/.config/nvim-kickstart` and create an alias:
131 ```
132 alias nvim-kickstart='NVIM_APPNAME="nvim-kickstart" nvim'
133 ```
134 When you run Neovim using `nvim-kickstart` alias it will use the alternative
135 config directory and the matching local directory
136 `~/.local/share/nvim-kickstart`. You can apply this approach to any Neovim
137 distribution that you would like to try out.
138* What if I want to "uninstall" this configuration:
139 * See [lazy.nvim uninstall](https://lazy.folke.io/usage#-uninstalling) information
140* Why is the kickstart `init.lua` a single file? Wouldn't it make sense to split it into multiple files?
141 * The main purpose of kickstart is to serve as a teaching tool and a reference
142 configuration that someone can easily use to `git clone` as a basis for their own.
143 As you progress in learning Neovim and Lua, you might consider splitting `init.lua`
144 into smaller parts. A fork of kickstart that does this while maintaining the
145 same functionality is available here:
146 * [kickstart-modular.nvim](https://github.com/dam9000/kickstart-modular.nvim)
147 * Discussions on this topic can be found here:
148 * [Restructure the configuration](https://github.com/nvim-lua/kickstart.nvim/issues/218)
149 * [Reorganize init.lua into a multi-file setup](https://github.com/nvim-lua/kickstart.nvim/pull/473)
150
151### Install Recipes
152
153Below you can find OS specific install instructions for Neovim and dependencies.
154
155After installing all the dependencies continue with the [Install Kickstart](#Install-Kickstart) step.
156
157#### Windows Installation
158
159<details><summary>Windows with Microsoft C++ Build Tools and CMake</summary>
160Installation may require installing build tools and updating the run command for `telescope-fzf-native`
161
162See `telescope-fzf-native` documentation for [more details](https://github.com/nvim-telescope/telescope-fzf-native.nvim#installation)
163
164This requires:
165
166- Install CMake and the Microsoft C++ Build Tools on Windows
167
168```lua
169{'nvim-telescope/telescope-fzf-native.nvim', build = 'cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release && cmake --build build --config Release && cmake --install build --prefix build' }
170```
171</details>
172<details><summary>Windows with gcc/make using chocolatey</summary>
173Alternatively, one can install gcc and make which don't require changing the config,
174the easiest way is to use choco:
175
1761. install [chocolatey](https://chocolatey.org/install)
177either follow the instructions on the page or use winget,
178run in cmd as **admin**:
179```
180winget install --accept-source-agreements chocolatey.chocolatey
181```
182
1832. install all requirements using choco, exit the previous cmd and
184open a new one so that choco path is set, and run in cmd as **admin**:
185```
186choco install -y neovim git ripgrep wget fd unzip gzip mingw make
187```
188</details>
189<details><summary>WSL (Windows Subsystem for Linux)</summary>
190
191```
192wsl --install
193wsl
194sudo add-apt-repository ppa:neovim-ppa/unstable -y
195sudo apt update
196sudo apt install make gcc ripgrep unzip git xclip neovim
197```
198</details>
199
200#### Linux Install
201<details><summary>Ubuntu Install Steps</summary>
202
203```
204sudo add-apt-repository ppa:neovim-ppa/unstable -y
205sudo apt update
206sudo apt install make gcc ripgrep unzip git xclip neovim
207```
208</details>
209<details><summary>Debian Install Steps</summary>
210
211```
212sudo apt update
213sudo apt install make gcc ripgrep unzip git xclip curl
214
215# Now we install nvim
216curl -LO https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.tar.gz
217sudo rm -rf /opt/nvim-linux-x86_64
218sudo mkdir -p /opt/nvim-linux-x86_64
219sudo chmod a+rX /opt/nvim-linux-x86_64
220sudo tar -C /opt -xzf nvim-linux-x86_64.tar.gz
221
222# make it available in /usr/local/bin, distro installs to /usr/bin
223sudo ln -sf /opt/nvim-linux-x86_64/bin/nvim /usr/local/bin/
224```
225</details>
226<details><summary>Fedora Install Steps</summary>
227
228```
229sudo dnf install -y gcc make git ripgrep fd-find unzip neovim
230```
231</details>
232
233<details><summary>Arch Install Steps</summary>
234
235```
236sudo pacman -S --noconfirm --needed gcc make git ripgrep fd unzip neovim
237```
238</details>
239