runtime/help/colors.md

   1 # Colors
   2
   3 This help page aims to cover two aspects of micro's syntax highlighting engine:
   4
   5 - How to create colorschemes and use them
   6 - How to create syntax files to add to the list of languages micro can highlight
   7
   8 ### Colorschemes
   9
  10 Micro comes with a number of colorschemes by default. Here is the list:
  11
  12 * simple: this is the simplest colorscheme. It uses 16 colors which are
  13   set by your terminal
  14
  15 * zenburn: this is micro's default colorscheme because it looks very good
  16   and works in 256 color terminals.
  17   this colorscheme also has the name 'default'
  18
  19 * solarized: this is the solarized colorscheme.
  20   You should have the solarized color palette in your terminal to use it.
  21
  22 * solarized-tc: this is the solarized colorscheme for true color; just
  23   make sure your terminal supports true color before using it and that the
  24   MICRO_TRUECOLOR environment variable is set to 1 before starting micro.
  25
  26 * monokai: this is the monokai colorscheme; you may recognize it as
  27   Sublime Text's default colorscheme. It requires true color to
  28   look perfect, but the 256 color approximation looks very good as well.
  29
  30 * atom-dark-tc: this colorscheme is based off of Atom's "dark" colorscheme.
  31   It requires true color to look good.
  32
  33 To enable one of these colorschemes just run the command `set colorscheme solarized`.
  34 (or whichever one you choose).
  35
  36 ---
  37
  38 Micro's colorschemes are also extremely simple to create. The default ones can be found
  39 [here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes).
  40
  41 They are only about 18 lines in total.
  42
  43 Basically to create the colorscheme you need to link highlight groups with actual colors.
  44 This is done using the `color-link` command.
  45
  46 For example, to highlight all comments in green, you would use the command:
  47
  48 ```
  49 color-link comment "green"
  50 ```
  51
  52 Background colors can also be specified with a comma:
  53
  54 ```
  55 color-link comment "green,blue"
  56 ```
  57
  58 This will give the comments a blue background.
  59
  60 If you would like no foreground you can just use a comma with nothing in front:
  61
  62 ```
  63 color-link comment ",blue"
  64 ```
  65
  66 You can also put bold, or underline in front of the color:
  67
  68 ```
  69 color-link comment "bold red"
  70 ```
  71
  72 ---
  73
  74 There are three different ways to specify the color.
  75
  76 Color terminals usually have 16 colors that are preset by the user. This means that
  77 you cannot depend on those colors always being the same. You can use those colors with
  78 the names `black, red, green, yellow, blue, magenta, cyan, white` and the bright variants
  79 of each one (brightblack, brightred...).
  80
  81 Then you can use the terminals 256 colors by using their numbers 1-256 (numbers 1-16 will
  82 refer to the named colors).
  83
  84 If the user's terminal supports true color, then you can also specify colors exactly using
  85 their hex codes. If the terminal is not true color but micro is told to use a true color colorscheme
  86 it will attempt to map the colors to the available 256 colors.
  87
  88 Generally colorschemes which require true color terminals to look good are marked with a `-tc` suffix.
  89
  90 ---
  91
  92 Here is a list of the colorscheme groups that you can use:
  93
  94 * default (color of the background and foreground for unhighlighted text)
  95 * comment
  96 * identifier
  97 * constant
  98 * statement
  99 * preproc
 100 * type
 101 * special
 102 * underlined
 103 * error
 104 * todo
 105 * statusline (color of the statusline)
 106 * indent-char (color of the character which indicates tabs if the option is enabled)
 107 * line-number
 108 * gutter-error
 109 * gutter-warning
 110 * cursor-line
 111 * current-line-number
 112 * color-column
 113
 114 Colorschemes can be placed in the `~/.config/micro/colorschemes` directory to be used.
 115
 116 ### Syntax files
 117
 118 The syntax files specify how to highlight certain languages.
 119
 120 The first statement in a syntax file will probably the syntax statement. This tells micro
 121 what language the syntax file is for and how to detect a file in that language.
 122
 123 Essentially, it's just
 124
 125 ```
 126 syntax "Name of language" "\.extension$"
 127 ```
 128
 129 For the extension, micro will just compare that regex to the filename and if it matches then it
 130 will use the syntax rules defined in the remainder of the file.
 131
 132 There is also a possibility to use a header statement which is a regex that micro will compare
 133 with the first line of the file. This is almost only used for shebangs at the top of shell scripts
 134 which don't have any extension (see sh.micro for an example).
 135
 136 ---
 137
 138 The rest of a syntax file is very simple and is essentially a list of regexes specifying how to highlight
 139 different expressions.
 140
 141 It is recommended that when creating a syntax file you use the colorscheme groups (see above) to
 142 highlight different expressions. You may also hard code colors, but that may not look good depending
 143 on what terminal colorscheme the user has installed.
 144
 145 Here is an example to highlight comments (expressions starting with `//`):
 146
 147 ```
 148 color comment "//.*"
 149 ```
 150
 151 This will highlight the regex `//.*` in the color that the user's colorscheme has linked to the comment
 152 group.
 153
 154 Note that this regex only matches the current line. Here is an example for multiline comments (`/* comment */`):
 155
 156 ```
 157 color comment start="/\*" end="\*/"
 158 ```