Usage

Get to know this configuration: :Tutor dots!

Universal settings

All commonly used entries have been implemented in settings.lua.

Structure

init.lua is the kernel config file. It requires configuration in lua directory.

lua directory contains 4 parts.
- core directory contains base configuration of neovim.
- keymap directory contains keybindings of plugins.
- modules directory contains three main subfolders.
  - plugins/{scope}.lua contains plugins within the scope.
  - configs/{scope}/ directory contains plugin settings according to the scope.
  - utils/icons.lua contains icons used for plugin settings. See below for details.
  - utils/init.lua contains utility functions used by plugins. See below for details.
  - {scope} definition
    - completion contains plugins for code completion.
    - editor contains plugins that improve the default ability of vanilla nvim.
    - lang contains plugins related to certain programming languages.
    - tool contains plugins using external tools and changing the default layout which provides new abilities to nvim.
    - ui contains plugins rendering the interface without any actions after the user fires nvim.
- user directory contains user custom configs.
  - plugins/{scope}.lua contains user-added plugins within the scope.
  - configs/{plugin-name}.lua contains default plugin override settings according to the plugin name.
  - configs/{scope}/ directory contains user-added plugin settings according to the scope.
    - dap-clients/ directory contains the settings of DAP clients.
    - lsp-servers/ directory contains the settings of LSP servers.
  - keymap/ directory contains custom keybindings of plugins.
  - event.lua contains custom user events.
  - options.lua contains override vanilla nvim options.
  - settings.lua contains override settings.
The modules directory default file tree is as follows:

init.lua
   └── lua/
       └── modules/
           ├── plugins/
           │   ├── completion.lua
           │   ├── editor.lua
           │   ├── lang.lua
           │   ├── tool.lua
           │   └── ui.lua
           ├── configs/
           │   ├── completion/
           │   ├── editor/
           │   ├── lang/
           │   ├── tool/
           │   └── ui/
           └── utils/
               ├── icons.lua
               └── init.lua

How to customize

Modify plugin setting

Check whether the plugin is written in lua or not.
Add a new entry in user/configs/<plugin-name>.lua
If your plugin is written in lua, override it with (See below for an example)
- Return a table when replacing some items in lua/modules/configs/<scope>/<plugin-name>.lua.
- Return a function if you want to completely replace the setting in lua/modules/configs/<scope>/<plugin-name>.lua.
  
  Note About override settings
  - A custom merge function honors user preferences.
  - Replaces the value if the key exists in the table.
  - Add the key and value if the key does not exist in the table.
  - If the existing table value is a nested table, it behaves as follows:
    - If the user gives a table,
      - Add values if the nested table is a list.
      - Update value or add key and value if nested table is a dictionary
    - If the user gave a function,
      - It completely replaces nested tables.
If your plugin is written in vimscript, override it with (See below for an example)

Return a function containing vim.g.<options> = foobar.

Here is an example (If the plugin is made by lua):

lua/user/configs/telesccope.lua

Update value or add key and value by return a table.

return {
	defaults = {
		mappings = {
			n = {
				["q"] = "close",
			},
		},
	},
}

Full replacement of values by return a function

return {
	defaults = function()
		return {
			mappings = {
				n = {
					["q"] = "close",
				},
			},
		}
	end,
}

Here is an example (If the plugin is made by VimScript):

lua/user/configs/telesccope.lua

return function()
	vim.g.go_doc_keywordprg_enabled = 1
end

Add a new plugin

Make a sub-directory called <scope> under user/configs and a file called <scope>.lua under plugins/. <scope>.lua should contain the following initial content: Note Here we adopt a structure similar to lua/modules/configs for user configuration

local custom = {}

return custom

Add this new plugin following the format that other plugins are configured in plugins/ and configs/. Specifically:
- Add a new entry in user/plugins/<scope>.lua (See below for an example)
- Create a new .lua file with plugin name as the filename under user/configs/<scope> (the filename can be slightly different, as long as it can be understood by you).

Here is an example:

lua/user/plugins/editor.lua

local custom = {}

custom["folke/todo-comments.nvim"] = {
	lazy = true,
	event = "BufRead",
	config = require("user.configs.editor.todo-comments"), -- Require that config
}

return custom

lua/user/configs/editor/todo-comments.lua

return function() -- This file MUST return a function accepting no parameter and has no return value
	require("todo-comments").setup()
end

(If you need help, feel free to open an issue.)

Remove a plugin

