• Stars
    star
    502
  • Rank 84,459 (Top 2 %)
  • Language
    Lua
  • License
    GNU General Publi...
  • Created about 3 years ago
  • Updated about 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Neovim configuration for the advanced martian hacker

Doom Nvim

License PRs Welcome Latest Release GitHub last commit (branch) Neovim version Discord

All Contributors

Doom Nvim demo

IMPORTANT NOTICE

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!

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

curl -s https://raw.githubusercontent.com/doom-neovim/doom-nvim/main/tools/install.sh | 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
  1. (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

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 (<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',
  }
}

All modules

Doom-nvim currently has 35+ features modules and 20+ langs modules. You can find a full list of modules here

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.

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

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

-- 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 in whichkey and mapper if you have those modules enabled.

Adding autocommands

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}
})
Adding commands

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 },
})

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

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

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

--- modules.lua
return {
  langs = {
    'julia',
  }
}

For more info, read the documentation for creating your own modules.

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_* helper functions.
  • Adding extra plugins done using new doom.use_package 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.

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

πŸ“–

More Repositories

1

cheovim

Neovim configuration switcher written in Lua. Inspired by chemacs.
Lua
323
star
2

doom-one.nvim

doom-emacs' doom-one Lua port for Neovim
Lua
185
star
3

sweetie.nvim

A clean, delightful and highly customizable Neovim colorscheme written in Lua
Lua
75
star
4

dotfiles

/boot: No such file or directory
Shell
53
star
5

nvenv

A lightweight and blazing fast Neovim version manager.
V
52
star
6

color-converter.nvim

Easily convert your CSS colors without leaving your favorite editor.
Lua
34
star
7

nvim

My personal blazingly fast Neovim setup
Lua
27
star
8

zig-tools.nvim

Zig development tools for Neovim.
Lua
24
star
9

lcfetch

A fast and easy to configure alternative to neofetch written in C and configured using Lua
C
23
star
10

doom-one-vscode

VSCode port of Doom Emacs' doom-one colorscheme
15
star
11

daylight.nvim

Automatic colorscheme/background switcher for Neovim based on your current time
Lua
13
star
12

sun

Sun programming language source code
C
9
star
13

calc.py

A powerful Python REPL calculator
Python
8
star
14

doombox.nvim

A perfect mix between doom-one and gruvbox-material
Lua
8
star
15

temple.nvim

Dead simple yet powerful Neovim templates engine
7
star
16

selene-action

GitHub action for selene lua linter
TypeScript
5
star
17

paul

Manage all your favorite system tools like ripgrep with just one command
5
star
18

exemplum.nvim

Take your functions and easily refactor them while keeping an eye on the initial implementation
Lua
5
star
19

better-neovim

I think the name says it all
4
star
20

NTBBloodbath

My bio
4
star
21

norg.py

Python parser for the Norg file format
Python
3
star
22

nvrg

Neovim Rockspecs Generator for plugins
Zig
3
star
23

logging.nvim

A very simple and asynchronous logging library for Neovim plugins
Lua
3
star
24

bull

Svelte and Neorg in a SSG?
Zig
2
star
25

st

My personal suckless terminal build
C
2
star
26

ntbbloodbath.github.io

Just my small personal blog
HTML
2
star
27

hive-ci

An experimental, modern and friendly CI engine
Rust
2
star
28

dart-tree-sitter

Dart bindings for tree-sitter (WIP)
Dart
1
star
29

notes

My personal notes written in norg documents
1
star
30

Seconds

Transform seconds to minutes, hours, etc. and vice versa quickly, easily, understandable by humans and without external dependencies
Python
1
star
31

nasm-exercises

Some NASM exercises I'm writing to learn ASM because I don't care about my mental health
Assembly
1
star