Skip to content

Latest commit

 

History

History
640 lines (480 loc) · 21.2 KB

usage.md

File metadata and controls

640 lines (480 loc) · 21.2 KB

Overview

Nightfox is a highly customizable theme for vim and neovim with support for lsp, treesitter and a variety of plugins. It comes with multiple different styles to suite your preference. These are:

  • Nightfox
  • Dayfox
  • Dawnfox
  • Duskfox
  • Nordfox
  • Terafox
  • Carbonfox

Usage

At it's core nightfox is simply a colorscheme just like any other. If you just want to use the theme out of the box simply set the colorscheme with the :colorscheme command

:colorscheme nightfox

Nightfox is built to be customizable. There are four main components that can be customized. These are option, palette, spec, and group.

Configuration

Nightfox allows you to set individual components separately as apposed to using the default setup function.

Init

The init() function set nightfox's config options.

require('nightfox').init({
  dim_inactive = true,
})

Overrides

The individual components: palettes, specs and groups can be set separately.

local override = require('nightfox').override
override.palettes({
  nightfox = {
    red = "#c94f6d",
  },
  nordfox = {
    comment = "#60728a",
  },
})
override.specs({
  nightfox = {
    syntax = {
      keyword = "magenta"
    }
  }
})
override.groups({
  all = {
    IncSearch = { bg = "palette.cyan" },
  },
})

Overrides for palettes and specs are defined per style. The purpose of overriding these components is to change colors. Colors are only relevant to a specific style. Groups on the other hand are not defined per style. These mainly use the color defined in the palette and spec objects in order to set values using templates.

Setup

The setup function is a convince wrapper for the above components. It takes each component as seperate keys and calls the correct init/override function.

local options = {
  dim_inactive = true,
}
local palettes = {
  nightfox = {
    red = "#c94f6d",
  },
  nordfox = {
    comment = "#60728a",
  },
}
local specs = {
  nightfox = {
    syntax = {
      keyword = "magenta"
    }
  }
}
local groups = {
  all = {
    IncSearch = { bg = "palette.cyan" },
  },
}
require('nightfox').setup({
  options = options,
  palettes = palettes,
  specs = specs,
  groups = groups,
})

Templates

Templates allow for referencing of other lower level objects in nightfox's config. For example instead of setting an absolute color value, you can refer to a lower object's value instead. The base of nightfox is a palette. A palette does not use a template as it is the base that others built off of. Palettes are used as the template source for spec objects. Specs objects are used as template source for group objects.

If a value does not start with # symbol it will be treated as the template path. Everything in lua is a table. This means that palettes and specs are just lua tables. A template path is the keys to index into the table separated by . characters.

Note: If the resulting value of a template is a [shade] then the base value will be used.

Example:

-- Specs use palettes as the template source
local specs = {
  nightfox = {
    syntax = {
      -- Value does not start with `#` so is treated as a template.
      -- Since `magenta` is a `shade` object the `base` value will be used.
      keyword = "magenta",

      -- Adding either `.bright` or `.dim` will change the value
      conditional = "magenta.bright",
      number = "orange.dim",
    },
    git = {
      -- A color define can also be used
      changed = "#f4a261",
    }
  }
}

-- Groups use specs as the template source
local groups = {
  all = {
    -- The template path is parsed to [`syntax`, `string`]. This is like calling into a lua table like:
    -- `spec.syntax.string`.
    String = { fg = "syntax.string" },

    -- If `link` is defined it will be applied over any other values defined
    Whitespace = { link = "Comment" }

    -- Specs are used for the template. Specs have their palette's as a field that can be accessed
    IncSearch = { bg = "palette.cyan" },
  },
}

require('nightfox').setup({ specs = specs, groups = groups })

Option

options.compile_path {path}

The output directory {path} where the compiled results will be written to. Default: vim.fn.stdpath("cache")/nightfox.

options.compile_file_suffix {suffix}

The string appended to the compiled file. Each style outputs to its own file. These files will append the {suffix} to the end of the file. Default: _compiled

options.transparent {bool}

A boolean value that if set will disable setting the background of Normal, NormalNC and other highlight groups. This lets you use the colors of the colorscheme but use the background of your terminal. Default: false.