Add settings["disabled_plugins"] to lua/user/settings.lua.
Enter the name of the plugin you want to remove.

Here is an example:

lua/settings.lua

-- Disable the two plugins
settings["disabled_plugins"] = {
	"karb94/neoscroll.nvim",
	"dstein64/nvim-scrollview",
}

Modify Keymaps

For vanilla nvim keymap

Modify lua/user/keymap/core.lua
For specific plugin's keymap

Modify lua/user/keymap/<scope>.lua

Command breakdown

    ┌─ sep     ┌── map_type
 ["n|gb"] = map_cr("BufferLinePick"):with_noremap():with_silent(),
   │  └── map_key          │              └── special     │
   └──── map_mode          └── map_content                └── special (can be chained)

Set the value to empty or false to remove the default keymap

Here is an example

lua/user/keymap/ui.lua

local bind = require("keymap.bind")
local map_cr = bind.map_cr
local map_cmd = bind.map_cmd
local map_callback = bind.map_callback

return {
	-- Remove default keymap
	["n|<leader>nf"] = "",
	["n|<leader>nr"] = false,
	-- Plugin: telescope
	["n|<leader><S-cr>"] = map_callback(function()
			_command_panel()
		end)
		:with_noremap()
		:with_silent()
		:with_desc("tool: Toggle command panel"),
}

Modify LSPs, linters and formatters

Add/remove Language Server Protocol (LSP) servers

Modify lua/user/settings -> settings[lsp_deps], users can find available sources here. Then add a server config file in lua/user/configs/lsp-servers, see lua/modules/configs/completions/servers/ for how to configure servers, users can take other server's config file as a reference. Restart nvim to install the new LSP servers.

Note: Some LSPs are already being shipped when installing the runtime packages. Like dartls is being shipped when installing dart runtime, so users won't see those LSPs when calling :Mason, see #525.
Add/remove linters and formatters

Modify lua/user/settings -> settings[null_ls_deps], users can find available sources here. If users want to change the behavior of a specific null-ls source, set the extra arguments in lua/user/configs/null-ls.lua -> sources table. (See below for an example) Restart nvim to install the new null-ls sources.

Here is an example

lua/user/configs/null-ls.lua

local null_ls = require("null-ls")
local btns = null_ls.builtins

return {
	sources = {
		btns.formatting.black.with({
			filetypes = { "python" },
			extra_args = { "--fast", "-q", "-l", "120", "extend-ignore = E203, E501" },
		}),
	},
}

Note: Some linters and formatters are already being shipped when installing the runtime packages. For example, dart_format is being shipped when installing dart runtime, so users won't see those formatters when calling :Mason. Just set dart_format, for example, in the settings[null_ls_deps] table, and mason-null-ls will set it up for you, see #525 for more.

Change Formatter's global behavior
- Disable formatting on certain filetype
  
  Modify lua/user/settings -> settings[formatter_block_list].
- Disable formatting ability on certain LSP server
  
  Modify lua/user/settings -> settings[server_formatting_block_list].
Changes in LSP server and Linter behavior
- Create and edit lua/user/configs/lsp-servers/<server-name>.lua.
- See lua/modules/configs/completions/servers/.

Modify Dap

Add/remove Debug Adapter Protocol (DAP) clients Modify lua/user/settings -> settings[dap_deps], users can find available sources here. Then add a client config file in lua/user/configs/dap-clients, see lua/modules/configs/tool/dap/clients/ for how to configure dap clients, users can take other client config files as a reference. Restart nvim to install the new DAP clients.

Modify event defined by `autocmd`

Modify lua/user/event.lua
See lua/core/events.lua for the key.

Here is an example

lua/user/events.lua

local definitions = {
	-- Example
	bufs = {
		{ "BufWritePre", "COMMIT_EDITMSG", "setlocal noundofile" },
	},
}

return definitions

Modify vanilla `nvim` options

Modify lua/user/options.lua
Global options are listed directly.

Here is an example

lua/user/options.lua

vim.g.editorconfig = 0
local options = {
	autoindent = true,
}

return options

Modify settings

Modify lua/user/settings.lua.
See lua/core/settings.lua for the keys and corresponding valid values.

Here is an example

lua/user/settings.lua

local settings = {}

-- Examples
settings["use_ssh"] = true

settings["colorscheme"] = "catppuccin"

return settings

Switch `colorscheme`

Modify the value of colorscheme in lua/user/settings.lua.

-- Set colorscheme to catppuccin-latte for example
settings["colorscheme"] = "catppuccin-latte"

