Doom Nvim

---

• Doom Nvim
  • What is Doom Nvim?
  • Install
  • Configuring
    • Enabling features: modules.lua
      • What is a module?
      • Enabing/disabling modules
      • All modules
    • Configuring and personalising: config.lua
      • Modifying neovim and doom options
        • Adding plugins
        • Adding Keybinds
        • Adding autocommands
      • Overriding module defaults
  • FAQ
  • Contributing
  • Contributors

---

What is Doom Nvim?

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:

• Fast Rapid startup time without defer_fn, packages are lazy loaded and languages are only configured when opening its relevent 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 Desgined 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

TODO: Add install docs here

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.

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. We organise modules into 3 categories:

• features extend the abilities of Doom Nvim by adding new functionality.
• langs add support for new languages.
• user (optional) You can create and enable your own modules without modifying the Doom Nvim source code (read more)[#TODO:].

Enabing/disabling modules

You can enable or disable a module by going to modules.lua (<leader>Dm) and commenting or uncommenting the entry.

-- modules.lua

return {
  features = {
    'lsp'
    -- 'telescope'
  },
  langs = {
    'lua',
    -- 'rust',
  }
}

Here the lsp module is enabled but the telescope module is disabled, similarly the lua language is enabled but the rust language module is disabled.

All modules

Doom-nvim currently has 39 features modules and 14 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].

-- 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 imported with the doom.use() function. This is a wrapper around packer.use() and provides the same API. DOCS

-- config.lua

-- Simple config
doom.use('sainnhe/sonokai', 'EdenEast/nightfox.nvim')

-- Advanced config
doom.use({
  'rafcamlet/nvim-luapad',
  opt = true,
  cmd = 'Luapad'
})

Adding Keybinds

Additional keybinds can be defined with the doom.bind() function. This is a wrapper around a custom nest.nvim implementation and provides the same API. DOCS

-- config.lua

doom.bind({
  { '<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 in whichkey and mapper if you have those modules enabled.

Adding autocommands

Additional autocommands can be defined with the doom.autocmd() function.

-- config.lua

doom.autcmd({
  -- { "<event>", "<aupat>", "<command or function>"}
  { "FileType", "javascript", function() print('Yuck!') end}
})

Overriding module defaults

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.

-- modules.lua

return {
  features = {
    'whichkey' -- Whichkey module is enabled
  }
}

-- config.lua
local whichkey = doom.modules.whichkey -- Get the whichkey module

-- 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.autcmds, { "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

Contributing

For for information please see our contributing docs.

Contributors

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 📖