Skip to content

Nvchad template and pages #1111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 12, 2023
Merged

Nvchad template and pages #1111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bfea158
# Template_Chadrc.md changes
sspencerwire Apr 12, 2023
bd86f1d
* forgot to save these changes
sspencerwire Apr 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/books/nvchad/.pages
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,6 @@ nav:
- ... | additional_software*.md
- ... | install_nvim*.md
- ... | install_nvchad*.md
- ... | template_chadrc*.md
- ... | nerd_fonts*.md
- NvChad UI: nvchad_ui
60 changes: 30 additions & 30 deletions docs/books/nvchad/template_chadrc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Chadrc Template
author: Franco Colussi
contributors: Steven Spencer
tested with: 8.7, 9.0
tested with: 8.7, 9.1
tags:
- nvchad
- coding
Expand All @@ -11,17 +11,17 @@ tags:

# Template Chadrc

In version 2.0 of NvChad, the developers introduced the ability to create, during the installation phase, a `custom` folder where you can make your own customizations. The introduction of this feature allows you to have from the start an editor with the basic features of an IDE.
In version 2.0 of NvChad, the developers introduced the ability to create, during the installation phase, a `custom` folder where you can make your own customizations. The introduction of this feature allows you to have an editor with the basic features of an IDE from the start.

The most important aspect of creating the _custom_ folder is writing the files that contain the configurations for setting up some advanced features such as language servers, linters, and formatters. These files allow us to integrate, with just a few changes, the functionality we need.

The folder also contains files for code highlighting and custom command mapping.

