navi/docs/configuration/README.md

Configuring Navi

Navi allows you to configure it with a YAML configuration.

• Configuring Navi
  • Paths and Environment Variables
    • The default configuration file path
    • Cheatsheets paths
      • The default cheatsheets path
      • Defining the cheatsheets path with the environment variable
      • Defining the cheatsheets path in the configuration file
        • [DEPRECATED] - Using the path directive
  • Customization
    • Changing colors
      • fzf color scheme
      • Navi colors
    • Resizing columns
    • Overriding fzf options
      • Overriding during cheats selection
      • Overriding during values selection
      • Overriding for all cases
  • Defining your own delimiter

Paths and Environment Variables

On the technical side, navi uses the directories-next crate for rust, which defines platform-specific locations to store the configuration files, the cache and other types of files an application might need.

Tip

For example, this is why cheatsheets are being stored in ~/Library/Application Support/navi on macOS.

Note

Interested on how directories-next works?
Go see their crates.io page: crates.io/crates/directories-next

The default configuration file path

During the compilation of navi, the default configuration file path is set by the $NAVI_CONFIG environment variable.
If it is not set, it fallbacks to ~/.config/navi/config.yaml.

You can check your default configuration file path with the info subcommand, see /docs/usage/commands/info/ for more details.

Cheatsheets paths

Navi checks the paths in the following order until it finds a value:

1. the $NAVI_PATH environment variable
2. the configuration file
3. The default value of navi

The default cheatsheets path

By default, navi stores the cheatsheets in the ~/.local/share/navi/cheats/ directory.

You can check your default cheatsheets path with the info subcommand, see /docs/usage/commands/info/ for more details.

Defining the cheatsheets path with the environment variable

The cheatsheets path can be defined using the $NAVI_PATH environment variable in a colon-separated list, for example:

export NAVI_PATH='/path/to/a/dir:/path/to/another/dir:/yet/another/dir'

Defining the cheatsheets path in the configuration file

You can define the cheatsheets path in the configuration file with the following syntax:

cheats:
  paths:
    - /path/to/some/dir # on unix-like os
    - F:\\path\\to\\dir # on Windows

[DEPRECATED] - Using the path directive

Until 2.17.0, you could define your cheatsheets path with the path directive with the following syntax:

cheats:
  path: /path/to/some/dir

The directive is now deprecated and will be removed in 2.27.0.

Customization

Changing colors

fzf color scheme

You can change the color scheme of fzf by overriding fzf options.

Note

See @junegunn/fzf/wiki/Color-schemes and #overriding-fzf-options for more details.

Navi colors

You can change the text color for each column of navi in the configuration file with the following syntax:

style:
  tag:
    color: <your color for tags>
  comment:
    color: <your color for comments>
  snippet:
    color: <your color for snippets>

Below is an example of what to do if you'd like navi to look like the French flag:

• config.yaml:

  style:
    tag:
      color: blue
    comment:
      color: white
    snippet:
      color: red
  

• The result:

  

Resizing columns

You can change the column width of each column of navi in the configuration file with the following syntax:

style:
  tag:
    width_percentage: <width relative to the terminal window>
    min_width: <width as number of characters>
  comment:
    width_percentage: <width relative to the terminal window>
    min_width: <width as number of characters>
  snippet:
    width_percentage: <width relative to the terminal window>
    min_width: <width as number of characters>

Overriding fzf options

You can override fzf options for two different cases:

• During the cheats selection

  Navi exposes the overrides directive in the configuration file and the NAVI_FZF_OVERRIDES environment variable.

• During the pre-defined variable values selection

  Navi exposes the overrides_var directive in the configuration file and the NAVI_FZF_OVERRIDES_VAR environment variable.

For all cases, navi exposes the FZF_DEFAULT_OPTS environment variable.

Overriding during cheats selection

If you want to do the override with --height 3, you can do it with the following syntax in the configuration file:

finder:
  command: fzf
  overrides: --height 3

But you can also define the environment variable like this:

export NAVI_FZF_OVERRIDES='--height 3'

Overriding during values selection

If you want to do the override with --height 3, you can do it with the following syntax in the configuration file:

finder:
  command: fzf
  overrides_var: --height 3

But you can also define the environment variable like this:

export NAVI_FZF_OVERRIDES_VAR='--height 3'

Overriding for all cases

You can define the environment variable like this:

export FZF_DEFAULT_OPTS="--height 3"

Note

See @junegunn/fzf for more details on $FZF_DEFAULT_OPTS.

Defining your own delimiter

Navi allows you to define your own delimiter to parse the selected result for a variable in your cheats.
It is equivalent to defining --delimiter used with --column.

You can define it as such:

finder:
  delimiter_var: <your-regex-delimiter> ### By default the expression is \s\s+

Caution

Defining the delimiter via the configuration file means that Navi will use this delimiter by default for every variable using the --column instruction.

You can override this configuration with the --delimiter instruction in the variable definition of your cheat.
See /docs/cheatsheet/syntax/ for more details.