options.terminal_colors {bool}

A boolean value that if set will define the terminal colors for the builtin terminal (vim.g.terminalcolor*). Default: true.

options.dim_inactive {bool}

A boolean value that if set will set the background of Non current windows to be darker. See :h hl-NormalNC.

options.module_default {bool}

The default value of a module that has not been overridden in the modules table.

options.styles {table}

styles is a table that contains a list of syntax components and their corresponding style. These styles can be any combination of |highlight-args|. The list of syntax components are:

  • comments
  • conditionals
  • constants
  • functions
  • keywords
  • numbers
  • operators
  • preprocs
  • strings
  • types
  • variables

Example:

local options = {
  styles = {
    comments = "italic",
    functions = "italic,bold",
  }
}

options.inverse {table}

inverse is a table that contains a list of highlight types. If a highlight type is enabled it will inverse the foreground and background colors instead of applying the normal highlight group. Thees highlight types are: match_paren, visual, search. For an example if search is enabled instead of highlighting a search term with the default search color it will inverse the foreground and background colors.

options.colorblind {table}

colorblind stores configuration information for nightfox's color vision deficiency (cdv) mode. This contains the following table:

colorblind = {
  enable = false,        -- Enable colorblind support
  simulate_only = false, -- Only show simulated colorblind colors and not diff shifted
  severity = {
    protan = 0,          -- Severity [0,1] for protan (red)
    deutan = 0,          -- Severity [0,1] for deutan (green)
    tritan = 0,          -- Severity [0,1] for tritan (blue)
  },
},

options.modules {table}

modules store configuration information for various plugins and other neovim modules. A module can either be a boolean or a table that contains additional configuration for that module. If the value is a table it also has a field called enable that will tell nightfox to load it. See modules for more information.

By default modules will be enabled. To change this behaviour change options.module_default to false.

Shade

A shade is a way to group a base color with a bright and dim version. This is the base struct/object that palette colors will be defined from. For example:

local Shade = require("nightfox.lib.shade")
local red = Shade.new("#bf616a", "#d06f79", "#a54e56"),
print(vim.inspect(red))
-- {
--   base = "#bf616a",
--   bright = "#d06f79",
--   dim = "#a54e56",
-- }

This is just a convience structure for building palette for nightfox and should not be used outside of it. This is noted here to help understand the structure of a palette.

Palette

A palette is the base color definitions of a style. Each style defines its own palette to be used by the other components. A palette defines base colors, as well as foreground and background shades. Along with the foreground and background colors a palette also defines other colors such as selection and comment colors.

The base colors are [shade] objects that define a base, bright, and dim color. These base colors are: black, red, green, yellow, blue, magenta, cyan, white, orange, pink.

Key Description
black Shade Color (Base, Bright, Dim)
red Shade Color (Base, Bright, Dim)
green Shade Color (Base, Bright, Dim)
yellow Shade Color (Base, Bright, Dim)
blue Shade Color (Base, Bright, Dim)
magenta Shade Color (Base, Bright, Dim)
cyan Shade Color (Base, Bright, Dim)
white Shade Color (Base, Bright, Dim)
orange Shade Color (Base, Bright, Dim)
pink Shade Color (Base, Bright, Dim)
comment Comment color
bg0 Darker bg (status line and float)
bg1 Default bg
bg2 Lighter bg (colorcolumn folds)
bg3 Lighter bg (cursor line)
bg4 Lighter bg (Conceal, border fg)
fg0 Lighter fg
fg1 Default fg
fg2 Darker fg (status line)
fg3 Darker fg (line numbers, fold columns)
sel0 Popup bg, visual selection bg
sel1 Popup sel bg, search bg

Spec

A spec or specification is a mapping of a palette values to a logical group that is used by the group.

The base of a spec is a re-export of the palette's fg bg and sel. The values that are re-exported are: bg0, bg1, bg2, bg3, bg4, fg0, fg1, fg2, fg3, sel0, sel1.

spec.syntax

The syntax table maps palette color values to syntax values to be used by the group.

