Doom Nvim

---

• Doom Nvim
  • What is Doom Nvim?
  • Install
  • Configuring
    • modules.lua
      • What is a module?
      • Enabing/disabling modules
      • All modules
    • 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.

Its 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 the file type.
• Stable Plugins are pinned to commit shas to avoid breaking between updates.
• Configurable All modules are 100% overridable and configurable, use a logical structure and have LSP completions.
• 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).
• Extensible Take advantage of the modular architecture, enable only the features you need, customise or add your own modules.

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.

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. Some standout features are:

• lsp Code completions provided by nvim-cmp
• linter Formatting and linting provided by null-ls.nvim
• whichkey Interactive cheatsheet that integrates with our keybind management to only show keybinds for modules you have active
• fidget Shows LSP loading/indexing progress status

You can find a full list of modules (here)[#TODO: ].

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 (here)[TODO:].

-- 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

-- 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

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.

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.uses["which-key.nvim"] = {
    "myfork/which-key.nvim"
}
-- Provide a different config function, the key has to match the entry in `whichkey.uses`
whichkey.configs["which-key.nvim"] = function ()
  local wk = require("which-key")
end

FAQ

TODO: Add FAQ

Contributing

TODO: Add small info on contributing + overhaul contributing docs.

Contributors

TODO: Copy contributors from old README.md