From c624ed7a10086ce5ed5a8b15b4da9e5019560541 Mon Sep 17 00:00:00 2001 From: Steven Spencer Date: Wed, 31 Aug 2022 12:42:42 -0500 Subject: [PATCH] Editing Passes - NvChad book * checked and fixed spelling issues * fixed sentence structure issues and simplified some sentences * checked accuracy within my own NvChad environment * checked formatting and readability * fixed meta tags where necessary * tried to make command structure consistent throughout and more understandable --- docs/books/nvchad/additional_software.md | 6 +-- docs/books/nvchad/custom/chadrc_lua.md | 21 ++++---- docs/books/nvchad/custom/custom_folder.md | 27 +++++----- docs/books/nvchad/custom/init_lua.md | 15 +++--- docs/books/nvchad/custom/lsp.md | 18 +++---- docs/books/nvchad/custom/mappings_lua.md | 24 +++++---- docs/books/nvchad/custom/override_lua.md | 17 +++--- docs/books/nvchad/custom/plugins/init_lua.md | 23 ++++---- .../nvchad/custom/plugins/lspconfig_lua.md | 21 ++++---- docs/books/nvchad/index.md | 22 ++++---- docs/books/nvchad/install_nvchad.md | 28 +++++----- docs/books/nvchad/install_nvim.md | 31 +++++------ docs/books/nvchad/nerd_fonts.md | 10 ++-- .../books/nvchad/nvchad_ui/builtin_plugins.md | 25 ++++----- docs/books/nvchad/nvchad_ui/nvchad_ui.md | 46 +++++++++------- docs/books/nvchad/nvchad_ui/using_nvchad.md | 53 +++++++++++-------- 16 files changed, 218 insertions(+), 169 deletions(-) diff --git a/docs/books/nvchad/additional_software.md b/docs/books/nvchad/additional_software.md index ba3104d0fc..0c2040d669 100644 --- a/docs/books/nvchad/additional_software.md +++ b/docs/books/nvchad/additional_software.md @@ -2,7 +2,7 @@ title: Additional Software author: Franco Colussi contributors: Steven Spencer -tested with: 9.0 +tested with: 8.6, 9.0 tags: - nvchad - coding @@ -47,7 +47,7 @@ RipGrep is needed for recursive searches with `:Telescope`. ## Lazygit -[LazyGit](https://github.com/jesseduffield/lazygit) is an ncurses-style interface that allows you to perform all `git` operations in a more user-friendly way, it is required by the _lazygit.nvim_ plugin, this plugin makes it possible to use LazyGit directly from NvChad, it opens a floating window from where you can perform all operations on your repositories, thus allowing you to make all changes to the _git repository_ without leaving the editor. +[LazyGit](https://github.com/jesseduffield/lazygit) is an ncurses-style interface that allows you to perform all `git` operations in a more user-friendly way. It is required by the _lazygit.nvim_ plugin. This plugin makes it possible to use LazyGit directly from NvChad, it opens a floating window from where you can perform all operations on your repositories, thus allowing you to make all changes to the _git repository_ without leaving the editor. To install it we can use the repository for Fedora. On Rocky Linux 9 it works perfectly. @@ -64,4 +64,4 @@ with the x key we can bring up the menu with all available commands. ![LazyGit UI](images/lazygit_menu.png) -Now that we have all the necessary supporting software on our system we can move on to installing the basic software, the editor on which all the configuration is based, [Neovim](install_nvim.md). +Now that we have all the necessary supporting software on our system we can move on to installing the basic software. We will start with the editor on which all the configuration is based, [Neovim](install_nvim.md). diff --git a/docs/books/nvchad/custom/chadrc_lua.md b/docs/books/nvchad/custom/chadrc_lua.md index 04d3233d78..d749d1f305 100644 --- a/docs/books/nvchad/custom/chadrc_lua.md +++ b/docs/books/nvchad/custom/chadrc_lua.md @@ -1,16 +1,19 @@ --- -title: WIP - chadrc.lua +title: chadrc.lua +author: Franco Colussi +contributors: Steven Spencer +tested with: 8.6, 9.0 tags: - nvhad - coding - editor --- -# chadrc.lua +# `chadrc.lua` -The chadrc.lua file in our `custom` folder contains information about where NvChad should look for additional configurations and personal plugins. +The `chadrc.lua` file in our `custom` folder contains information about where NvChad should look for additional configurations and personal plugins. -Special attention must be paid to the file hierarchy as there may be multiple files with the same name (see *init.lua*) but in different locations, the location is what determines the order in which the files are included in the configuration. Respectively `core` -> `custom` -> `plugins`. +Special attention must be paid to the file hierarchy, as there may be multiple files with the same name (see *init.lua*) but in different locations. The location is what determines the order in which the files are included in the configuration. That order is `core` -> `custom` -> `plugins`. The contents of the `chadrc.lua` file are as follows: @@ -37,16 +40,16 @@ M.plugins = { return M ``` -The first call you encounter refers to the inclusion of our *custom/override.lua* file containing the custom settings for the plugins in the *override* table defined in `M.plugins`, in particular the customizations refer to the state of the files with respect to a Git *repository* (if you are working with one), the automatic installation of *treesitter parsers* and the exclusion of the reference lines of nested routines and commands, this functionality in writing documentation in Markdown is not that important, in case you want to have this functionality as well just remove the line: +The first call you encounter refers to the inclusion of our `custom/override.lua` file containing the custom settings for the plugins in the *override* table defined in `M.plugins`. In particular, the customizations refer to the state of the files with respect to a Git *repository* (if you are working with one), the automatic installation of *treesitter parsers*, and the exclusion of the reference lines of nested routines and commands. This functionality in writing documentation in Markdown is not that important. If you want to have this functionality as well, just remove the line: ```lua ["lukas-reineke/indent-blankline.nvim"] = override.blankline, ``` -And perform a `:PackerSync`. +And perform a SHIFT + :PackerSync from NORMAL mode in the editor. -Then follows the configuration of the default theme with its clear variant and next the `require` call of the *custom/mapping.lua* file that contains the custom commands. +Then follows the configuration of the default theme with its clear variant, followed by the `require` call of the `custom/mapping.lua` file that contains the custom commands. -We then find settings that call up personal configuration files (contained in *custom/plugins*) that will replace the default settings. +Finally, we find settings that call up personal configuration files (contained in *custom/plugins*) that will replace the default settings. -So we can say that the *chadrc.lua* file is the file that takes care of some aspects of the UI and more importantly to include our files in the NvChad configuration. +So we can say that the `chadrc.lua` file is the file that takes care of some aspects of the UI, and more importantly, the inclusion of *our* files in the NvChad configuration. diff --git a/docs/books/nvchad/custom/custom_folder.md b/docs/books/nvchad/custom/custom_folder.md index 101f35d1f3..e79e18b28e 100644 --- a/docs/books/nvchad/custom/custom_folder.md +++ b/docs/books/nvchad/custom/custom_folder.md @@ -1,15 +1,19 @@ --- -title: WIP -Custom Folder +title: Custom Folder +author: Franco Colussi +contributors: Steven Spencer +tested with: 8.6, 9.0 tags: - nvchad - coding + - custom --- # Advanced configuration of the Custom Folder ## Introduction -NvChad uses the version manager `git` for updates, this implies that at every update part or the whole configuration is overwritten by new commits, consequently it would be useless to make customizations within the default configuration. To solve this problem the NvChad developers have set up the possibility to make your changes in a folder called `custom` which must be mandatorily placed in `.config/nvim/lua/`. Below we have a representation of the basic structure of a standard NvChad installation +NvChad uses the version manager `git` for updates. This implies that at every update, part or the whole configuration is overwritten by new commits. Consequently it would be useless to make customizations within the default configuration. To solve this problem the NvChad developers have set up the possibility to make your changes in a folder called `custom` which **must** be placed in `.config/nvim/lua/`. Below we have a representation of the basic structure of a standard NvChad installation. ```text nvim/ @@ -27,7 +31,7 @@ nvim/ ### Structure Creation -To start the customization we have to create for first the `custom` folder that will contain all our files, let's take the opportunity to also create the `plugins` folder that will contain the _configuration files_ of our plugins, since surely the folders will not be present we will use the `-p` flag to tell the _mkdir_ command to create the missing folders, the command will be as follows: +To start the customization we have to create the `custom` folder that will contain all our files and also the `plugins` folder that will contain the _configuration files_ of our plugins. Since the folders will not be present, we will use the `-p` flag to tell the `mkdir` command to create the missing folders. The command will be as follows: ```bash mkdir -p ~/.config/nvim/lua/custom/plugins @@ -43,7 +47,7 @@ The structure of the `nvim/lua` folder should now look like this: │   └── plugins ``` -The choice of path is not accidental but responds to the need to preserve this folder from updates, otherwise with each update the folder would simply be deleted as it is not part of the repository. The NvChad developers have prepared a `.gitignore` file for this, which determines its exclusion. +The choice of path is not accidental. It responds to the need to preserve this folder from updates. Without this, with each update the folder would simply be deleted as it is not part of the repository. The NvChad developers have prepared a `.gitignore` file for this, which determines its exclusion. ```bash cat .config/nvim/.gitignore @@ -67,9 +71,9 @@ custom/ └── lspconfig.lua ``` -We are going to analyze its contents and briefly describe the files it contains; the files will be analyzed in detail later on the pages dedicated to them. +We are going to analyze its contents, and briefly describe the files it contains. The files will be analyzed in detail later, on the pages dedicated to them. -- `chadrc.lua`: this file allows the override of default configurations. It also allows plugins to be overridden so that they can then be associated with _override.lua_ configurations. For example, it is used to save the interface theme with: +- `chadrc.lua`: This file allows for the override of default configurations. It also allows plugins to be overridden so that they can then be associated with _override.lua_ configurations. For example, it is used to save the interface theme with: ```lua M.ui = { @@ -77,22 +81,21 @@ M.ui = { } ``` -- `init.lua`: this file is executed after the main `init.lua` file contained in `nvim/lua/core/` and allows the execution of personalized commands at NvChad startup. +- `init.lua`: This file is executed after the primary `init.lua` file, contained in `nvim/lua/core/`, and allows the execution of personalized commands at NvChad startup. -- `mappings.lua`: allows the setting of custom commands, these commands are normally used to abbreviate standard commands. An example is the abbreviation of the command `:Telescope find_files` which with this setting in _mapping.lua_: +- `mappings.lua`: Allows for the setting of custom commands. These commands are normally used to abbreviate standard commands. An example is the abbreviation of the command `:Telescope find_files`, which with this setting in _mapping.lua_: ```lua ["\\\\"] = { " Telescope find_files", "file finder" }, ``` -Allows you to retrieve **:Telescope find_files** by typing two `\\` +allows you to retrieve **:Telescope find_files** by typing two `\\` ![Telescope Find Files](../images/telescope_find_files.png) -- `override.lua`: this file contains the custom configurations that replace the default ones, this is possible thanks to the override effected upstream in _chadrc.lua_. +- `override.lua`: This file contains the custom configurations that replaces the default ones. This is made possible thanks to the override effected upstream in _chadrc.lua_. -Let us now move on to the `plugins` folder, the folder contains all the configuration files of the various plugins installed and most importantly the `init.lua` file. In the `init.lua` file should be inserted the plugins we want to install on our IDE. Once inserted and configured, if necessary, they will be installable via the `:PackerSync` command. +Let us now move on to the `plugins` folder. This folder contains all the configuration files of the various plugins installed. It also contains the `init.lua` file for the customizations. The `init.lua` file should contain the plugins we want to install on our IDE. Once inserted and configured, they will be installable via the `:PackerSync` command. The only plugin required is _neovim/nvim-lspconfig_, which enables LSP (language server) functionality for advanced editing. - diff --git a/docs/books/nvchad/custom/init_lua.md b/docs/books/nvchad/custom/init_lua.md index f1fdfbb800..a3e82d7c5b 100644 --- a/docs/books/nvchad/custom/init_lua.md +++ b/docs/books/nvchad/custom/init_lua.md @@ -1,16 +1,19 @@ --- -title: WIP - init.lua +title: init.lua +author: Franco Colussi +contributors: Steven Spencer +tested with: 8.6, 9.0 tags: - nvchad - coding - editor --- -# init.lua +# `init.lua` -The *nvim/lua/custom/init.lua* file is used for overwriting the default NvChad options defined in *lua/core/options.lua* and setting its own options. It is also used for the execution of Auto-Commands. +The `nvim/lua/custom/init.lua` file is used for overwriting the default NvChad options, defined in `lua/core/options.lua`, and setting its own options. It is also used for the execution of Auto-Commands. -Writing documents in Makdown does not require much modification; we are going to set some behaviors such as the number of spaces for tabbing, a setting that makes formatting Markdown files very smooth. +Writing documents in Markdown does not require much modification. We are going to set some behaviors such as the number of spaces for tabbing, a setting that makes formatting Markdown files very smooth. Our file will look like this: @@ -29,6 +32,6 @@ opt.autoindent = true opt.smartindent = true ``` -In our example we used an auto-command for synchronous buffer formatting and formatting options. +In our example we used an auto-command for synchronous buffer formatting and options. -To summarize, the *init.lua* file is used for overwriting the default settings, this is because being read after the *core/init.lua* file replaces all previous options with the new ones we set. +To summarize, the `init.lua` file in our `custom` folder is used for overwriting the default settings. This works because it is being read after the `core/init.lua` file, replacing all previous options with the new ones we have set. diff --git a/docs/books/nvchad/custom/lsp.md b/docs/books/nvchad/custom/lsp.md index f159b2d3ff..ecc60c085c 100644 --- a/docs/books/nvchad/custom/lsp.md +++ b/docs/books/nvchad/custom/lsp.md @@ -2,7 +2,7 @@ title: Language Server Protocol author: Franco Colussi contributors: Steven Spencer -tested with: 9.0 +tested with: 8.6, 9.0 tags: - NvChad - coding @@ -40,7 +40,7 @@ The combined use of the two plugins allows the required language servers to be d #### Downloading Language Servers -To download the language server of choice, we open the interface of *Mason* from our editor with the command `:Mason`. Suppose we want to install the language server for *Markdown*. To do so, we type 2 to take us to the `LSP` section. Now we go down with the arrow key until we find the language server `marksman`. By pressing the space bar we can get some information about the server as you can see in the screenshot below. +To download the language server of choice, we open the interface of *Mason* from our editor with the command SHIFT + :Mason. Suppose we want to install the language server for *Markdown*. To do so, we type 2 to take us to the `LSP` section. Now we go down with the arrow key until we find the language server `marksman`. By pressing the space bar we can get some information about the server as you can see in the screenshot below. ![Mason Marksman](../images/mason_marksman.png) @@ -59,13 +59,13 @@ The servers to be installed by this procedure are: Installed servers are not yet configured in NvChad. To perform server registration we need to perform additional configuration. -First we create the `custom/plugins` folder in `~/.local/nvim/lua`: +First we create the `custom/plugins` folder in `~/.local/nvim/lua`. Note that if you are following along completely, this path may already be created: ```bash mkdir -p ~/.local/nvim/lua/custom/plugins ``` -We used the `-p` flag since the _custom_ folder was definitely not present. Once the folder is created, we need to create two files: `init.lua`, which will take care of instructing *Packer* to install the plugin, and `lspconfig.lua`, which will define our servers. +We used the `-p` flag since we want to create the entire path if it doesn't already exist. Once the folder is created, we need to create two files: `init.lua`, which will take care of instructing *Packer* to install the plugin, and `lspconfig.lua`, which will define our servers. Let's start by creating the two files first: @@ -107,7 +107,7 @@ nvim ~/.config/nvim/lua/custom/plugins/init.lua ![NvChad init.lua](../images/init_custom_plugins.png) -Once the changes are finished, we save the file with the command `:wq`. +Once the changes are finished, we save the file with the command SHIFT + :wq. We can now edit the configuration file of our local servers. @@ -139,9 +139,9 @@ nvim ~/.config/nvim/lua/custom/plugins/lspconfig.lua ![Custom lspconfig.lua](../images/lspconfig_custom.png) -After finishing the changes we save and close the editor as before with `:wq` +After finishing the changes we save and close the editor as before with SHIFT + :wq. -As we can see, we have added in the table of `local servers` the servers we have installed with *Mason*: +As we can see, we have added to the table of `local servers` the servers we have installed with *Mason*: ```lua local servers = { "html", "marksman", "yamlls"} @@ -149,7 +149,7 @@ local servers = { "html", "marksman", "yamlls"} This gives *nvim-lspconfig* a way to retrieve the configurations needed for their operation in the IDE. -Once we have finished the changes, to make them effective we need to tell *Packer* to synchronize them. This is done with a simple `:PackerSync` at the end of which the new installation of *neovim/nvim-lspconfig* will be highlighted in the log. Now opening a Markdown file should bring up a gear icon in the lower right corner and say `LSP - marksman`. +Once we have finished the changes, to make them effective we need to tell *Packer* to synchronize them. This is done with a simple SHIFT + :PackerSync at the end of which the new installation of *neovim/nvim-lspconfig* will be highlighted in the log. Now opening a Markdown file should bring up a gear icon in the lower right corner and say `LSP - marksman`. ![Marksman Enable](../images/marksman_enable.png) @@ -193,4 +193,4 @@ Once installed it will spring into action whenever we open a `.yaml` file by mak The use of LSPs greatly aids the editing process, enriching it with advanced features. It also allows us to keep track of its consistency in real time. It is definitely a tool to have in our IDE. -The introduction of *Mason*, although some manual intervention is still required to configure the environment, has made available an automated procedure for the installation of language servers, and more importantly, allows us to avoid the periodic checks for updates that would have been necessary in the case of manual installation. Once installed and configured, all our servers will be upgradeable from the *Mason GUI* with a simple press of the U key. +The introduction of *Mason*, although some manual intervention is still required to configure the environment, has made available an automated procedure for the installation of language servers. More importantly, it allows us to avoid the periodic checks for updates that would have been necessary in the case of manual installation. Once installed and configured, all our servers will be upgradeable from the *Mason GUI* with a simple press of the U key. diff --git a/docs/books/nvchad/custom/mappings_lua.md b/docs/books/nvchad/custom/mappings_lua.md index 84ec3cce23..0cc8f36498 100644 --- a/docs/books/nvchad/custom/mappings_lua.md +++ b/docs/books/nvchad/custom/mappings_lua.md @@ -1,18 +1,21 @@ --- -title: WIP - mappings.lua +title: mappings.lua +author: Franco Colussi +contributors: Steven Spencer +tested with: 8.6, 9.0 tags: - nvchad - coding - editor --- -The *custom/mappings.lua* file allows us to set up custom commands, these allow to perform even non-editor tasks as well as greatly shortening the typing of full commands. +The `custom/mappings.lua` file allows us to set up custom commands. These commands allow us to perform non-editor tasks as well as greatly shortening the typing of full commands. -This is probably the most "personal" file of those contained in the `custom` folder in that everyone has their own set of commands and associated utilities to which they are accustomed. We will try to lay out the subject in a general way to give you the foundation on which to build your own mapping. +This is probably the most "personal" file of those contained in the `custom` folder. Everyone has their own set of commands and associated utilities to which they are accustomed. We will try to lay out this subject in a general way to give you the foundation on which to build your own mapping. The interesting thing about mappings is that they can be inserted into the various working states of the editor (INSERT, NORMAL..) giving us a way to have even more granular customization of commands. -The states are denoted by the letters `n`, `v`, `i`, `t`. As can be seen these are corresponding to the various NORMAL, VISUAL, etc. Let us take the following example to introduce the configuration: +The states are denoted by the letters `n`, `v`, `i`, `t`. These correspond to the various NORMAL, VISUAL, etc. editor commands. Let us take the following example to introduce the configuration: ```lua local M = {} @@ -54,14 +57,15 @@ M.git = { return M ``` -In this file the `M` variable initialized in the first line passes and collects all our mappings before being returned to the configuration from the last line, so everything we set in this file will be available in the editor in the form of keyboard shortcuts. +In this file the `M` variable initialized in the first line passes and collects all our mappings before being returned to the configuration from the last line. In this way, everything that we set in this file will be available in the editor in the form of keyboard shortcuts. -The first part `M.general` is an example of overriding the default settings, the new mapping replaces the default mapping for movement between rows in INSERT mode `i = {` with one that is easier to remember (and also more logical, the original shortcut Ctrl + l to move to the right is an example) +The first part `M.general` is an example of overriding the default settings. The new mapping replaces the default mapping for movement between rows in INSERT mode `i = {` with one that is easier to remember, and also more logical. The original shortcut CTRL + l to move to the right is an example. -In the second part we have the command mapping for plugin management with `:Packer` this time set for the NORMAL `n = {` state. +In the second part we have the command mapping for plugin management with `:Packer`, this time set for the NORMAL `n = {` state. -And in the final part of our example we have two sets of shortcuts both for the NORMAL `n = {` state, one concerning the opening of *Telescope* for searching files and some shortcuts for controlling and managing *Git repositories*, -As you can see this file allows you to manage the keyboard shortcuts of all NvChad/Neovim commands and also of its plugins allowing a much faster workflow. +In the final part of our example we have two sets of shortcuts, both for the NORMAL `n = {` state; one concerning the opening of *Telescope* for searching files, and some shortcuts for controlling and managing *Git repositories*. -This example is only meant to be an introduction to a level of customization that can be very high; to consult the standard mapping you can refer to [this file](https://github.com/NvChad/NvChad/blob/main/lua/core/mappings.lua), while for plugin-specific commands you must refer to the various projects. +As you can see, this file allows you to manage the keyboard shortcuts of all NvChad/Neovim commands and plugins, allowing for a much faster workflow. + +This example is only meant to be an introduction to a level of customization that can be made. Customizations can be quite extensive. To consult the standard mapping, you can refer to [this file](https://github.com/NvChad/NvChad/blob/main/lua/core/mappings.lua). For plugin-specific commands you must refer to the various projects. diff --git a/docs/books/nvchad/custom/override_lua.md b/docs/books/nvchad/custom/override_lua.md index 57566dd165..780f5bdb6a 100644 --- a/docs/books/nvchad/custom/override_lua.md +++ b/docs/books/nvchad/custom/override_lua.md @@ -1,14 +1,17 @@ --- -title: WIP - override.lua +title: override.lua +author: Franco Colussi +contributors: Steven Spencer +tested with: 8.6, 9.0 tags: - nvchad - coding - editor --- -# override.lua +# `override.lua` -The `custom/override.lua` file is used for overriding the settings of plugins defined in *chadrc.lua* allows various *parsers* to be installed at startup, extend the functionality of *nvimtree*, and other customizations. +The `custom/override.lua` file is used for overriding the settings of plugins defined in `chadrc.lua`, allows various *parsers* to be installed at startup, extends the functionality of *nvimtree*, and other customizations. The file used for our example is as follows: @@ -68,17 +71,17 @@ M.mason = { return M ``` -Let's go through the content, the first part checks, and if missing installs the *treesitter* parsers defined in the table, in our example we added only those useful for writing documents in Markdown, for a complete list of available parsers you can refer to [this page](https://github.com/nvim-treesitter/nvim-treesitter#supported-languages). +Let's step through the content. The first part checks, and if missing, installs the *treesitter* parsers defined in the table. In our example, we added only those useful for writing documents in Markdown. For a complete list of available parsers you can refer to [this page](https://github.com/nvim-treesitter/nvim-treesitter#supported-languages). ![NvimTree Git](../images/nvimtree_git.png){ align=right } -The second part enriches our file explorer (*nvimtree*) with decorations for the state of the files with respect to the *Git* repository and moves the view to the right. +The second part enriches our file explorer (*nvimtree*) with decorations for the state of the files with respect to the *Git* repository, and moves the view to the right. -We then have a part that takes care of removing the lines that indicate nesting in the code and the last one that takes care of informing *Mason* which language servers are needed in the IDE, called by the `ensure_installed` function. +Then we have a section that takes care of removing the lines that indicate nesting in the code. Finally, one that takes care of informing *Mason* which language servers are needed in the IDE, called by the `ensure_installed` function. The control and eventual installation of *parser* and *LSP* is very useful in managing one's customizations on multiple workstations. By saving the *custom* folder in a Git Repository, one has the ability to clone one's customization to any machine on which NvChad is installed, and any changes can be synchronized between all the machines on which one is working. -Summarizing the *custom/override.lua* file is used to override parts of the default plugin configuration, customizations set in this file are taken into account only if the plugin is defined in *custom/chadrc.lua* in the *plugin override* section. +Summarizing the `custom/override.lua` file is used to override parts of the default plugin configuration. Customizations set in this file are taken into account *only* if the plugin is defined in `custom/chadrc.lua` in the *plugin override* section. ```lua M.plugins = { diff --git a/docs/books/nvchad/custom/plugins/init_lua.md b/docs/books/nvchad/custom/plugins/init_lua.md index b411b4e281..14aa533219 100644 --- a/docs/books/nvchad/custom/plugins/init_lua.md +++ b/docs/books/nvchad/custom/plugins/init_lua.md @@ -1,20 +1,23 @@ --- -title: WIP - init.lua +title: init.lua +author: Franco Colussi +contributors: Steven Spencer +tested with: 8.6, 9.0 tags: - nvchad - coding - editor --- -# init.lua +# `init.lua` -The file `custom/plugins/init.lua` closes the NvChad configuration, it is the last *init.lua* that is read and inserts our additional plugins into the configuration. Its configuration consists of inserting the plugins in the format: +The file `custom/plugins/init.lua` closes the NvChad configuration. It is the last `init.lua` that is read and inserts our additional plugins into the configuration. Its configuration consists of inserting the plugins in the format: ```lua ["github_username/plugin_name"] = {}, ``` -If the plugin does not need additional configurations, the configuration described above is sufficient, but if additional configurations are needed, they will be placed inside the curly brackets. +If the plugin does not need additional configurations, the configuration described above is sufficient. If additional configurations are needed, they will be placed inside the curly brackets. Let us then take our example file: @@ -31,14 +34,14 @@ return { } ``` -In this configuration we have included only the two necessary plugins *nvim-lspconfig* and *which-key* plus one that requires no additional configuration as an example. The two plugins are necessary since without their configuration we will not have support for LSPs (language servers) even if they are installed and the functionality of *which-key* since it is disabled by default. +In this configuration we have included only the two necessary plugins *nvim-lspconfig* and *which-key*, plus one that requires no additional configuration as an example. The two plugins are necessary since without their configuration we will not have support for LSPs (language servers) even if they are installed. The functionality of *which-key* is disabled by default, and we want to enable it here. -As we can see, the first plugin calls the configuration function and reads first the file `nvim/lua/plugins/configs/lspconfig.lua` and then our file `nvim/lua/custom/plugins/lspconfig.lua`. In this case an additional file is used for personal configurations, the choice depends on the amount of changes to be made. +As we can see, the first plugin calls the configuration function and reads first the file `nvim/lua/plugins/configs/lspconfig.lua`, and then *our* file `nvim/lua/custom/plugins/lspconfig.lua`. In this case an additional file is used for personal configurations. The choice depends on the number of changes to be made. -The second is an example of a plugin that needs no additional configuration allows once installed to access Git repository management directly from the editor with the command `:LazyGit`. For the installation of LazyGit you can refer to the [Additional Software](../../additional_software.md) page. +The second is an example of a plugin that needs no additional configuration. Once installed, it is allowed to access Git repository management directly from the editor with the command SHIFT + :LazyGit. For the installation of LazyGit you can refer to the [Additional Software](../../additional_software.md) page. -The third is an example of putting configurations to be overwritten directly into the file, in this case the only change is the reactivation of the default disabled plugin. This plugin is enclosed by two single quotes that can replace double quotes; the two notations are equivalent. +The third is an example of putting configurations to be overwritten directly into the file. In this case, the only change is the reactivation of the default disabled plugin (which-key). This plugin is enclosed by two single quotes that can replace double quotes. The two notations are equivalent. -Once you have finished configuring the file and related configuration files, to activate the new plugins, it is recommended that you exit the editor, re-enter and perform a `:PackerSync` +Once you have finished configuring the file, and any related configuration files, we need to activate them. To do this, you should exit the editor, re-enter, and then perform a SHIFT + :PackerSync. -In short we can say that this file is the engine of all our personal plugins, this is where most of the additional functionality of our IDE are configured. +In short we can say that this file is the engine of all our personal plugins. This is where most of the additional functionality of our IDE is configured. diff --git a/docs/books/nvchad/custom/plugins/lspconfig_lua.md b/docs/books/nvchad/custom/plugins/lspconfig_lua.md index b84e838a65..0202923a93 100644 --- a/docs/books/nvchad/custom/plugins/lspconfig_lua.md +++ b/docs/books/nvchad/custom/plugins/lspconfig_lua.md @@ -1,14 +1,17 @@ --- -title: WIP - lspconfig.lua +title: lspconfig.lua +author: Franco Colussi +contributors: Steven Spencer +tested with: 8.6, 9.0 tags: - nvchad - coding - editor --- -# lspconfig.lua +# `lspconfig.lua` -This configuration file assigns the functionality defined in `nvim/lua/plugins/configs/lspconfig.lua` to the language servers we have installed with `Mason`, the language servers should be placed in the local servers according to this format: +This configuration file assigns the functionality defined in `nvim/lua/plugins/configs/lspconfig.lua` to the language servers we have installed with `Mason`. The language servers should be placed in the local servers according to this format: ```lua local servers = { "html", "marksman", "yamlls"} @@ -16,7 +19,7 @@ local servers = { "html", "marksman", "yamlls"} As pointed out earlier, there is no need to make explicit support for Lua as it is enabled by default by NvChad; however, the *lua-language-server* must be installed with *Mason* to be available in the IDE. -Let us then look at our *lspconfig.lua* file: +Let us then look at our `lspconfig.lua` file: ```lua local on_attach = require("plugins.configs.lspconfig").on_attach @@ -33,12 +36,8 @@ for _, lsp in ipairs(servers) do end ``` -The first two instructions import the `on_attach` and `capabilities` features from NvChad's *lspconfig.lua* file, then follows the configuration of the language servers to which to provide the features, and finally the routine that associates the features with the LSPs set up. - -At the first configuration it is advisable to exit and re-enter the editor before running `:PackerSync`, subsequent language server entries to the configuration can be registered with `:LspRestart` without the need to reload the configuration. The next time a supported file is opened it will bring up an icon at the bottom with associated LSP and language server used, this gives us confirmation that the LSP is running properly. - -Summarizing the *lspconfig.lua* file configures the functionality of the servers we install, it is a file that after the first configuration will not need much editing as long as we write documentation in Markdown. For more information on the **L**anguage **S**erver **P**rotocol you can consult the [dedicated page](../lsp.md). - - +The first two instructions import the `on_attach` and `capabilities` features from NvChad's `lspconfig.lua` file. Following this comes the configuration of the language servers to provide the features. Finally, the routine that associates the features with the LSPs set up is called. +After the first configuration, it is advisable to exit and re-enter the editor before running SHIFT + :PackerSync. Subsequent language server entries to the configuration can be registered with SHIFT + :LspRestart without the need to reload the configuration. The next time a supported file is opened, it will bring up an icon at the bottom with associated LSP and language server used. This gives us confirmation that the LSP is running properly. +Summarizing, the `lspconfig.lua` file configures the functionality of the servers we install. It is a file that, after the first configuration, will not need much editing as long as we write documentation in Markdown. For more information on the **L**anguage **S**erver **P**rotocol you can consult the [dedicated page](../lsp.md). diff --git a/docs/books/nvchad/index.md b/docs/books/nvchad/index.md index f79e888607..a092f24667 100644 --- a/docs/books/nvchad/index.md +++ b/docs/books/nvchad/index.md @@ -2,7 +2,7 @@ title: Overview author: Franco Colussi contributors: Steven Spencer -tested with: 9.0 +tested with: 8.6, 9.0 tags: - nvchad - coding @@ -13,19 +13,21 @@ tags: Throughout this book, you will find ways to implement Neovim, along with NvChad, to create a fully functional **I**ntegrated **D**evelopment **E**nvironment (IDE). -I say "ways" because there are many possibilities. The author focuses the chapters here on using these tools for writing markdown, but if markdown isn't your focus, don't worry simply read on. If you are unfamiliar with either of these tools (NvChad or Neovim), then this book will give you an introduction to both, and if you step through the chapters here, you'll soon realize that you can set up this environment to be a huge help for whatever your programming or script writing needs are. +I say "ways" because there are many possibilities. The author focuses the sections here on using these tools for writing markdown, but if markdown isn't your focus, don't worry simply read on. If you are unfamiliar with either of these tools (NvChad or Neovim), then this book will give you an introduction to both, and if you step through these documents, you'll soon realize that you can set up this environment to be a huge help for whatever your programming or script writing needs are. -Want an IDE that will help in writing Ansible playbooks? You can get that! Want and IDE for Golang? That's available too. Simply want a good interface for writing BASH scripts? That's also available. +Want an IDE that will help in writing Ansible playbooks? You can get that! Want and IDE for Golang? That's available too. Simply want a good interface for writing BASH scripts? It's also available. Through the use of **L**anguage **S**erver **P**rotocols and linters, you can setup an environment that is customized just for you. The best part is that once you have the environment setup, it can quickly be updated when new changes are available through the use of Packer and Mason, both of which are covered here. -Because Neovim is a fork of `vim`, the overall interface will be familiar to `vim` users. If you aren't a `vim` user, then you will pick up on the syntax of the commands quickly using this book. There's a lot of information covered here but it's easy to follow along, and once you've completed the chapters you'll know enough to build your own IDE for _your_ needs with these tools. +Because Neovim is a fork of `vim`, the overall interface will be familiar to `vim` users. If you aren't a `vim` user, you will pick up on the syntax of the commands quickly using this book. There's a lot of information covered here but it's easy to follow along, and once you've completed the content, you'll know enough to build your own IDE for _your_ needs with these tools. + +It was the author's intent **not** to break this book down into chapters. The reason is that this implies an order that must be followed and, for the most part, that's not necessary. You *will* want to start with this page, read and follow the "Additional Software", "Install Neovim" and "Install NvChad" sections, but from there, you can choose how you want to proceed. ## Using Neovim as an IDE -The basic installation of Neovim provides an excellent editor for development, but it cannot yet be called an IDE; all the features even if already preset are not yet activated. To do this we need to pass the necessary configurations to Neovim, and this is where NvChad comes to our aid, which allows us to have a basic configuration out of the box with just one command! +The basic installation of Neovim provides an excellent editor for development, but it cannot yet be called an IDE; all the features, even if already preset, are not yet activated. To do this we need to pass the necessary configurations to Neovim, and this is where NvChad comes to our aid. This allows us to have a basic configuration out of the box with just one command! -The configuration is written in Lua, a very fast programming language that allows NvChad to have startup and execution times for commands and keystrokes that are very fast as well. This is also made possible by the `Lazy loading` technique used for plugins that allows them to load only when required. +The configuration is written in Lua, a very fast programming language that allows NvChad to have startup and execution times for commands and keystrokes that are very fast. This is also made possible by the `Lazy loading` technique used for plugins that loads them only when required. The interface turns out to be very clean and pleasant. @@ -41,7 +43,7 @@ As the developers of NvChad are keen to point out, the project is only intended - **Extremely Configurable.** Due to the modularity derived from the base used (NeoVim), the editor can be adapted perfectly to one's needs. Keep in mind, however, that when we talk about customization we are referring to functionality not to the appearance of the interface. -- **Automatic update mechanism.** The editor comes with a mechanism (through the use of _git_) that allows updating with a simple `uu` command. +- **Automatic update mechanism.** The editor comes with a mechanism (through the use of _git_) that allows updating with a simple `uu` command. - **Powered by Lua.** NvChad's configuration is written entirely in _lua_, which allows it to integrate seamlessly into Neovim's configuration by taking advantage of the full potential of the editor on which it is based. @@ -80,13 +82,13 @@ Lua is not interpreted directly through a Lua file like other languages, for exa - Portability and integration: The portability of Lua is almost unlimited. Any platform that supports the standard C compiler can run Lua without problems. Lua does not require complex rewrites to be compatible with other programming languages. -- Simplicity: Lua has a simple design but provides powerful functionality. One of the main features of Lua are meta-mechanisms, which allow developers to implement their own functionality. The syntax is simple and in an easily understood format, so that anyone can easily learn Lua and use it in their own programs. +- Simplicity: Lua has a simple design but provides powerful functionality. One of the main features of Lua is meta-mechanisms, which allow developers to implement their own functionality. The syntax is simple and in an easily understood format, so that anyone can easily learn Lua and use it in their own programs. - License: Lua is free and open-source software distributed under the MIT license. This allows anyone to use it for any purpose without paying any license or royalties. ### Neovim -Neovim is dealt with in detail on its [dedicated page](to be built) so we will just dwell on the main features, which are: +Neovim is dealt with in detail on its [dedicated page](install_nvim.md) so we will just dwell on the main features, which are: - Performance: Very fast. @@ -119,6 +121,6 @@ A parser is a component that decomposes data into smaller elements to facilitate !!! notes "LSP and tree-sitter complementarity." - Although it may seem that the two services (LSP and tree-sitter) are redundant they are actually complementary in that LSP works at the project level while tree-sitter works only on the open source file. + Although it may seem that the two services (LSP and tree-sitter) are redundant, they are actually complementary in that LSP works at the project level while tree-sitter works only on the open source file. Now that we have explained a bit about the technologies used to create the IDE we can move on to the [Additional Software](additional_software.md) needed to configure our NvChad. diff --git a/docs/books/nvchad/install_nvchad.md b/docs/books/nvchad/install_nvchad.md index ac8655483b..707b9d5ce4 100644 --- a/docs/books/nvchad/install_nvchad.md +++ b/docs/books/nvchad/install_nvchad.md @@ -2,7 +2,7 @@ title: Install NvChad author: Fanco Colussi contributors: Steven Spencer -tested with: 9.0 +tested with: 8.6, 9.0 tags: - nvchad - coding @@ -57,7 +57,7 @@ Once the cloning process is finished, the plugins that are part of the default c ![NvChad Themes](images/nvchad_init.png) -As can be seen from the screenshot below, the editor, thanks to the configuration changes made, has completely changed in appearance from the basic version of Neovim. It should be remembered, however, that although the configuration of NvChad completely transforms the editor, the base is, and remains Neovim. +As can be seen from the screenshot below, thanks to the configuration changes made, the editor has completely changed in appearance from the basic version of Neovim. It should be remembered, however, that although the configuration of NvChad completely transforms the editor, the base remains Neovim. ![NvChad Rockydocs](images/nvchad_ui.png) @@ -119,12 +119,12 @@ require "plugins" pcall(require, "custom") ``` -Inclusion of the `core` folder also results in the inclusion of the _core/init.lua_ file, which overrides some Neovim interface configurations and prepares for buffer management. +Inclusion of the `core` folder also results in the inclusion of the `core/init.lua` file, which overrides some Neovim interface configurations and prepares for buffer management. -As we can see, each _init.lua_ file is included following a well-established order, and we can anticipate that the _init.lua_ file we are going to create in our customization will also be included in turn-last, of course. Broadly speaking, we can say that _init.lua_ files have the following functions: +As we can see, each `init.lua` file is included following a well-established order. We can anticipate that the `init.lua` file we are going to create in our customization will also be included, but logically, last in the load order. Broadly speaking, we can say that `init.lua` files have the following functions: - load global options, autocmds, or anything else. -- override the default options in _core/options.lua_. +- override the default options in `core/options.lua`. Returning to the call for command mapping: @@ -135,23 +135,27 @@ Returning to the call for command mapping: This sets four main keys from which, in association with other keys, commands can be launched. The main keys are: - C = CTRL -- leader = space +- leader = SPACE - A = ALT - S = SHIFT +!!! note + + We will refer to these key mappings several times throughout these documents. + The default mapping is contained in _core/mapping.lua_ but can be extended with other custom commands using its own _mappings.lua_. Some examples of the standard mapping are: ```text -uu to update NvChad -th to change the theme - to open nvimtree - to open a terminal in a floating tab +uu to update NvChad +th to change the theme + to open nvimtree + to open a terminal in a floating tab ``` -The combinations set are really many, and cover all the use of NvChad. It is worth pausing to analyze the mapping before starting to use it. +There are many combinations that are set, and they cover all the uses of NvChad. It is worth pausing to analyze the mapping before starting to use it. -Continuing with the structure analysis we find the _lua/plugins_ folder, which contains the setup of the built-in plugins and their configurations. The main plugins in the configuration will be described in the next section. As we can see, the _core/plugins_ folder also contains an _init.lua_ file, which is used here for the installation and subsequent compilation of the plugins. +Continuing with the structure analysis we find the _lua/plugins_ folder, which contains the setup of the built-in plugins and their configurations. The main plugins in the configuration will be described in the next section. As we can see, the _core/plugins_ folder also contains an `init.lua` file, which is used here for the installation and subsequent compilation of the plugins. To close we find the _nvim/plugin_ folder that contains an autogenerated file of the compiled plugins. diff --git a/docs/books/nvchad/install_nvim.md b/docs/books/nvchad/install_nvim.md index 192013f829..59179d04ad 100644 --- a/docs/books/nvchad/install_nvim.md +++ b/docs/books/nvchad/install_nvim.md @@ -2,9 +2,10 @@ title: Install Neovim author: Franco Colussi contributors: Steven Spencer -tested with: 9.0 +tested with: 8.6, 9.0 tags: - nvchad + - nvim - coding --- @@ -14,11 +15,11 @@ Neovim is one of the best code editors due of its speed, ease of customization, Neovim is a fork of the `Vim` editor. It was born in 2014, mainly due to the lack at the time of asynchronous support in Vim. Written in the Lua language with the goal of modularizing the code to make it more manageable, Neovim was designed with the modern user in mind. As the official website states, "Neovim is built for users who want the best parts of Vim, and more". -The developers of Neovim chose Lua as it was perfect for embedding, using LuaJIT quickly, and with a simple, scripting-oriented syntax. +The developers of Neovim chose Lua as it was perfect for embedding, using LuaJIT quickly, and with a simple, script-oriented syntax. From version 0.5 Neovim includes Treesitter (a parser generator tool) and supports Language Server Protocol (LSP). This reduces the number of plugins needed to achieve advanced editing functions. It improves the performance of operations such as code completion and linting. -One of its strengths is its customization. All of its configuration is contained in a single file that can be distributed to the various installations through a version manager (Git or other) so that the various installations are always synchronized. +One of its strengths is its customization. All of its configuration is contained in a single file that can be distributed to the various installations through a version manager (Git or other) so that they are always synchronized. ### Community of developers @@ -38,7 +39,7 @@ As with Vim, Neovim requires a basic knowledge of its commands and options. You ### Installation from EPEL -Before moving on to the installation of NvChad, we need to make sure that we have an installation of Neovim available. If it is not already installed, you can install it from the EPEL Repository, even if the version provided does not meet the minimum requirements. +Before moving on to the installation of NvChad, we need to make sure that we have an installation of Neovim available. If it is not already installed, you can install it from the EPEL repository. Keep in mind, though, that this version is older and does not provide everything that is needed for a fully functioning NvChad installation. For this reason, the author recommends that you skip the EPEL install procedure and use the "Installation from Precompiled Package" below. The EPEL version *is* an option however, so it is included here. To install the Neovim release provided by EPEL, we install if you have not already done so the repository. @@ -68,7 +69,7 @@ Next, we download the compressed archive for our architecture (linux64) from thi https://github.com/neovim/neovim/releases ``` -The file to be downloaded is `nvim-linux64.tar.gz`, to verify the integrity of the archive we also download the file `nvim-linux64.tar.gz.sha256sum`, once downloaded we need to verify its integrity and unpack it somewhere in our `home directory`. The proposed solution is to unpack it in `~/.local/share/`, assuming we downloaded it in _/home/user/downloads/_ we will need to run the following commands: +The file to be downloaded is `nvim-linux64.tar.gz`. To verify the integrity of the archive we also need to download the file `nvim-linux64.tar.gz.sha256sum`. Once downloaded we need to verify its integrity and unpack it somewhere in our `home directory`. The proposed solution is to unpack it in `~/.local/share/`. Assuming we downloaded it in _/home/user/downloads/_, we will need to run the following commands: ```bash sha256sum -c /home/user/downloads/nvim-linux64.tar.gz.sha256sum @@ -85,7 +86,7 @@ cd ~/.local/bin/ ln -sf ~/.local/share/nvim-linux64/bin/nvim nvim ``` -To be shure, we check the version provided by the `nvim -v` command, which should now show: +Now verify you have the correct version with the `nvim -v` command, which should now show: ```txt nvim -v @@ -105,7 +106,7 @@ Run :checkhealth for more info ### Installation from Source -Installation from precompiled package provides an installation for only the user who runs it, in case you want to make Neovim available to all users of the system you will have to do an installation from source. Compiling Neovim is not particularly difficult and consists of the following steps. +Installing from precompiled package, as above, provides `nvim` only for the user who runs it. If you want to make Neovim available to all users of the system, you will have to do an installation from source. Compiling Neovim is not particularly difficult and consists of the following steps. We first install the packages required for compilation: @@ -113,9 +114,9 @@ We first install the packages required for compilation: dnf install ninja-build libtool autoconf automake cmake gcc gcc-c++ make pkgconfig unzip patch gettext curl ``` -Once we have installed the necessary packages we need to download the Neovim sources, sources that are distributed with *Git*. In our example we will have a folder already created for the purpose in `/home/user/lab/build`. Adapt your commands according to the structure you choose. +Once we have installed the necessary packages we need to download the Neovim sources that are distributed with *Git*. In our example we will have a folder already created for this purpose in `/home/user/lab/build`. Adapt your commands according to the structure you choose. -The Neovim clone by default is synchronized with the Neovim development branch (currently the 8.0), to compile the stable version we will have to switch to the corresponding branch before cloning with: +The Neovim clone, by default, is synchronized with the Neovim development branch (at the time of this writing, version 8.0). To compile the stable version we will have to switch to the corresponding branch before cloning with: ```bash cd ~/lab/build @@ -128,22 +129,22 @@ And subsequently clone the repository: git clone https://github.com/neovim/neovim ``` -Once the operation is finished we will have a folder named *neovim* containing all the necessary files, the next step is to configure and compile the sources, an operation that is done with the `make` command, we then go to the *neovim* folder and proceed with the configuration: +Once the operation is finished, we will have a folder named *neovim* containing all the necessary files. The next step is to configure and compile the sources. This is done with the `make` command in the *neovim* folder we created: ```bash cd ~/lab/build/neovim/ make CMAKE_BUILD_TYPE=RelWithDebInfo ``` -We chose the `RelWithDebInfo` type because it provides not only optimizations but also a useful debugging layer for later customizations, you could have also used the `Release` type if you want maximum performance. +We chose the `RelWithDebInfo` type because it provides not only optimizations, but also a useful debugging layer for later customizations. You could have also used the `Release` type if you want maximum performance. -The process takes care of configuring and compiling the files that are to be put into our system, files that are saved in `neovim/build`, to install them we will still use the *make* command: +The process takes care of configuring and compiling the files that are to be put into our system. These files are saved in `neovim/build`. To install them, we will use the *make install* command: ```bash make install ``` -This command going to modify the filesystem needs superuser (sudo) privileges or to be run as the root user. +Because this command is going to modify the filesystem, it needs to be run as the superuser, either with `sudo`, or directly by the root user. Once the installation is finished, we can verify that everything went well by checking the path to Neovim: @@ -166,7 +167,7 @@ As you can see from the command excerpt above, an installation of the developmen #### Uninstall -In case we need to remove the installation, for example to switch to another version, we will have to take ourselves back to the build folder and use the `target` cmake provided by Neovim itself, to perform the uninstallation, you need to execute the following command: +In case we need to remove the installation, for example to switch to another version, we will have to take ourselves back to the build folder and use the `target` cmake provided by Neovim itself. To perform the uninstallation, you need to execute the following command: ```bash cmake --build build/ --target uninstall @@ -181,7 +182,7 @@ rm /usr/local/bin/nvim rm -r /usr/local/share/nvim/ ``` -Always with administrator permissions. +Again, you need to execute these commands with superuser permissions. ## Neovim Basic diff --git a/docs/books/nvchad/nerd_fonts.md b/docs/books/nvchad/nerd_fonts.md index cc1cd76f75..13b6c3d4b7 100644 --- a/docs/books/nvchad/nerd_fonts.md +++ b/docs/books/nvchad/nerd_fonts.md @@ -1,8 +1,8 @@ --- -title: wip - Installing Nerd Fonts +title: Installing Nerd Fonts author: Franco Colussi contributors: Steven Spencer -tested: 9.0 +tested: 8.6, 9.0 tags: - nvchad - coding @@ -11,7 +11,9 @@ tags: # Nerd Fonts - Fonts for Developers -![Nerd Fonts](images/nerd_fonts_site_small.png){ align=right } Nerd Fonts is a collection of modified fonts aimed at developers with a large number of glyphs (icons). In particular, "iconic fonts" such as Font Awesome, Devicons, Octicons etc. are used to add extra glyphs. +Installation of Nerd Fonts does not change the function of Neovim or NvChad, but simply adds fonts that are more pleasing to the eye than whatever the standard terminal font is currently. + +![Nerd Fonts](images/nerd_fonts_site_small.png){ align=right } Nerd Fonts are a collection of modified fonts aimed at developers with a large number of glyphs (icons). In particular, "iconic fonts" such as Font Awesome, Devicons, Octicons etc. are used to add extra glyphs. Nerd Fonts takes the most popular programming fonts and modifies them by adding a group of glyphs. A font patcher is also available if the desired font has not already been edited. A convenient preview is available on the site, allowing you to see how the font should look in the editor. For more information, check the [site](https://www.nerdfonts.com/). @@ -25,7 +27,7 @@ https://www.nerdfonts.com/font-downloads ## Installation -The procedure for installing fonts on Rocky Linux is to save the fonts you want to add somewhere and then install them with the `fc-cache` command; the procedure is not a true installation so much as a registration of the new fonts in the system. +The procedure for installing fonts on Rocky Linux is to save the fonts you want to add somewhere, and then install them with the `fc-cache` command. This procedure is not a true installation so much as a registration of the new fonts in the system. !!! important "Creation of compressed packages" diff --git a/docs/books/nvchad/nvchad_ui/builtin_plugins.md b/docs/books/nvchad/nvchad_ui/builtin_plugins.md index 63de409b25..ec4c7c6534 100644 --- a/docs/books/nvchad/nvchad_ui/builtin_plugins.md +++ b/docs/books/nvchad/nvchad_ui/builtin_plugins.md @@ -2,13 +2,14 @@ title: Built-In Plugins author: Franco Colussi contributors: Steven Spencer +tested with: 8.6, 9.0 tags: - nvchad - coding - plugins --- -## Basic configuration plugins +# Basic configuration plugins !!! note "Plugin Naming Convention" @@ -39,9 +40,9 @@ local plugins = { require("core.packer").run(plugins) ``` -It is necessary to acknowledge the huge amount of work done by the NvChad developers, whose contributions have created an integrated environment among all plugins. Everything is perfectly adhered to the user interface making it very clean and professional. In addition, plugins that work *under the hood* allow advanced editing and other useful features. All of this allows ordinary users to have, in an instant, a basic IDE to start working with and an extensible configuration so that it can adapt to our needs. +There's a huge amount of work by the NvChad developers that must be acknowledged. They have created an integrated environment among all plugins which makes the user interface clean and professional. In addition, plugins that work *under the hood* allow for enhanced editing and other features. All of this means that ordinary users can have, in an instant, a basic IDE to start working, and an extensible configuration that can adapt to their needs. -### Main Plugins +## Main Plugins The following is a brief analysis of the main plugins: @@ -67,9 +68,9 @@ The following is a brief analysis of the main plugins: - [NvChad/nvterm](https://github.com/NvChad/nvterm) Provides a terminal to our IDE where we can issue commands. The terminal can be opened within the buffer in various ways: - - `` opens a terminal by dividing the buffer horizontally - - `` opens the terminal by dividing the buffer vertically - - `` opens a terminal in a floating tab + - `` opens a terminal by dividing the buffer horizontally + - `` opens the terminal by dividing the buffer vertically + - `` opens a terminal in a floating tab - [kyazdani42/nvim-web-devicons](https://github.com/kyazdani42/nvim-web-devicons) Adds icons (requires a Font Nerd) to file types and folders in our IDE. This allows us to visually identify file types in our File Explorer by speeding up operations. @@ -81,7 +82,7 @@ The following is a brief analysis of the main plugins: - [lewis6991/gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim) Provides decoration for *git* with reports for added, removed, and changed lines-reports that are also integrated into the *statusline*. -### LSP functionality +## LSP functionality Now let's move on to the plugins that provide the functionality to integrate LSPs (Language Server Protocols) into our projects. This is definitely one of the best features provided by NvChad. Thanks to LSPs we can be in control of what we write in real time. @@ -100,9 +101,9 @@ Now let's move on to the plugins that provide the functionality to integrate LSP - `:LspStop` - `:LspRestart` -### Lua Code +## Lua Code -Following LSP, come all the plugins that provide functionality in writing and executing Lua code such as snippets, lsp commands, buffers etc. We will not go into detail for these plugins, but they can be viewed in their respective projects on GitHub. +Following LSP, come all the plugins that provide functionality in writing and executing Lua code such as snippets, lsp commands, buffers etc. We will not go into detail on these, but they can be viewed in their respective projects on GitHub. The plugins are: @@ -115,7 +116,7 @@ The plugins are: - [hrsh7th/cmp-buffer](https://github.com/hrsh7th/cmp-buffer) - [hrsh7th/cmp-path](https://github.com/hrsh7th/cmp-path) -### Mixed Plugins +## Mixed Plugins - [windwp/nvim-autopairs](https://github.com/windwp/nvim-autopairs) Thanks to this plugin we have the functionality of automatic closing of parentheses and other characters. For example, by inserting a beginning parenthesis `(` completion will automatically insert the closing parenthesis `)` placing the cursor in the middle. @@ -123,7 +124,7 @@ The plugins are: - [numToStr/Comment.nvim](https://github.com/numToStr/Comment.nvim) Provides advanced functionality for code commenting. -### File Management +## File Management - [kyazdani42/nvim-tree.lua](https://github.com/kyazdani42/nvim-tree.lua) A File Explorer for Neovim that allows the most common operations on files (copy, paste, etc.), has an integration with Git, identifies files with different icons, and other features. Most importantly, it updates automatically (this is very useful when you work with Git repositories). @@ -139,4 +140,4 @@ The plugins are: - [lewis6991/impatient.nvim](https://github.com/lewis6991/impatient.nvim) Performs several operations at the start of the editor to make the loading of modules faster. -Now having introduced the plugins that make up the basic configuration of NvChad we can move on to the description of the interface. +Having introduced the plugins that make up the basic configuration of NvChad, we can move on to the description of the interface. diff --git a/docs/books/nvchad/nvchad_ui/nvchad_ui.md b/docs/books/nvchad/nvchad_ui/nvchad_ui.md index bb16828700..fbf1725568 100644 --- a/docs/books/nvchad/nvchad_ui/nvchad_ui.md +++ b/docs/books/nvchad/nvchad_ui/nvchad_ui.md @@ -2,7 +2,7 @@ title: NvChad UI author: Franco Colussi contributors: Steven Spencer -tested: 9.0 +tested: 8.6, 9.0 tags: - nvchad - coding @@ -11,27 +11,40 @@ tags: # NvChad Interface +!!! note "A few words about `mappings.lua`" + + Throughtout NvChad's official documentation, commands such as `` are mentioned, along with other keys that might not be understandable to the casual reader. The reason for this is the default `mappings.lua` file (`../nvim/lua/core/mappings.lua`). This file and the key mappings it describes are outlined [here](https://nvchad.com/config/Mappings). To be clear, you can override any key mappings using a custom `mappings.lua` file (`../nvim/lua/custom/mappings.lua`). To avoid confusion in the documents you are now reading, we are going to assume that you are using the default `mappings.lua` file and will substitute in the actual commands that you need to use to access a function. Standard key references are: + + * leader = SPACE + * A = ALT + * C = CTRL + * S = SHFT + + If a command would specify `uu` as an example, we will substitute in the actual key combination of SPACEuu. + + This will be covered again in the next section [Using NvChad](./using_nvchad.md) + Once Neovim is installed and the NvChad configuration is entered, our IDE should look like this: ![NvChad Default](../images/ui_default.png) -The interface already comes with some advanced functionality (such as indicating the status of the git repository) but can be further enhanced by using, for example, the [Language Servers](../custom/lsp.md) and customized by overriding some basic configurations. The basic modules that make it up are: +The interface already comes with some advanced functionality, such as indicating the status of the git repository, but can be further enhanced by using the [Language Servers](../custom/lsp.md), and customized by overriding some basic configurations. The basic modules that make it up are detailed below. ## Tabufline ![Tabufline](../images/ui_tabufline.png) -The user interface presents a top bar called `Tabufline` where the open buffers are managed. The open buffer presents the file type icon, the file name and its status. Status is indicated with an icon. If as in the screenshot we have a red `x` it means that the file can be closed as it is already saved. If instead the icon is a green dot `.`, then the file needs to be saved, and a close command :q will produce a warning about saving to be done before the buffer is closed. +The user interface presents a top bar called `Tabufline` where the open buffers are managed. `Tabufline` only shows if you have more than one file open. The open buffer presents the file type icon, the file name, and its status. Status is indicated with an icon. If as in the screenshot we have a red `x`, it means that the file can be closed as it is already saved. If instead the icon is a green dot `.`, then the file needs to be saved, and a close command SHIFT + :q will produce a warning: "No write since last change". -To the right is the icon for setting the *dark* or *light* theme. By clicking on it with the mouse, we can select the chosen theme. +To the right is the icon for setting the *dark* or *light* theme. By clicking on it with the mouse, we can select the theme we want. ![NvChad Light](../images/ui_default_light.png) -On the right also we have the icon for closing our editor. +On the right we also have the icon for closing our editor. ## Middle Section - Open Buffers -The central part of the editor is composed of the buffer active on the editor at that moment (*index.en.md*). To anticipate some additional functionality we can work simultaneously on two files in a split buffer by opening one more in the example (*index.it.md*). In the editor we will have the first buffer in the foreground and the second one listed in the Tabufline. Now if we split the first buffer with the `:vsplit` command and select the right buffer, clicking on the name of the second file (*index.it.md*) in the tabufline, this will be opened in the right buffer and we can work with the two files side by side. +The central part of the editor is composed of the buffer active on the editor at that moment (*index.en.md*). To anticipate some additional functionality we can work simultaneously on two files in a split buffer by opening one more in the example (*index.it.md*). In the editor we will have the first buffer in the foreground and the second one listed in the Tabufline. Now if we split the first buffer with the SHIFT + :vsplit command and select the right buffer, clicking on the name of the second file (*index.it.md*) in the tabufline, this will be opened in the right buffer and we can work with the two files side by side. ![NvChad Split](../images/ui_nvchad_split.png) @@ -42,11 +55,8 @@ The central part of the editor is composed of the buffer active on the editor at At the bottom we find the Statusline, which handles status information. On the right we find the editor status. We must not forget that we are using a text editor and that, in particular, it maintains the philosophy and operation of Vim. The possible states are: - **NORMAL** - - **INSERT** - - **COMMAND** - - **VISUAL** Editing a document starts from the **NORMAL** state where you open the file, switch to **INSERT** mode for editing, and when finished exit with ESC and return to **NORMAL** mode. Now to save the file you switch to **COMMAND** mode by typing `:` in the statusline followed by `w` (*write*) to write it and with ESC you return to **NORMAL** mode. The status indication is very useful while learning how to use it, particularly if one is not very familiar with the Vim workflow. @@ -59,11 +69,11 @@ Turning to the right side we find the indication of the folder from which we ope NvChad and Neovim provide some useful commands for displaying preset key combinations and available options. -If the `` key alone is pressed it will provide a legend of associated commands as in the following screenshot: +If the SPACE key is pressed alone, it will provide a legend of associated commands as in the following screenshot: ![Space Key](../images/ui_escape_key.png) -To view all the commands included in the editor we can use the `wK` command, which will give the following result: +To view all the commands included in the editor we can use the SPACE + wK command, which will give the following result: ![leader wK](../images/ui_wK_key.png) @@ -71,9 +81,9 @@ and by pressing d we can display the remaining commands: ![leader wK d](../images/ui_wK_01.png) -As we can see, almost all the commands refer to navigation within the document or buffer. No commands for opening the file are included. These are provided by the Neovim commands. +As we can see, almost all the commands refer to navigation within the document or buffer. No commands for opening the file are included. These are provided by the Neovim. -To view all of Neovim's options, the `:options` command is available, which will present a tree of options indexed by category. +To view all of Neovim's options, the SHIFT + :options command is available, which will present a tree of options indexed by category. ![Nvim Options](../images/nvim_options.png) @@ -81,19 +91,19 @@ This gives us a way, through the built-in help, to learn the commands while usin ## NvimTree -In order to work with our files we need a File Explorer, and this is provided by the *kyazdani42/nvim-tree.lua* plugin. With the combination CTRL n we can open NvimTree. +In order to work with our files we need a File Explorer, and this is provided by the *kyazdani42/nvim-tree.lua* plugin. With the combination CTRL + n we can open NvimTree. ![NvimTree](../images/nvim_tree.png) -As we can see below, after NORMAL the open file is not shown but instead the buffer with NvimTree. In case we are not in the right buffer, we can use the leader e command provided by NvChad to switch the focus on NvimTree. +As we can see below, after NORMAL the open file is not shown but instead the buffer with NvimTree. In case we are not in the right buffer, we can use the SPACE + e command provided by NvChad to switch the focus on NvimTree. Once positioned, we will have a series of commands for working on the file tree. The most common commands are: - > and < to navigate up and down the tree (mouse support for navigation is also active) - Enter or o to open the file in the buffer, subsequent openings of other files will always be done on the same buffer in a new tab but placed in the backgroud, to change the default behavior you can use the following keys: - - CTRL v to open the new file in the vertically divided buffer - - CTRL x to open the new file in the horizontally split buffer - - CTRL t to open the new file in a new tab in a new buffer + - CTRL + v to open the new file in the vertically divided buffer + - CTRL + x to open the new file in the horizontally split buffer + - CTRL + t to open the new file in a new tab in a new buffer - R to refresh files - a to create a new file - r to rename a file diff --git a/docs/books/nvchad/nvchad_ui/using_nvchad.md b/docs/books/nvchad/nvchad_ui/using_nvchad.md index 699abbf3a1..c8a06f1cf6 100644 --- a/docs/books/nvchad/nvchad_ui/using_nvchad.md +++ b/docs/books/nvchad/nvchad_ui/using_nvchad.md @@ -11,12 +11,14 @@ tags: # Editing with NvChad -This chapter will introduce some NvChad-specific commands and some standard Neovim (vim) commands. NvChad commands are set in the `nvim/lua/core/mapping.lua` file and allow keys to be used to execute sometimes very long composite commands. All sequences are started with a primary key followed by an option. The four main keys are: +This chapter will introduce some NvChad-specific commands and some standard Neovim (vim) commands. As previously outlined in [NvChad UI](./nvchad_ui.md), NvChad commands are set in the `..nvim/lua/core/mapping.lua` file, and allow keys to be used to execute sometimes very long composite commands. All sequences are started with a primary key followed by an option. The four main keys are: -- C = Ctrl -- leader = Space -- A = Alt -- S = shift +* leader = SPACE +* A = ALT +* C = CTRL +* S = SHFT + +Just as in the "NvChad UI" document, we will be substituting the actual command to enter, rather than the mappings. ## Open a file @@ -28,15 +30,24 @@ nvim /path/to/the/file or open the editor with the `nvim` command. -If we use the latter method we have several possibilities. We can open the file in the buffer with the command `:e` (edit) followed by the path or by having the command followed by the Tab key. This will show us all the available files and folders starting from the root of the project. It is good to remember that when we use the Tab key in file opening commands, we can select the file from a convenient drop-down menu. Once this drop-down menu is open, we continue to navigate within it by repeated use of the Tab key. +If we use the latter method we have several possibilities. We can open the file in the buffer with the command SHIFT + :e + SPACE (edit) followed by the path, or by following the command with the TAB key. This will show us all the available files and folders starting from the root of the project. It is good to remember that when we use the TAB key in file opening commands, we can select the file from a convenient drop-down menu. Once this drop-down menu is open, we continue to navigate within it by repeated use of the TAB key. ![Command :e + TAB](../images/e_tab_command.png) -In case we just want to view the file without the ability to edit it we can use the `:view` command. This will open the file in read-only mode avoiding the possibility of making unwanted changes to critical files. We can also open a file side by side with the command ` :split ` or open it in a new *tab* with the command ` :tabedit `. +It's good to remember that each of the commands listed is preceded by SHIFT and followed with a SPACE and either the path or the TAB key. Here is a list of other actions: + +* `:view` - View the file in read-only mode without the possibility to change it. Very good for the protection of critical files. +* `:split` - Open the file in an horizontal split screen. +* `:vsplit` - Open the file in a vertical split screen. +* `:tabedit` - Open the file in a new tab. + +In the following example, we have opened the file using `:vsplit`. ![Vsplit Open](../images/vsplit_open.png) -Thanks to the work done by the developers of NvChad we are provided with an additional way to open a file which is to use the *nvim-telescope/telescope.nvim* plugin. This plugin, when used in combination with *RipGrep*, allows us to search for the file to be opened in interactive mode. By typing the initial characters of the file we are looking for, the plugin will delete all non-matching files and present us with only those that match our search. This allows for a very smooth search and open process. +Thanks to the work done by the developers of NvChad, we are provided with an additional way to open a file, which is to use the *nvim-telescope/telescope.nvim* plugin. This plugin, when used in combination with *RipGrep*, allows us to search for the file to be opened in interactive mode. By typing the initial characters of the file we are looking for, the plugin will delete all non-matching files and present us with only those that match our search. This allows for a very smooth search and open process. + +To access telescope's find file feature, we need to be in NORMAL mode in the editor and then type: SHIFT + :Telescope fd ![ff](../images/leader_ff.png) @@ -44,14 +55,14 @@ Thanks to the work done by the developers of NvChad we are provided with an addi Once the file is open we can start editing it. To do this we need to switch to INSERT mode which is activated by pressing the i (insert) key. The mode indicator in the Statusline should change from NORMAL to INSERT, and the cursor placed in the buffer should also change from a colored rectangle to a `|` pipe. Now all the characters we type are inserted into the document starting from the position of the cursor. To move the cursor in INSERT mode the Nvchad developers have set up some convenient mappings which are: -- Ctrl + b to go to the beginning of the line -- Ctrl + e to go to the end of the line -- Ctrl + h to move one character to the left -- Ctrl + l to move one character to the right -- Ctrl + j to go to the next line -- Ctrl + k to go to the previous line +- CTRL + b to go to the beginning of the line +- CTRL + e to go to the end of the line +- CTRL + h to move one character to the left +- CTRL + l to move one character to the right +- CTRL + j to go to the next line +- CTRL + k to go to the previous line -Learning all the combinations takes some time but once acquired they will make navigation very fast. For example, if we want to edit the end of the next line to where the cursor is positioned we can get to the end of the current line with Ctrl + e and then get to the next one with a Ctrl + j and already be in position to add the changes. +Learning all the combinations takes some time but, once acquired, they will make navigation very fast. For example, if we want to edit the end of the next line to where the cursor is positioned we can get to the end of the current line with CTRL + e, and then get to the next one with a CTRL + j and already be in position to add the changes. Navigation in the document can also be done using the arrow keys on the keyboard, or the mouse. @@ -59,27 +70,27 @@ Navigation in the document can also be done using the arrow keys on the keyboard Text selection can also be done with the mouse and is very convenient, but for this chapter we will use the traditional method. -To select text we need to enter the VISUAL mode. To do this we must first exit the insert mode and switch to normal mode, which is done with the ESC key. Once we place the cursor at the beginning of the part we want to select, we use the keys Ctrl + v to enter the V-BLOC (Visual Block) mode. Now moving with the cursor we will see that our selection will be highlighted. At this point we can work on the selected part. If we want to copy the selection to the clipboard we will use the y key. If we want to delete it the d key. Once the operation is done, the text will no longer be highlighted. For an overview of all the operations that can be performed in Visual Mode you can consult the help directly from the editor with `:help Visual-Mode`. +To select text we need to enter the VISUAL mode. To do this we must first exit the insert mode and switch to normal mode, which is done with the ESC key. Once we place the cursor at the beginning of the part we want to select, we use the keys CTRL + v to enter the V-BLOC (Visual Block) mode. Now moving with the cursor we will see that our selection will be highlighted. At this point we can work on the selected part. If we want to copy the selection to the clipboard we will use the y key. If we want to delete iti, the d key. Once the operation is done, the text will no longer be highlighted. For an overview of all the operations that can be performed in Visual Mode you can consult the help directly from the editor with SHIFT + :help Visual-Mode. ![Help Visual Mode](../images/help_visual_mode.png) ### Text search -To search, the slash character / followed by the search key `/search_key` is used, which highlights all occurrences found. To move to the next one, the combination / + Enter is used. To move to the previous one ? + Enter. Once the changes are finished, the highlighting is removed with the command `:noh` (no highlight). +To search, the slash character / followed by the search key `/search_key` is used, which highlights all occurrences found. To move to the next one, the combination / + Enter is used. To move to the previous one ? + Enter. Once the changes are finished, the highlighting is removed with the command SHIFT + :noh (no highlight). ![Find Command](../images/find_command.png) -Searches can be even more complex than the one illustrated above; wildcards, counters, and other options can be used. The help `:help /` can be used to consult the options. +Searches can be even more complex than the one illustrated above; wildcards, counters, and other options can be used. The help SHIFT + :help / can be used to consult the options. ## Saving the Document -Once the file is created or modified it is saved with the command `:w` (write) which will save the file with the current name in the location it is in, in case you want to save the file with another name or in another location just have the command follow the save path: +Once the file is created or modified it is saved by first exiting the INSERT mode with ESC and then entering the command SHIFT + :w (write) which will save the file with the current name in the location it is in. If you want to save the file with another name or in another location, just have the command follow the save path: ```text :w /path/to/new/file_or_position ``` -To save and simultaneously close the editor, the command `:wq` (write - quit) is used. +To save and simultaneously close the editor, the command SHIFT + :wq (write - quit) is used. -In this chapter we have introduced you to the editor. There are many more advanced features than those described here. These features can be consulted on the [Neovim help](https://neovim.io/doc/user/) page or by typing in the editor `:help`. +In this chapter we have introduced you to the editor. There are many more advanced features than those described here. These features can be consulted on the [Neovim help](https://neovim.io/doc/user/) page or by typing in the editor SHIFT + :help.