NOTE: The colorscheme of lualine will also be changed according to the current colorscheme of nvim. Please see the function custom_theme in lua/modules/configs/ui/lualine.lua if you are interested in it.

All of the modified configs will have effects after you restart nvim.

Global assets

Palette

This configuration provides a global unified palette. You may use require("modules.utils").get_palette({ <color_name> = <hex_value> }?) to get the global color palette. Specific colors may be overwritten in settings.lua or can be passed in as function parameter(s). You will get parameter completion when typing.

The order of priority for modifying the palette is:

preset colors < global colors defined in `settings.lua` < incoming function parameters

All available colors can be found here. You can also explore implementation details in this file.

Icons

This configuration also provides a dedicated icon set. It can be accessed via require("modules.utils.icons").get(category, add_space?). You will get parameter completion when typing.

You can find the list of icons here.

Operation manual

Find word

Region operation

Guide on how to use the catppuccin colorscheme

What is Catppuccin? ^[1]

Catppuccin is a community-driven soothing pastel theme that aims to be the middle ground between low and high-contrast themes, providing a warm color palette with 26 eye-candy colors that are bright enough to be visible during the day, yet pale enough to be easy on your eyes throughout the night.

Basic Usage

Modify these lines. (Note: This link might be slightly different from HEAD, but it can be used as a reference.) See detailed explanation of each option below.

General

These settings are unrelated to any group and are globally independent.

flavour: (Can be any one of: latte, frappe, macchiato, or mocha) This is mandatory. You must set this value in order to make catppuccin work correctly. Note that latte is a light colorscheme, and the rest are dark schemes; The mocha palette is the only one that has been modified to make catppuccin look like the v0.1 one. Check out this PR for details.
transparent_background: (Boolean) if true, disables setting the background color.
term_colors: (Boolean) if true, sets terminal colors (a.k.a., g:terminal_color_0).

Dim inactive

This setting manages the ability to dim inactive splits/windows/buffers.

enabled: (Boolean) if true, dims the background color of inactive window or buffer or split.
shade: (string) sets the shade to apply to the inactive split or window or buffer.
percentage: (number from 0 to 1) percentage of the shade to apply to the inactive window, split or buffer.

Styles

Handles the style of general highlight groups (see :h highlight-args for detailed explanation):

comments: (Table) changes the style of comments.
functions: (Table) changes the style of functions (e.g., button in config).
keywords: (Table) changes the style of keywords (e.g., local).
strings: (Table) changes the style of strings.
variables: (Table) changes the style of variables.
properties: (Table) changes the style of a phantom field with only getter and/or setter (e.g., field access tbl.field).
operators: (Table) changes the style of operators.
conditionals: (Table) changes the style of conditional check keywords (e.g., if).
loops: (Table) changes the style of loop keywords (e.g., for).
booleans: (Table) changes the style of booleans.
numbers: (Table) changes the style of numbers.
types: (Table) changes the style of types (e.g., int).

Integrations

These integrations allow catppuccin to set the theme of various plugins. To enable an integration you need to set it to true.

Using the auto-compile feature

Catppuccin is a highly customizable and configurable colorscheme. This does however come at the cost of complexity and execution time.

Catppuccin can pre-compute the results of configuration and store the results in a compiled lua file. These pre-cached values are later used to set highlights. The cached file is stored at vim.fn.stdpath("cache") .. "/catppuccin" by default (use :lua print(vim.fn.stdpath("cache") .. "/catppuccin") to see where it locates on your computer). You may change this behavior by modifying this line.

Note: As of 7/10/2022, catppuccin should be able to automatically recompile when the setup table changes. You cannot disable this feature.

Advanced Feature

Customizing the palette

Not satisfied with the current appearance? You may modify the palette yourself, like mocha!

Get catppuccin colors

local latte = require("catppuccin.palettes").get_palette "latte"
local frappe = require("catppuccin.palettes").get_palette "frappe"
local macchiato = require("catppuccin.palettes").get_palette "frappe"
local mocha = require("catppuccin.palettes").get_palette "mocha"

local colors = require("catppuccin.palettes").get_palette() -- current flavour's palette

These lines would all return a table respectively, where the key is the name of the color and the value is its hex value.

Overwriting highlight groups

Global highlight groups can be overwritten like so:

custom_highlights = function(cp)
	return {
		<hl_group> = { <fields> }
	}
end

Here is an example:

