Chalklines for NeoVim

About

Currently a WIP. Please check issues for things that are missing. Chalklines is a Light/Dark color scheme for neovim written in lua.

📖 Table of Contents

Features
Requirements
Installation
Usage
Configuration
Supported Plugins
Comparison to VS Code's One Dark Pro
Extras
FAQs
Credits

Features

Override default styles, colors and highlight groups
Create custom highlight groups and even highlight groups by filetypes
Treesitter support
Support for many popular plugins

Requirements

Neovim 0.5+ (0.7+ for filetype highlights)
termguicolors enabled for true color support
treesitter for full syntax highlighting

Installation

Install with your package manager:

use "jzone1366/chalklines.nvim"    -- Packer

Plug 'jzone1366/chalklines.nvim'   " Vim-Plug

Usage

Use the built-in :colorscheme command to load:

vim.cmd("colorscheme chalklines")  -- Lua

colorscheme chalklines             " Vimscript

Configuration

Default configuration

A call to the setup function is only required if you wish to change the defaults:

require("chalklines").setup({
  dark_theme = "chalklines_main", -- The default dark theme
  light_theme = "chalklines_bright", -- The default light theme
  -- The theme function can be overwritten with a string value for the theme
  theme = function()
      if vim.o.background == "dark" then
          return config.dark_theme
      else
          return config.light_theme
      end
  end,
  colors = {}, -- Override default colors by specifying colors for 'chalklines_main' or 'chalklines_bright' themes
  hlgroups = {}, -- Override default highlight groups
  filetype_hlgroups = {}, -- Override default highlight groups for specific filetypes
  plugins = { -- Override which plugin highlight groups are loaded
    -- ...
  },
  styles = { -- Choose from "bold,italic,underline"
      strings = "NONE", -- Style that is applied to strings.
      comments = "NONE", -- Style that is applied to comments
      keywords = "NONE", -- Style that is applied to keywords
      functions = "NONE", -- Style that is applied to functions
      variables = "NONE", -- Style that is applied to variables
      virtual_text = "NONE", -- Style that is applied to virtual text
  },
  options = {
      bold = false, -- Use the colorscheme's opinionated bold styles?
      italic = false, -- Use the colorscheme's opinionated italic styles?
      underline = false, -- Use the colorscheme's opinionated underline styles?
      undercurl = false, -- Use the colorscheme's opinionated undercurl styles?
      cursorline = false, -- Use cursorline highlighting?
      transparency = false, -- Use a transparent background?
      terminal_colors = false, -- Use the colorscheme's colors for Neovim's :terminal?
      window_unfocussed_color = false, -- When the window is out of focus, change the normal background?
  }
})

Configuring themes

Currently, there are two themes available:

chalklines_main
chalklines_bright

A default theme can be set with:

theme = "chalklines_main",

If no value is specified, the colorscheme will use the values as per the default config which uses vim.o.background. With a dark background, the theme will use onedark and with a light background, onelight, by default. For greater customisation with vim.o.background, default dark and light themes can be set:

dark_theme = "chalklines_main",
light_theme = "chalklines_bright",

Configuring plugins

By default, all of the plugins supported by the theme are loaded at runtime. Specific plugins can be disabled as follows:

plugins = {
  native_lsp = false,
  polygot = false,
  treesitter = false
}

Alternatively, all of the plugins can be disabled at once:

plugins = {
  all = false
}

Or, all of the plugins can be disabled with only a select few enabled:

plugins = {
  all = false
  native_lsp = true,
  treesitter = true
}

Note: For a full list of plugins supported, and their names, see the plugins section

Configuring styles

Within the colorscheme, collections of highlight groups have been grouped together into styles. For users who use monospaced fonts with nice italics, this can go someway to enhancing the aesthetic of the colorscheme. These styles may be configured as below:

styles = {
  comments = "italic",
  functions = "NONE",
  keywords = "bold,italic",
  strings = "NONE",
  variables = "NONE",
  virtual_text = "NONE"
}

| Note: See the Neovim help for a full list of styles

Configuring colors

The colorscheme has a palette of 13 core colors alongside many additional ones which are used for menus and git diffs. These colors can be found in the themes.

The default colors can be changed by specifying the name of the color and a new hex code:

colors = {
  red = "#FF0000"
}

Specifying new colors

New colors may be created which will then be merged into a theme's color palette:

colors = {
  my_new_red = "#f44336"
}

Note: Custom colors can also be referenced when creating custom highlight group overrides

Specifying colors by theme

