diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 3f2111b..e825e03 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -17,23 +17,23 @@ diverse, inclusive, and healthy community.
Examples of behavior that contributes to a positive environment for our
community include:
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
+- Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
-* The use of sexualized language or imagery, and sexual attention or
+- The use of sexualized language or imagery, and sexual attention or
advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
@@ -106,7 +106,7 @@ Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
+standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
diff --git a/docs/README.md b/docs/README.md
index 3f39a66..8cc69e2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,8 +4,8 @@ Doom Nvim is a port to Neovim of the [Doom Emacs](https://github.com/hlissner/do
configuration framework for [GNU Emacs](https://www.gnu.org/software/emacs/) adapted
for all vimmer who want less framework in their framework and the performance of
a handmade configuration (or better). It can be a base for your own setup or a
-resource for Vim enthusiasts to learn more about our favorite editor and how to
-do X things on it by using Vimscript/Lua.
+resource for Neovim enthusiasts to learn more about our favorite editor and how to
+do X things on it by using Lua.
Doom Nvim is an opinionated collection of reasonable (and optional) defaults with
a focus on performance (both runtime and startup) and on abstraction-light, readable
@@ -15,6 +15,7 @@ code design, so that there is less between you and Neovim.
> `:h doom_nvim`.
# Table of Contents
+
- [Documentation](#documentation)
- [Getting Started](#getting-started)
- [Modules](#modules)
@@ -43,7 +44,6 @@ code design, so that there is less between you and Neovim.
- [Suggesting features, keybinds and enhancements](./contributing.md#suggesting-features-keybinds-and-enhancements)
- [Contributing code](./contributing.md#contributing-code)
-
# Community Resources
## Asking for help
diff --git a/docs/contributing.md b/docs/contributing.md
index 245aee5..4cf24b2 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -42,17 +42,10 @@ and which code style you should use :heart:
## Acquire a backtrace from errors
-All the errors ocurred in Doom Nvim are saved into a `doom.log` file inside a `logs/`
-directory inside your Doom Nvim root dir (`$HOME/.config/doom-nvim` by default).
+All the errors ocurred in Doom Nvim are saved into a `doom.log` file inside the
+`~/.local/share/nvim/` directory.
If the logs are very long, please paste it using a [gist].
-> **NOTE:** Alternatively you can paste the most recent lines starting with the
-> following if the logs are extremely long.
->
-> [!] - Errors
->
-> [!!!] - Critical errors
-
## Create a step-by-step reproduction guide
A step-by-step guide can help considerably to debug the error that occurs and
@@ -84,10 +77,9 @@ type of issue and handle the requests.
Doom Nvim follows some code style rules like ones the mentioned below:
-- Single quotes instead of double quotes.
+- Single quotes over double quotes.
- Variable names in `snake_case`, except in the BASH installation script.
-- Function names in `snake_case`, the only exception are the Vimscript functions
- which does not are from doom itself, e.g. `function ToggleTerm() ... endfunction`.
+- Function names in `snake_case`.
- [stylua] is used to format lua files with the following configuration:
```toml
@@ -99,6 +91,16 @@ quote_style = "AutoPreferSingle"
```
+> **NOTE:** use `--config-path /path/to/doom/nvim/stylua.toml` to use doom's
+> stylua configuration.
+
+- [selene] is a blazing-fast modern Lua linter written in Rust which is used for
+ linting doom's source code. We make use of some custom rules so we can be sure
+ that selene will not raise false errors.
+
+> **NOTE:** use `selene .` in doom's root dir and selene will automatically
+> detect the `selene.toml` and `doom.toml` files.
+
### Commits & PRs
- Target `develop` instead of `main`.
@@ -106,8 +108,8 @@ quote_style = "AutoPreferSingle"
### Keybind conventions
-- The keybindings should be declared in [config/keybindings](../lua/doom/keybindings.lua),
- except when they are keybindings of [Lua plugins](../lua/plugins/configs).
+- The keybindings should be declared in [core/keybindings](../lua/doom/core/keybindings/init.lua),
+ except when they are keybindings of [Lua plugins](../lua/doom/modules/config).
## Submitting pull requests
@@ -116,3 +118,4 @@ they work and do not break any of the current code, you can proceed to upload
your pull request :)
[stylua]: https://github.com/JohnnyMorganz/StyLua
+[selene]: https://github.com/Kampfkarren/selene
diff --git a/docs/faq.md b/docs/faq.md
index f74b396..9071144 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -1,6 +1,7 @@
# Frequently Asked Questions
# Table of Contents
+
- [General](#general)
- [What type of vimmer is Doom Nvim intended for?](#what-type-of-vimmer-is-doom-nvim-intended-for)
- [Why does Doom Nvim only support Neovim nightly?](#why-does-doom-nvim-only-support-neovim-nightly)
@@ -15,6 +16,7 @@ development environment without spending a lot of time setting everything up.
## Why does Doom Nvim only support Neovim nightly?
Doom Nvim doesn't support Neovim versions lower than Nightly (0.5) due to:
+
- some features would be lost
- Not all Lua plugins have good alternatives in Vimscript, so the experience
would not be the same
diff --git a/docs/getting_started.md b/docs/getting_started.md
index 014ed76..9e63817 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -17,12 +17,13 @@
- [On MacOS](#on-macos)
- [On Windows](#on-windows)
- [Doom Nvim](#doom-nvim)
+ - [Using cheovim](#using-cheovim)
- [Update & Rollback](#update--rollback)
- [Update Doom Nvim](#update-doom-nvim)
- [Rollback](#rollback)
- [Configuration](#configuration)
- [Modules](#modules)
- - [Package Management](#package-management)
+ - [Plugins Management](#plugins-management)
- [Installing plugins](#installing-plugins)
- [Disabling plugins](#disabling-plugins)
- [Configuring Doom](#configuring-doom)
@@ -58,6 +59,8 @@ of your distribution, so you have several options to install it.
2. Using extra repositories according to your distribution (PPA/COPR/AUR/etc).
+3. Using a Neovim version manager like [nvenv](https://github.com/NTBBloodbath/nvenv).
+
#### Ubuntu
You can get nightly builds of git master from the
@@ -68,6 +71,17 @@ add-apt-repository ppa:neovim-ppa/unstable
apt-get update
```
+#### Fedora
+
+Nightly builds can be installed by using the
+[agriffis/neovim-nightly](https://copr.fedorainfracloud.org/coprs/agriffis/neovim-nightly/)
+COPR repository.
+
+```sh
+dnf copr enable agriffis/neovim-nightly
+dnf update
+```
+
#### Arch
Neovim Nightly builds can be installed using the PKGBUILD
@@ -76,9 +90,18 @@ available on the [AUR](https://wiki.archlinux.org/index.php/Arch_User_Repository
### On MacOS
-Neovim nightly can be installed with [homebrew](https://brew.sh/) with the following command.
+You can download a prebuilt binary from the [Neovim](https://github.com/neovim/neovim/releases/tag/nightly) nightly releases page.
+
+1. Download: `curl -LO https://github.com/neovim/neovim/releases/download/nightly/nvim-macos.tar.gz`
+2. Extract: `tar xzvf nvim-macos.tar.gz`
+3. Run: `./nvim-osx64/bin/nvim`
+
+You may wish to add it to your PATH using something like:
+`export PATH="$HOME/nvim-osx64/bin:$PATH"`
-`brew install --HEAD neovim`
+Neovim nightly can also be downloaded with [homebrew](https://brew.sh/):
+
+`brew install --HEAD neovim` will download the source and build it locally on your machine.
If you already have Neovim v4 installed you may need to unlink it.
@@ -124,8 +147,10 @@ You can also download a prebuilt binary from the [Neovim](https://github.com/neo
```sh
# Required dependencies
apt-get install git ripgrep
+
# (Optional) Improves performance for many file indexing commands
apt-get install fd-find
+
# (Optional) Required by Language Server Protocols
apt-get install nodejs npm
```
@@ -135,8 +160,10 @@ apt-get install nodejs npm
```sh
# Required dependencies
dnf install git ripgrep
+
# (Optional) Improves performance for many file indexing commands
dnf install fd-find # is 'fd' in Fedora <28
+
# (Optional) Required by Language Server Protocols
dnf install nodejs
```
@@ -146,8 +173,10 @@ dnf install nodejs
```sh
# Required dependencies
pacman -S git ripgrep
+
# (Optional) Improves performance for many file indexing commands
pacman -S fd
+
# (Optional) Required by Language Server Protocols
pacman -S nodejs npm
```
@@ -192,6 +221,19 @@ curl -sLf https://raw.githubusercontent.com/NTBBloodbath/doom-nvim/main/install.
The installation script will set up everything for you and will work you through
the first-time setup of Doom Nvim.
+### Using cheovim
+
+If you're using cheovim as your Neovim configurations manager you can use the
+recipe listed in cheovim documentation:
+
+```lua
+doom_nvim = { "~/.config/doom-nvim", {
+ plugins = "packer",
+ preconfigure = "doom-nvim"
+ }
+}
+```
+
# Update & Rollback
## Update Doom Nvim
@@ -209,11 +251,11 @@ and restore the backup of your previous setup.
You can configure Doom Nvim by tweaking the file `doomrc` in your Doom Nvim root
dir (`$HOME/.config/doom-nvim/` by default), please see
-:h doom_nvim for more information.
+:h doom_nvim_options for more information.
> **IMPORTANT:** any changes to your Doom Nvim configuration occassionally
-> need a run of `:PackerSync` inside Neovim. For instance, when you enable
-> a disabled plugin.
+> need a run of `:PackerSync` inside Neovim (if you're using the stable branch).
+> For instance, when you enable a disabled plugin.
## Modules
@@ -221,21 +263,21 @@ Doom Nvim consists of around 7 modules and growing. A Doom Nvim Module is a bund
configuration and commands, organized into a unit that can be toggled easily by
tweaking your doomrc (found in `$HOME/.config/doom-nvim`).
-Please see [Package Management](#package-management) for more information.
+Please see [Plugins Management](#plugins-management) for more information.
> **IMPORTANT:** any changes to your Doom Nvim Modules won't take effect until
> you run `:PackerSync` inside Neovim.
-## Package Management
+## Plugins Management
-Doom Nvim does not use Vim-Plug in the Neovim Nightly version. Instead, it uses
-a declarative and use-package inspired package manager called
+Doom Nvim uses a declarative and use-package inspired package manager called
[packer.nvim](https://github.com/wbthomason/packer.nvim).
-Modules and plugins are declared in `lua/plugins/init.lua` file, located in your Doom Nvim root dir.
-Read on to learn how to use this system to install your own plugins.
+Modules and plugins are declared in `lua/doom/modules/init.lua` file, located
+in your Doom Nvim root dir. Read on to learn how to use this system to install
+your own plugins.
-> **WARNING:** Do not install plugins directly in `lua/plugins/init.lua`. Instead,
+> **WARNING:** Do not install plugins directly in `lua/doom/modules/init.lua`. Instead,
> use your `doomrc` to modify them.
### Installing plugins
@@ -248,22 +290,25 @@ in your `doomrc`.
custom_plugins = { 'plugin_author/plugin_repo' }
```
-You can also use other method if the plugin depends on other plugins.
+You can also use other method if the plugin depends on other plugins. All the
+available options for the plugins can be found on
+[packer.nvim](https://github.com/wbthomason/packer.nvim) README file.
```lua
custom_plugins = {
'plugin_author/plugin_repo',
{
- 'repo': 'plugin_author/second_plugin_repo',
- 'enabled': true, -- not required, true by default
- 'requires': { 'foo', 'bar' } -- not required if the plugin does not have dependencies
+ 'plugin_author/second_plugin_repo',
+ disable = false, -- not required, false by default
+ requires = { 'foo', 'bar' } -- not required if the plugin does not have dependencies
},
}
```
> **NOTES:**
>
-> 1. Do not forget to run `:PackerInstall` to install your new plugins.
+> 1. Do not forget to run `:PackerInstall` to install your new plugins if you're
+> using the stable branch of Doom Nvim.
### Disabling plugins
@@ -275,12 +320,13 @@ To disable plugins from Doom Nvim Modules or disable a module itself, just use t
disabled_plugins = { 'terminal', 'treesitter' }
-- @default = { 'git', 'lsp', 'web' }
-let g:doom_disabled_modules = { 'web' }
+disabled_modules = { 'web' }
```
> **NOTES:**
>
-> 1. Do not forget to run `:PackerSync` or your changes won't take effect.
+> 1. Do not forget to run `:PackerSync` or your changes won't take effect if you're
+> using the stable branch of Doom Nvim.
>
> 2. You can see a list of the plugins that you can disable on [Modules](./modules.md#list-of-modules).
>
@@ -291,19 +337,19 @@ let g:doom_disabled_modules = { 'web' }
### Configuring settings
You can change Doom's default settings by tweaking your `doomrc`, please see
-:h doom_nvim to know how to.
+:h doom_nvim_options to know how to.
### Configuring plugins
Do you want to change some configurations of some modules?
-Go to `lua/plugins/configs` dir and you will find the configurations for the plugins.
+Go to `lua/doom/modules/config` dir and you will find the configurations for the plugins.
#### Configuring LSP
[LSP](https://microsoft.github.io/language-server-protocol/) is installed as a plugin.
Be aware that this plugin is disabled per default. To enable it, remove it from the
-`Disabled plugins` section in your `doomrc`.
+`disabled_modules` section in your `doomrc`.
To easily install LSPs and without having to do it system-wide or having to
manually configure servers, Doom Nvim makes use of [kabouzeid/nvim-lspinstall](https://github.com/kabouzeid/nvim-lspinstall).
@@ -319,5 +365,5 @@ You can see a list of currently supported languages at [bundled installers](http
You can modify the default keybindings by modifying the following files:
-- `lua/doom/keybindings/init.lua` - General and SPC keybindings
-- `lua/plugins/configs` - lua plugins keybindings
+- `lua/doom/core/keybindings/init.lua` - General and SPC keybindings
+- `lua/doom/modules/config` - lua plugins keybindings
diff --git a/docs/modules.md b/docs/modules.md
index 3afe4f5..2536241 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -55,7 +55,7 @@ including their plugins individually.
- Use `tree` to disable it
- [x] [galaxyline.nvim] - galaxyline is a light-weight and Super Fast statusline plugin.
- Use `statusline` to disable it
- - [x] [barbar.nvim] - Tabs, as understood by any other editor.
+ - [x] [nvim-bufferline.lua] - Tabs, as understood by any other editor.
- Use `tabline` to disable it
- [x] [nvim-toggleterm.lua] - A neovim plugin to persist and toggle multiple terminals during an editing session
- Use `terminal` to disable it
@@ -98,6 +98,10 @@ including their plugins individually.
- **NOTE:** do not disable it if you are going to use LSP!
- [x] [nvim-compe] - Auto completion plugin for nvim that written in Lua.
- Use `compe` to disable it
+ - [x] [lspsaga.nvim] - A light-weight lsp plugin based on neovim built-in lsp with highly a performant UI.
+ - Use `lspsaga` to disable it
+ - [x] [nvim-lspinstall] - Provides the missing :LspInstall for nvim-lspconfig.
+ - Use `lspinstall` to disable it
### Files
@@ -109,9 +113,9 @@ including their plugins individually.
- Use `suda` to disable it
- [x] [format.nvim] - Neovim lua plugin to format the current buffer with external executables.
- Use `formatter` to disable it
- - [x] [pears.nvim] - Auto pair plugin for neovim
+ - [x] [nvim-autopairs] - A super powerful autopairs for Neovim.
- Use `autopairs` to disable it
- - [x] [indentLine] - A vim plugin to display the indention levels with thin vertical lines
+ - [x] [indent-blankline.nvim] - Indent guides for Neovim
- Use `indentlines` to disable it
- [x] [editorconfig-vim] - EditorConfig support
- Use `editorconfig` to disable it
@@ -188,7 +192,7 @@ disabled_plugins = { 'emmet' }
[dashboard-nvim]: https://github.com/glepnir/dashboard-nvim
[nvim-tree.lua]: https://github.com/kyazdani42/nvim-tree.lua
[galaxyline.nvim]: https://github.com/glepnir/galaxyline.nvim
-[barbar.nvim]: https://github.com/romgrk/barbar.nvim
+[nvim-bufferline.lua]: https://github.com/akinsho/nvim-bufferline.lua
[nvim-toggleterm.lua]: https://github.com/akinsho/nvim-toggleterm.lua
[symbols-outline.nvim]: https://github.com/simrat39/symbols-outline.nvim
[minimap.vim]: https://github.com/wfxr/minimap.vim
@@ -207,11 +211,16 @@ disabled_plugins = { 'emmet' }
[nvim-lspconfig]: https://github.com/neovim/nvim-lspconfig
-[nvim-compe]:
+[nvim-compe]: https://github.com/hrsh7th/nvim-compe
+[lspsaga.nvim]: https://github.com/glepnir/lspsaga.nvim
+[nvim-lspinstall]: https://github.com/kabouzeid/nvim-lspinstall
+
+
+
[suda.vim]: https://github.com/lambdalisue/suda.vim
[format.nvim]: https://github.com/lukas-reineke/format.nvim
-[pears.nvim]: https://github.com/steelsojka/pears.nvim
-[indentline]: https://github.com/Yggdroot/indentLine
+[nvim-autopairs]: https://github.com/windwp/nvim-autopairs
+[indent-blankline.nvim]: https://github.com/lukas-reineke/indent-blankline.nvim
[editorconfig-vim]: https://github.com/editorconfig/editorconfig-vim
[kommentary]: https://github.com/b3nj5m1n/kommentary
diff --git a/lua/colors/README.md b/lua/colors/README.md
new file mode 100644
index 0000000..36efdbb
--- /dev/null
+++ b/lua/colors/README.md
@@ -0,0 +1,59 @@
+# Colors
+
+This module contains the embedded colorschemes for Doom Nvim and the utils
+module required by those colorschemes.
+
+Actually the embedded colorschemes are the following:
+
+- doom-one (dark and light variant)
+
+## utils
+
+The utils module contains a few utilities for easily port Doom Emacs colorschemes
+to Lua colorschemes. These utilities are the following:
+
+- `Lighten` - lighten the provided HEX color in X percentage (5 by default).
+- `Darken` - darken the provided HEX color in X percentage (5 by default).
+- `Mix` - mix two provided HEX colors in X percentage (0 by default)
+
+## Contributing
+
+### Write colorschemes
+
+If you want to write colorschemes for Doom Nvim you will need to follow some
+requirements.
+
+- The colorscheme should be a Doom Emacs colorscheme, see [emacs-doom-themes].
+- The colorscheme should be written in pure Lua **without using helpers like lush**,
+ you can take a look at [doom-one] source or use it as a template (highly recommended).
+
+### Update embedded colorschemes
+
+If you want to update the embedded colorschemes like [doom-one] you'll need to
+copy the doom-one files to the proper locations and change a few lines to match
+Doom Nvim structure.
+
+- Changes in `colors/doom-one.lua`:
+
+```lua
+--- FROM:
+package.loaded['doom-one'] = nil
+require('doom-one')
+
+--- TO:
+package.loaded['colors.doom-one'] = nil
+require('colors.doom-one')
+```
+
+- Changes in `doom-one/init.lua`:
+
+```lua
+--- FROM:
+local utils = require('utils')
+
+--- TO:
+local utils = require('colors.utils')
+```
+
+[doom-one]: https://github.com/NTBBloodbath/doom-one.nvim
+[emacs-doom-themes]: https://github.com/hlissner/emacs-doom-themes
diff --git a/lua/doom/README.md b/lua/doom/README.md
new file mode 100644
index 0000000..f6231b1
--- /dev/null
+++ b/lua/doom/README.md
@@ -0,0 +1,11 @@
+# Doom
+
+This is the entry point module for Doom Nvim. Herein lies the core of Doom
+divided into three different sub-modules.
+
+- [core](./core/README.md) - The Doom core, herein lies the entire Doom core,
+ e.g. configurations, keybindings.
+- [modules](./modules/README.md) - The Doom modules, herein lies the Doom plugins
+ and their configurations.
+- [utils](./utils/README.md) - The Doom utilities, herein lies the Doom utility
+ functions.
diff --git a/lua/doom/core/README.md b/lua/doom/core/README.md
new file mode 100644
index 0000000..45b4d3b
--- /dev/null
+++ b/lua/doom/core/README.md
@@ -0,0 +1,15 @@
+# Core
+
+Herein lies the core of Doom. In other words, the modules needed for Doom to
+be Doom.
+
+Those modules are the following:
+
+- autocmds - Doom autocommands.
+- config - Doom configurations, handles doomrc file and UI settings.
+- default - Doom configurations for Neovim, e.g. `tabwidth`, `showmode`.
+- functions - Doom core functions, e.g. `create_report`.
+- health - Doom health add-on.
+- keybindings - Doom keybindings.
+- logging - Doom logging system.
+- system - Doom system detection (unused at the moment).
diff --git a/lua/doom/modules/README.md b/lua/doom/modules/README.md
new file mode 100644
index 0000000..f4040bf
--- /dev/null
+++ b/lua/doom/modules/README.md
@@ -0,0 +1,6 @@
+# Modules
+
+Herein lies all the Doom plugins and their configurations.
+
+Refer to [List of modules](../../../docs/modules.md#list-of-modules) for more
+information about what's inside this module.
diff --git a/lua/doom/utils/README.md b/lua/doom/utils/README.md
new file mode 100644
index 0000000..9525138
--- /dev/null
+++ b/lua/doom/utils/README.md
@@ -0,0 +1,19 @@
+# Utils
+
+Herein lies all the Doom utility functions and variables.
+
+## Variables
+
+- `doom_version` - Doom Nvim version.
+- `doom_root` - Doom Nvim root directory.
+- `doom_logs` - Doom Nvim logs file path.
+- `doom_report` - Doom Nvim crash report path.
+
+## Functions
+
+- `map` - Wrapper for `nvim_set_keymap`.
+- `create_augroups` - Autocommands wrapper for Lua.
+- `is_empty` - Check if a string is empty or nil.
+- `has_value` - Search if a table have a value.
+- `try` and `catch` - Try/Catch for error handling.
+- `get_os` - Get the current OS using LuaJIT.