*nightfox.txt*                  A highly customizable theme for vim and neovim

==============================================================================
Table of Contents                                 *nightfox-table-of-contents*

  - Overview                                               |nightfox-overview|
  - Usage                                                     |nightfox-usage|
  - Configuration                                     |nightfox-configuration|
  - Templates                                             |nightfox-templates|
  - Option                                                   |nightfox-option|
  - Shade                                                     |nightfox-shade|
  - Palette                                                 |nightfox-palette|
  - Spec                                                       |nightfox-spec|
  - Group                                                     |nightfox-group|
  - Modules                                                 |nightfox-modules|
  - Color                                                     |nightfox-color|
  - Colorblind                                           |nightfox-colorblind|
  - Compile                                                 |nightfox-compile|
  - Interactive                                         |nightfox-interactive|

OVERVIEW                                                   *nightfox-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                                                         *nightfox-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 |nightfox-option|, |nightfox-palette|,
|nightfox-spec|, and |nightfox-group|.

CONFIGURATION                                         *nightfox-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 |nightfox-options|.

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


OVERRIDES ~

The individual components: |nightfox-palettes|, |nightfox-specs| and
|nightfox-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 |nightfox-palettes| and |nightfox-specs| are defined per style.
The purpose of overriding these components is to change colors. Colors are only
relevant to a specific style. |nightfox-groups| on the other hand are not
defined per style. These mainly use the color defined in the |nightfox-palette|
and |nightfox-spec| objects in order to set values using |nightfox-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                                                 *nightfox-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
|nightfox-palette|. A palette does not use a template as it is the base that
others built off of. |nightfox-palettes| are used as the template source for
|nightfox-spec| objects. |nightfox-specs| objects are used as template source
for |nightfox-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 |nightfox-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                                                       *nightfox-option*

                                               *nightfox-options.compile_path*

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


                                        *nightfox-options.compile_file_suffix*

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`


                                                *nightfox-options.transparent*

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`.


                                            *nightfox-options.terminal_colors*

options.terminal_colors {bool}         A boolean value that if set will define
                                       the terminal colors for the builtin
                                       `terminal` (vim.g.terminal_color_*).
                                       Default: `true`.


                                               *nightfox-options.dim_inactive*

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`.


                                             *nightfox-options.module_default*

options.module_default {bool}          The default value of a module that has
                                       not been overridden in the modules
                                       table.


                                                     *nightfox-options.styles*

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",
      }
    }
<


                                                    *nightfox-options.inverse*

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
                                       foureground and background colors.


                                                 *nightfox-options.colorblind*

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)
      },
    },
<


                                                    *nightfox-options.modules*

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
                                       |nightfox-modules| for more information.


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

SHADE                                                         *nightfox-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 |nightfox-palette|.

PALETTE                                                     *nightfox-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 |nightfox-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                                                           *nightfox-spec*

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

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

                                                        *nightfox-spec.syntax*

spec.syntax                            The `syntax` table maps
                                       |nightfox-palette| color values to
                                       syntax values to be used by the
                                       |nightfox-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                      │


                                                          *nightfox-spec.diag*

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


                                                       *nightfox-spec.diag_bg*

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


                                                          *nightfox-spec.diff*

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


                                                           *nightfox-spec.git*

spec.git                               The `git` table maps |nightfox-palette|
                                       colors to git colors. These values are:
                                       `add`, `removed`, `changed`, `conflict`,
                                       and `ignored`.


GROUP                                                         *nightfox-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                                                     *nightfox-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
- rainbow-delimiters
- 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 ~

                                                        *nightfox-modules.coc*

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│


                                                 *nightfox-modules.diagnostic*

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│


                                                 *nightfox-modules.native_lsp*

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│


                                                       *nightfox-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-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')
<


                                                   *nightfox-color.from_hex()*

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


                                                  *nightfox-color.from_rgba()*

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]`.


                                                   *nightfox-color.from_hsv()*

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]`.


                                                   *nightfox-color.from_hsl()*

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]`.


                                                     *nightfox-color:to_hex()*

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`.


                                                     *nightfox-color:to_css()*

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`.


                                                    *nightfox-color:to_rgba()*

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.


                                                     *nightfox-color:to_hsv()*

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.


                                                     *nightfox-color:to_hsl()*

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.


                                                      *nightfox-color:blend()*

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.


                                                      *nightfox-color:shade()*

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.


                                                   *nightfox-color:brighten()*

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].


                                                    *nightfox-color:lighten()*

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].


                                                   *nightfox-color:saturate()*

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].


                                                     *nightfox-color:rotate()*

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                                               *nightfox-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-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 ~

                                                          *nightfox-compile()*

compile()                              Compile nightfox settings for each
                                       `style` and write compiled file to
                                       |nightfox-compile_path|.


                                                   *nightfox-:NightfoxCompile*

:NightfoxCompile                       Compile nightfox settings for each
                                       `style` and write compiled file to
                                       |nightfox-compile_path|.


INTERACTIVE                                             *nightfox-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.


                                               *nightfox-:NightfoxInteractive*

:NightfoxInteractive                   Enable Nightfox configuration reloading
                                       on buffer save.


Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl:
