diff --git a/Home.md b/Home.md index ea2508d..416ddc6 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,729 @@ -Welcome to the LunarVim wiki! +![LunarVim Demo](./utils/media/lunarvim_logo_dark.png) + +
+ +![LunarVim Demo](./utils/media/demo.png) + +# Table of contents + +- [What’s included?](#whats-included) + * [Why do I want tree-sitter and LSP?](#why-do-i-want-tree-sitter-and-lsp) +- [Project Goals](#project-goals) +- [Install In One Command!](#install-in-one-command) + * [Get the latest version of Neovim](#get-the-latest-version-of-neovim) + * [Manual Install](#manual-install) + * [Troubleshooting installation + problems](#troubleshooting-installation-problems) +- [Getting started](#getting-started) + * [Home screen](#home-screen) + * [Leader and Whichkey](#leader-and-whichkey) + * [Important Configuration files](#important-configuration-files) +- [Install your own plugins](#install-your-own-plugins) + * [An example installation of the colorizer plugin](#an-example-installation-of-the-colorizer-plugin) + * [Finding plugins](#finding-plugins) +- [Using Packer](#using-packer) + * [Packer commands](#packer-commands) + * [Packer reports missing plugins](#packer-reports-missing-plugins) +- [Clipboard Support](#clipboard-support) +- [LSP](#lsp) + * [Lsp errors](#lsp-errors) + + [Understanding LspInfo](#understanding-lspinfo) + + [Example configurations](#example-configurations) + * [Last resort](#last-resort) +- [Useful Programs](#useful-programs) +- [EFM server](#efm-server) +- [Formatters and Linters](#formatters-and-linters) +- [De-bugging](#de-bugging) +- [VSCodium](#vscodium) +- [Color Schemes](#color-schemes) + * [Available colorschemes](#available-colorschemes) + * [Switching colors](#switching-colors) +- [Useful commands for + troubleshooting](#useful-commands-for-troubleshooting) +- [Uninstalling](#uninstalling) +- [Community links](#community-links) +- [TODO](#todo) + +# What’s included? + +LunarVim provides neovim configuration files that take advantage of +tree-sitter and language server protocol. The configuration is written +in lua. + +## Why do I want tree-sitter and LSP? + +- Normally, an editor uses regular expression parsing for things like + highlighting and checking the syntax of your file. Each time you make + a change, the editor must re-parse the entire file. Tree-sitter, on + the other hand, transforms text into a syntax tree. Each time you make + a change, only the parts of the code that change need to be parsed. + This greatly improves the speed of parsing. This can make a huge + difference when editing large files. + +- Neovim 0.5 including language server protocol means your editor can + provide: code actions, completions, formatting, navigating to + definitions, renaming, etc. The language server only has to be written + once and will work on any editor that supports LSP. Any improvements + made to the language server will immediately be used by all editors + that support LSP. + +# Project Goals + +- This project aims to help one transition away from VSCode, and into a + superior text editing experience. (Just making this clear) + +- This is also a community project, if you would like to see support for + a feature or + [language](https://github.com/neovim/nvim-lspconfig/blob/master/CONFIG.md) + consider making a PR. + +- This project will do it’s best to include core features you would + expect from a modern IDE, while making it easy to add or remove what + the user wants. + +# Install In One Command! + +Make sure you have the newest version of Neovim (0.5). + +``` bash +bash <(curl -s https://raw.githubusercontent.com/ChristianChiarulli/lunarvim/master/utils/installer/install.sh) +``` + +After installation run `nvim` and then `:PackerInstall` + +## Get the latest version of Neovim + +Some operating systems package versions of Neovim 0.5. You can install +those or you can follow the steps below to compile from source. +Compiling from source is the recommended method. + +First, get the dependencies. For distributions other than Ubuntu or Arch +go +[here](https://github.com/neovim/neovim/wiki/Building-Neovim#build-prerequisites) + +``` bash +#Ubuntu +sudo apt-get install gettext libtool libtool-bin autoconf automake cmake g++ pkg-config unzip build-essential +#Arch +sudo pacman -S base-devel cmake unzip ninja tree-sitter +``` + +Download and compile Neovim + +``` bash +cd $(mktemp -d) +git clone https://github.com/neovim/neovim --depth 1 +cd neovim +sudo make CMAKE_BUILD_TYPE=Release install +cd .. +sudo rm -r neovim +``` + +or if you are on Arch you can get it from the AUR + +``` bash +yay -S neovim-git +``` + + +If you are on Gentoo you have to emerge the 9999 neovim version with luajit as the lua single target + +## Manual install + +First make sure you have version [0.5 of +neovim](#get-the-latest-version-of-neovim). + +Back up your current configuration files + +```bash +mv ~/.config/nvim ~/.config/nvim.bak +``` + +Install xclip, python3, ripgrep, fzf, npm, nodejs, pip, and ranger with the package manager for your distribution. + +```bash +# Ubuntu +sudo apt install xclip python3-pip nodejs npm ripgrep fzf ranger libjpeg8-dev zlib1g-dev python-dev python3-dev libxtst-dev python3-pip + +# Arch +sudo pacman -S xclip python python-pip nodejs npm ripgrep fzf ranger + +# Fedora +sudo dnf groupinstall "X Software Development" +sudo dnf install -y xclip python3-devel pip nodejs npm ripgrep fzf ranger +pip3 install wheel ueberzug + +# Gentoo +sudo emerge -avn sys-apps/ripgrep app-shells/fzf app-misc/ranger dev-python/neovim-remote virtual/jpeg sys-libs/zlib +sudo emerge -avn dev-python/pip +# Optional. Enable npm USE flag with flaggie +sudo flaggie net-libs/nodejs +npm +sudo emerge -avnN net-libs/nodejs + +# Mac +brew install lua node yarn ripgrep fzf ranger +sudo curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py +python3 get-pip.py +rm get-pip.py +``` + +Install tree-sitter. To globally install packages without the need for sudo +follow [this guide](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) + +```bash +npm install -g tree-sitter-cli +``` + +Install ueberzug, neovim-remote, and pynvim with pip3 + +```bash +pip3 install ueberzug neovim neovim-remote pynvim --user +``` + +Clone LunarVim and Packer + +```bash +git clone https://github.com/wbthomason/packer.nvim ~/.local/share/nvim/site/pack/packer/start/packer.nvim +git clone https://github.com/ChristianChiarulli/lunarvim.git ~/.config/nvim +``` + +Install plugins +``` +nvim -u $HOME/.config/nvim/init.lua +PackerInstall +``` + +## Troubleshooting installation problems +If you encounter problems with the installation check the following: +1. Make sure you have at least version 0.5 of neovim. +2. Make sure neovim was compiled with luajit. + ```bash + # The output of version information should include a line for: LuaJIT + nvim -v + ``` +3. If you ran the [quick-install script](#install-in-one-command) using sudo, follow the steps to [uninstall](#uninstalling) and try again without sudo. +4. Make sure the [dependencies](#useful-programs) were installed. +5. Make sure your plugins are installed and updated. Run :PackerSync + +# Getting started + +## Home screen + +The home screen is a plugin called +[Dashboard](https://github.com/glepnir/dashboard-nvim). It uses the +[Telescope](https://github.com/nvim-telescope/telescope.nvim) plugin to +find files or find words within files. The home screen provides a link +to load saved Sessions. The home screen links to the settings file +located at this path: \~/.config/nvim/lv-settings.lua + +## Leader and Whichkey + +The default leader key is set to <Space>. Pressing it will also +open up [Whichkey](https://github.com/folke/which-key.nvim). Whichkey +will help you easily access many of the default keybindings. Whichkey +defines keymappings in this file: +\~/.config/nvim/lua/lv-which-key/init.lua + +## Other key bindings + +Other key bindings can be found in \~/.config/nvim/lua/keymappings.lua + +If you already have a set of keybindings in vimscript that you prefer, +source your vimscript file from \~/.config/nvim/init.lua + +Example: + +``` lua +vim.cmd('source ~/.config/nvim/vimscript/keymappings.vim') +``` + +Or you can translate your old bindings to lua and keep them in the +provided keymappings file. Follow the lua guide available +[here](https://github.com/nanotee/nvim-lua-guide) + +## Important Configuration files + +| Path | Description | +|-------------------------------------|----------------------------| +| \~/.config/nvim/lv-settings.lua | The main settings file | +| \~/.config/nvim/lua/keymappings.lua | Key bindings | +| \~/.config/nvim/lua/plugins.lua | Add or remove plugins here | + +# Install your own plugins + +The steps for configuring your own plugin are: +1. Add the plugin to `plugins.lua` +2. If the plugin requires configuration, create a configuration file for it +3. If you created a configuration, require the file in `init.lua` +4. Use Packer to download and install the plugin + +Please note that every plugin will require different configuration steps. +Follow the instructions provided by the README of plugin you're interested in. If +those instructions are written in lua, copy and paste the code they provide. +If the instructions are written in vimscript, either translate the code to +lua or wrap the vimscript in this lua function: + +```lua +vim.cmd([[ +YOUR_VIMSCRIPT_GOES_HERE +]]) +``` + +## An example installation of the colorizer plugin + +'use' is a function provided by the Packer plugin. In the example below, +we tell Packer to optionally load the plugin. This means the plugin will not +start unless some other function manually loads it. + +The 'require_plugin' function is part of LunarVim. It loads the plugin. + +``` lua +# ~/.config/nvim/lua/plugins.lua +use {"norcalli/nvim-colorizer.lua", opt = true} +require_plugin("nvim-colorizer.lua") +``` + +From the [ README ](https://github.com/norcalli/nvim-colorizer.lua) we find out [ Colorizer ](https://github.com/norcalli/nvim-colorizer.lua) is written and configured in lua. +Colorizer provides a setup function which must be called for the plugin to work correctly. So we create a folder 'lv-colorizer' and +a file 'init.lua'. And populate the file with the configuration mentioned in the +[ README ](https://github.com/norcalli/nvim-colorizer.lua) + + +``` lua +# ~/.config/nvim/lua/lv-colorizer/init.lua +require'colorizer'.setup() +``` + +We created the lua/lv-colorizer/init.lua file. Creating this file means that we've created a module. Now we need to make sure this module +gets loaded when we start neovim. 'require' is a lua function that loads +a module. + +``` lua +# ~/.config/nvim/init.lua +require('lv-colorizer') +``` + +``` lua +:PackerCompile +:PackerInstall +``` + +The example above loads the plugin when neovim starts. If you want to take advantage of Packer's built-in lazy loading, do not use the 'require_plugin' function. Instead, define the loading strategy in Packer's 'use' method. For a more in-depth explantion, read the [Packer docs](https://github.com/wbthomason/packer.nvim) + +## Finding plugins + +If you want to find other plugins that take advantage of neovim’s latest +features go [here](https://github.com/rockerBOO/awesome-neovim) + +# Using Packer + +[Packer](https://github.com/wbthomason/packer.nvim) manages your +installed plugins. Any time you make changes to your list of plugins in +\~/.config/nvim/lua/plugins.lua you must first run the command +:PackerCompile then :PackerInstall. \#\# Packer commands + +``` bash +-- You must run this or `PackerSync` whenever you make changes to your plugin configuration +:PackerCompile + +-- Only install missing plugins +:PackerInstall + +-- Update and install plugins +:PackerUpdate + +-- Remove any disabled or unused plugins +:PackerClean + +-- Performs `PackerClean` and then `PackerUpdate` +:PackerSync + +-- View the status of your plugins +:PackerStatus +``` + +## Packer reports missing plugins + +If you get an error message about missing plugins and the above commands +do not work, remove the plugin directory and reinstall from scratch. + +``` bash +rm -rf ~/.local/share/nvim/site +:PackerCompile +:PackerInstall +``` + +# Clipboard Support + +- On Mac `pbcopy` should be built-in + +- Ubuntu + + ```bash + sudo apt install xclip + ``` + +- Arch + + ```bash + sudo pacman -S xclip + ``` + +- WSL2 + + Make sure ~/bin is in your path in this case. + + ```bash + curl -sLo/tmp/win32yank.zip https://github.com/equalsraf/win32yank/releases/download/v0.0.4/win32yank-x64.zip + unzip -p /tmp/win32yank.zip win32yank.exe > /tmp/win32yank.exe + chmod +x /tmp/win32yank.exe + mv /tmp/win32yank.exe ~/bin + ``` + +# LSP + +Neovim comes bundled with a language client but not a language server. +To install a supported language server: + +``` md + :LspInstall