sonokai.txt

*sonokai.txt* High Contrast & Vivid Color Scheme based on Monokai Pro
*sonokai*
>
                 _____                   __         _
                / ___/____  ____  ____  / /______ _(_)
                \__ \/ __ \/ __ \/ __ \/ //_/ __ `/ /
               ___/ / /_/ / / / / /_/ / ,< / /_/ / /
              /____/\____/_/ /_/\____/_/|_|\__,_/_/
<

==============================================================================
CONTENTS                                     *sonokai-contents*

Introduction                                 |sonokai-introduction|
Installation                                 |sonokai-installation|
Usage                                        |sonokai-usage|
Configuration                                |sonokai-configuration|
FAQ                                          |sonokai-faq|

Note: Type |gO| in neovim to show the outline of contents.

==============================================================================
INTRODUCTION                                              *sonokai-introduction*

Sometimes I need a high contrast color scheme, and I think monokai is one of
the best solutions, it's very beautiful and vivid.

However there is one thing I can't stand -- the contrast is too high, which is
totally unacceptable for me.

This color scheme is based on Monokai Pro, the contrast is adjusted to be a
bit lower while keeping the colors vivid enough.

The `shusia`, `maia` and `espresso` variants are basically modified versions of
Monokai Pro. I'm not going to port all variants of Monokai Pro because I don't
like some of them. In addition, I designed some new variants inspired by other
color schemes.

Features~

- High contrast but within acceptable range.
- Vivid colors.
- Highly customizable.
- Rich support for common file types and plugins.
- Tree-sitter support.
- Semantic highlighting support.
- Italic support 🎉

==============================================================================
INSTALLATION                                              *sonokai-installation*

Note: For better syntax highlighting support, consider installing one of the
following plugins additionally to this colorscheme:

	https://github.com/sheerun/vim-polyglot
	https://github.com/nvim-treesitter/nvim-treesitter.

------------------------------------------------------------------------------
Via a Plugin Manager

VIM-PLUG
>
    Plug 'sainnhe/sonokai'
<
Refer to https://github.com/junegunn/vim-plug for further information.

LAZY.NVIM

In Neovim (Lua configuration):
>
    {
      'sainnhe/sonokai',
      lazy = false,
      priority = 1000,
      config = function()
        -- Optionally configure and load the colorscheme
        -- directly inside the plugin declaration.
        vim.g.sonokai_enable_italic = true
        vim.cmd.colorscheme('sonokai')
      end
    }
<
Refer to https://github.com/folke/lazy.nvim for further information.

------------------------------------------------------------------------------
As a Native Vim Package

Users of Vim 8 and greater may leverage Vim's native |packages| system.

1. Create a new directory: `$ mkdir -p ~/.vim/pack/colors/opt`

2. Clone this repository: `$ git clone --depth 1 https://github.com/sainnhe/sonokai.git ~/.vim/pack/colors/opt/sonokai`

3. Generate help tags: `:helptags ~/.vim/pack/colors/opt/sonokai/doc/`

4. Add `packadd! sonokai` to your vimrc.

Note: If you install this color scheme to `pack/*/start` instead of
`pack/*/opt`, you still need to add `packadd! sonokai` to your vimrc,
as discussed in the following issue:
https://github.com/sainnhe/gruvbox-material/issues/60

------------------------------------------------------------------------------
Manually

Users of Vim 7 and lower may install the colorscheme manually.

1. Clone the repository: `git clone --depth 1 https://github.com/sainnhe/sonokai.git`

2. Copy `sonokai/autoload/sonokai.vim` to `~/.vim/autoload/`.

3. Copy `sonokai/colors/sonokai.vim` to `~/.vim/colors/`.

4. Copy `sonokai/doc/sonokai.txt` to `~/.vim/doc/` and
   execute `:helptags ~/.vim/doc/` to generate help tags.

5. To install the airline theme, copy
   `sonokai/autoload/airline/themes/sonokai.vim`
   to `~/.vim/autoload/airline/themes/`.
   https://github.com/vim-airline/vim-airline

6. To install the lightline theme,
   copy `sonokai/autoload/lightline/colorscheme/sonokai.vim`
   to `~/.vim/autoload/lightline/colorscheme/`.
   https://github.com/itchyny/lightline.vim

7. To install the lualine theme,
   copy `sonokai/lua/lualine/themes/sonokai.lua`
   to `~/.config/nvim/lua/lualine/themes/`.
   https://github.com/nvim-lualine/lualine.nvim

------------------------------------------------------------------------------
AUR

There are some packages available for Arch Linux users in AUR:

	https://aur.archlinux.org/pkgbase/vim-sonokai-git (Vim)
	https://aur.archlinux.org/pkgbase/neovim-sonokai-git (Neovim)

