From 6fd0a4900e75ff8b213dd16e4ea90d15650b1bde Mon Sep 17 00:00:00 2001 From: Pocco81 Date: Thu, 11 Nov 2021 23:19:45 -0500 Subject: [PATCH] updated README to follow new format --- README.md | 379 +++++++++++------------------------------------------- 1 file changed, 72 insertions(+), 307 deletions(-) diff --git a/README.md b/README.md index f032e40..6977734 100644 --- a/README.md +++ b/README.md @@ -1,169 +1,75 @@ -# Read this: -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 - -
- 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, ...). -
- -# 🌲 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) - - [Hooks](#hooks) -- [Contribute](#-contribute) - - [Need Help](#need-help) -- [Inspirations](#-inspirations) -- [License](#-license) -- [FAQ](#-faq) -- [To-Do](#-to-do) - -# 🍨 Flavors - -## Dark catppuccin - - - -## Neon Latte - - - -## Soft Manilo - - - -## Light Melya - - - -# πŸ“· Extra - -## Tmux Ports -

- Neon Latte -      - Dark catppuccin +

😸 Catppuccin for NeoVim

+

Warm mid-tone dark theme to show off your vibrant self!

+

- Soft Manilo -      - Light Melya +

# 🎁 Features -- Multiple colorschemes (AKA [flavors](#-flavors)) available! -- Handy CLI. -- Allows user remaps. -- Extensible for many use cases. -- Integrations with a lot of stuff: - - [Treesitter](https://github.com/tree-sitter/tree-sitter) - - [Native LSP](https://github.com/neovim/nvim-lspconfig) - - [Telescope](https://github.com/nvim-telescope/telescope.nvim) - - [LSP Saga](https://github.com/glepnir/lspsaga.nvim) - - [Trouble](https://github.com/folke/trouble.nvim) - - [WhichKey](https://github.com/folke/which-key.nvim) - - [Git signs](https://github.com/lewis6991/gitsigns.nvim) - - [BarBar](https://github.com/romgrk/barbar.nvim) - - [NvimTree](https://github.com/kyazdani42/nvim-tree.lua) - - [Lualine](https://github.com/hoob3rt/lualine.nvim) - - [Git Gutter](https://github.com/airblade/vim-gitgutter) - - [Fern](https://github.com/lambdalisue/fern.vim) - - [Lightline](https://github.com/itchyny/lightline.vim) - - [Dashboard](https://github.com/glepnir/dashboard-nvim) - - [Markdown](https://www.markdownguide.org/) - - [Lightspeed](https://github.com/ggandor/lightspeed.nvim) - - [Nvim-ts-Rainbow](https://github.com/p00f/nvim-ts-rainbow) - - [Sneak](https://github.com/justinmk/vim-sneak) - - [Hop](https://github.com/phaazon/hop.nvim) - - [Neogit](https://github.com/TimUntersberger/neogit) - - [Indent Blankline](https://github.com/lukas-reineke/indent-blankline.nvim) - - [Tmux](https://github.com/tmux/tmux) - - [Kitty](https://github.com/kovidgoyal/kitty) - - [Alacritty](https://github.com/alacritty/alacritty) - -# πŸ“Ί Notices - -Checkout the [CHANGELOG.md](https://github.com/Pocco81/Catppuccin.nvim/blob/main/CHANGELOG.md) file for more information on the notices below: - - - -
-Old notices... -

-

-

