nvim-paper-tonic

Default Settings Preview

Introduction

nvim-paper-tonic is a colorscheme template repository for Neovim 0.5+.

This template's defaults focus on:

1. Compatability with semantic highlighting.
   • I was using colorschemes that often did not provide enough highlight groups to provide distinction between tokens.
2. Visibility in any range of blue-light.
   • I use redshift often, and many colorschemes did not allow for me to see when I had lower color temperatures.

This template's design focuses on:

1. Ease of use and rapid development.
   • New features may simply be integrated with current configurations, rather than rewritten over them.
   • Merging with the upstream repository is simplified by GitHub, allowing you to select what new defaults to add.
   • It provides a large supply of defaults for plugins and programming languages.
     • Define a smaller set of "categorical" highlights (see Neovim's group-name help page) and many more will link automatically.
2. Inversion of Control
   • Changes made to the highlighting algorithm won't affect how you write your colorscheme.
   • New highlight group attributes which are unaccounted for in older versions will simply be ignored without errors due to Lua's tables.

Installation

The only prerequisite is Neovim 0.5+

Creating Your Own

1. Fork this repository, or clone it with git clone https://github.com/Iron-E/nvim-paper-tonic.
2. Follow the instructions in colors/paper-tonic.vim.
   • If you are on a Unix system, use the setup script like so:

   chmod +x ./setup.sh
   ./setup.sh paper-tonic <colorscheme>
   

   Where <colorscheme> is the name of your desired colorscheme.
   • If you are on Windows, rename the files manually.

Whenever you want to update from then on, you can run the update script. This will load the latest upstream changes to the core highlighting library.

Just The Defaults

1. Install a plugin manager such as packer.nvim:

   -- packer.nvim example
   local fn = vim.fn
   
   local install_path = fn.stdpath('data')..'/site/pack/packer/opt/packer.nvim'
   
   if not vim.loop.fs_stat(fn.glob(install_path)) then
   	os.execute('git clone https://github.com/wbthomason/packer.nvim '..install_path)
   end
   
   vim.api.nvim_command 'packadd packer.nvim'
   
   return require('packer').startup {function(use)
   	use {'wbthomason/packer.nvim', opt=true}
   	use 'Iron-E/nvim-paper-tonic'
   end}
   

2. Specify this colorscheme as your default colorscheme in the init.vim:

   " Enable 24-bit color output. Only do this IF your environment supports it.
   " This plugin is fully compatible with 8-bit, 16-bit, and 24-bit colors.
   set termguicolors
   " Use the colorscheme
   colorscheme paper-tonic
   

   Or using init.lua:

   vim.opt.termguicolors = true
   vim.api.nvim_command 'colorscheme paper-tonic'
   

Usage

This repository in itself is an example of how to use nvim-paper-tonic. Aside from this, the following colorschemes are built using nvim-paper-tonic:

• (if you use this, open an issue and I'll add it here!)

As Dependency

Below is an example of how to use nvim-paper-tonic as a dependency.

• See :h paper-tonic-usage for more.

-- Import nvim-paper-tonic
local paper-tonic = require('paper-tonic')

-- First, define some colors
local red = {'#FF0000', 1, 'red'}
local black = {'#000000', 0, 'black'}
local white = {'#FFFFFF', 255, 'white'}

-- Highlight 'Identifier'
paper-tonic.highlight('Identifier', {bg=red, fg=black, style='bold'})

-- Highlight 'Function' conditionally according to background color.
paper-tonic.highlight('Function', {bg=black, fg=red, light={bg=white}})

-- Link 'Example' to 'Identifier'
paper-tonic.highlight('Example', 'Identifier')

-- You can also reference specific attributes of another highlight group.
paper-tonic.highlight('AnotherExample', {bg=paper-tonic.group'SpellBad'.bg, fg=white})

As Template

Below is an example of how to use nvim-paper-tonic as a template.

• See paper-tonic.vim for more.

-- First, define some colors
local red = {'#FF0000', 1, 'red'}
local black = {'#000000', 0, 'black'}
local white = {'#FFFFFF', 255, 'white'}

-- Next define some highlight groups.
local highlight_groups = {
	-- Any field which can be set to "NONE" doesn't need to be set, it will be automatically assumed to be "NONE".
	Identifier = {bg=red, fg=black, style='bold'},
	-- If your colorscheme should respond to multiple background settings, you can do that too:
	Function = {bg=black, fg=red, light={bg=white}},
	--[[ Note that light/dark differentiation is completely optional. ]]

	-- You can also reference specific attributes of another highlight group.
	SomethingElse = function(self) return {fg=self.Identifier.fg, bg=self.Function.bg} end,
}

-- The rest is mostly handled by the template.

FAQ

How can I override the highlighting of one specific highlight group in my init.vim?

When using this plugin, it is important to know that you can't just run :hi on a highlight group and expect that its changes will be retained. You must attach them to the ColorScheme autocmd event, as shown below:

packadd nvim-paper-tonic
set termguicolors "optional

" WRONG! Don't do this.
hi! Error guifg=#000000 guibg=#FFFFFF

" Do this instead.
augroup Highlite
	" You can also use `paper-tonic.highlight()` instead of `:hi!`
	autocmd ColorScheme paper-tonic hi! Error guifg=#000000 guibg=#FFFFFF
augroup end

colorscheme paper-tonic

Of course, substitute paper-tonic with the name of your colorscheme.

Why am I receiving E5108: Error executing lua [string ":lua"]:1: module '<colorscheme>' not found?

Ensure your colorscheme's base folder is in Neovim's rtp before sourcing.

What syntax files should I use for X language?

You can either use nvim-treesitter, vim-polyglot, or some of the following:

Language	Syntax Plugin
ALGOL	sterpe/vim-algol68
C++	bfrg/vim-cpp-modern
Coq	whonore/Coqtail
Dart	dart-lang/dart-vim-plugin
DTrace	vim-scripts/dtrace-syntax-file
F#	ionide/Ionide-vim
Gas	Shirk/vim-gas
Git	tpope/vim-git
Go	fatih/vim-go
GraphViz	liuchengxu/graphviz
HTML5	othree/html5
i3conf	mboughaba/i3config
Java	Iron-E/java-syntax
JavaScript	pangloss/vim-javascript
JSON	elzr/vim-json
Julia	JuliaEditorSupport/julia-vim
Kotlin	udalov/kotlin-vim
LESS	groenewege/vim-less
LLVM	rhysd/vim-llvm
Lua	tbastos/vim-lua
Markdown	plasticboy/vim-markdown
MIPS	vim-scripts/mips
Moonscript	leafo/moonscript-vim
PlantUML	aklt/plantuml-syntax
Prettier	prettier/vim-prettier
Python	vim-python/python-syntax
Razor	jlcrochet/vim-razor
RST	marshallward/vim-restructuredtext
Ruby	vim-ruby/vim-ruby
Rust	Iron-E/rust.vim
SCSS	cakebaker/scss-syntax
Shell	arzg/vim-sh
SQL	shmup/vim-sql-syntax
Stylus	wavded/vim-stylus
SystemD	wgwoods/vim-systemd-syntax
SystemTap	nickhutchinson/vim-systemtap
TeX	lervag/vimtex
TOML	cespare/vim-toml
Ungrammar	Iron-E/vim-ungrammar
VB.NET	vim-scripts/vbnet
Vim Logs	MTDL9/vim-log-highlighting
XML	amadeus/vim-xml
YAML	stephpy/vim-yaml
YATS	HerringtonDarkholme/yats

Contribution

This repository is looking for contributions! The following things are appreciated:

• More default support for plugins, languages, etc.
• Setup scripts for Windows.

If you would like to contribute something, and you aren't sure how, open a ticket! I'd love to help you help me.