require("catppuccin").setup({
	custom_highlights = function(cp)
		return {
			Comment = { fg = cp.flamingo },
			["@constant.builtin"] = { fg = cp.peach, style = {} },
			["@comment"] = { fg = cp.surface2, style = { "italic" } },
		}
	end,
})

Per flavour highlight groups can be overwritten starting from this line like so:

highlight_overrides = {
	all = function(cp) -- Global highlight, will be replaced with custom_highlights if exists
		return {
			<hl_group> = { <fields> }
		}
	end, -- Same for each flavour
	latte = function(latte) end,
	frappe = function(frappe) end,
	macchiato = function(macchiato) end,
	mocha = function(mocha) end,
}

Here is an example:

local ucolors = require("catppuccin.utils.colors")
require("catppuccin").setup({
	highlight_overrides = {
		all = function(colors)
			return {
				NvimTreeNormal = { fg = colors.none },
				CmpBorder = { fg = "#3E4145" },
			}
		end,
		latte = function(latte)
			return {
				Normal = { fg = ucolors.darken(latte.base, 0.7, latte.mantle) },
			}
		end,
		frappe = function(frappe)
			return {
				["@comment"] = { fg = frappe.surface2, style = { "italic" } },
			}
		end,
		macchiato = function(macchiato)
			return {
				LineNr = { fg = macchiato.overlay1 },
			}
		end,
		mocha = function(mocha)
			return {
				Comment = { fg = mocha.flamingo },
			}
		end,
	},
})

Additionally, if you want to load other custom highlights later, you may use this function:

require("catppuccin.lib.highlighter").syntax()

For example:

local colors = require("catppuccin.palettes").get_palette() -- fetch colors from palette
require("catppuccin.lib.highlighter").syntax({
	Comment = { fg = colors.surface0 }
})

Note: Custom highlights loaded using the require("catppuccin.lib.highlighter").syntax() function won't be pre-compiled.

Unlike the :highlight command which can update a highlight group, this function completely replaces the definition. (:h nvim_set_hl)

Overwriting colors

Colors can be overwritten using color_overrides starting from this line, like so:

require("catppuccin").setup {
	color_overrides = {
		all = {
			text = "#FFFFFF",
		},
		latte = {
			base = "#FF0000",
			mantle = "#242424",
			crust = "#474747",
		},
		frappe = {},
		macchiato = {},
		mocha = {},
	}
}

Customizing auto-compile Hook

Available Compile Commands

:CatppuccinCompile " Create/update the compile file

Catppuccin also provides the following function to work with the catppuccin compiler:

require('catppuccin').compile() -- Create/update the compile files

Post-install/update hooks

You may add :CatppuccinCompile to post-install/update hooks here, like so:

ui["catppuccin/nvim"] = {
	lazy = false,
	name = "catppuccin",
	config = require("ui.catppuccin"),
	build = ":CatppuccinCompile"
}

Want to know more details?

Visit catppuccin on github!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Usage

Universal settings

Structure

How to customize

Modify plugin setting

Add a new plugin

Remove a plugin

Modify Keymaps

Modify LSPs, linters and formatters

Modify Dap

Modify event defined by `autocmd`

Modify vanilla `nvim` options

Modify settings

Switch `colorscheme`

Global assets

Palette

Icons

Operation manual

Guide on how to use the catppuccin colorscheme

What is Catppuccin? ^[1]

Basic Usage

General

Dim inactive

Styles

Integrations

Using the auto-compile feature

Advanced Feature

Customizing the palette

Get catppuccin colors

Overwriting highlight groups

Overwriting colors

Customizing auto-compile Hook

Available Compile Commands

Post-install/update hooks

Want to know more details?

Clone this wiki locally

Usage

Universal settings

Structure

How to customize

Modify plugin setting

Add a new plugin

Remove a plugin

Modify Keymaps

Modify LSPs, linters and formatters

Modify Dap

Modify event defined by autocmd

Modify vanilla nvim options

Modify settings

Switch colorscheme

Global assets

Palette

Icons

Operation manual

Guide on how to use the catppuccin colorscheme

What is Catppuccin? [1]

Basic Usage

General

Dim inactive

Styles

Integrations

Using the auto-compile feature

Advanced Feature

Customizing the palette

Get catppuccin colors

Overwriting highlight groups

Overwriting colors

Customizing auto-compile Hook

Available Compile Commands

Post-install/update hooks

Want to know more details?

Clone this wiki locally

Modify event defined by `autocmd`

Modify vanilla `nvim` options

Switch `colorscheme`

What is Catppuccin? ^[1]