Key Description
bracket Brackets and Punctuation
builtin0 Builtin variable
builtin1 Builtin type
builtin2 Builtin const
comment Comment
conditional Conditional and loop
const Constants, imports and booleans
dep Deprecated
field Field
func Functions and Titles
ident Identifiers
keyword Keywords
number Numbers
operator Operators
preproc PreProc
regex Regex
statement Statements
string Strings
type Types
variable Variables

spec.diag

The diag table maps palette colors to vim diagnostic colors values. These values are: error, warn, info, hint, and ok.

spec.diag_bg

The diag_bg table maps palette colors to vim diagnostic background colors. These values are: error, warn, info, hint, and ok.

spec.diff

The diff table maps palette colors to vimdiff highlight colors. These values are: add, delete, change and text.

spec.git

The git table maps palette colors to git colors. These values are: add, removed, changed, conflict, and ignored.

Group

A group is the definition of a highlight-group. The key of the group table is the highlight-group that will be defined, and the table value is the arguments to the |:highlight| command.

Key Help Description
fg |highlight-guifg| The color value of the foreground of the highlight group
bg |highlight-guibg| The color value of the background of the highlight group
sp |highlight-guisp| The color for underlines and undercurls
style |highlight-gui| The style of the highlight group. Ex italic, bold, etc
link |highlight-link| Link one highlight-group to another

If the value of link is present and is not empty, nightfox will link the group to the corresponding value.

Modules

Modules are a way to adding extra information for various plugins or features. This also allows them to be enabled or disabled. There are two types of modules, base modules and extended modules. A base modules do not have any other information and are just a boolean denoting if it is enabled. An extended module is a module that has extra customization information. It is a table that contains the additional configuration as well as a field called enable to determine if the module is applied.

Current list of modules are:

  • alpha
  • aerial
  • barbar
  • cmp
  • coc
  • dap-ui
  • dashboard
  • diagnostic
  • fern
  • fidget
  • gitgutter
  • gitsigns
  • glyph_palette
  • hop
  • illuminate
  • indent_blanklines
  • lazy.nvim
  • leap
  • lightspeed
  • lsp_saga
  • lsp_trouble
  • mini
  • modes
  • native_lsp
  • navic
  • neogit
  • neotest
  • neotree
  • notify
  • nvimtree
  • pounce
  • signify
  • sneak
  • symbol_outline
  • telescope
  • treesitter
  • tsrainbow
  • tsrainbow2
  • whichkey

Neovim specific modules

The following modules are enabled by default only when on neovim, diagnostic, native_lsp, treesitter. These modules are part of the core neovim experience and are liked to by other modules. This also means that they will still be enabled when setting module_default to false.

Extended modules

modules.coc

This module sets highlight groups from neoclide/coc.nvim.

key type default description
enable boolean true Enable the module to be included
background boolean true Set virtual text background color

modules.diagnostic

This module sets highlight groups from vim.diagnostic.

key type default description
enable boolean true Enable the module to be included
background boolean true Set virtual text background color

modules.native_lsp

This module sets highlight groups from neovim's builtin lsp.

key type default description
enable boolean true Enable the module to be included
background boolean true Set virtual text background color

modules.leap

key type default description
enable boolean true Enable the module to be included
background boolean true Sets the label color to the background
harsh boolean false Sets label's contrast to be harsher

Color

Nightfox exposes a color utility library to help with manipulating colors. This library can be required using the following module:

local Color = require('nightfox.lib.color')

color.from_hex({hex})

Create a Color object from either a {hex} number or a css-style hex string ("#RRGGBB[AA]").

color.from_rgba({red}, {green}, {blue}, {alpha})

Create a Color object from a RGBA value. The {red}, {green} and {blue} components ranging from [0,255]. {alpha} is optional and defaults to 1. The {alpha} value's is from [0,1].

color.from_hsv({hue}, {sat}, {value}, {alpha})

Create a Color object from a HSV value. The {hue} is a float ranging [0,360]. {sat} and {value} are floats ranging from [0,100]. {alpha} is optional and defaults to 1. The {alpha} value's is from [0,1].

color.from_hsl({hue}, {sat}, {lightness}, {alpha})

