This project is NOT abandoned. There is a major refactoring and incremental rewrite happening under the hood. If you want to know the current progress on this or if you want to contribute by making suggestions, reporting bugs, writing code for Doom, etc. please join us in the Discord server. Any suggestion is welcome!
Doom Nvim is a Neovim interpretation of the 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:
curl -s https://raw.githubusercontent.com/doom-neovim/doom-nvim/main/tools/install.sh | sh
git clone https://github.com/doom-neovim/doom-nvim.git ${XDG_CONFIG_HOME:-$HOME/.config}/nvim
my-config
so the auto-updater works.
git checkout tags/$(git tag -l --sort -version:refname | head -n 1) -b my-config
:DoomCheckUpdates
command and manage updates manually.modules.lua
config.lua
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.
modules.lua
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.You can enable or disable a module by going to modules.lua
(<leader>Dm
) and
commenting or uncommenting the entry.
-- modules.lua
return {
-- `lsp` module is enabled, `telescope is disabled`
features = {
'lsp'
-- 'telescope'
},
-- `lua` language is enabled, `rust is disabled`
langs = {
'lua',
-- 'rust',
}
}
Doom-nvim currently has 35+ features
modules and 20+ langs
modules.
You can find a full list of modules here
config.lua
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.
-- 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 andlsp
module enabled all of these options will be autocompleted.
Additional packages can be installed with the doom.use_package()
function.
This is a wrapper around packer.use()
and provides the same API. DOCS
-- 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.
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
-- config.lua
doom.use_keybind({
{ '<leader>u', name = '+user', { -- Names this group in whichkey "+user"
{ 's', '<cmd>Telescope git_status<CR>', name = 'Git status' } -- Adds `<leader>us` keybind to trigger `Telescope git_status`
}},
})
NOTE: By providing the
name
field your custom keybinds will show up inwhichkey
andmapper
if you have those modules enabled.
Additional autocommands can be defined with the doom.use_autocmd()
function.
-- config.lua
doom.use_autocmd({
-- { "<event>", "<aupat>", "<command or function>"}
{ "FileType", "javascript", function() print('Yuck!') end}
})
Additional commands can be define with the doom.use_cmd()
function.
-- 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 },
})
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
-- 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.
-- 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 `<module>.settings` table.
whichkey.settings.window.height.max = 5
-- Inspect the existing config
print(vim.inspect(whichkey))
-- Add an additional keybind
table.insert(whichkey.binds, { '<leader>u', name = '+user', {
{ "wr", function() require("which-key").reset(), name = "Reset whichkey"}
}
})
-- Replace all keybinds
whichkey.binds = {
{ '<leader>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
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
--- modules.lua
return {
langs = {
'julia',
}
}
For more info, read the documentation for creating your own modules.
The majors changes between v3 and v4 are the following.
doom_config.lua
renamed to config.lua
doom.use_*
helper functions.doom.use_package
helper
function.doom_modules.lua
renamed to modules.lua
features
(modifying capabilities of doom-nvim) and languages
(add support for a language)+lsp
, +formatting
, etc flags are no longer necessaryBecause of the durastic changes to the way you configure doom-nvim we recommend starting a new branch and porting your changes across.
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
)
For for information please see our contributing docs.
Also try to refer to excelent guide to develop in nvim lua
Special thanks to these amazing people for helping improve doom (see emoji key):
John Irle 📖 |
Brian Ketelsen 💻 🐛 |
Samantha-uk 📖 |
rscircus 📖 |
bandithedoge 📖 |
vhyrro 💻 |
Ifeanyichukwu Sampson Ebenezer 🐛 |
Gustavo Prieto 💻 |
ZeusThundr 🐛 |
Leo Nistor 🐛 |
notusknot 📖 |
Bruce Dillahunty 📖 🐛 |
amxj9 🐛 |
Kyle Guerrero 📖 |