ViMix

Use a template to manage the nitty gritty of vim colorschemes. Take your favorite colorscheme and easily mix it up a bit. Mix up new colorschemes easily.

tl;dr Just create a vimix file (from a template) and run :Vimix.

Usage

Once installed, edit a file with a .vimix extension. It's easiest to install a template, but feel free to start from scratch. Each line in the vimix file tells the plugin to perform a specific action when the :Vimix command is issued. This :Vimix command takes the current vimix buffer and generates a colorscheme (in ~/.vim/colors/ unless it's changed by passing an argument).

Comments

A comment can be in any line. It

Lines beginning with ! are comments that are only visible in the vimix file. When running :Vimix they disappear.

Lines beginning with " are comments that appear both in the vimix file and in the colorscheme generated by :Vimix. They also are used by the header section to generated meta data.

Lines beginning with '<' are comments that are glued to the links (see links section. Only put these on lines by themselves.

Header

At the top, you should have a header section (a comment block where each comment begins with title-case words followed by a colon (":")).

" Name: nightsky
" Description: dark, low-contrast colorscheme
" Author: Your Name
" Last Change: 01 January 2020
" URL: https://github.com/YourName/nightsky
" Type: dark

You, at least, must have the "Name" and "Type". These are used when generating the colorscheme. The others are just nice to have. They must begin with a capital letter. It's recommended that all words before the colon for any header line begin with a capital letter and only contain letters, numbers, and underscores after.

Links

These lines link one or more groups to a target group. Multiple of these linkages can be concatenated with a ";". For example, A -> B -> T1 ; C -> D -> E -> T2 links "A" and "B" to "T1" in addition to "C", "D", and "E" to "T2".

Here is a real example:

Function -> PreProc -> Special -> Type -> Identifier
StatusLineTerm -> StatusLine ; StatusLineTermNC -> StatusLineNC

The first line links "Function", "PreProc", "Special", and "Type" to "Identifier". The second line links "StatusLineTerm" to "StatusLine" and links "StatusLineTermNC" to "StatusLineNC".

See Links Relativity section for more information about preserving surrounding comments and ex commands.

Definitions

These types of lines define the colors that will be used throughout the rest of the file. So, add them above any groups, but you can and should put them below the header section. The way to create a definition is to create a number or a lower-case word followed by a colon. Here are three examples:

fg: 187 ~ [7,7]
0: 238 ~ [grey]
black: 232 ~ [0,none]

There are three types of definitions (depending on what comes before the colon):

Palette: Numbers 0-15 define a color for the palette [required]
Special: "fg"/"bg" for foreground/background [required]
Extra: any name beginning with a lower-case letter [optional]
- specifically, the name must begin with lower-case and then any letter, number, or underscore may follow

There are three mandatory fields following the colon:

Ansi: this is the ansi color for color terminals
- must be a number from 16 to 255 (inclusive)
Hex: this is the hex color for 'termguicolors' and gvim
- must be anything from #000000 to #ffffff
Alias: either create an aliased name (for a palette def) or a base-16 mapping (for any other def)
- eg, 0: 238 ~ [grey] allows grey to be used in Groups
- eg, black: 232 ~ [0,none] maps black to 0 if used for foreground and t_Co is below 256.
- eg, black: 232 ~ [0,none] maps black to none if used for background and t_Co is below 256.

(For now, base-16 mappings are required; there is no convenient way to get around this, either.)

Groups

This is where all of the magic culminates. Groups let you bind definitions to highlight groups. Here are a few examples:

Constant red
Bold BU
Tag U orange
QuickFixLine B ~ light_black
ColorColumn ~ faint_black

Constant red makes constants have a red foreground; this uses 1 from the palette (aliased to red, of course)
Bold BU makes Bold group be bold and underlined
Tag U orange makes Tag underlined with orange foreground
QuickFixLine B ~ light_black makes QuickFiixLine be bold with no foreground and light-black background
ColorColumn ~ faint_black make ColorColumn have no foreground and faint-black background

There are four parts to a Group:

Name: the highlight group (eg: Constant) [mandatory]
Attributes: Concatenated first letter of Bold, Underline, Italic, Reverse, or NONE [optional]
Color: foreground followed by background; order matters; at least one [mandatory]
- eg: red or red ~ means red foreground
- eg: ~ red means red background

Links Relativity

When the colorscheme is being generated, all of these links are moved to the top so that any conditionals that have finish in them do not prevent any links from being formed. Since this happens, any comments near the links will be lost, so instead of using " for a comment prefix, you can use < for a comment prefix to keep the comment relatively in sync with the surrounding links. Lastly, > can be used to inject an ex command around the links. Therefore, in the vimix file, the following

>if get(g:, 'nightsky_dolinks')
    < Link groups mostly in "middle" to Identifier
    Function -> PreProc -> Special -> Type -> Identifier
    < Keep StatusLine same for :terminal
    StatusLineTerm -> StatusLine ; StatusLineTermNC -> StatusLineNC
>endif

... will result in this after running :Vimix

if
    " Link groups mostly in "middle" to Identifier
    Function -> PreProc -> Special -> Type -> Identifier
    " Keep StatusLine same for :terminal
    StatusLineTerm -> StatusLine ; StatusLineTermNC -> StatusLineNC
endif

... even though the links are moved up to the top.

Todo

[ ] Add usable templates [ ] Add development tools to pick color (hex or 256) [ ] Automatically highlight Groups in the vimix files [ ] Allow hex to approximate ~ in Ansi field for Definitions [ ] Add more checking to prevent bad breakages [ ] Use local list instead of returning with echom + echohl ErrorMsg

novasenco / vimix