It's possible to override default colors within a theme such as the bg color. This is a common question for those who wish to have a darker background than the default. Of course it would make sense to have different bg colors for the chalklines_main and chalklines_bright themes. This can be achieved by specifying the theme name as a table, followed by the color:

colors = {
  chalklines_main = {
    bg = "#FFFF00" -- yellow
  },
  chalklines_bright = {
    bg = "#00FF00" -- green
  }
}

Configuring highlight groups

The editor, syntax and plugin files use a large array of highlight groups. There are three ways to customize or override them:

Using specific hex colors:

hlgroups = {
  Comment = { fg = "#FF0000", bg = "#FFFF00" }
}

Referencing the name of colors:

hlgroups = {
  Comment = { fg = "${my_new_red}" bg = "${yellow}" }
}

Linking to other highlight groups:

hlgroups = {
  Comment = { link = "Substitute" }
}

Configuring filetype highlight groups

filetype_hlgroups = {
  -- Use the filetype as per the `set filetype?` command
  yaml = {
    TSField = { fg = "${red}" }
  },
  python = {
    TSConstructor = { fg = "${bg}", bg = "${red}" }
  }
}

Note:

Neovim 0.7+ is required for filetype highlights

Currently support for highlighting in Telescope's previewer is unavailable

The excellent hlargs.nvim plugin allows for greater customisation over arguments definitions and usages

Ignoring filetypes and buffer types

Certain file and buffer types may be ignored to prevent filetype highlights being overwritten when navigating to a new buffer. The default types to be ignored are:

filetype_hlgroups_ignore = {
  filetypes = {
    "^aerial$",
    "^alpha$",
    "^fugitive$",
    "^fugitiveblame$",
    "^help$",
    "^NvimTree$",
    "^packer$",
    "^qf$",
    "^startify$",
    "^startuptime$",
    "^TelescopePrompt$",
    "^TelescopeResults$",
    "^terminal$",
    "^toggleterm$",
    "^undotree$"
  },
  buftypes = {
    "^terminal$"
  }

Configuring options

Formatting

Alongside styles, the colorscheme applies some opinionated formatting. These can be configured with the following options:

options = {
  bold = true, -- Use the colorscheme's opinionated bold styles?
  italic = true, -- Use the colorscheme's opinionated italic styles?
  underline = true, -- Use the colorscheme's opinionated underline styles?
  undercurl = true -- Use the colorscheme's opinionated undercurl styles?
}

Transparency

The colorscheme supports transparent backgrounds:

options = {
  transparency = true
}

By setting the transparency option to true, the Normal, Folded, SignColumn, Statusline and Tabline groups will have NONE as the background color. Additional transparency may be achieved by overriding more highlight groups.

Terminal Colors

The colorscheme supports changing the colors for Neovim's :terminal to the current theme:

options = {
  terminal_colors = true
}

Window Focus Color

The colorscheme supports changing the color of the main window in Neovim when focussed is lost. For example, when a telescope or packer pop up appears:

options = {
  window_unfocussed_color = true
}

Note: This can be seen in the screenshots above where nvim-tree is opened and out of focus

Cursorline

Cursorline highlighting is supported in the colorscheme using a cursorline color (which may of course be overriden). This can be enabled with the following:

colors = {
  cursorline = "#FF0000" -- This is optional. The default cursorline color is based on the background
},
options = {
  cursorline = true
}

Supported Plugins

The colorscheme supports the following plugins:

aerial.nvim (aerial)
barbar.nvim (barbar)
Copilot.vim (copilot)
Dashboard (dashboard)
gitsigns.nvim (gitsigns_nvim)
Hop.nvim (hop)
Indent Blankline (indentline)
lspsaga.nvim (lsp_saga)
marks.nvim (marks)
Neotest (neotest)
neo-tree (neo_tree)
nvim-cmp (nvim_cmp)
nvim-dap (nvim_dap)
nvim-dap-ui (nvim_dap_ui)
nvim-hlslens (nvim_hlslens)
nvim-lspconfig (native_lsp)
nvim-navic (nvim_navic)
nvim-notify (nvim_notify)
nvim-tree (nvim_tree)
nvim-ts-rainbow (nvim_ts_rainbow)
packer.nvim (packer)
polygot (polygot)
startify (startify)
telescope.nvim (telescope)
toggleterm.nvim (toggleterm)
Treesitter (treesitter)
Trouble (trouble_nvim)
Vim Ultest (vim_ultest)
Which Key (which_key_nvim)

jzone1366/chalklines.nvim