diff --git a/docs/books/nvchad/additional_software.md b/docs/books/nvchad/additional_software.md index e2d22378ba..5e26746694 100644 --- a/docs/books/nvchad/additional_software.md +++ b/docs/books/nvchad/additional_software.md @@ -8,45 +8,45 @@ tags: - coding --- -# Additional Software Needed +# :material-cart-plus: Additional Software Needed There are several pieces of additional software that, while not required, will aid in the overall use of NvChad. The sections below will walk you through that software and its uses. -## RipGrep +## :material-text-search: RipGrep -`ripgrep` is a line-oriented search tool that recursively searches the current directory for a _regex_ (regular expression) pattern. By default, _ripgrep_ respects the rules of _gitignore_ and automatically skips hidden files/directories and binaries. Ripgrep offers excellent support on Windows, macOS and Linux, with binaries available for each release. +`ripgrep` is a line-oriented search tool that recursively searches the current directory for a *regex* (regular expression) pattern. By default, *ripgrep* respects the rules of *gitignore* and automatically skips hidden files/directories and binaries. Ripgrep offers excellent support on Windows, macOS and Linux, with binaries available for each release. -### Install RipGrep from EPEL +=== "Install RipGrep from EPEL" -In both Rocky Linux 8 and 9, you can install RipGrep from the EPEL. To do this, install the `epel-release`, upgrade the system, and then install `ripgrep`: + In both Rocky Linux 8 and 9, you can install RipGrep from the EPEL. To do this, install the `epel-release`, upgrade the system, and then install `ripgrep`: -```bash -sudo dnf install -y epel-release -sudo dnf upgrade -sudo dnf install ripgrep -``` + ```bash + sudo dnf install -y epel-release + sudo dnf upgrade + sudo dnf install ripgrep + ``` -### Install RipGrep using `cargo` +=== "Install RipGrep using cargo" -Ripgrep is software written in _Rust_ and is installable with the `cargo` utility. Note, however, that `cargo` is not installed by the default installation of _rust_, so you have to install it explicitly. If you run into errors using this method, revert back to installing from the EPEL. + Ripgrep is software written in *Rust* and is installable with the `cargo` utility. Note, however, that `cargo` is not installed by the default installation of *rust*, so you have to install it explicitly. If you run into errors using this method, revert back to installing from the EPEL. -```bash -dnf install rust cargo -``` + ```bash + dnf install rust cargo + ``` -Once the necessary software is installed, we can install `ripgrep` with: + Once the necessary software is installed, we can install `ripgrep` with: -```bash -cargo install ripgrep -``` + ```bash + cargo install ripgrep + ``` -The installation will save the `rg` executable in the `~/.cargo/bin` folder which is outside the PATH, to use it at the user level we will link it to `~/.local/bin/`. + The installation will save the `rg` executable in the `~/.cargo/bin` folder which is outside the PATH, to use it at the user level we will link it to `~/.local/bin/`. -```bash -ln -s ~/.cargo/bin/rg ~/.local/bin/ -``` + ```bash + ln -s ~/.cargo/bin/rg ~/.local/bin/ + ``` -## RipGrep Verification +## :material-check-all: RipGrep Verification At this point we can check that everything is okay with: @@ -59,9 +59,9 @@ ripgrep 13.0.0 RipGrep is needed for recursive searches with `:Telescope`. -## Lazygit +## :material-source-merge: 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. @@ -72,9 +72,9 @@ sudo dnf install lazygit Once installed we open a terminal and type the command `lazygit` and an interface similar to this will appear: -![LazyGit UI](images/lazygit_ui.png) +![LazyGit UI](./images/lazygit_ui.png) -With the ++x++ key, we can bring up the menu with all available commands. +With the ++"?"++ key, we can bring up the menu with all available commands. ![LazyGit UI](images/lazygit_menu.png) diff --git a/docs/books/nvchad/images/lazygit_menu.png b/docs/books/nvchad/images/lazygit_menu.png index ae1d647928..3c4ef2aa3a 100644 Binary files a/docs/books/nvchad/images/lazygit_menu.png and b/docs/books/nvchad/images/lazygit_menu.png differ diff --git a/docs/books/nvchad/images/lazygit_ui.png b/docs/books/nvchad/images/lazygit_ui.png index 07a4f322ee..88cac71486 100644 Binary files a/docs/books/nvchad/images/lazygit_ui.png and b/docs/books/nvchad/images/lazygit_ui.png differ diff --git a/docs/books/nvchad/index.md b/docs/books/nvchad/index.md index 4dfe49c3f4..c6a131be03 100644 --- a/docs/books/nvchad/index.md +++ b/docs/books/nvchad/index.md @@ -17,9 +17,9 @@ I say "ways" because there are many possibilities. The author focuses here on us Want an IDE that will help in writing Ansible playbooks? You can get that! Want an 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 [lazy.nvim] and [Mason], both of which are covered here. +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 [lazy.nvim](https://github.com/folke/lazy.nvim) and [Mason](https://github.com/williamboman/mason.nvim), 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, 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. +Because Neovim is a fork of [Vim](https://www.vim.org/), 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. @@ -97,7 +97,7 @@ The idea behind the Language Server Protocol (LSP) is to standardize the communi ### :material-file-document-check-outline: tree-sitter -[Tree-sitter] basically consists of two components: a ==parser generator==, and an ==incremental parsing library==. It can build a syntactic tree of the source file and efficiently update it with each change. +[Tree-sitter](https://tree-sitter.github.io/tree-sitter/) basically consists of two components: a ==parser generator==, and an ==incremental parsing library==. It can build a syntactic tree of the source file and efficiently update it with each change. A parser is a component that decomposes data into smaller elements to facilitate its translation into another language, or as in our case, to be then passed to the parsing library. Once the source file has been decomposed, the parsing library parses the code and transforms it into a syntactic tree, allowing the structure of the code to be manipulated more intelligently. This makes it possible to improve (and speed up) @@ -110,10 +110,4 @@ A parser is a component that decomposes data into smaller elements to facilitate 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] needed to configure our NvChad. - -[lazy.nvim]: https://github.com/folke/lazy.nvim -[Mason]: https://github.com/williamboman/mason.nvim -[Tree-sitter]: https://tree-sitter.github.io/tree-sitter/ -[Vim]: https://www.vim.org/ -[Additional Software]: additional_software.md +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 2b7a7a3cd4..e6747ff46e 100644 --- a/docs/books/nvchad/install_nvchad.md +++ b/docs/books/nvchad/install_nvchad.md @@ -6,28 +6,29 @@ tested_with: 8.7, 9.1 tags: - nvchad - coding + - editor --- -# Turning Neovim into an advanced IDE +# :simple-neovim: Turning Neovim into an advanced IDE -## Pre-requisites +## :material-arrow-bottom-right-bold-outline: Pre-requisites As specified on the NvChad site you need to ensure the system meets the following requirements: -- [Neovim 0.8.3](https://github.com/neovim/neovim/releases/tag/v0.8.3). -- [Nerd Font](https://www.nerdfonts.com/) Set it in your terminal emulator. - - Make sure the nerd font you set doesn't end with **Mono** - - **Example:** Iosevka Nerd Font and not ~~Iosevka Nerd Font Mono~~ -- [Ripgrep](https://github.com/BurntSushi/ripgrep) is required for grep searching with Telescope **(OPTIONAL)**. -- GCC +* [Neovim 0.9.4](https://github.com/neovim/neovim/releases/tag/v0.9.4). +* [Nerd Font](https://www.nerdfonts.com/) Set it in your terminal emulator. + * Make sure the nerd font you set doesn't end with **Mono** + * **Example:** Iosevka Nerd Font and not ~~Iosevka Nerd Font Mono~~ +* [Ripgrep](https://github.com/BurntSushi/ripgrep) is required for grep searching with Telescope **(OPTIONAL)**. +* GCC and Make This is actually not a real "installation" but rather writing a custom Neovim configuration for our user. -!!! warning "Performing a Clean Installation" +??? warning "Performing a Clean Installation" As specified in the requirements, installing this new configuration on top of a previous one can create unfixable problems. A clean installation is recommended. -### Preliminary Operations +### :material-content-save-cog-outline: Preliminary Operations If you have used the Neovim installation before, it will have created three folders in which to write your files, which are: @@ -54,23 +55,29 @@ rm -rf ~/.local/share/nvim rm -rf ~/.cache/nvim ``` +## :material-monitor-arrow-down-variant: Installation + Now that we have cleaned up, we can move on to installing NvChad. -To do this, simply run the following command from any location within your _home directory_: +### :octicons-repo-clone-16: Clone configuration + +To do this, simply run the following command from any location within your *home directory*: ```bash git clone https://github.com/NvChad/NvChad ~/.config/nvim --depth 1 && nvim ``` -The first part of the command clones the NvChad repository to the `~/.config/nvim` folder; this is Neovim's default path for searching the user configuration. The `--depth 1` option instructs _git_ to clone only the repository set as "default" on GitHub. +The first part of the command clones the NvChad repository to the ==~/.config/nvim== folder; this is Neovim's default path for searching the user configuration. The ==--depth 1== option instructs *git* to clone only the repository set as "default" on GitHub. + +Once the cloning process is finished in the second part of the command, the Neovim executable (*nvim*) is called, which upon finding a configuration folder will start importing the configurations encountered in the ==init.lua== files of it in a predefined order. -Once the cloning process is finished in the second part of the command, the Neovim executable (_nvim_) is called, which upon finding a configuration folder will start importing the configurations encountered in the `init.lua` files of it in a predefined order. +### :material-timer-cog-outline: Bootstrap -Before starting the bootstrap, the installation will offer us the installation of a base structure (_template chadrc_) for our further customizations: +Before starting the bootstrap, the installation will offer us the installation of a base structure (*template chadrc*) for our further customizations: > Do you want to install chadrc template? (y/n): -Although choosing to install the recommended structure is not mandatory, it is definitely recommended for anyone new to this Editor. Current users of NvChad who already have a `custom` folder will be able to continue using it after making the necessary changes. +Although choosing to install the recommended structure is not mandatory, it is definitely recommended for anyone new to this Editor. Current users of NvChad who already have a ==custom== folder will be able to continue using it after making the necessary changes. The structure created by the template will also be used in this guide for developing the configuration to be used for writing documents in Markdown. @@ -86,9 +93,15 @@ As can be seen from the screenshot below, thanks to the configuration changes ma ![NvChad Rockydocs](images/nvchad_ui.png) -### Configuration Structure +## :material-file-tree-outline: Configuration Structure + +The installed configuration consists of two parts, one part dedicated to the editor that remains under version control (==git==) of the NvChad repository and one dedicated to user customization that is excluded from version control through the use of a ==.gitignore== file. + +This makes it possible to update the editor without compromising personal configuration. -Let us now go on to analyze the structure that the configuration created, the structure is as follows: +### Basic structure + +The part reserved for the editor is as follows: ```text .config/nvim @@ -111,12 +124,13 @@ Let us now go on to analyze the structure that the configuration created, the st │   ├── nvimtree.lua │   ├── others.lua │   ├── telescope.lua - │   ├── treesitter.lua - │   └── whichkey.lua + │   └── treesitter.lua └── init.lua ``` -And if we chose to also install the _template chadrc_ we will also have the `nvim/lua/custom` folder with the following structure: +### Template Structure + +While the part concerning customizations consists of the following structure: ```text .config/nvim/lua/custom/ @@ -128,10 +142,13 @@ And if we chose to also install the _template chadrc_ we will also have the `nvi ├── highlights.lua ├── init.lua ├── mappings.lua -└── plugins.lua +├── plugins.lua +└── README.md ``` -The first file we encounter is the `init.lua` file which initializes the configuration by inserting the `lua/core` folder and `lua/core/utils.lua` (and if present, the `lua/custom/init.lua`) files into the _nvim_ tree. Runs the bootstrap of `lazy.nvim` (the plugin manager) and once finished initialize the `plugins` folder. +## :octicons-file-code-16: Structure analysis + +The first file we encounter is the `init.lua` file which initializes the configuration by inserting the `lua/core` folder and `lua/core/utils.lua` (and if present, the `lua/custom/init.lua`) files into the *nvim* tree. Runs the bootstrap of `lazy.nvim` (the plugin manager) and once finished initialize the `plugins` folder. In particular, the `load_mappings()` function is called for loading keyboard shortcuts. In addition, the `gen_chadrc_template()` function provides the subroutine for creating the `custom` folder. @@ -164,6 +181,14 @@ Inclusion of the `core` folder also results in the inclusion of the `core/init.l As we can see, each `init.lua` file is included following a well-established order. This is used to selectively override the various options from the basic settings. Broadly speaking, we can say that `init.lua` files have the functions to load global options, autocmds, or anything else. +Continuing with the structural 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. + +Finally, we find the ==lazy-lock.json== file. This file allows us to synchronize the configuration of NvChad plugins across multiple workstations, so that we have the same functionality on all the workstations used. Its function will be better explained in the section dedicated to the plugins manager. + +## :material-keyboard-outline: Main keyboard keys + +The installation of NvChad also inserts a set of keys for common commands into the editor, their configuration is contained in the file `lua/core/mappings.lua` and can be modified or extended with the file `lua/custom/mappings.lua`. + This is the call that returns basic command mappings: ```lua @@ -172,27 +197,19 @@ require("core.utils").load_mappings() This sets four main keys from which, in association with other keys, commands can be launched. The main keys are: -- C = ++ctrl++ -- leader = ++space++ -- A = ++alt++ -- S = ++shift++ +* C = ++ctrl++ +* 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: +These are some of the keys set, for an exhaustive list we recommend consulting the file mentioned above. -```text -th to change the theme - to open nvimtree - to open a terminal in a floating tab -``` +`th` to change the theme ++space++ + ++"t"++ + ++"h"++ +`` to open nvimtree ++ctrl++ + ++"n"++ +`` to open a terminal in a floating tab ++alt++ + ++"i"++ There are many combinations pre-set for you, and they cover all the uses of NvChad. It is worth pausing to analyze the key mappings before starting to use your NvChad-configured instance of Neovim. - -Continuing with the structural 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. - -Finally, we find the `lazy-lock.json` file. This file allows us to synchronize the configuration of NvChad plugins across multiple workstations, so that we have the same functionality on all the workstations used. Its function will be better explained in the section dedicated to the plugins manager.