The folder is created from an example one ([example-config](https://github.com/NvChad/example_config)) found on NvChad's GitHub repository. To create it during the installation, simply answer "y" to the question we are asked at the beginning of the installation:
The folder is created from an example one on NvChad's GitHub repository: ([example-config](https://github.com/NvChad/example_config)). To create it during the installation, simply answer "y" to the question we are asked at the beginning of the installation:

> Do you want to install chadrc template? (y/N) :

An affirmative answer will start a process that will clone the contents of the _example-config_ folder from GitHub into **~/.config/nvim/lua/custom/** and once finished will remove the **.git** folder from it, this is to allow us to put the configuration under our own version control.
An affirmative answer will start a process that will clone the contents of the _example-config_ folder from GitHub into **~/.config/nvim/lua/custom/** and once finished, will remove the **.git** folder from it. This is to allow us to put the configuration under our own version control.

Upon completion we will have the following structure:

Expand All @@ -39,7 +39,7 @@ custom/
└── README.md
```

As we can see the folder contains some files with the same name also encountered in the basic structure of NvChad, these files allow you to integrate the configuration and override the basic settings of the editor.
As we can see, the folder contains some files with the same name also encountered in the basic structure of NvChad. These files allow you to integrate the configuration and override the basic settings of the editor.

## Structure Analysis

Expand Down Expand Up @@ -87,11 +87,11 @@ Its function is to insert files from our _custom_ folder into the NvChad configu
require "custom.mappings"
```

The string **custom.mappings** indicates the relative path to the file without the extension as opposed to the default path, which in this case is **~/.config/nvim/lua/**, the dot replaces the slash since this is the convention in code written in Lua (in the _lua language_ there is no concept of _directory_).
The string **custom.mappings** indicates the relative path to the file without the extension as opposed to the default path, which in this case is **~/.config/nvim/lua/**. The dot replaces the slash since this is the convention in code written in Lua (in the _lua language_ there is no concept of _directory_).

In summary, we can say that the call described above inserts the configurations written in the **custom/mappings.lua** file into the NvChad mapping thus inserting our shortcuts to invoke the commands of our plugins.

We then have a section that overrides some of the NvChad UI configuration settings contained in **~/.config/nvim/lua/core/default_config.lua**, more specifically the `M.ui` section that allows us, for example, to select light or dark theme.
We then have a section that overrides some of the NvChad UI configuration settings contained in **~/.config/nvim/lua/core/default_config.lua**, more specifically the `M.ui` section that allows us, for example, to select a light or dark theme.

And we also have the inclusion of our plugins defined in **custom/plugins.lua** corresponding to the string:

Expand All @@ -103,7 +103,7 @@ In this way our plugins will be passed along with those that make up the NvChad

#### init.lua

This file is used for overwriting settings defined in **~/.config/nvim/lua/core/init.lua** such as indentation or swap write interval to disk. It is also used for the creation of auto-commands, as described in the commented lines in the file. An example might be the following in which some settings for writing documents in Markdown have been included:
This file is used for overwriting settings defined in **~/.config/nvim/lua/core/init.lua**, such as indentation or swap write interval, to disk. It is also used for the creation of auto-commands, as described in the commented lines in the file. An example might be the following in which some settings for writing documents in Markdown have been included:

```lua
--local autocmd = vim.api.nvim_create_autocmd
Expand All @@ -130,11 +130,11 @@ In this way our settings will replace the default settings.

#### plugins.lua

This file as you can guess from the name is used to add our plugins to those in the basic NvChad configuration, the insertion of plugins is explained in detail on the page dedicated to [Plugins Manager](nvchad_ui/plugins_manager.md).
This file, as you can guess from the name, is used to add our plugins to those in the basic NvChad configuration. The insertion of plugins is explained in detail on the page dedicated to [Plugins Manager](nvchad_ui/plugins_manager.md).

The _plugins.lua_ file created by the _template chadrc_ has in the first part a number of customizations that override the plugin definition options and default plugin configurations, this part of the file does not need to be modified by us as the developers have prepared for the purpose special files present in the _config_ folder.
The _plugins.lua_ file created by the _template chadrc_ has in the first part a number of customizations that override the plugin definition options and default plugin configurations. This part of the file does not need to be modified by us as the developers have prepared special files for this purpose that are present in the _config_ folder.

Then follows the installation of a plugin, this is set up as an example so that you can begin to become familiar with the format used by _lazy.nvim_ which differs slightly from the format used by _packer.nvim_ the handler used in version 1.0.
Then follows the installation of a plugin. This is set up as an example so that you can begin to become familiar with the format used by _lazy.nvim_ which differs slightly from the format used by _packer.nvim_, the handler used in version 1.0.

```lua
-- Install a plugin
Expand All @@ -147,7 +147,7 @@ Then follows the installation of a plugin, this is set up as an example so that
},
```

After this plugin and before the last bracket we can insert all our plugins, there is a whole ecosystem of plugins suitable for every purpose, for an initial overview you can visit [Neovimcraft](https://neovimcraft.com/).
After this plugin and before the last bracket we can insert all our plugins. There is a whole ecosystem of plugins suitable for every purpose. For an initial overview you can visit [Neovimcraft](https://neovimcraft.com/).

#### mappings.lua

Expand All @@ -163,19 +163,19 @@ M.general = {
}
```

In this mapping is entered for the NORMAL state `n =` the character <kbd>;</kbd> which when pressed on the keyboard plays the character <kbd>:</kbd>, this character is the character used to enter COMMAND mode, the option `nowait = true` is also set to enter that mode immediately. In this way on a keyboard with a US QWERTY layout we will not need to use <kbd>SHIFT</kbd> to enter COMMAND mode.
This mapping is entered for the NORMAL state `n =` the character <kbd>;</kbd> which when pressed on the keyboard plays the character <kbd>:</kbd>. This character is the character used to enter COMMAND mode. The option `nowait = true` is also set to enter that mode immediately. In this way on a keyboard with a US QWERTY layout, we will not need to use <kbd>SHIFT</kbd> to enter COMMAND mode.

!!! Tip

For users of European keyboards (such as Italian), it is recommended to substitute the character <kbd>;</kbd> with <kbd>,</kbd>.
For users of European keyboards (such as Italian), it is recommended to substitute the character <kbd>;</kbd> with <kbd>,</kbd>.

#### highlights.lua

The file is used to customize the style of the editor, the settings written here go to change aspects such as font style (**bold**,_italic_) background color of an element, foreground color, etc..
The file is used to customize the style of the editor. The settings written here are used to change aspects such as font style (**bold**,_italic_), background color of an element, foreground color, etc..

### Configs folder

The files in this folder are all configuration files that are used in the **custom/plugins.lua** file to change the default settings of the plugins that deal with language servers (_lspconfig_) and linter/formatters (_null-ls_) and for overriding the basic settings of **treesitter**, **mason**, and **nvim-tree** (_override_).
The files in this folder are all configuration files that are used in the **custom/plugins.lua** file to change the default settings of the plugins that deal with language servers (_lspconfig_), linter/formatters (_null-ls_), and for overriding the basic settings of **treesitter**, **mason**, and **nvim-tree** (_override_).

```text
configs/
Expand All @@ -186,27 +186,27 @@ configs/

#### lspconfig.lua

The _lspconfig.lua_ file sets the local language servers that the editor can use, this will allow for advanced features for supported files such as autocomplete or snippets for quick creation of pieces of code. To add our _lsp_ to the configuration, we simply edit the table (in _lua_ what is rapprented below in curly brackets is a table) prepared especially by the NvChad developers:
The _lspconfig.lua_ file sets the local language servers that the editor can use. This will allow for advanced features for supported files, such as autocomplete or snippets, for quick creation of pieces of code. To add our _lsp_ to the configuration, we simply edit the table (in _lua_ what is represented below in curly brackets is a table) prepared especially by the NvChad developers:

```lua
local servers = { "html", "cssls", "tsserver", "clangd" }
```

As we can see some servers are already set up by default, to add a new one simply enter it at the end of the table. The available servers can be found at [this link](https://github.com/williamboman/mason.nvim/blob/main/PACKAGES.md) and for their configurations you can refer to this [page](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md).
As we can see some servers are already set up by default. To add a new one simply enter it at the end of the table. The available servers can be found at [mason packages](https://github.com/williamboman/mason.nvim/blob/main/PACKAGES.md) and for their configurations you can refer to [lsp server configurations](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md).

For example if we also want to have support for the `yaml` language we can add it as in the following example:

```lua
local servers = { "html", "cssls", "tsserver", "clangd", "yamlls" }
```

Changing the file, however, does not involve installing the related language server; this will have to be installed separately with _Mason_. The language server that provides support for _yaml_ is [yaml-language-server](https://github.com/redhat-developer/yaml-language-server) which we will have to install with the command `:MasonInstall yaml-language-server`. At this point we will have, for example, control of the code written in the headers (_frontmatter_) of the Rocky Linux documentation pages.
Changing the file, however, does not involve installing the related language server. This will have to be installed separately with _Mason_. The language server that provides support for _yaml_ is [yaml-language-server](https://github.com/redhat-developer/yaml-language-server) which we will have to install with the command `:MasonInstall yaml-language-server`. At this point we will have, for example, control of the code written in the headers (_frontmatter_) of the Rocky Linux documentation pages.

#### null-ls.lua

This file takes care of configuring some features geared toward control and formatting of written code; editing this file requires a bit more research for configuration than the previous file. An overview of the available components can be referred to this [page](https://github.com/jose-elias-alvarez/null-ls.nvim/blob/main/doc/BUILTINS.md).
This file takes care of configuring some features geared toward control and formatting of written code. Editing this file requires a bit more research for configuration than the previous file. An overview of the available components can be found on [the builtins page](https://github.com/jose-elias-alvarez/null-ls.nvim/blob/main/doc/BUILTINS.md).

Again, a table has been set up, the `local sources` table where we can enter our customizations, which we can see below:
Again, a table has been set up, the `local sources` table, where we can enter our customizations which we can see below:

```lua
local sources = {
Expand All @@ -222,7 +222,7 @@ local sources = {
}
```

As we can see in the initial configuration only formatters were included but we might for example need a diagnostic for the Markdown language and in that case we could add [Markdownlint](https://github.com/DavidAnson/markdownlint) like this:
As we can see, in the initial configuration only formatters were included, but we might for example need a diagnostic for the Markdown language and in that case we could add [Markdownlint](https://github.com/DavidAnson/markdownlint) like this:

```lua
-- diagnostic markdown
Expand All @@ -241,11 +241,11 @@ Again, the configuration needs the installation of the related package, which we

#### overrides.lua

The _overrides.lua_ file contains the changes to be made to the default plugin settings; the plugins to which the changes are to be applied are specified in the `-- override plugin configs` section of the **custom/plugins.lua** file through the use of the `opts` option (e.g. `opts = overrides.mason`).
The _overrides.lua_ file contains the changes to be made to the default plugin settings. The plugins to which the changes are to be applied are specified in the `-- override plugin configs` section of the **custom/plugins.lua** file through the use of the `opts` option (e.g. `opts = overrides.mason`).

In the initial configuration there are three plugins marked as needing to be overridden and they are _treesitter_, _mason_ and _nvim-tree_, leaving out _nvim-tree_ for the moment we will focus on the first two that allow us to change our editing experience significantly.
In the initial configuration there are three plugins marked as needing to be overridden and they are _treesitter_, _mason_ and _nvim-tree_. Leaving out _nvim-tree_ for the moment, we will focus on the first two that allow us to change our editing experience significantly.

_treesitter_ is a code parser that takes care of its formatting in an interactive way, whenever we save a file recognized by _treesitter_ it is passed to the parser which returns an optimally indented and highlighted code tree, so it will be easier to read, interpret and edit the code in the editor.
_treesitter_ is a code parser that takes care of its formatting in an interactive way. Whenever we save a file recognized by _treesitter_ it is passed to the parser which returns an optimally indented and highlighted code tree, so it will be easier to read, interpret and edit the code in the editor.

The part of the code that deals with this is as follows:

Expand Down Expand Up @@ -292,7 +292,7 @@ To have the parser available directly in the running instance of NvChad we can a
:TSInstall yaml
```

Following in the file is the part regarding the installation of servers by _Mason_, all servers set in this table are installed in one operation with the command `:MasonInstallAll` (this command is also invoked during the creation of the _custom_ folder). The part is as follows:
Following in the file is the part regarding the installation of servers by _Mason_. All servers set in this table are installed in one operation with the command `:MasonInstallAll` (this command is also invoked during the creation of the _custom_ folder). The part is as follows:

```lua
M.mason = {
Expand All @@ -311,7 +311,7 @@ M.mason = {
}
```

Again following the initial example where we enabled support for _yaml_ by manually installing the server we can make sure we always have it installed by adding it to the table:
Again, following the initial example where we enabled support for _yaml_ by manually installing the server, we can make sure we always have it installed by adding it to the table:

```text
...
Expand All @@ -326,7 +326,7 @@ Again following the initial example where we enabled support for _yaml_ by manua

Although this aspect may be marginal on a running instance of NvChad since we can always manually install the missing servers it turns out to be very useful during the transfer of our configuration from one machine to another.

For example, suppose we have configured our `custom` folder with all the features we need and we want to transfer it to another installation of NvChad, if we have configured this file, after copying or cloning our `custom` folder a `:MasonInstallAll` will be sufficient to have all the servers ready to use on the other installation as well.
For example, suppose we have configured our `custom` folder with all the features we need and we want to transfer it to another installation of NvChad. If we have configured this file, after copying or cloning our `custom` folder a `:MasonInstallAll` will be sufficient to have all the servers ready to use on the other installation as well.

The final part of the configuration, the `M.nvimtree` section, takes care of configuring _nvim-tree_ by enabling the functionality to display the state in the file tree with respect to the git repository:

Expand All @@ -351,6 +351,6 @@ their highlighting and corresponding icons:

## Conclusion

The introduction in NvChad 2.0 of the possibility to create a `custom` folder already at the first installation is certainly a great help for all those users who are approaching this editor for the first time, but it is also a considerable time-saver for those who have already dealt with NvChad.
The introduction in NvChad 2.0 of the possibility to create a `custom` folder during the first installation is certainly a great help for all those users who are approaching this editor for the first time. It is also a considerable time-saver for those who have already dealt with NvChad.

Thanks of its introduction, and along with the use of _Mason_, it is very easy and fast to integrate your own functionality; it only takes a few changes and you are immediately ready to use the IDE to write code.
Thanks to its introduction, and along with the use of _Mason_, it is very easy and fast to integrate your own functionality. It only takes a few changes and you are immediately ready to use the IDE to write code.