==============================================================================
USAGE                                                            *sonokai-usage*

------------------------------------------------------------------------------

Vim~

    Put something like this in your vimrc:
>
        " Important!!
        if has('termguicolors')
          set termguicolors
        endif

        " The configuration options should be placed before `colorscheme sonokai`.
        let g:sonokai_style = 'andromeda'
        let g:sonokai_better_performance = 1

        colorscheme sonokai
<
    See |sonokai-configuration| for more configuration options.

    If you want to apply this color scheme temporarily, run this command in
    vim(this may cause broken colors):
>
        :colorscheme sonokai
<
------------------------------------------------------------------------------

Airline~

    To enable [airline](https://github.com/vim-airline/vim-airline) color
    scheme, put this in your vimrc:
>
        let g:airline_theme = 'sonokai'
<
    To apply it without reloading:
>
        :AirlineTheme sonokai
<
------------------------------------------------------------------------------

Lightline~

    To enable [lightline](https://github.com/itchyny/lightline.vim) color
    scheme, put this in your vimrc:
>
        let g:lightline = {}
        let g:lightline.colorscheme = 'sonokai'

        " Or this line:
        let g:lightline = {'colorscheme' : 'sonokai'}
<
    To apply it without reloading:
>
        :let g:lightline.colorscheme = 'sonokai'
        :call lightline#init()
        :call lightline#colorscheme()
<
------------------------------------------------------------------------------

Lualine~

    To enable [lualine](https://github.com/nvim-lualine/lualine.nvim) color
    scheme, put this in your init.lua:
>
        require'lualine'.setup {
          options = {
            theme = 'sonokai'
          }
        }
<
    To apply it without reloading:
>
        :lua require'lualine'.setup {options = {theme = 'sonokai'}}
<
==============================================================================
CONFIGURATION                                            *sonokai-configuration*

Note: the configuration options should be placed before `colorscheme sonokai`

E.g.
>
    if has('termguicolors')
      set termguicolors
    endif

    let g:sonokai_style = 'andromeda'
    let g:sonokai_better_performance = 1

    colorscheme sonokai
    let g:lightline = {'colorscheme' : 'sonokai'}
<
------------------------------------------------------------------------------
                                                               *g:sonokai_style*
g:sonokai_style~

The style of this color scheme.

    Type:               |String|
    Available values:   `'default'`, `'atlantis'`, `'andromeda'`, `'shusia'`, `'maia'`,
    `'espresso'`
    Default value:      `'default'`

------------------------------------------------------------------------------
                                              *g:sonokai_disable_italic_comment*
g:sonokai_disable_italic_comment~

By default, italic is enabled in `Comment`. To disable italic in `Comment`, set
this option to `1`.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

------------------------------------------------------------------------------
                                                       *g:sonokai_enable_italic*
g:sonokai_enable_italic~

To enable italic in this color scheme, set this option to `1`.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

Note: This option is designed to use with fonts that support cursive italics.
See |sonokai-faq| for more information.

------------------------------------------------------------------------------
                                                              *g:sonokai_cursor*
g:sonokai_cursor~

Customize the cursor color, only works in GUI clients.

    Type:               |String|
    Available values:   `'auto'`, `'red'`, `'orange'`, `'yellow'`, `'green'`,
    `'blue'`, `'purple'`
    Default value:      `'auto'`

------------------------------------------------------------------------------
                                              *g:sonokai_transparent_background*
g:sonokai_transparent_background~

To use transparent background, set this option to `1`.

If you want more ui components to be transparent (for example, status line
background), set this option to `2`.

    Type:               |Number|
    Available values:   `0`, `1`, `2`
    Default value:      `0`

------------------------------------------------------------------------------
                                                *g:sonokai_dim_inactive_windows*
g:sonokai_dim_inactive_windows~

Dim inactive windows. Only works in Neovim currently.

When this option is used in conjunction with |g:sonokai_show_eob| set to 0,
the end of the buffer will only be hidden inside the active window. Inside
inactive windows, the end of buffer filler characters will be visible in
dimmed symbols. This is due to the way Vim and Neovim handle |hl-EndOfBuffer|.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

------------------------------------------------------------------------------
                                           *g:sonokai_menu_selection_background*
g:sonokai_menu_selection_background~

Customize the background color of |hl-PmenuSel| and |hl-WildMenu|.

    Type:               |String|
    Available values:   `'blue'`, `'green'`, `'red'`
    Default value:      `'blue'`

------------------------------------------------------------------------------
                                                    *g:sonokai_spell_foreground*
g:sonokai_spell_foreground~

By default, this color scheme won't color the foreground of |spell|, instead
colored under curls will be used. If you also want to color the foreground,
set this option to `'colored'`.

    Type:               |String|
    Available values:   `'none'`, `'colored'`
    Default value:      `'none'`

------------------------------------------------------------------------------
                                                            *g:sonokai_show_eob*
g:sonokai_show_eob~

Whether to show |hl-EndOfBuffer|.

    Type:               |Number|
    Available values:   `1`, `0`
    Default value:      `1`

------------------------------------------------------------------------------
                                                         *g:sonokai_float_style*
g:sonokai_float_style~

Style used to make floating windows stand out from other windows. `'bright'`
makes the background of these windows lighter than |hl-Normal|, whereas
`'dim'` makes it darker.

Floating windows include for instance diagnostic pop-ups, scrollable
documentation windows from completion engines, overlay windows from
installers, etc.

    Type:               |String|
    Available values:   `'bright'`, `'dim'`
    Default value:      `'bright'`

------------------------------------------------------------------------------
                                           *g:sonokai_diagnostic_text_highlight*
g:sonokai_diagnostic_text_highlight~

Some plugins support highlighting error/warning/info/hint texts, by default
these texts are only underlined, but you can use this option to also highlight
the background of them.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

Currently, the following plugins are supported:

- neovim's built-in language server client
- https://github.com/neoclide/coc.nvim
- https://github.com/prabirshrestha/vim-lsp
- https://github.com/ycm-core/YouCompleteMe
- https://github.com/dense-analysis/ale
- https://github.com/neomake/neomake
- https://github.com/vim-syntastic/syntastic

------------------------------------------------------------------------------
                                           *g:sonokai_diagnostic_line_highlight*
g:sonokai_diagnostic_line_highlight~

Some plugins support highlighting error/warning/info/hint lines, but this
feature is disabled by default in this color scheme. To enable this feature,
set this option to `1`.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

Currently, the following plugins are supported:

- https://github.com/neoclide/coc.nvim
- https://github.com/ycm-core/YouCompleteMe
- https://github.com/dense-analysis/ale
- https://github.com/vim-syntastic/syntastic

------------------------------------------------------------------------------
                                             *g:sonokai_diagnostic_virtual_text*
g:sonokai_diagnostic_virtual_text~

Some plugins can use the virtual text feature of Neovim to display
error/warning/info/hint information. You can use this option to adjust the
way these virtual texts are highlighted.

    Type:               |String|
    Available values:   `'grey'`, `'colored'`, `'highlighted'`
    Default value:      `'grey'`

Currently, the following plugins are supported:

- Neovim's built-in language server client
- https://github.com/neoclide/coc.nvim
- https://github.com/prabirshrestha/vim-lsp
- https://github.com/dense-analysis/ale
- https://github.com/neomake/neomake
- https://github.com/ycm-core/YouCompleteMe

------------------------------------------------------------------------------
                                                        *g:sonokai_current_word*
g:sonokai_current_word~

Some plugins can highlight the word under current cursor, you can use this
option to control their behavior.

    Type:               |String|
    Available values:   `'grey background'`, `'high contrast background'`, `'bold'`,
    `'underline'`, `'italic'`
    Default value:      `'grey background'` when not in transparent mode, `'bold'`
    when in transparent mode.

Currently, the following plugins are supported:

- https://github.com/neoclide/coc-highlight
- https://github.com/dominikduda/vim_current_word
- https://github.com/RRethy/vim-illuminate
- https://github.com/itchyny/vim-cursorword
- https://github.com/prabirshrestha/vim-lsp

------------------------------------------------------------------------------
                                              *g:sonokai_inlay_hints_background*
g:sonokai_inlay_hints_background~

Inlay hints are special markers that are displayed inline with the code to
provide you with additional information. You can use this option to customize
the background color of inlay hints.

    Type:               |String|
    Available values:   `'none'`, `'dimmed'`
    Default value:      `'none'`

Currently, the following LSP clients are supported:

- neovim's built-in language server client
- https://github.com/neoclide/coc.nvim
- https://github.com/prabirshrestha/vim-lsp
- https://github.com/ycm-core/YouCompleteMe

------------------------------------------------------------------------------
                                             *g:sonokai_disable_terminal_colors*
g:sonokai_disable_terminal_colors~

Setting this option to `1` will disable terminal colors provided by this color
scheme so you can remain terminal colors the same when using |:terminal| in
vim and outside of vim.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

------------------------------------------------------------------------------
                                              *g:sonokai_lightline_disable_bold*
g:sonokai_lightline_disable_bold~

By default, bold is enabled in lightline color scheme. To disable bold in
lightline color scheme, set this option to `1`.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

Note: this configuration option doesn't need to be placed before `colorscheme sonokai`

------------------------------------------------------------------------------
                                                  *g:sonokai_better_performance*
g:sonokai_better_performance~

The loading time of this color scheme is very long because too many file types
and plugins are optimized. This feature allows you to load part of the code on
demand by placing them in the `after/syntax` directory.

Enabling this option will reduce loading time by approximately 50%.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

------------------------------------------------------------------------------
                                                     *g:sonokai_colors_override*
g:sonokai_colors_override~

Override color palette. The available keys can be found in
`/path/to/sonokai/autoload/sonokai.vim`.

E.g.
>
    let g:sonokai_colors_override = {'bg0': ['#1e222a', '235'], 'bg2': ['#282c34', '236']}
    colorscheme sonokai
<
    Type:               |Dictionary|
    Default value:      `{}`

==============================================================================
FAQ                                                                *sonokai-faq*

------------------------------------------------------------------------------

The colors don't match those in the screenshots.~

1. This color scheme is mainly designed for true colors, `set termguicolors`
is required. Check output of `vim --version`, maybe your vim doesn't support
`termguicolors`.

2. Maybe your terminal emulator doesn't support true colors, you can test it
using [this script](https://unix.stackexchange.com/questions/404414/print-true-color-24-bit-test-pattern).

3. If you are running vim in tmux, you need to override default true colors of
tmux, as tmux cannot display true colors properly:
[#1246 How to use true colors in vim under tmux?](https://github.com/tmux/tmux/issues/1246)

------------------------------------------------------------------------------

The configuration options don't work.~

You should place them before `colorscheme sonokai` .

------------------------------------------------------------------------------

A lot of errors are detected if I install with pack feature.~

You'll need to add `packadd! sonokai` before applying this color scheme.
Check [sainnhe/gruvbox-material#60](https://github.com/sainnhe/gruvbox-material/issues/60)

------------------------------------------------------------------------------

How to enable cursive italic keywords?~

1. Install a font that supports cursive italics, for example https://aka.sainnhe.dev/fonts

2. Enable italic keywords in this color scheme: `let g:sonokai_enable_italic = 1`

3. (Optional) Disable italic comment: `let g:sonokai_disable_italic_comment = 1`

------------------------------------------------------------------------------

The comment color looks weird.~

Some terminal emulators don't support italics, which may cause the comment
color looks weird. See https://github.com/sainnhe/gruvbox-material/issues/5#issuecomment-729586348

A temporary solution is to disable italic comments via
|g:sonokai_disable_italic_comment|.

If you are using tmux, you may also need to override default true colors of
tmux: https://github.com/tmux/tmux/issues/1246

------------------------------------------------------------------------------

How to use custom colors?~
>
    function! s:sonokai_custom() abort
      " Link a highlight group to a predefined highlight group.
      " See `colors/sonokai.vim` for all predefined highlight groups.
      highlight! link groupA groupB
      highlight! link groupC groupD

      " Initialize the color palette.
      " The first parameter is a valid value for `g:sonokai_style`,
      " and the second parameter is a valid value for `g:sonokai_colors_override`.
      let l:palette = sonokai#get_palette('atlantis', {})
      " Define a highlight group.
      " The first parameter is the name of a highlight group,
      " the second parameter is the foreground color,
      " the third parameter is the background color,
      " the fourth parameter is for UI highlighting which is optional,
      " and the last parameter is for `guisp` which is also optional.
      " See `autoload/sonokai.vim` for the format of `l:palette`.
      call sonokai#highlight('groupE', l:palette.red, l:palette.none, 'undercurl', l:palette.red)
    endfunction

    augroup SonokaiCustom
      autocmd!
      autocmd ColorScheme sonokai call s:sonokai_custom()
    augroup END

    colorscheme sonokai
<
Or in Neovim (Lua configuration):
>
    vim.api.nvim_create_autocmd('ColorScheme', {
      group = vim.api.nvim_create_augroup('custom_highlights_sonokai', {}),
      pattern = 'sonokai',
      callback = function()
        local config = vim.fn['sonokai#get_configuration']()
        local palette = vim.fn['sonokai#get_palette'](config.style, config.colors_override)
        local set_hl = vim.fn['sonokai#highlight']

        set_hl('Search', palette.none, palette.diff_green)
        set_hl('IncSearch', palette.none, palette.diff_red)
      end
    })
<
Note: Make sure to define the `augroup` before calling `colorscheme`.

------------------------------------------------------------------------------

What's your status line configuration?~

See this post: https://aka.sainnhe.dev/statusline

------------------------------------------------------------------------------

What's the font used here?~

See this post: https://aka.sainnhe.dev/fonts

==============================================================================
vim:tw=78:nosta:noet:ts=8:sts=0:ft=help:et:sw=4:fen:fdm=marker:fmr={{{,}}}: