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 * mc: A 16-color theme based on the look and feel of GNU Midnight Commander.
  16   This will look great used in conjunction with Midnight Commander.
  17
  18 * nano: A 16-color theme loosely based on GNU nano's syntax highlighting.
  19
  20 * monokai: this is the monokai colorscheme; you may recognize it as
  21   Sublime Text's default colorscheme. It requires true color to
  22   look perfect, but the 256 color approximation looks very good as well.
  23   It's also the default colorscheme.
  24
  25 * zenburn: The 'zenburn' colorscheme and works well with 256 color terminals
  26
  27 * solarized: this is the solarized colorscheme.
  28   You should have the solarized color palette in your terminal to use it.
  29
  30 * solarized-tc: this is the solarized colorscheme for true color; just
  31   make sure your terminal supports true color before using it and that the
  32   MICRO_TRUECOLOR environment variable is set to 1 before starting micro.
  33
  34 * atom-dark-tc: this colorscheme is based off of Atom's "dark" colorscheme.
  35   It requires true color to look good.
  36
  37 * cmc-16: A very nice 16-color theme. Written by contributor CaptainMcClellan
  38   (Collin Warren.) Licensed under the same license as the rest of the themes.
  39
  40 * cmc-paper: Basically cmc-16, but on a white background. ( Actually light grey on most
  41   ANSI (16-color) terminals.)
  42
  43 * cmc-tc: A true colour variant of the cmc theme.
  44   It requires true color to look its best. Use cmc-16 if your terminal doesn't support true color.
  45
  46 * codeblocks: A colorscheme based on the Code::Blocks IDE's default syntax highlighting.
  47
  48 * codeblocks-paper: Same as codeblocks, but on a white background. ( Actually light grey. )
  49
  50 * github-tc: A colorscheme based on Github's syntax highlighting. Requires true color to look its best.
  51
  52 * paper-tc: A nice minimalist theme with a light background, good for editing documents on.
  53   Requires true color to look its best. Not to be confused with `-paper` suffixed themes.
  54
  55 * geany: Colorscheme based on geany's default highlighting.
  56
  57 * geany-alt-tc: Based on an alternate theme bundled with geany.
  58
  59 * flamepoint-tc: A fire inspired, high intensity true color theme written by CaptainMcClellan.
  60   As with all the other `-tc` suffixed themes, it looks its best on a
  61
  62 To enable one of these colorschemes just press CtrlE in micro and type `set colorscheme solarized`.
  63 (or whichever one you choose). You can also use `set colorscheme monochrome` if you'd prefer
  64 to have just the terminal's default foreground and background colors.
  65 Note: This provides no syntax highlighting!
  66
  67 See `help gimmickcolors` for a list of some true colour themes that are more
  68 just for fun than for serious use. ( Though feel free if you want! )
  69
  70 ---
  71
  72 ### Creating a Colorscheme
  73
  74 Micro's colorschemes are also extremely simple to create. The default ones can be found
  75 [here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes).
  76
  77 They are only about 18-30 lines in total.
  78
  79 Basically to create the colorscheme you need to link highlight groups with actual colors.
  80 This is done using the `color-link` command.
  81
  82 For example, to highlight all comments in green, you would use the command:
  83
  84 ```
  85 color-link comment "green"
  86 ```
  87
  88 Background colors can also be specified with a comma:
  89
  90 ```
  91 color-link comment "green,blue"
  92 ```
  93
  94 This will give the comments a blue background.
  95
  96 If you would like no foreground you can just use a comma with nothing in front:
  97
  98 ```
  99 color-link comment ",blue"
 100 ```
 101
 102 You can also put bold, or underline in front of the color:
 103
 104 ```
 105 color-link comment "bold red"
 106 ```
 107
 108 ---
 109
 110 There are three different ways to specify the color.
 111
 112 Color terminals usually have 16 colors that are preset by the user. This means that
 113 you cannot depend on those colors always being the same. You can use those colors with
 114 the names `black, red, green, yellow, blue, magenta, cyan, white` and the bright variants
 115 of each one (brightblack, brightred...).
 116
 117 Then you can use the terminals 256 colors by using their numbers 1-256 (numbers 1-16 will
 118 refer to the named colors).
 119
 120 If the user's terminal supports true color, then you can also specify colors exactly using
 121 their hex codes. If the terminal is not true color but micro is told to use a true color colorscheme
 122 it will attempt to map the colors to the available 256 colors.
 123
 124 Generally colorschemes which require true color terminals to look good are marked with a `-tc` suffix
 125 and colorschemes which supply a white background are marked with a `-paper` suffix.
 126
 127 ---
 128
 129 Here is a list of the colorscheme groups that you can use:
 130
 131 * default (color of the background and foreground for unhighlighted text)
 132 * comment
 133 * identifier
 134 * constant
 135 * statement
 136 * symbol
 137 * preproc
 138 * type
 139 * special
 140 * underlined
 141 * error
 142 * todo
 143 * statusline ( Color of the statusline)
 144 * tabbar ( Color of the tabbar that lists open files.)
 145 * indent-char ( Color of the character which indicates tabs if the option is enabled)
 146 * line-number
 147 * gutter-error
 148 * gutter-warning
 149 * cursor-line
 150 * current-line-number
 151 * color-column
 152 * ignore
 153 * divider ( Color of the divider between vertical splits. )
 154
 155 Colorschemes must be placed in the `~/.config/micro/colorschemes` directory to be used.
 156
 157 ---
 158
 159 In addition to the main colorscheme groups, there are subgroups that you can
 160 specify by adding `.subgroup` to the group. If you're creating your own
 161 custom syntax files, you can make use of your own subgroups.
 162
 163 If micro can't match the subgroup, it'll default to the root group, so
 164 it's safe and recommended to use subgroups in your custom syntax files.
 165
 166 For example if `constant.string` is found in your colorscheme, micro will
 167 use that for highlighting strings. If it's not found, it will use constant
 168 instead. Micro tries to match the largest set of groups it can find in the
 169 colorscheme definitions, so if, for examle `constant.bool.true` is found then
 170 micro will use that. If `constant.bool.true` is not found but `constant.bool`
 171 is found micro will use `constant.bool`. If not, it uses `constant`.
 172
 173 Here's a list of subgroups used in micro's built-in syntax files.
 174
 175 * comment.bright ( Some filetypes have distinctions between types of comments.)
 176 * constant.bool
 177 * constant.bool.true
 178 * constant.bool.false
 179 * constant.number
 180 * constant.specialChar
 181 * constant.string
 182 * constant.string.url
 183 * identifier.class ( Also used for functions. )
 184 * identifier.macro
 185 * identifier.var
 186 * preproc.shebang ( The #! at the beginning of a file that tells the os what script interpreter to use. )
 187 * symbol.brackets ( {}()[] and sometimes <> )
 188 * symbol.operator ( Color operator symbols differently. )
 189 * symbol.tag ( For html tags, among other things.)
 190 * type.keyword ( If you want a special highlight for keywords like `private` )
 191
 192 In the future, plugins may also be able to use color groups for styling.
 193
 194 ### Syntax files
 195
 196 The syntax files specify how to highlight certain languages.
 197
 198 Micro's builtin syntax highlighting tries very hard to be sane, sensible
 199 and provide ample coverage of the meaningful elements of a language. Micro has
 200 syntax files built int for over 100 languages now. However, there may be
 201 situations where you find Micro's highlighting to be insufficient or not to
 202 your liking. Good news is you can create syntax files (.micro extension), place them in
 203 `~/.config/micro/syntax` and Micro will use those instead.
 204
 205 The first statement in a syntax file will probably the syntax statement. This tells micro
 206 what language the syntax file is for and how to detect a file in that language.
 207
 208 Essentially, it's just
 209
 210 ```
 211 syntax "Name of language" "\.extension$"
 212 ```
 213
 214 For the extension, micro will just compare that regex to the filename and if it matches then it
 215 will use the syntax rules defined in the remainder of the file.
 216
 217 There is also a possibility to use a header statement which is a regex that micro will compare
 218 with the first line of the file. This is almost only used for shebangs at the top of shell scripts
 219 which don't have any extension (see sh.micro for an example).
 220
 221 ---
 222
 223 The rest of a syntax file is very simple and is essentially a list of regexes specifying how to highlight
 224 different expressions.
 225
 226 It is recommended that when creating a syntax file you use the colorscheme groups (see above) to
 227 highlight different expressions. You may also hard code colors, but that may not look good depending
 228 on what terminal colorscheme the user has installed.
 229
 230 Here is an example to highlight comments (expressions starting with `//`):
 231
 232 ```
 233 color comment "//.*"
 234 ```
 235
 236 This will highlight the regex `//.*` in the color that the user's colorscheme has linked to the comment
 237 group.
 238
 239 Note that this regex only matches the current line. Here is an example for multiline comments (`/* comment */`):
 240
 241 ```
 242 color comment start="/\*" end="\*/"
 243 ```
 244
 245 Note: The format of syntax files will be changing with the view refactor.
 246 If this help file still retains this note but the syntax files are yaml
 247 please open an issue.