Nvchad main

docs/books/nvchad/.pages

@@ -0,0 +1,9 @@
+---
+nav:
+    - ... | index*.md
+    - ... | additional_software*.md
+    - ... | install_nvim*.md
+    - ... | install_nvchad*.md
+    - ... | nerd_fonts*.md
+    - NvChad UI: nvchad_ui
+    - Customisation: custom

docs/books/nvchad/additional_software.md

@@ -0,0 +1,67 @@
+---
+title: Additional Software
+author: Franco Colussi
+contributors: Steven Spencer
+tested with: 8.6, 9.0
+tags:
+    - nvchad
+    - coding
+---
+
+# 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
+
+`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 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.
+
+```bash
+dnf install rust cargo
+```
+
+Once the necessary software is installed, we can install `ripgrep` with:
+
+```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/`.
+
+```bash
+ln -s ~/.cargo/bin/rg ~/.local/bin/
+```
+
+At this point we can check that everything is okay with:
+
+```bash
+rg --version
+ripgrep 13.0.0
+-SIMD -AVX (compiled)
++SIMD +AVX (runtime)
+```
+
+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.
+
+To install it we can use the repository for Fedora. On Rocky Linux 9 it works perfectly.
+
+```bash
+sudo dnf copr enable atim/lazygit -y
+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)
+
+With the <kbd>x</kbd> 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. We will start with the editor on which the whole configuration is based, [Neovim](install_nvim.md).

docs/books/nvchad/custom/.pages

@@ -0,0 +1,9 @@
+---
+nav:
+    - ... | custom_folder*.md
+    - ... | chadrc_lua*.md
+    - ... | init_lua*.md
+    - ... | mappings_lua*.md
+    - ... | override_lua*.md
+    - Plugins: plugins
+    - ... | lsp*.md

docs/books/nvchad/custom/chadrc_lua.md

@@ -0,0 +1,59 @@
+---
+title: chadrc.lua
+author: Franco Colussi
+contributors: Steven Spencer
+tested with: 8.6, 9.0
+tags:
+    - nvhad
+    - coding
+    - editor
+---
+
+# `chadrc.lua`
+
+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. That order is `core` -> `custom` -> `plugins`.
+
+The contents of the `chadrc.lua` file are as follows:
+
+```lua
+local M = {}
+local override = require("custom.override")
+
+M.ui = {
+    theme = "everforest",
+    theme_toggle = { "everforest", "everforest_light" },
+}
+
+M.mappings = require("custom.mappings")
+
+M.plugins = {
+  user = require("custom.plugins"),
+  override = {
+    ["kyazdani42/nvim-tree.lua"] = override.nvimtree,
+    ["nvim-treesitter/nvim-treesitter"] = override.treesitter,
+    ["lukas-reineke/indent-blankline.nvim"] = override.blankline,
+  },
+}
+
+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 in 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 <kbd>SHIFT</kbd> + <kbd>:PackerSync</kbd> from NORMAL mode in the editor.
+
+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.
+
+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, the inclusion of *our* files in the NvChad configuration.

docs/books/nvchad/custom/custom_folder.md

@@ -0,0 +1,105 @@
+---
+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 `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 `custom` folder which **must** be placed in `.config/nvim/lua/`, and is designed to house all of your custom configuration files. Below we have a representation of the basic structure of a standard NvChad installation. 
+
+```text
+nvim/
+├── examples
+│   ├── chadrc.lua
+│   └── init.lua
+├── init.lua
+├── LICENSE
+├── lua
+│   ├── core
+│   └── plugins
+└── plugin
+    └── packer_compiled.lua
+```
+
+### Structure Creation
+
+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
+```
+
+The structure of the `nvim/lua` folder should now look like this:
+
+```text
+├── lua
+│   ├── core
+│   ├── custom
+│   │   └── plugins
+│   └── plugins
+```
+
+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 
+plugin
+custom
+spell
+```
+
+### Structure of the Custom Folder
+
+The structure of the _custom_ folder used for this guide is as follows:
+
+```text
+custom/
+├── chadrc.lua
+├── init.lua
+├── mappings.lua
+├── override.lua
+└── plugins
+    ├── init.lua
+    └── 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.
+
+- `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 = {
+  theme = "everforest",
+}
+```
+
+- `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 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 can be set in _mappings.lua_ like so:
+
+```lua
+["\\\\"] = { "<cmd> Telescope find_files<CR>", "file finder" },
+```
+
+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 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. 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.

docs/books/nvchad/custom/init_lua.md

@@ -0,0 +1,37 @@
+---
+title: init.lua 
+author: Franco Colussi
+contributors: Steven Spencer
+tested with: 8.6, 9.0
+tags:
+    - nvchad
+    - coding
+    - editor
+---
+
+# `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.
+
+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:
+
+```lua
+vim.cmd [[autocmd BufWritePre * lua vim.lsp.buf.formatting_sync()]]
+-- on 0.8, you should use vim.lsp.buf.format({ bufnr = bufnr }) instead
+
+local opt = vim.opt
+
+opt.tabstop = 4
+opt.softtabstop = 4
+opt.shiftwidth = 4
+opt.shiftround = false
+opt.expandtab = true
+opt.autoindent = true
+opt.smartindent = true
+```
+
+In our example we used an auto-command for synchronous buffer formatting and options.
+
+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.