This post is going to be a bit self-serving, I'm putting it here so I can find it later just as much as I'm putting it here in case others might need it or find it useful.

Customizing Vim Color Schemes

I recently got tired of color schemes that were really really close to looking good, or that looked awesome in the GUI, but had a few colors that just didn't contrast well in the terminal. So I went hunting for information on how to create color schemes. I found a broken tutorial that I'm not going to link because it was confusingly broken. Then I launched vim and used the :help command.

First, I tried :help colorscheme which showed me the following:

:colo[rscheme]  Output the name of the currently active color scheme.
                This is basically the same as >
                    :echo g:colors_name
                In case g:colors_name has not been defined :colo will
                output "default".  When compiled without the |+eval|
                feature it will output "unknown".

I scrolled a bit and spotted this gem:

:hi[ghlight]    List all the current highlight groups that have
                attributes set.

:hi[ghlight] {group-name}
                List one highlight group.

And also this:

:hi[ghlight] clear  Reset all highlighting to the defaults.  Removes all
                    highlighting for groups added by the user!
                    Uses the current value of 'background' to decide which
                    default colors to use.

:hi[ghlight] [default] {group-name} {key}={arg} ..
                Add a highlight group, or change the highlighting for
                an existing group.
                See |highlight-args| for the {key}={arg} arguments.
                See |:highlight-default| for the optional [default]
                argument.

Further on they give lots of helpful background information that explains all the different values for the keys and the sorts of arguments they can take, feel free to :help highlight and read through it yourself, but we've already got enough information to start customizing.

Create a new file for the color scheme to live in:

    mkdir -p ~/.vim/colors/
    vim ~/.vim/colors/awesomesauce.vim

And put the following in it:

    if exists("syntax_on")
        syntax reset
    endif

    set background&
    highlight clear

    let g:colors_name = "awesomesauce"

The content all comes from /usr/share/vim/vim74/colors/default.vim except we've customized the value used for the scheme name. If you picked something less awesome than awesomesauce.vim as the file, that's fine, but make sure it matches the g:colors_name value inside the file.

To make Vim use the new color scheme by default, edit your ~/.vimrc file to include colorscheme awesomesauce (again, name needs to match the file name and the colors_name value.

So now, the next part is to use the :highlight command to view the current color settings. Launch a new instance of Vim and either manually set the color scheme (:colorscheme awesomesauce) or have set it as the default as described above. Then, pick any that you want to change.

Depending on the type of file that's currently open, you may have more or less colors than when trying the command while viewing different files.

So, here's the process, first, do :highlight and there will be a screen full of settings, you can use the regular motion keys for moving through the list, but be aware that paging with the space will close the list when you reach the end. Each setting will have a sample xxx so you can see the effects of the settings. The values that are most likely of interest are Normal, Comment, Statement, and LineNr.

For example, I put the following in my config so that the foreground color for all normal text would be gray and the background would be.. err.. light black? Yeah, I know, another gray, but I find the contrast to be nice and light on my eyes.

highlight Normal ctermfg=grey  guifg=#bcbcbc ctermbg=80 guibg=#2b2b28

The ctermfg is the terminal foreground color. The guifg is the foreground color for the GUI. The ctermbg is the terminal background color. The guibg is the background color.

Before I settled on that color, I tested out what it would look like by entering that as a command into vim as :highlight Normal ctermfg=grey guifg=#bcbcbc ctermbg=80 guibg=#2b2b28 -- While I was tweaking the stting, I only modified the ctermfg and ctermbg because I was using the command-line Vim and not the GUI.

If you're curious about valid colors (like that mysterious 80?) there are some resources I stumbled over that can shed some light on the values. One is a color chart for values that can be used in the GUI. And another is a command that can be run in the terminal (or turned into a shell script).

The command you can do in bash to see the available colors:

    for code in {0..255}; do echo -e "\e[38;05;${code}m $code: Test"; done

After saving the file, you'll need to source it (if it's the currently open file :source %) to see the change, or reload Vim. If you want to save some time, you can just enter the commands, tweaking the colors, and when it looks right, then save it to the file.

There are likely other settings from the list that you'll want to change, for example, if you use vimdiff you'll probably want to change the DiffAdd, DiffChange, DiffDelete, and DiffText colors because they always look like shit by default.

Another useful resource with color schemes and screenshots: Vim Colors site

Summary

You can view the current colors with :highlight, test modifying it by copying a line from the output and removing the xxx preview in it, and when the value is good, save it to a custom .vim color file. Edit your .vimrc to make it active by default.