mini.base16 documentation
Generated from the main
branch of ‘mini.nvim’
mini.base16 Base16 colorscheme creation
MIT License Copyright (c) 2021 Evgeni Chasnovski
Module
Fast implementation of chriskempson/base16 color scheme (with Copyright (C) 2012 Chris Kempson) adapted for modern Neovim Lua plugins. Extra features:
Configurable automatic support of cterm colors (see highlight-cterm).
Opinionated palette generator based only on background and foreground colors.
Supported highlight groups:
Built-in Neovim LSP and diagnostic.
Plugins (either with explicit definition or by verification that default highlighting works appropriately):
Setup
This module needs a setup with require('mini.base16').setup({})
(replace {}
with your config
table). It will create global Lua table MiniBase16
which you can use for scripting or manually (with :lua MiniBase16.*
).
See MiniBase16.config for config
structure and default values.
This module doesn’t have runtime options, so using vim.b.minibase16_config
will have no effect here.
Example:
require('mini.base16').setup({
palette = {
base00 = '#112641',
base01 = '#3a475e',
base02 = '#606b81',
base03 = '#8691a7',
base04 = '#d5dc81',
base05 = '#e2e98f',
base06 = '#eff69c',
base07 = '#fcffaa',
base08 = '#ffcfa0',
base09 = '#cc7e46',
base0A = '#46a436',
base0B = '#9ff895',
base0C = '#ca6ecf',
base0D = '#42f7ff',
base0E = '#ffc4ff',
base0F = '#00a5c5',
},
use_cterm = true,
plugins = {
default = false,
['nvim-mini/mini.nvim'] = true,
},
})
Notes
This is used to create some of plugin’s color schemes (see MiniBase16-color-schemes).
Using
setup()
doesn’t actually create a :colorscheme. It basically creates a coordinated set of highlight-groups. To create your own theme:Put “myscheme.lua” file (name after your chosen theme name) inside any “colors” directory reachable from ‘runtimepath’ (“colors” inside your Neovim config directory is usually enough).
Inside “myscheme.lua” call
require('mini.base16').setup()
with your palette and only after that set g:colors_name to “myscheme”.
Color schemes
Base16 colorschemes
This module comes with several pre-built color schemes. Each of them is a mini.base16 theme created with faster version of the following Lua code:
require('mini.base16').setup({ palette = palette, use_cterm = true })
Activate them as regular :colorscheme (for example, :colorscheme minischeme
).
minischeme
Blue and yellow main colors with high contrast and saturation palette. Palettes are:
-- For dark 'background':
MiniBase16.mini_palette('#112641', '#e2e98f', 75)
-- For light 'background':
MiniBase16.mini_palette('#e2e5ca', '#002a83', 75)
minicyan
Cyan and grey main colors with moderate contrast and saturation palette. Palettes are:
-- For dark 'background':
MiniBase16.mini_palette('#0A2A2A', '#D0D0D0', 50)
-- For light 'background':
MiniBase16.mini_palette('#C0D2D2', '#262626', 80)
setup()
MiniBase16.setup
({config})
Module setup
Setup is done by applying base16 palette to enable colorscheme. Highlight groups make an extended set from original base16-vim plugin. It is a good idea to have config.palette
respect the original styling principles.
By default only ‘gui highlighting’ (see highlight-gui and ‘termguicolors’) is supported. To support ‘cterm highlighting’ (see highlight-cterm) supply config.use_cterm
argument in one of the formats:
true
to auto-generate frompalette
(as closest colors).Table with similar structure to
palette
but having terminal colors (integers from 0 to 255) instead of hex strings.
Parameters
{config} (table)
Module config table. See MiniBase16.config.
Usage
require('mini.base16').setup({}) -- replace {} with your config table
-- needs `palette` field present
config
MiniBase16.config
Defaults
MiniBase16.config = {
-- Table with names from `base00` to `base0F` and values being strings of
-- HEX colors with format "#RRGGBB". NOTE: this should be explicitly
-- supplied in `setup()`.
palette = nil,
-- Whether to support cterm colors. Can be boolean, `nil` (same as
-- `false`), or table with cterm colors. See `setup()` documentation for
-- more information.
use_cterm = nil,
-- Plugin integrations. Use `default = false` to disable all integrations.
-- Also can be set per plugin (see |MiniBase16.config|).
plugins = { default = true },
}
Plugin integrations
config.plugins
defines for which supported plugins highlight groups will be created. Limiting number of integrations slightly decreases startup time. It is a table with boolean (true
/false
) values which are applied as follows:
If plugin name (as listed in mini.base16) has entry, it is used.
Otherwise
config.plugins.default
is used.
Example which will load only “mini.nvim” integration:
require('mini.base16').setup({
palette = require('mini.base16').mini_palette('#112641', '#e2e98f', 75),
plugins = {
default = false,
['nvim-mini/mini.nvim'] = true,
}
})
mini_palette()
MiniBase16.mini_palette
({background}, {foreground}, {accent_chroma})
Create ‘mini’ palette
Create base16 palette based on the HEX (string ‘#RRGGBB’) colors of main background and foreground with optional setting of accent chroma (see details).
Algorithm design
Main operating color space is CIELCh(uv) which is a cylindrical representation of a perceptually uniform CIELUV color space. It defines color by three values: lightness L (values from 0 to 100), chroma (positive values), and hue (circular values from 0 to 360 degrees). Useful converting tool: https://www.easyrgb.com/en/convert.php
There are four important lightness values: background, foreground, focus (around the middle of background and foreground, leaning towards foreground), and edge (extreme lightness closest to foreground).
First four colors have the same chroma and hue as
background
but lightness progresses from background towards focus.Second four colors have the same chroma and hue as
foreground
but lightness progresses from foreground towards edge in such a way that ‘base05’ color is main foreground color.The rest eight colors are accent colors which are created in pairs
Each pair has same hue from set of hues ‘most different’ to background and foreground hues (if respective chorma is positive).
All colors have the same chroma equal to
accent_chroma
(if not provided, chroma of foreground is used, as they will appear next to each other). Note: this means that in case of low foreground chroma, it is a good idea to setaccent_chroma
manually. Values from 30 (low chorma) to 80 (high chroma) are common.Within pair there is base lightness (equal to foreground lightness) and alternative (equal to focus lightness). Base lightness goes to colors which will be used more frequently in code: base08 (variables), base0B (strings), base0D (functions), base0E (keywords). How exactly accent colors are mapped to base16 palette is a result of trial and error. One rule of thumb was: colors within one hue pair should be more often seen next to each other. This is because it is easier to distinguish them and seems to be more visually appealing. That is why
base0D
andbase0F
have same hues because they usually represent functions and delimiter (brackets included).
Parameters
{background} (string)
Background HEX color (formatted as #RRGGBB
).
{foreground} (string)
Foreground HEX color (formatted as #RRGGBB
).
{accent_chroma} (number)
Optional positive number (usually between 0 and 100). Default: chroma of foreground color.
Return
(table)
Table with base16 palette.
Usage
local p = require('mini.base16').mini_palette('#112641', '#e2e98f', 75)
require('mini.base16').setup({ palette = p })
rgb_palette_to_cterm_palette()
MiniBase16.rgb_palette_to_cterm_palette
({palette})
Converts palette with RGB colors to terminal colors
Useful for caching use_cterm
variable to increase speed.
Parameters
{palette} (table)
Table with base16 palette (same as in MiniBase16.config.palette
).
Return
(table)
Table with base16 palette using highlight-cterm.