# doom-nvim
**Repository Path**: daolothy/doom-nvim
## Basic Information
- **Project Name**: doom-nvim
- **Description**: A Neovim configuration for the advanced martian hacker
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-12-07
- **Last Updated**: 2022-12-07
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Doom Nvim
[](http://makeapullrequest.com)
[](https://discord.gg/xhvBM45zBf)
[](#contributors-)
> Note: Doom nvim v4.0.0 has just been released (29th July 2022).
> This release introduces many changes so feel free to ask questions on the
> discord or in the github discussions page or create an issue ticket and I'll
> solve it as soon as possible.
## What is Doom Nvim?
Doom Nvim is a Neovim interpretation of the [doom-emacs](https://github.com/hlissner/doom-emacs) framework, adapted to Vim philosophy.
Our goal is to provide a configurable, extensible, performant and stable basis for any neovim configuration.
Some of the defining features that make this project unique are:
- **Fast** Rapid startup time without defer_fn, packages are lazy loaded and languages are only configured when opening its relevant file type.
- **Stable** Plugins are pinned to commit shas to avoid breaking between updates.
- **Scalable** Because of modular architecture you can disable any features you don't use. Your config is as simple or complex as you want it to be.
- **Configurable** All modules are 100% overridable and configurable, use a logical structure and have LSP completions.
- **Extensible** With a simple api you can easily add, and or contribute, your own modules.
- **Integrated** Designed to handle and setup integrations between plugins for you. For example, whichkey will only show keybinds for
modules you have enabled (and will automatically handle your custom bindings).
## Install
### Mac OS / Linux
```bash
bash <(curl -s https://raw.githubusercontent.com/doom-neovim/doom-nvim/main/tools/install.sh)
```
### Manual (Mac OS / Linux)
1. Clone doom-nvim to ~/.config/nvim
- `git clone https://github.com/doom-neovim/doom-nvim.git ${XDG_CONFIG_HOME:-$HOME/.config}/nvim`
2. (optional) Checkout the latest stable version in a new branch called `my-config` so the auto-updater works.
- `git checkout tags/$(git tag -l --sort -version:refname | head -n 1) -b my-config`
- âšī¸ The auto-updater will be broken without this step but you're free to check updates using the `:DoomCheckUpdates` command and manage updates manually.
---
- [Configuring](#configuring)
- [Enabling features: `modules.lua`](#enabling-features-moduleslua)
- [What is a module?](#what-is-a-module)
- [Enabling/disabling modules](#enablingdisabling-modules)
- [All modules](#all-modules)
- [Configuring and personalising: `config.lua`](#configuring-and-personalising-configlua)
- [Modifying neovim and doom options](#modifying-neovim-and-doom-options)
* [Adding plugins](#adding-plugins)
* [Adding keybinds](#adding-keybinds)
* [Adding autocommands](#adding-autocommands)
* [Adding commands](#adding-commands)
- [Overriding module defaults](#overriding-module-defaults)
- [FAQ](#faq)
- [Contributing](#contributing)
- [Contributors](#contributors)
- [Uninstall](#uninstalling)
---
## Configuring
Doom nvim is configured by enabling modules in the `modules.lua` file and then
tweaking, overriding or adding new packages, keybinds and more within the
`config.lua` module.
> We recommend creating a custom config branch (the auto install script will
> do this for you) and committing your changes to this branch. The auto updater
> will merge new releases into your config branch for you.
### Enabling features: `modules.lua`
#### What is a module?
A module is a collection of packages, autocommands, keybinds and functions that
add new capabilities or functionality to Doom Nvim. See what's available in
`modules.lua` and enable the modules that you think you would like. Then restart
`doom-nvim`, run `:PackerSync` and then restart `doom-nvim` again.
We organise modules into 2 categories:
- `features` extend the abilities of Doom Nvim by adding new functionality.
- `langs` add support for new languages.
#### Enabling/disabling modules
You can enable or disable a module by going to `modules.lua` (`Dm`) and
commenting or uncommenting the entry.
```lua
-- modules.lua
return {
-- `lsp` module is enabled, `telescope is disabled`
features = {
'lsp'
-- 'telescope'
},
-- `lua` language is enabled, `rust is disabled`
langs = {
'lua',
-- 'rust',
}
}
```
#### All modules
Doom-nvim currently has 35+ `features` modules and 20+ `langs` modules.
You can find a full list of modules [here](./docs/modules.md#all-modules)
### Configuring and personalising: `config.lua`
#### Modifying neovim and doom options
Doom nvim provides a number of config options, including wrapping some of vim's
own options. See all available config options [in the API Reference](./docs/api.md).
```lua
-- config.lua
doom.freeze_dependencies = false -- Don't use pinned packer dependencies
doom.logging = 'trace' -- Debug doom internal issues
doom.indent = 2 -- Sets vim.opt.shiftwith, vim.opt.softtabstop, vim.opt.tabstop to 2
vim.opt.colorcolumn = 120 -- Regular vim options can also be set
```
> **NOTE:** If you have the `lua` language and `lsp` module enabled all of these
> options will be autocompleted.
##### Adding plugins
Additional packages can be installed with the `doom.use_package()` function.
This is a wrapper around `packer.use()` and provides the same API. [DOCS](https://github.com/wbthomason/packer.nvim#quickstart)
```lua
-- config.lua
-- Simple config
doom.use_package('sainnhe/sonokai', 'EdenEast/nightfox.nvim')
-- Advanced config
doom.use_package({
'rafcamlet/nvim-luapad',
opt = true,
cmd = 'Luapad'
})
```
> Note: you will need to restart nvim and run `:PackerSync` after add/removing packages to import them correctly.
##### Adding Keybinds
Additional keybinds can be defined with the `doom.use_keybind()` function.
This is a wrapper around a custom `nest.nvim` implementation and provides the
same API. [DOCS](https://github.com/connorgmeehan/nest.nvim/tree/integrations-api#quickstart-guide)
```lua
-- config.lua
doom.use_keybind({
{ 'u', name = '+user', { -- Names this group in whichkey "+user"
{ 's', 'Telescope git_status', name = 'Git status' } -- Adds `us` keybind to trigger `Telescope git_status`
}},
})
```
> **NOTE:** By providing the `name` field your custom keybinds will show up
> in `whichkey` and `mapper` if you have those modules enabled.
##### Adding autocommands
Additional autocommands can be defined with the `doom.use_autocmd()` function.
```lua
-- config.lua
doom.use_autocmd({
-- { "", "", ""}
{ "FileType", "javascript", function() print('Yuck!') end}
})
```
##### Adding commands
Additional commands can be define with the `doom.use_cmd()` function.
```lua
-- config.lua
-- Bind single
doom.use_cmd( { 'Test', function() print('test') end } )
-- Bind multiple
doom.use_cmd({
{ 'Test1', function() print('test1') end },
{ 'Test2', function() print('test2') end },
})
```
#### Configuring modules
The settings and config for all modules are also exposed inside of the `doom` global object.
Here you can override the plugin git sources, pre-defined settings, keybinds or autocmds.
Make sure that the module that you want to configure/override is enabled in `modules.lua`
```lua
-- modules.lua
return {
features = {
'whichkey' -- Whichkey module is enabled
}
}
```
The same module with be avaliable in your `config.lua` in the `doom.features.module_name` field.
The settings should have autocomplete from sumneko lua lsp.
```lua
-- config.lua
local whichkey = doom.features.whichkey -- Get the whichkey module
-- You can also access it as `doom.modules.features.whichkey`
-- Some common settings are exposed in the `.settings` table.
whichkey.settings.window.height.max = 5
-- Inspect the existing config
print(vim.inspect(whichkey))
-- Add an additional keybind
table.insert(whichkey.binds, { 'u', name = '+user', {
{ "wr", function() require("which-key").reset(), name = "Reset whichkey"}
}
})
-- Replace all keybinds
whichkey.binds = {
{ 'u', name = '+user', {
{ "wr", function() require("which-key").reset(), name = "Reset whichkey"}
}}
}
-- Add an additional autocommand
table.insert(whichkey.autocmds, { "event", "aupat", "cmd"})
-- Replace all autocommands
whichkey.autocmds = {
{ "event", "aupat", "cmd"}
}
-- Modify the plugin source repo, plugins are indexed via the repository name.
whichkey.packages["which-key.nvim"] = {
"myfork/which-key.nvim"
}
-- Provide a different config function, the key has to match the entry in `whichkey.packages`
whichkey.configs["which-key.nvim"] = function ()
local wk = require("which-key")
end
-- Another example with a language module
local lua = doom.langs.lua
-- Disable lua-dev loading library definitions
lua.settings.dev.library.plugins = false
```
#### Overriding modules or adding custom modules
It's possible to add your own doom modules or completely replace builtin doom
modules without editing the original files. Doom will first check the `lua/user/modules`
directory if a module exists before loading the default from `lua/doom/modules`.
As an example, if we wanted to replace the `lua` module in the `langs` section we
would create a new file at `lua/user/modules/langs/lua/init.lua`.
Alternatively if we wanted to add support for a new language (lets use julia as
an example) we would create a new file at `lua/user/modules/langs/julia/init.lua`.
You would then enable the module in `modules.lua`
```lua
--- modules.lua
return {
langs = {
'julia',
}
}
```
> For more info, read the [documentation for creating your own modules.](./docs/modules.md#building-your-own-module)
## Migration guide from v3
The majors changes between v3 and v4 are the following.
- `doom_config.lua` renamed to `config.lua`
- Adding custom commands, keybinds and autocommands done using new [`doom.use_*`](#-configlua-)
helper functions.
- Adding extra plugins done using new [`doom.use_package`](#adding-plugins) helper
function.
- `doom_modules.lua` renamed to `modules.lua`
- Many of the modules categories have been combined, there are now only `features`
(modifying capabilities of doom-nvim) and `languages` (add support for a language)
- Languages `+lsp`, `+formatting`, etc flags are no longer necessary
> Because of the durastic changes to the way you configure doom-nvim we recommend
> starting a new branch and porting your changes across.
## Uninstalling
To uninstall doom-nvim delete the `.nvim` folder from `$XDG_CONFIG_HOME/nvim` (`rm -r ~/.config/nvim`)
You will also need to delete `packer_compiled.lua` from `$XDG_DATA_HOME/nvim/plugin/packer_compiled` (`rm ~/.local/share/nvim/plugin/packer_compiled.lua`)
## Contributing
For for information please see our [contributing docs](./docs/contributing.md).
## Contributors
Special thanks to these amazing people for helping improve doom (see [emoji key](https://allcontributors.org/docs/en/emoji-key)):