-
- -# πŸ“¦ Installation - -## Prerequisites - -- [NeoVim 0.5+](https://github.com/neovim/neovim/releases/tag/v0.5.0) - -## Adding the plugin +- Handy CLI. +- Allows user remaps. +- Extensible for many use cases. +- Integrations with a bunch of plugins: + - [Treesitter](https://github.com/tree-sitter/tree-sitter) + - [Native LSP](https://github.com/neovim/nvim-lspconfig) + - [Telescope](https://github.com/nvim-telescope/telescope.nvim) + - [LSP Saga](https://github.com/glepnir/lspsaga.nvim) + - [Trouble](https://github.com/folke/trouble.nvim) + - [WhichKey](https://github.com/folke/which-key.nvim) + - [Git signs](https://github.com/lewis6991/gitsigns.nvim) + - [BarBar](https://github.com/romgrk/barbar.nvim) + - [NvimTree](https://github.com/kyazdani42/nvim-tree.lua) + - [Lualine](https://github.com/hoob3rt/lualine.nvim) + - [Git Gutter](https://github.com/airblade/vim-gitgutter) + - [Fern](https://github.com/lambdalisue/fern.vim) + - [Lightline](https://github.com/itchyny/lightline.vim) + - [Dashboard](https://github.com/glepnir/dashboard-nvim) + - [Markdown](https://www.markdownguide.org/) + - [Lightspeed](https://github.com/ggandor/lightspeed.nvim) + - [Nvim-ts-Rainbow](https://github.com/p00f/nvim-ts-rainbow) + - [Sneak](https://github.com/justinmk/vim-sneak) + - [Hop](https://github.com/phaazon/hop.nvim) + - [Neogit](https://github.com/TimUntersberger/neogit) + - [Indent Blankline](https://github.com/lukas-reineke/indent-blankline.nvim) + +## Usage You can use your favorite plugin manager for this. Here are some examples with the most popular ones: -### Vim-plug +#### Vim-plug ```lua -Plug 'Pocco81/Catppuccin.nvim' +Plug 'catppuccin/nvim' ``` -### Packer.nvim +#### Packer.nvim ```lua -use "Pocco81/Catppuccin.nvim" +use "catppuccin/nvim" ``` -### Vundle +#### Vundle ```lua -Plugin 'Pocco81/Catppuccin.nvim' +Plugin 'catppuccin/nvim' ``` -### NeoBundle +#### NeoBundle ```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: ```lua -colorscheme = "dark_catppuccin", -transparency = false, +transparent_background = false, term_colors = false, styles = { comments = "italic", @@ -187,7 +93,7 @@ integrations = { hints = "underline", warnings = "underline", information = "underline", - } + }, }, lsp_trouble = false, lsp_saga = false, @@ -213,7 +119,7 @@ integrations = { lightspeed = false, ts_rainbow = false, hop = false, -} +}, ``` 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 catppuccin.setup( { - colorscheme = "dark_catppuccin", - transparency = false, + transparent_background = false, term_colors = false, styles = { comments = "italic", @@ -253,7 +158,7 @@ catppuccin.setup( hints = "underline", warnings = "underline", information = "underline", - } + }, }, lsp_trouble = false, lsp_saga = false, @@ -279,7 +184,7 @@ catppuccin.setup( lightspeed = false, ts_rainbow = false, hop = false, - } + }, } ) ``` @@ -298,8 +203,7 @@ local catppuccin = require("catppuccin") -- configure it catppuccin.setup( { - colorscheme = "dark_catppuccin", - transparency = false, + transparent_background = false, term_colors = false, styles = { comments = "italic", @@ -323,7 +227,7 @@ catppuccin.setup( hints = "underline", warnings = "underline", information = "underline", - } + }, }, lsp_trouble = false, lsp_saga = false, @@ -349,7 +253,7 @@ catppuccin.setup( lightspeed = false, ts_rainbow = false, hop = false, - } + }, } ) EOF @@ -369,46 +273,8 @@ colorscheme catppuccin -- Lua 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 ` 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.") -``` - -### Modules - -- `colors` - -```lua -cp_api.get_colors() -``` - -> Gets the colors from ``. 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! @@ -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. -- `colorscheme`: (String) code name of the color-scheme to be used. All of them can be found in the section below. -- `transparency`: (Boolean) if true, disables setting the background color. -- `term_colors`: (Boolean) if true, sets terminal colors (e.g. `g:terminal_color_0`). +- `transparent_background`: (Boolean) if true, disables setting the background color. +- `term_colors`: (Boolean) if true, sets terminal colors (e.g. `g:terminal_color_0`). ## Styles Handles the style of general hi groups (see `:h highlight-args`): -- `comments`: (String) changed the style of the comments. -- `functions`: (String) changed the style of the functions. -- `keywords`: (String) changed the style of the keywords. -- `strings`: (String) changed the style of the strings. -- `variables`: (String) changed the style of the variables. +- `comments`: (String) changed the style of the comments. +- `functions`: (String) changed the style of the functions. +- `keywords`: (String) changed the style of the keywords. +- `strings`: (String) changed the style of the strings. +- `variables`: (String) changed the style of the variables. ## 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 -- **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): +- **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): ```lua 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 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. -- **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. -- **Tmux**: Follow the instructions [here](https://github.com/Pocco81/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. -- **NvimTree:** setting `enabled` to `true` enables this integration: +- **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/catppuccin/nvim/tree/main/extra/alacritty) on your Alacritty config. +- **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. +- **NvimTree:** setting `enabled` to `true` enables this integration: ```lua integration = { @@ -471,112 +336,12 @@ integration = { } ``` -## List of colorschemes - -| 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({},{}) -``` - -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") - -if err.status then -- good - catppuccin.remap({ - green = "#ffffff" - }, - { - Comment = { fg = colors.comment, style = "bold" }, -- any comment - }) -end -``` - -- 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. - -
- - -## Hooks - -Use them to execute code at certain events [described by their names]. These are the ones available: - -| Function | Description | -| ------------------ | ---------------------------- | -| `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). +## πŸ™‹ FAQ -# πŸ’­ 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. -- [norcalli/nvim-base16.lua](https://github.com/norcalli/nvim-base16.lua): Programmatic lua library for setting base16 themes in Neovim. - -# πŸ“œ License - -Catppuccin.nvim is released under the GPL v3.0 license. It grants open-source permissions for users including: - -- The right to download and run the software freely -- The right to make changes to the software as desired -- The right to redistribute copies of the software -- The right to modify and distribute copies of new versions of the software - -For more convoluted language, see the [LICENSE file](https://github.com/Pocco81/Catppuccin.nvim/blob/main/LICENSE.md). - -# πŸ“‹ TO-DO - -**High Priority** - -- Add Aquamarine FrappΓ© - -**Low Priority** - -- Finish DOC -- Add more integrations - -
-

- Enjoy! -

+- [LuisxSullivaN](https://github.com/LuisxSullivaN) +- [Pocco81](https://github.com/Pocco81)