3 This help page aims to cover two aspects of micro's syntax highlighting engine:
5 * How to create colorschemes and use them.
6 * How to create syntax files to add to the list of languages micro can
11 To change your colorscheme, press Ctrl-e in micro to bring up the command
15 set colorscheme twilight
18 (or whichever colorscheme you choose).
20 Micro comes with a number of colorschemes by default. The colorschemes that you
21 can display will depend on what kind of color support your terminal has.
23 Omit color-link default "[fg color],[bg color]" will make the background color match the terminal's, and transparency if set.
25 Modern terminals tend to have a palette of 16 user-configurable colors (these
26 colors can often be configured in the terminal preferences), and additional
27 color support comes in three flavors.
29 * 16-color: A colorscheme that uses the 16 default colors will always work but
30 will only look good if the 16 default colors have been configured to the
31 user's liking. Using a colorscheme that only uses the 16 colors from the
32 terminal palette will also preserve the terminal's theme from other
33 applications since the terminal will often use those same colors for other
34 applications. Default colorschemes of this type include `simple` and
37 * 256-color: Almost all terminals support displaying an additional 240 colors
38 on top of the 16 user-configurable colors (creating 256 colors total).
39 Colorschemes which use 256-color are portable because they will look the
40 same regardless of the configured 16-color palette. However, the color
41 range is fairly limited due to the small number of colors available.
42 Default 256-color colorschemes include `monokai`, `twilight`, `zenburn`,
45 * true-color: Some terminals support displaying "true color" with 16 million
46 colors using standard RGB values. This mode will be able to support
47 displaying any colorscheme, but it should be noted that the user-configured
48 16-color palette is ignored when using true-color mode (this means the
49 colors while using the terminal emulator will be slightly off). Not all
50 terminals support true color but at this point most do. True color
51 support in micro is off by default but can be enabled by setting the
52 environment variable `MICRO_TRUECOLOR` to 1. In addition your terminal
53 must support it (usually indicated by setting `$COLORTERM` to `truecolor`).
54 True-color colorschemes in micro typically end with `-tc`, such as
55 `solarized-tc`, `atom-dark`, `material-tc`, etc... If true color is not
56 enabled but a true color colorscheme is used, micro will do its best to
57 approximate the colors to the available 256 colors.
59 Here is the list of colorschemes:
63 These should work and look nice in most terminals. I recommend these
66 * `monokai` (also the `default` colorscheme)
72 * `bubblegum` (light theme)
76 These may vary widely based on the 16 colors selected for your terminal.
79 * `solarized` (must have the solarized color palette in your terminal to use
80 this colorscheme properly)
87 True color requires your terminal to support it. This means that the
88 environment variable `COLORTERM` should have the value `truecolor`, `24bit`,
89 or `24-bit`. In addition, to enable true color in micro, the environment
90 variable `MICRO_TRUECOLOR` must be set to 1. Note that you have to create
91 and set this variable yourself.
93 * `solarized-tc`: this is the solarized colorscheme for true color.
94 * `atom-dark`: this colorscheme is based off of Atom's "dark" colorscheme.
95 * `cmc-tc`: A true colour variant of the cmc theme. It requires true color to
96 look its best. Use cmc-16 if your terminal doesn't support true color.
97 * `gruvbox-tc`: The true color version of the gruvbox colorscheme
98 * `material-tc`: Colorscheme based off of Google's Material Design palette
100 ## Creating a Colorscheme
102 Micro's colorschemes are also extremely simple to create. The default ones can
104 [here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes).
106 Custom colorschemes should be placed in the `~/.config/micro/colorschemes`
109 A number of custom directives are placed in a `.micro` file. Colorschemes are
110 typically only 18-30 lines in total.
112 To create the colorscheme you need to link highlight groups with
113 actual colors. This is done using the `color-link` command.
115 For example, to highlight all comments in green, you would use the command:
118 color-link comment "green"
121 Background colors can also be specified with a comma:
124 color-link comment "green,blue"
127 This will give the comments a blue background.
129 If you would like no foreground you can just use a comma with nothing in front:
132 color-link comment ",blue"
135 You can also put bold, italic, or underline in front of the color:
138 color-link comment "bold red"
143 There are three different ways to specify the color.
145 Color terminals usually have 16 colors that are preset by the user. This means
146 that you cannot depend on those colors always being the same. You can use those
147 colors with the names `black, red, green, yellow, blue, magenta, cyan, white`
148 and the bright variants of each one (brightblack, brightred...).
150 Then you can use the terminals 256 colors by using their numbers 1-256 (numbers
151 1-16 will refer to the named colors).
153 If the user's terminal supports true color, then you can also specify colors
154 exactly using their hex codes. If the terminal is not true color but micro is
155 told to use a true color colorscheme it will attempt to map the colors to the
156 available 256 colors.
158 Generally colorschemes which require true color terminals to look good are
159 marked with a `-tc` suffix and colorschemes which supply a white background are
160 marked with a `-paper` suffix.
164 Here is a list of the colorscheme groups that you can use:
166 * default (color of the background and foreground for unhighlighted text)
178 * selection (Color of the text selection)
179 * statusline (Color of the statusline)
180 * tabbar (Color of the tabbar that lists open files)
181 * indent-char (Color of the character which indicates tabs if the option is
190 * current-line-number
194 * divider (Color of the divider between vertical splits)
195 * message (Color of messages in the bottom line of the screen)
196 * error-message (Color of error messages in the bottom line of the screen)
198 Colorschemes must be placed in the `~/.config/micro/colorschemes` directory to
203 In addition to the main colorscheme groups, there are subgroups that you can
204 specify by adding `.subgroup` to the group. If you're creating your own custom
205 syntax files, you can make use of your own subgroups.
207 If micro can't match the subgroup, it'll default to the root group, so it's
208 safe and recommended to use subgroups in your custom syntax files.
210 For example if `constant.string` is found in your colorscheme, micro will us
211 that for highlighting strings. If it's not found, it will use constant instead.
212 Micro tries to match the largest set of groups it can find in the colorscheme
213 definitions, so if, for examle `constant.bool.true` is found then micro will
214 use that. If `constant.bool.true` is not found but `constant.bool` is found
215 micro will use `constant.bool`. If not, it uses `constant`.
217 Here's a list of subgroups used in micro's built-in syntax files.
219 * comment.bright (Some filetypes have distinctions between types of comments)
222 * constant.bool.false
224 * constant.specialChar
226 * constant.string.url
227 * identifier.class (Also used for functions)
230 * preproc.shebang (The #! at the beginning of a file that tells the os what
231 script interpreter to use)
232 * symbol.brackets (`{}()[]` and sometimes `<>`)
233 * symbol.operator (Color operator symbols differently)
234 * symbol.tag (For html tags, among other things)
235 * type.keyword (If you want a special highlight for keywords like `private`)
237 In the future, plugins may also be able to use color groups for styling.
242 The syntax files are written in yaml-format and specify how to highlight
245 Micro's builtin syntax highlighting tries very hard to be sane, sensible and
246 provide ample coverage of the meaningful elements of a language. Micro has
247 syntax files built in for over 100 languages now! However, there may be
248 situations where you find Micro's highlighting to be insufficient or not to
249 your liking. The good news is that you can create your own syntax files, and
250 place them in `~/.config/micro/syntax` and Micro will use those instead.
252 ### Filetype definition
254 You must start the syntax file by declaring the filetype:
260 ### Detect definition
262 Then you must provide information about how to detect the filetype:
269 Micro will match this regex against a given filename to detect the filetype.
270 You may also provide an optional `header` regex that will check the first line
271 of the file. For example:
275 filename: "\\.ya?ml$"
281 Next you must provide the syntax highlighting rules. There are two types of
282 rules: patterns and regions. A pattern is matched on a single line and usually
283 a single word as well. A region highlights between two patterns over multiple
284 lines and may have rules of its own inside the region.
286 Here are some example patterns in Go:
290 - special: "\\b(break|case|continue|default|go|goto|range|return)\\b"
291 - statement: "\\b(else|for|if|switch)\\b"
292 - preproc: "\\b(package|import|const|var|type|struct|func|go|defer|iota)\\b"
295 The order of patterns does matter as patterns lower in the file will overwrite
296 the ones defined above them.
298 And here are some example regions for Go:
305 - constant.specialChar: "%."
306 - constant.specialChar: "\\\\[abfnrtv'\\\"\\\\]"
307 - constant.specialChar: "\\\\([0-7]{3}|x[A-Fa-f0-9]{2}|u[A-Fa-f0-9]{4}|U[A-Fa-f0-9]{8})"
313 - todo: "(TODO|XXX|FIXME):?"
319 - todo: "(TODO|XXX|FIXME):?"
322 Notice how the regions may contain rules inside of them. Any inner rules that
323 are matched are then skipped when searching for the end of the region. For
324 example, when highlighting `"foo \" bar"`, since `\"` is matched by an inner
325 rule in the region, it is skipped. Likewise for `"foo \\" bar`, since `\\` is
326 matched by an inner rule, it is skipped, and then the `"` is found and the
327 string ends at the correct place.
329 You may also explicitly mark skip regexes if you don't want them to be
330 highlighted. For example:
342 You may also include rules from other syntax files as embedded languages. For
343 example, the following is possible for html:
350 - include: "javascript"
359 ## Syntax file headers
361 Syntax file headers are an optimization and it is likely you do not need to
364 Syntax file headers are files that contain only the filetype and the detection
365 regular expressions for a given syntax file. They have a `.hdr` suffix and are
366 used by default only for the pre-installed syntax files. Header files allow
367 micro to parse the syntax files much faster when checking the filetype of a
368 certain file. Custom syntax files may provide header files in
369 `~/.config/micro/syntax` as well but it is not necessary (only do this if you
370 have many (100+) custom syntax files and want to improve performance).