Create a Color object from a HSL value. The {hue} is a float ranging [0,360]. {sat} and {lightness} are floats ranging from [0,100]. {alpha} is optional and defaults to 1. The {alpha} value's is from [0,1].

color:to_hex({with_alpha})

Convert a Color object to a integer number. If {with_alpha} is true the hex value will be returned with the alpha value added. This is defaulted to false.

color:to_css({with_alpha})

Convert a Color object to a css_style string ("#RRGGBB[AA]"). If {with_alpha} is true the hex value will be returned with the alpha value added. This is defaulted to false.

color:to_rgba()

Convert a Color object to a RGBA table. The resulting table will have red, green, blue and alpha components as keys of the table.

color:to_hsv()

Convert a Color object to a HSV table. The resulting table will have hue, saturation and value components as keys of the table.

color:to_hsl()

Convert a Color object to a HSL table. The resulting table will have hue, saturation and lightness components as keys of the table.

color:blend({other}, {factor})

Returns a new Color that is a linear blend between two colors. {other} is the other color to blend. {factor} is the percentage of the {other} color that will be blended. This percentage is represented [0,1] where 0 is no color blending and 1 is entirely the {other} color.

color:shade({factor})

Returns a new Color that has been shaded by the {factor}. The factor is a precentage from [-1,1] where -1 is black and 1 is white.

color:brighten({value})

Returns a new Color with {value} added to the value (hsv) of the current color. This returns a lighter version of of the current color if {value} is positive and a darker color is {value} is negative. {value} is Float [-100, 100].

color:lighten({value})

Returns a new Color with {value} added to the lightness (hsl) of the current color. This returns a lighter version of of the current color if {value} is positive and a darker color is {value} is negative. {value} is Float [-100, 100].

color:saturate({value})

Returns a new Color with {value} added to the saturation (hsv) of the current color. This returns either a more or less saturated version depending of +/- v. {value} is Float [-100, 100].

color:rotate({value})

Returns a new Color with {value} added to the hue (hsv) of the current color. The resulting value of hue will be wrapped from [0,360], meaning that if the value exceeds 360 it will be wrapped back to 0.

Colorblind

For individuals with color vision deficiency (cvd), nightfox has implemented a colorblind mode to help enhance color contrast. This can be enabled with this option colorblind.enable.

There are three types of color vision deficiency (cvd)

Cone Type Weak (trichromacy) Missing (Dichromacy)
L / Red Protan Protanomaly Protanopia
M / Green Deutan Deuteranomaly Deuteranopia
S / Blue Tritan Tritanomaly Tritanopia

The severity of protan, deutan, and tritan can be set individually. Severity is a value ranging from 0 to 1. where 1 is full dichromacy (missing cone type).

Example:

require("nightfox").setup({
  options = {
    colorblind = {
      enable = true,
      severity = {
        protan = 0.3,
        deutan = 0.6,
      },
    },
  },
})

Compile

Nightfox is a highly customizable and configurable colorscheme. This does however come at the cost of complexity and execution time.

Nightfox pre-computes the result of your configuration and saves the lua bytecode in a cache to be used on next load. This significantly speeds up nightfox's execution time. Changes to your configuration will be re-computed and cached automatically.

By default nightfox writes the compiled results into the system's cache directory. On unix this is $XDG_CACHE_HOME/nvim/nightfox and on windows this is %localappdata%\\Temp\\nvim\\nightfox.

Compile commands

compile()

Compile nightfox settings for each style and write compiled file to compile_path.

:NightfoxCompile

Compile nightfox settings for each style and write compiled file to compile_path.

Interactive

Nightfox makes it easy to make changes to its config and see the results. For this nightfox exposes the command:

NightfoxInteractive

This command will attach an autocmd to the current buffer that executes on BufferWritePost. The autocmd will clear nightfox's internal state and re-source it's config from the newly saved file. It will then reset the colorscheme.

There are a few things to note:

  • This requires executing luafile on the current file. Any syntax errors will throw errors.
  • If you are using packer and have nightfox's config in a config = function() end block, this will not work as packer would require to be re-compiled and the compiled file sourced.

:NightfoxInteractive

Enable Nightfox configuration reloading on buffer save.