Fix broken Vim Themes

I’ve been around the houses on this problem long enough, and after many years of trying various tricks and having them fail I decided to document an actual working solution.

1. Install a terminal that has good colour support (e.g. Alacritty)
2. Install a better Vim (i.e. Neovim) †

† This should still work with standard Vim, but actually Neovim has so many performance improvements, and quality of life plugins it’s not worth fighting for purity (trust me, I had been using standard vim and the standard macOS terminal app for 10 years before admitting I was fighting the tide).

Now that you have the right tools, let’s explain the configuration.

~/.config/nvim/init.vim

" this will tell Neovim to enable 24bit true color
if (has("termguicolors"))
 set termguicolors
endif

~/.bashrc

# this isn't necessary when using Neovim in an appropriate terminal, 
# but it will help when running Neovim inside of tmux.
export TERM="xterm-256color"

~/.tmux.conf

set-option -g default-terminal 'screen-256color-bce'
set-option -ga terminal-overrides ",xterm-256color:Tc"

The tmux manual states that default-terminal should be set to screen, tmux or a derivative of them, which is why this doesn’t get set to the same value (xterm-256color) that TERM has in the .bashrc file.

Additionally, we use the -bce suffix (rather than just setting screen-256color) because otherwise tmux won’t use a transparent background. Having a transparent background allows the terminal colour palette to be utilised and this helps Vim themes to display correctly.

Lastly, terminal-overrides let’s you configure tmux to know about terminal capabilities it otherwise might not be able to detect by itself. So this is why we set it to the same value (xterm-256color) that TERM has in the .bashrc file.