mirror of
https://github.com/nushell/nushell.git
synced 2024-11-22 08:23:24 +01:00
add docs about coloring and theming (#654)
This commit is contained in:
Darren Schroeder
GitHub
parent
fe5f65a247
commit
91d807b1d2
458
docs/How_To_Coloring_and_Theming.md
Normal file
458
docs/How_To_Coloring_and_Theming.md
Normal file
@ -0,0 +1,458 @@
|
||||
# Coloring and Theming in Nushell
|
||||
|
||||
There are a few main parts that nushell allows you to change the color. All of these can be set in the `config.nu` configuration file. If you see the hash/hashtag/pound mark `#` in the config file it means the text after it is commented out.
|
||||
|
||||
1. table borders
|
||||
2. primitive values
|
||||
3. flatshapes (this is the command line syntax)
|
||||
4. prompt
|
||||
5. LS_COLORS
|
||||
|
||||
## `Table borders`
|
||||
___
|
||||
|
||||
Table borders are controlled by the `table_mode` setting in the `config.nu`. Here is an example:
|
||||
```
|
||||
let $config = {
|
||||
table_mode: rounded
|
||||
}
|
||||
```
|
||||
|
||||
Here are the current options for `table_mode`:
|
||||
1. `rounded` # of course, this is the best one :)
|
||||
2. `basic`
|
||||
3. `compact`
|
||||
4. `compact_double`
|
||||
5. `light`
|
||||
6. `thin`
|
||||
7. `with_love`
|
||||
8. `rounded`
|
||||
9. `reinforced`
|
||||
10. `heavy`
|
||||
11. `none`
|
||||
12. `other`
|
||||
|
||||
### `Color symbologies`
|
||||
---
|
||||
|
||||
* `r` - normal color red's abbreviation
|
||||
* `rb` - normal color red's abbreviation with bold attribute
|
||||
* `red` - normal color red
|
||||
* `red_bold` - normal color red with bold attribute
|
||||
* `"#ff0000"` - "#hex" format foreground color red (quotes are required)
|
||||
* `{ fg: "#ff0000" bg: "#0000ff" attr: b }` - "full #hex" format foreground red in "#hex" format with a background of blue in "#hex" format with an attribute of bold abbreviated.
|
||||
|
||||
### `attributes`
|
||||
---
|
||||
|
||||
|code|meaning|
|
||||
|-|-|
|
||||
|l|blink|
|
||||
|b|bold|
|
||||
|d|dimmed|
|
||||
|h|hidden|
|
||||
|i|italic|
|
||||
|r|reverse|
|
||||
|s|strikethrough|
|
||||
|u|underline|
|
||||
|n|nothing|
|
||||
||defaults to nothing|
|
||||
|
||||
### `normal colors` and `abbreviations`
|
||||
|
||||
|code|name|
|
||||
|-|-|
|
||||
|g|green|
|
||||
|gb|green_bold|
|
||||
|gu|green_underline|
|
||||
|gi|green_italic|
|
||||
|gd|green_dimmed|
|
||||
|gr|green_reverse|
|
||||
|gbl|green_blink|
|
||||
|gst|green_strike|
|
||||
|lg|light_green|
|
||||
|lgb|light_green_bold|
|
||||
|lgu|light_green_underline|
|
||||
|lgi|light_green_italic|
|
||||
|lgd|light_green_dimmed|
|
||||
|lgr|light_green_reverse|
|
||||
|lgbl|light_green_blink|
|
||||
|lgst|light_green_strike|
|
||||
|r|red|
|
||||
|rb|red_bold|
|
||||
|ru|red_underline|
|
||||
|ri|red_italic|
|
||||
|rd|red_dimmed|
|
||||
|rr|red_reverse|
|
||||
|rbl|red_blink|
|
||||
|rst|red_strike|
|
||||
|lr|light_red|
|
||||
|lrb|light_red_bold|
|
||||
|lru|light_red_underline|
|
||||
|lri|light_red_italic|
|
||||
|lrd|light_red_dimmed|
|
||||
|lrr|light_red_reverse|
|
||||
|lrbl|light_red_blink|
|
||||
|lrst|light_red_strike|
|
||||
|u|blue|
|
||||
|ub|blue_bold|
|
||||
|uu|blue_underline|
|
||||
|ui|blue_italic|
|
||||
|ud|blue_dimmed|
|
||||
|ur|blue_reverse|
|
||||
|ubl|blue_blink|
|
||||
|ust|blue_strike|
|
||||
|lu|light_blue|
|
||||
|lub|light_blue_bold|
|
||||
|luu|light_blue_underline|
|
||||
|lui|light_blue_italic|
|
||||
|lud|light_blue_dimmed|
|
||||
|lur|light_blue_reverse|
|
||||
|lubl|light_blue_blink|
|
||||
|lust|light_blue_strike|
|
||||
|b|black|
|
||||
|bb|black_bold|
|
||||
|bu|black_underline|
|
||||
|bi|black_italic|
|
||||
|bd|black_dimmed|
|
||||
|br|black_reverse|
|
||||
|bbl|black_blink|
|
||||
|bst|black_strike|
|
||||
|ligr|light_gray|
|
||||
|ligrb|light_gray_bold|
|
||||
|ligru|light_gray_underline|
|
||||
|ligri|light_gray_italic|
|
||||
|ligrd|light_gray_dimmed|
|
||||
|ligrr|light_gray_reverse|
|
||||
|ligrbl|light_gray_blink|
|
||||
|ligrst|light_gray_strike|
|
||||
|y|yellow|
|
||||
|yb|yellow_bold|
|
||||
|yu|yellow_underline|
|
||||
|yi|yellow_italic|
|
||||
|yd|yellow_dimmed|
|
||||
|yr|yellow_reverse|
|
||||
|ybl|yellow_blink|
|
||||
|yst|yellow_strike|
|
||||
|ly|light_yellow|
|
||||
|lyb|light_yellow_bold|
|
||||
|lyu|light_yellow_underline|
|
||||
|lyi|light_yellow_italic|
|
||||
|lyd|light_yellow_dimmed|
|
||||
|lyr|light_yellow_reverse|
|
||||
|lybl|light_yellow_blink|
|
||||
|lyst|light_yellow_strike|
|
||||
|p|purple|
|
||||
|pb|purple_bold|
|
||||
|pu|purple_underline|
|
||||
|pi|purple_italic|
|
||||
|pd|purple_dimmed|
|
||||
|pr|purple_reverse|
|
||||
|pbl|purple_blink|
|
||||
|pst|purple_strike|
|
||||
|lp|light_purple|
|
||||
|lpb|light_purple_bold|
|
||||
|lpu|light_purple_underline|
|
||||
|lpi|light_purple_italic|
|
||||
|lpd|light_purple_dimmed|
|
||||
|lpr|light_purple_reverse|
|
||||
|lpbl|light_purple_blink|
|
||||
|lpst|light_purple_strike|
|
||||
|c|cyan|
|
||||
|cb|cyan_bold|
|
||||
|cu|cyan_underline|
|
||||
|ci|cyan_italic|
|
||||
|cd|cyan_dimmed|
|
||||
|cr|cyan_reverse|
|
||||
|cbl|cyan_blink|
|
||||
|cst|cyan_strike|
|
||||
|lc|light_cyan|
|
||||
|lcb|light_cyan_bold|
|
||||
|lcu|light_cyan_underline|
|
||||
|lci|light_cyan_italic|
|
||||
|lcd|light_cyan_dimmed|
|
||||
|lcr|light_cyan_reverse|
|
||||
|lcbl|light_cyan_blink|
|
||||
|lcst|light_cyan_strike|
|
||||
|w|white|
|
||||
|wb|white_bold|
|
||||
|wu|white_underline|
|
||||
|wi|white_italic|
|
||||
|wd|white_dimmed|
|
||||
|wr|white_reverse|
|
||||
|wbl|white_blink|
|
||||
|wst|white_strike|
|
||||
|dgr|dark_gray|
|
||||
|dgrb|dark_gray_bold|
|
||||
|dgru|dark_gray_underline|
|
||||
|dgri|dark_gray_italic|
|
||||
|dgrd|dark_gray_dimmed|
|
||||
|dgrr|dark_gray_reverse|
|
||||
|dgrbl|dark_gray_blink|
|
||||
|dgrst|dark_gray_strike|
|
||||
|
||||
### `"#hex"` format
|
||||
---
|
||||
|
||||
The "#hex" format is one way you typically see colors represented. It's simply the `#` character followed by 6 characters. The first two are for `red`, the second two are for `green`, and the third two are for `blue`. It's important that this string be surrounded in quotes, otherwise nushell thinks it's a commented out string.
|
||||
|
||||
Example: The primary `red` color is `"#ff0000"` or `"#FF0000"`. Upper and lower case in letters shouldn't make a difference.
|
||||
|
||||
This `"#hex"` format allows us to specify 24-bit truecolor tones to different parts of nushell.
|
||||
|
||||
## `full "#hex"` format
|
||||
---
|
||||
The `full "#hex"` format is a take on the `"#hex"` format but allows one to specify the foreground, background, and attributes in one line.
|
||||
|
||||
Example: ``{ fg: "#ff0000" bg: "#0000ff" attr: b }`
|
||||
|
||||
* foreground of red in "#hex" format
|
||||
* background of blue in "#hex" format
|
||||
* attribute of bold abbreviated
|
||||
|
||||
## `Primitive values`
|
||||
___
|
||||
|
||||
Primitive values are things like `int` and `string`. Primitive values and flatshapes can be set with a variety of color symbologies seen above.
|
||||
|
||||
This is the current list of primitives. Not all of these are configurable. The configurable ones are marked with *.
|
||||
|
||||
* `any`
|
||||
* `binary` *
|
||||
* `block` *
|
||||
* `bool` *
|
||||
* `cellpath` *
|
||||
* `condition`
|
||||
* `custom`
|
||||
* `date` *
|
||||
* `duration` *
|
||||
* `expression`
|
||||
* `filesize` *
|
||||
* `float` *
|
||||
* `glob`
|
||||
* `import`
|
||||
* `int` *
|
||||
* `list` *
|
||||
* `nothing` *
|
||||
* `number`
|
||||
* `operator`
|
||||
* `path`
|
||||
* `range` *
|
||||
* `record` *
|
||||
* `signature`
|
||||
* `string` *
|
||||
* `table`
|
||||
* `var`
|
||||
* `vardecl`
|
||||
* `variable`
|
||||
|
||||
#### special "primitives" (not really primitives but they exist solely for coloring)
|
||||
|
||||
* `leading_trailing_space_bg` *
|
||||
* `header` *
|
||||
* `empty` *
|
||||
* `row_index` *
|
||||
* `hints` *
|
||||
|
||||
Here's a small example of changing some of these values.
|
||||
```
|
||||
let config = {
|
||||
color_config: {
|
||||
separator: purple
|
||||
leading_trailing_space_bg: "#ffffff"
|
||||
header: gb
|
||||
date: wd
|
||||
filesize: c
|
||||
row_index: cb
|
||||
bool: red
|
||||
int: green
|
||||
duration: blue_bold
|
||||
range: purple
|
||||
float: red
|
||||
string: white
|
||||
nothing: red
|
||||
binary: red
|
||||
cellpath: cyan
|
||||
hints: dark_gray
|
||||
}
|
||||
}
|
||||
```
|
||||
Here's another small example using multiple color syntaxes with some comments.
|
||||
```
|
||||
let config = {
|
||||
color_config: {
|
||||
separator: "#88b719" # this sets only the foreground color like PR #486
|
||||
leading_trailing_space_bg: white # this sets only the foreground color in the original style
|
||||
header: { # this is like PR #489
|
||||
fg: "#B01455", # note, quotes are required on the values with hex colors
|
||||
bg: "#ffb900",# note, commas are not required, it could also be all on one line
|
||||
attr: bli # note, there are no quotes around this value. it works with or without quotes
|
||||
}
|
||||
date: "#75507B"
|
||||
filesize: "#729fcf"
|
||||
row_index: { # note, that this is another way to set only the foreground, no need to specify bg and attr
|
||||
fg: "#e50914"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## `FlatShape` values
|
||||
|
||||
As mentioned above, `flatshape` is a term used to indicate the sytax coloring. (get better words from jt)
|
||||
|
||||
Here's the current list of flat shapes.
|
||||
|
||||
* `flatshape_block`
|
||||
* `flatshape_bool`
|
||||
* `flatshape_custom`
|
||||
* `flatshape_external`
|
||||
* `flatshape_externalarg`
|
||||
* `flatshape_filepath`
|
||||
* `flatshape_flag`
|
||||
* `flatshape_float`
|
||||
* `flatshape_garbage`
|
||||
* `flatshape_globpattern`
|
||||
* `flatshape_int`
|
||||
* `flatshape_internalcall`
|
||||
* `flatshape_list`
|
||||
* `flatshape_literal`
|
||||
* `flatshape_nothing`
|
||||
* `flatshape_operator`
|
||||
* `flatshape_range`
|
||||
* `flatshape_record`
|
||||
* `flatshape_signature`
|
||||
* `flatshape_string`
|
||||
* `flatshape_string_interpolation`
|
||||
* `flatshape_table`
|
||||
* `flatshape_variable`
|
||||
|
||||
Here's a small example of how to apply color to these items. Anything not specified will receive the default color.
|
||||
|
||||
```
|
||||
let $config = {
|
||||
color_config: {
|
||||
flatshape_garbage: { fg: "#FFFFFF" bg: "#FF0000" attr: b}
|
||||
flatshape_bool: green
|
||||
flatshape_int: { fg: "#0000ff" attr: b}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## `Prompt` configuration and coloring
|
||||
|
||||
The nushell prompt is configurable through these environment variables settings.
|
||||
|
||||
* `PROMPT_COMMAND`: Code to execute for setting up the prompt (block)
|
||||
* `PROMPT_INDICATOR` = "〉": The indicator printed after the prompt (by default ">"-like Unicode symbol)
|
||||
* `PROMPT_INDICATOR_VI_INSERT` = ": "
|
||||
* `PROMPT_INDICATOR_VI_VISUAL` = "v "
|
||||
* `PROMPT_MULTILINE_INDICATOR` = "::: "
|
||||
|
||||
Example: For a simple prompt one could do this. Note that `PROMPT_COMMAND` requires a `block` whereas the others require a `string`.
|
||||
|
||||
`> let-env PROMPT_COMMAND = { build-string (date now | date format '%m/%d/%Y %I:%M:%S%.3f') ': ' (pwd | decode utf-8 | path basename) }`
|
||||
|
||||
If you don't like the default `PROMPT_INDICATOR` you could change it like this.
|
||||
|
||||
`> let-env PROMPT_INDICATOR = "> "`
|
||||
|
||||
Coloring of the prompt is controlled by the `block` in `PROMPT_COMMAND` where you can write your own custom prompt. We've written a slightly fancy one that has git statuses located in the [nu_scripts repo](https://github.com/nushell/nu_scripts/blob/main/prompt/oh-my.nu).
|
||||
|
||||
## `LS_COLORS` colors for the `ls` command
|
||||
|
||||
Nushell will respect and use the `LS_COLORS` environment variable setting on Mac, Linux, and Windows. This setting allows you to define the color of file types when you do a `ls`. For instance, you can make directories one color, *.md markdown files another color, *.toml files yet another color, etc. There are a variety of ways to color your file types.
|
||||
|
||||
There's an exhaustive list [here](https://github.com/trapd00r/LS_COLORS), which is overkill, but gives you an rudimentary understanding of how to create a ls_colors file that `dircolors` can turn into a `LS_COLORS` environment variable.
|
||||
|
||||
[This](https://www.linuxhowto.net/how-to-set-colors-for-ls-command/) is a pretty good introduction to `LS_COLORS`. I'm sure you can fine many more tutorials on the web.
|
||||
|
||||
I like the `vivid` application and currently have it configured in my `config.nu` like this. You can find `vivid` [here](https://github.com/sharkdp/vivid).
|
||||
|
||||
`let-env LS_COLORS = (vivid generate molokai | decode utf-8 | str trim)`
|
||||
|
||||
## Theming
|
||||
|
||||
Theming combines all the coloring above. Here's a quick example of one we put together quickly to demonstrate the ability to theme. This is a spin on the `base16` themes that we see so widespread on the web.
|
||||
|
||||
The key to making theming work is to make sure you specify all themes and colors you're going to use in the `config.nu` file *before* you declare the `let config = ` line.
|
||||
|
||||
```
|
||||
# lets define some colors
|
||||
|
||||
let base00 = "#181818" # Default Background
|
||||
let base01 = "#282828" # Lighter Background (Used for status bars, line number and folding marks)
|
||||
let base02 = "#383838" # Selection Background
|
||||
let base03 = "#585858" # Comments, Invisibles, Line Highlighting
|
||||
let base04 = "#b8b8b8" # Dark Foreground (Used for status bars)
|
||||
let base05 = "#d8d8d8" # Default Foreground, Caret, Delimiters, Operators
|
||||
let base06 = "#e8e8e8" # Light Foreground (Not often used)
|
||||
let base07 = "#f8f8f8" # Light Background (Not often used)
|
||||
let base08 = "#ab4642" # Variables, XML Tags, Markup Link Text, Markup Lists, Diff Deleted
|
||||
let base09 = "#dc9656" # Integers, Boolean, Constants, XML Attributes, Markup Link Url
|
||||
let base0a = "#f7ca88" # Classes, Markup Bold, Search Text Background
|
||||
let base0b = "#a1b56c" # Strings, Inherited Class, Markup Code, Diff Inserted
|
||||
let base0c = "#86c1b9" # Support, Regular Expressions, Escape Characters, Markup Quotes
|
||||
let base0d = "#7cafc2" # Functions, Methods, Attribute IDs, Headings
|
||||
let base0e = "#ba8baf" # Keywords, Storage, Selector, Markup Italic, Diff Changed
|
||||
let base0f = "#a16946" # Deprecated, Opening/Closing Embedded Language Tags, e.g. <?php ?>
|
||||
|
||||
# we're creating a theme here that uses the colors we defined above.
|
||||
|
||||
let base16_theme = {
|
||||
separator: $base03
|
||||
leading_trailing_space_bg: $base04
|
||||
header: $base0b
|
||||
date: $base0e
|
||||
filesize: $base0d
|
||||
row_index: $base0c
|
||||
bool: $base08
|
||||
int: $base0b
|
||||
duration: $base08
|
||||
range: $base08
|
||||
float: $base08
|
||||
string: $base04
|
||||
nothing: $base08
|
||||
binary: $base08
|
||||
cellpath: $base08
|
||||
hints: dark_gray
|
||||
|
||||
# flatshape_garbage: { fg: $base07 bg: $base08 attr: b} # base16 white on red
|
||||
# but i like the regular white on red for parse errors
|
||||
flatshape_garbage: { fg: "#FFFFFF" bg: "#FF0000" attr: b}
|
||||
flatshape_bool: $base0d
|
||||
flatshape_int: { fg: $base0e attr: b}
|
||||
flatshape_float: { fg: $base0e attr: b}
|
||||
flatshape_range: { fg: $base0a attr: b}
|
||||
flatshape_internalcall: { fg: $base0c attr: b}
|
||||
flatshape_external: $base0c
|
||||
flatshape_externalarg: { fg: $base0b attr: b}
|
||||
flatshape_literal: $base0d
|
||||
flatshape_operator: $base0a
|
||||
flatshape_signature: { fg: $base0b attr: b}
|
||||
flatshape_string: $base0b
|
||||
flatshape_filepath: $base0d
|
||||
flatshape_globpattern: { fg: $base0d attr: b}
|
||||
flatshape_variable: $base0e
|
||||
flatshape_flag: { fg: $base0d attr: b}
|
||||
flatshape_custom: {attr: b}
|
||||
}
|
||||
|
||||
# now let's apply our regular config settings but also apply the "color_config:" theme that we specified above.
|
||||
|
||||
let config = {
|
||||
filesize_metric: $true
|
||||
table_mode: rounded # basic, compact, compact_double, light, thin, with_love, rounded, reinforced, heavy, none, other
|
||||
use_ls_colors: $true
|
||||
color_config: $base16_theme # <-- this is the theme
|
||||
use_grid_icons: $true
|
||||
footer_mode: always #always, never, number_of_rows, auto
|
||||
animate_prompt: $false
|
||||
float_precision: 2
|
||||
without_color: $false
|
||||
filesize_format: "b" # b, kb, kib, mb, mib, gb, gib, tb, tib, pb, pib, eb, eib, zb, zib, auto
|
||||
edit_mode: emacs # vi
|
||||
max_history_size: 10000
|
||||
log_level: error
|
||||
}
|
||||
```
|
||||
if you want to go full-tilt on theming, you'll want to theme all the items I mentioned at the very beginning, including LS_COLORS, and the prompt. Good luck!
|
||||
Loading…
Reference in New Issue
Block a user