Hello there and thanks for following the development of Catppuccin.nvim: remastered version. This branch is meant to hopefully end up being merged to main. As of now, all of the development discussions are carried out on #44, so feel free to leave your suggestions and ideas there :)
# About
<divstyle="text-align: justify">
Catppuccin.nvim is a NeoVim plugin that provides multiple colorschemes based on the catppuccin color palette but varying their properties. Apart from the eye-candy colorschemes, Catppuccin.nvim also provides integrations with multiple plugins and tools you are probably already using (e.g. Treesitter, Native LSP, ...).
</div>
# 🌲 Table of Contents
- [Flavors](#-flavors)
- [Features](#-features)
- [Notices](#-notices)
- [Installation](#-installation)
- [Prerequisites](#prerequisites)
- [Adding the plugin](#adding-the-plugin)
- [Setup](#setup)
- [For init.lua](#for-initlua)
- [For init.vim](#for-initvim)
- [Updating](#updating)
- [Usage](#usage)
- [Commands](#commands)
- [API](#api)
- [Modules](#modules)
- [Configuration](#-configuration)
- [General](#general)
- [Styles](#styles)
- [Integrations](#integrations)
- [Special Integrations](#special-integrations)
- [List of Colorschemes](#list-of-colorschemes)
- [Overwriting colors & hi groups](overwriting-colors--hi-groups)
You can use your favorite plugin manager for this. Here are some examples with the most popular ones:
You can use your favorite plugin manager for this. Here are some examples with the most popular ones:
### Vim-plug
#### Vim-plug
```lua
```lua
Plug 'Pocco81/Catppuccin.nvim'
Plug 'catppuccin/nvim'
```
```
### Packer.nvim
#### Packer.nvim
```lua
```lua
use "Pocco81/Catppuccin.nvim"
use "catppuccin/nvim"
```
```
### Vundle
#### Vundle
```lua
```lua
Plugin 'Pocco81/Catppuccin.nvim'
Plugin 'catppuccin/nvim'
```
```
### NeoBundle
#### NeoBundle
```lua
```lua
NeoBundleFetch 'Pocco81/Catppuccin.nvim'
NeoBundleFetch 'catppuccin/nvim'
```
```
## Setup
### Setup
There are already some sane defaults that you may like, however you can change them to match your taste. These are the defaults:
There are already some sane defaults that you may like, however you can change them to match your taste. These are the defaults:
```lua
```lua
colorscheme = "dark_catppuccin",
transparent_background = false,
transparency = false,
term_colors = false,
term_colors = false,
styles = {
styles = {
comments = "italic",
comments = "italic",
@ -187,7 +93,7 @@ integrations = {
hints = "underline",
hints = "underline",
warnings = "underline",
warnings = "underline",
information = "underline",
information = "underline",
}
},
},
},
lsp_trouble = false,
lsp_trouble = false,
lsp_saga = false,
lsp_saga = false,
@ -213,7 +119,7 @@ integrations = {
lightspeed = false,
lightspeed = false,
ts_rainbow = false,
ts_rainbow = false,
hop = false,
hop = false,
}
},
```
```
The way you setup the settings on your configuration varies on whether you are using vimL for this or Lua.
The way you setup the settings on your configuration varies on whether you are using vimL for this or Lua.
@ -228,8 +134,7 @@ local catppuccin = require("catppuccin")
-- configure it
-- configure it
catppuccin.setup(
catppuccin.setup(
{
{
colorscheme = "dark_catppuccin",
transparent_background = false,
transparency = false,
term_colors = false,
term_colors = false,
styles = {
styles = {
comments = "italic",
comments = "italic",
@ -253,7 +158,7 @@ catppuccin.setup(
hints = "underline",
hints = "underline",
warnings = "underline",
warnings = "underline",
information = "underline",
information = "underline",
}
},
},
},
lsp_trouble = false,
lsp_trouble = false,
lsp_saga = false,
lsp_saga = false,
@ -279,7 +184,7 @@ catppuccin.setup(
lightspeed = false,
lightspeed = false,
ts_rainbow = false,
ts_rainbow = false,
hop = false,
hop = false,
}
},
}
}
)
)
```
```
@ -298,8 +203,7 @@ local catppuccin = require("catppuccin")
-- configure it
-- configure it
catppuccin.setup(
catppuccin.setup(
{
{
colorscheme = "dark_catppuccin",
transparent_background = false,
transparency = false,
term_colors = false,
term_colors = false,
styles = {
styles = {
comments = "italic",
comments = "italic",
@ -323,7 +227,7 @@ catppuccin.setup(
hints = "underline",
hints = "underline",
warnings = "underline",
warnings = "underline",
information = "underline",
information = "underline",
}
},
},
},
lsp_trouble = false,
lsp_trouble = false,
lsp_saga = false,
lsp_saga = false,
@ -349,7 +253,7 @@ catppuccin.setup(
lightspeed = false,
lightspeed = false,
ts_rainbow = false,
ts_rainbow = false,
hop = false,
hop = false,
}
},
}
}
)
)
EOF
EOF
@ -369,46 +273,8 @@ colorscheme catppuccin
-- Lua
-- Lua
vim.cmd[[colorscheme catppuccin]]
vim.cmd[[colorscheme catppuccin]]
```
```
Passing `catppuccin` to the `colorscheme` command will pick the colorscheme in the config. Optionally, you could pass one by its code name (e.g. `colorscheme neon_latte`).
For instructions on how to configure the plugin, check out the [configuration](#configuration) section.
## Updating
This depends on your plugin manager. If, for example, you are using Packer.nvim, you can update it with this command:
```lua
:PackerUpdate
```
# 🤖 Usage
## Commands
The provides commands that follows the _camel casing_ naming convention and have the `CP` prefix so that it's easy to remember that they are part of Catppuccin.nvim:
- `:CPClear` clear all highlight groups.
- `:colorscheme <colorscheme_name>` load a colorscheme, not necessarily a catppuccin one. (Note: this is a built-in NVim command).
## API
The API allows you fetch data from catppuccin. It can be required as a Lua module:
```lua
local cp_api = require("catppuccin.api.<module>")
```
### Modules
- `colors`
```lua
cp_api.get_colors(<colorscheme>)
```
> Gets the colors from `<colorscheme>`. Returns two values: the first one is a table with a `status` field (for the exit status) and a `msg` field with an error message in case `status` is `false` (error), and the second value is a table with the colors. If it fails, it will return the colors from `dark_catppuccin`.
# 🐬 Configuration
### Configuration
Although settings already have self-explanatory names, here is where you can find info about each one of them and their classifications!
Although settings already have self-explanatory names, here is where you can find info about each one of them and their classifications!
@ -416,30 +282,29 @@ Although settings already have self-explanatory names, here is where you can fin
This settings are unrelated to any group and are independent.
This settings are unrelated to any group and are independent.
- `colorscheme`: (String) code name of the color-scheme to be used. All of them can be found in the section below.
- `transparent_background`: (Boolean) if true, disables setting the background color.
- `transparency`: (Boolean) if true, disables setting the background color.
- `term_colors`: (Boolean) if true, sets terminal colors (e.g. `g:terminal_color_0`).
- `term_colors`: (Boolean) if true, sets terminal colors (e.g. `g:terminal_color_0`).
## Styles
## Styles
Handles the style of general hi groups (see `:h highlight-args`):
Handles the style of general hi groups (see `:h highlight-args`):
- `comments`: (String) changed the style of the comments.
- `comments`: (String) changed the style of the comments.
- `functions`: (String) changed the style of the functions.
- `functions`: (String) changed the style of the functions.
- `keywords`: (String) changed the style of the keywords.
- `keywords`: (String) changed the style of the keywords.
- `strings`: (String) changed the style of the strings.
- `strings`: (String) changed the style of the strings.
- `variables`: (String) changed the style of the variables.
- `variables`: (String) changed the style of the variables.
## Integrations
## Integrations
These integrations allow catppuccin to set the theme of various plugins/stuff. To enable an integration you just need to set it to `true`, however, there are some special integrations...
These integrations allow catppuccin to set the theme of various plugins/stuff. To enable an integration you just need to set it to `true`, however, there are some special integrations...
If you'd like to know which highlight groups are being affected by catppuccin, checkout this directory: [`lua/catppuccin/core/integrations/`](https://github.com/Pocco81/Catppuccin.nvim/tree/main/lua/catppuccin/core/integrations).
If you'd like to know which highlight groups are being affected by catppuccin, checkout this directory: [`lua/catppuccin/core/integrations/`](https://github.com/catppuccin/nvim/tree/main/lua/catppuccin/core/integrations).
### Special Integrations
### Special Integrations
- **Native Nvim LSP:** setting `enabled` to `true` enables this integration. In the inners tables you can set the style for the diagnostics, both `virtual_text` (what you see on the side) and `underlines` (what points directly at the thing (e.g. an error)).
- **Native Nvim LSP:** setting `enabled` to `true` enables this integration. In the inners tables you can set the style for the diagnostics, both `virtual_text` (what you see on the side) and `underlines` (what points directly at the thing (e.g. an error)).
- **Lualine:** use this to set it up (Note: `catppuccin` is the only valid theme name. It will pick the one set in your config):
- **Lualine:** use this to set it up (Note: `catppuccin` is the only valid theme name. It will pick the one set in your config):
```lua
```lua
require('lualine').setup {
require('lualine').setup {
@ -450,17 +315,17 @@ require('lualine').setup {
}
}
```
```
- **Lightline:** use this to set it up (Note: `catppuccin` is the only valid colorscheme name. It will pick the one set in your config):
- **Lightline:** use this to set it up (Note: `catppuccin` is the only valid colorscheme name. It will pick the one set in your config):
```lua
```lua
let g:lightline = {'colorscheme': 'catppuccin'}
let g:lightline = {'colorscheme': 'catppuccin'}
```
```
- **Kitty:** Copy and paste the file corresponding to theme you want to use from [this directory](https://github.com/Pocco81/Catppuccin.nvim/tree/main/extra/kitty) on your Kitty config.
- **Kitty:** Copy and paste the file corresponding to theme you want to use from [this directory](https://github.com/catppuccin/nvim/tree/main/extra/kitty) on your Kitty config.
- **Alacritty:** Copy and paste the file corresponding to theme you want to use from [this directory](https://github.com/Pocco81/Catppuccin.nvim/tree/main/extra/alacritty) on your Alacritty config.
- **Alacritty:** Copy and paste the file corresponding to theme you want to use from [this directory](https://github.com/catppuccin/nvim/tree/main/extra/alacritty) on your Alacritty config.
- **Tmux**: Follow the instructions [here](https://github.com/Pocco81/Catppuccin.nvim/tree/main/extra/tmux)
- **Tmux**: Follow the instructions [here](https://github.com/catppuccin/nvim/tree/main/extra/tmux)
- **Indent-blankline.nvim**: setting `enabled` to `true` enables this integration. `colored_indent_levels` enables char highlights per indent level. Follow the instructions [here](https://github.com/lukas-reineke/indent-blankline.nvim#with-custom-gindent_blankline_char_highlight_list) to set the latter up.
- **Indent-blankline.nvim**: setting `enabled` to `true` enables this integration. `colored_indent_levels` enables char highlights per indent level. Follow the instructions [here](https://github.com/lukas-reineke/indent-blankline.nvim#with-custom-gindent_blankline_char_highlight_list) to set the latter up.
- **NvimTree:** setting `enabled` to `true` enables this integration:
- **NvimTree:** setting `enabled` to `true` enables this integration:
```lua
```lua
integration = {
integration = {
@ -471,112 +336,12 @@ integration = {
}
}
```
```
## List of colorschemes
## 🙋 FAQ
| Colorschemes | Code Names |
| ---------------- | ------------------ |
| Dark catppuccin | `dark_catppuccin` |
| Neon Latte | `neon_latte` |
| Soft Manilo | `soft_manilo` |
| Light Melya | `light_melya` |
## Overwriting colors & hi groups
Both colors and highlight groups can be overwritten like so:
```lua
catppuccin.remap({<colors>},{<hi_groups>})
```
Since you want to overwrite hi groups, then it's likely that you'll want to use the API to get the colors from x colorscheme as well:
```lua
local err, colors = cp_api.get_colors("neon_latte")
```
Here is an example using the API to overwrite the color green and change the style of the comments:
```lua
local cp_api = require("catppuccin.api.colors")
local err, colors = cp_api.get_colors("neon_latte")
- For colorschemes: all editable fields are the same as the ones mentioned in any of the colorschemes found at: [`lua/catppuccin/color_schemes`](https://github.com/Pocco81/Catppuccin.nvim/tree/main/lua/catppuccin/color_schemes). You could also use one as a template, if you will.
- For highlight groups: all the highlight groups have three editable fields: `fg` for the foreground, `bg` for the background and `style` for the style.
<br/>
</details>
## Hooks
Use them to execute code at certain events [described by their names]. These are the ones available:
| `before_loading()` | Before loading a colorscheme |
| `after_loading()` | After loading a colorscheme |
They can be used like so:
```lua
local catppuccin = require("catppuccin")
catppuccin.before_loading = function ()
print("I ran before setting a colorscheme!")
end
```
# 🙋 FAQ
- Q: **_"How can I view the doc from NeoVim?"_**
A: Use `:help Catppuccin.nvim`
- Q: **_"Why are the colorschemes named like that? Do they follow any convention(s)?"_**
A: A colorscheme's name is constructed by two words: the first one is a word that represents the tonalities in the colors used and the second one is the name of a coffee drink from [this list](https://en.wikipedia.org/wiki/List_of_coffee_drinks).
# 👐 Contribute
See [CONTRIBUTING.md](https://github.com/Pocco81/Catppuccin.nvim/blob/dev/CONTRIBUTING.md).
# 💭 Inspirations
- Q: **_"How can I view the doc from NeoVim?"_**
A: Use `:help catppuccin`
The following projects inspired the creation of Catppuccin.nvim. If possible, go check them out to see why they are so amazing :]
## 💝 Thanks to
- [folke/tokyonight.nvim](https://github.com/folke/tokyonight.nvim): A clean, dark Neovim theme written in Lua, with support for lsp, treesitter and lots of plugins. Includes additional themes for Kitty, Alacritty, iTerm and Fish.
Pocco81
3 years ago