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 highlight.
10 To change your colorscheme, press CtrlE in micro to bring up the command
14 set colorscheme twilight
17 (or whichever colorscheme you choose).
19 Micro comes with a number of colorschemes by default. The colorschemes that you
20 can display will depend on what kind of color support your terminal has.
22 Modern terminals tend to have a palette of 16 user-configurable colors (these
23 colors can often be configured in the terminal preferences), and additional
24 color support comes in three flavors.
26 * 16-color: A colorscheme that uses the 16 default colors will always work but
27 will only look good if the 16 default colors have been configured to the user's
28 liking. Using a colorscheme that only uses the 16 colors from the terminal palette
29 will also preserve the terminal's theme from other applications since the terminal
30 will often use those same colors for other applications. Default colorschemes
31 of this type include `simple` and `solarized`.
33 * 256-color: Almost all terminals support displaying an additional 240 colors on
34 top of the 16 user-configurable colors (creating 256 colors total). Colorschemes
35 which use 256-color are portable because they will look the same regardless of
36 the configured 16-color palette. However, the color range is fairly limited
37 due to the small number of colors available. Default 256-color colorschemes
38 include `monokai`, `twilight`, `zenburn`, `darcula` and more.
40 * true-color: Some terminals support displaying "true color" with 16 million
41 colors using standard RGB values. This mode will be able to support displaying
42 any colorscheme, but it should be noted that the user-configured 16-color palette
43 is ignored when using true-color mode (this means the colors while using the
44 terminal emulator will be slightly off). Not all terminals support true color
45 but at this point most do. True color support in micro is off by default but
46 can be enabled by setting the environment variable `MICRO_TRUECOLOR` to 1.
47 In addition your terminal must support it (usually indicated by setting `$COLORTERM`
49 True-color colorschemes in micro typically end with `-tc`, such as `solarized-tc`,
50 `atom-dark-tc`, `material-tc`, etc... If true color is not enabled but a true
51 color colorscheme is used, micro will do its best to approximate the colors
52 to the available 256 colors.
54 Here is the list of colorschemes:
58 These should work and look nice in most terminals. I recommend these
61 * `monokai` (also the `default` colorscheme)
71 These may vary widely based on the 16 colors selected for your terminal.
74 * `solarized` (must have the solarized color palette in your terminal to use this colorscheme properly)
81 True color requires your terminal to support it. This means that the environment variable
82 `COLORTERM` should have the value `truecolor`, `24bit`, or `24-bit`. In addition, to enable
83 true color in micro, the environment variable `MICRO_TRUECOLOR` must be set to 1.
85 * `solarized-tc`: this is the solarized colorscheme for true color.
86 * `atom-dark-tc`: this colorscheme is based off of Atom's "dark" colorscheme.
87 * `cmc-tc`: A true colour variant of the cmc theme. It requires true color to
88 look its best. Use cmc-16 if your terminal doesn't support true color.
89 * `gruvbox-tc`: The true color version of the gruvbox colorscheme
90 * `github-tc`: The true color version of the Github colorscheme
92 ## Creating a Colorscheme
94 Micro's colorschemes are also extremely simple to create. The default ones can
95 be found [here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes).
97 Custom colorschemes should be placed in the `~/.config/micro/colorschemes` directory.
99 A number of custom directives are placed in a `.micro` file. Colorschemes are
100 typically only 18-30 lines in total.
102 To create the colorscheme you need to link highlight groups with
103 actual colors. This is done using the `color-link` command.
105 For example, to highlight all comments in green, you would use the command:
108 color-link comment "green"
111 Background colors can also be specified with a comma:
114 color-link comment "green,blue"
117 This will give the comments a blue background.
119 If you would like no foreground you can just use a comma with nothing in front:
122 color-link comment ",blue"
125 You can also put bold, or underline in front of the color:
128 color-link comment "bold red"
133 There are three different ways to specify the color.
135 Color terminals usually have 16 colors that are preset by the user. This means
136 that you cannot depend on those colors always being the same. You can use those
137 colors with the names `black, red, green, yellow, blue, magenta, cyan, white`
138 and the bright variants of each one (brightblack, brightred...).
140 Then you can use the terminals 256 colors by using their numbers 1-256 (numbers
141 1-16 will refer to the named colors).
143 If the user's terminal supports true color, then you can also specify colors
144 exactly using their hex codes. If the terminal is not true color but micro is
145 told to use a true color colorscheme it will attempt to map the colors to the
146 available 256 colors.
148 Generally colorschemes which require true color terminals to look good are
149 marked with a `-tc` suffix and colorschemes which supply a white background are
150 marked with a `-paper` suffix.
154 Here is a list of the colorscheme groups that you can use:
156 * default (color of the background and foreground for unhighlighted text)
168 * statusline (Color of the statusline)
169 * tabbar (Color of the tabbar that lists open files)
170 * indent-char (Color of the character which indicates tabs if the option is
176 * current-line-number
179 * divider (Color of the divider between vertical splits)
181 Colorschemes must be placed in the `~/.config/micro/colorschemes` directory to
186 In addition to the main colorscheme groups, there are subgroups that you can
187 specify by adding `.subgroup` to the group. If you're creating your own custom
188 syntax files, you can make use of your own subgroups.
190 If micro can't match the subgroup, it'll default to the root group, so it's
191 safe and recommended to use subgroups in your custom syntax files.
193 For example if `constant.string` is found in your colorscheme, micro will us
194 that for highlighting strings. If it's not found, it will use constant instead.
195 Micro tries to match the largest set of groups it can find in the colorscheme
196 definitions, so if, for examle `constant.bool.true` is found then micro will use
197 that. If `constant.bool.true` is not found but `constant.bool` is found micro
198 will use `constant.bool`. If not, it uses `constant`.
200 Here's a list of subgroups used in micro's built-in syntax files.
202 * comment.bright (Some filetypes have distinctions between types of comments)
205 * constant.bool.false
207 * constant.specialChar
209 * constant.string.url
210 * identifier.class (Also used for functions)
213 * preproc.shebang (The #! at the beginning of a file that tells the os what
214 script interpreter to use)
215 * symbol.brackets (`{}()[]` and sometimes `<>`)
216 * symbol.operator (Color operator symbols differently)
217 * symbol.tag (For html tags, among other things)
218 * type.keyword (If you want a special highlight for keywords like `private`)
220 In the future, plugins may also be able to use color groups for styling.
225 The syntax files are written in yaml-format and specify how to highlight
228 Micro's builtin syntax highlighting tries very hard to be sane, sensible and
229 provide ample coverage of the meaningful elements of a language. Micro has
230 syntax files built in for over 100 languages now! However, there may be
231 situations where you find Micro's highlighting to be insufficient or not to your
232 liking. The good news is that you can create your own syntax files, and place them
233 in `~/.config/micro/syntax` and Micro will use those instead.
235 ### Filetype definition
237 You must start the syntax file by declaring the filetype:
243 ### Detect definition
245 Then you must provide information about how to detect the filetype:
252 Micro will match this regex against a given filename to detect the filetype. You
253 may also provide an optional `header` regex that will check the first line of
254 the file. For example:
258 filename: "\\.ya?ml$"
264 Next you must provide the syntax highlighting rules. There are two types of
265 rules: patterns and regions. A pattern is matched on a single line and usually a
266 single word as well. A region highlights between two patterns over multiple
267 lines and may have rules of its own inside the region.
269 Here are some example patterns in Go:
273 - special: "\\b(break|case|continue|default|go|goto|range|return)\\b"
274 - statement: "\\b(else|for|if|switch)\\b"
275 - preproc: "\\b(package|import|const|var|type|struct|func|go|defer|iota)\\b"
278 The order of patterns does matter as patterns lower in the file will overwrite
279 the ones defined above them.
281 And here are some example regions for Go:
288 - constant.specialChar: "%."
289 - constant.specialChar: "\\\\[abfnrtv'\\\"\\\\]"
290 - constant.specialChar: "\\\\([0-7]{3}|x[A-Fa-f0-9]{2}|u[A-Fa-f0-9]{4}|U[A-Fa-f0-9]{8})"
296 - todo: "(TODO|XXX|FIXME):?"
302 - todo: "(TODO|XXX|FIXME):?"
305 Notice how the regions may contain rules inside of them. Any inner rules that
306 are matched are then skipped when searching for the end of the region. For
307 example, when highlighting `"foo \" bar"`, since `\"` is matched by an inner
308 rule in the region, it is skipped. Likewise for `"foo \\" bar`, since `\\` is
309 matched by an inner rule, it is skipped, and then the `"` is found and the
310 string ends at the correct place.
312 You may also explicitly mark skip regexes if you don't want them to be
313 highlighted. For example:
325 You may also include rules from other syntax files as embedded languages. For
326 example, the following is possible for html:
333 - include: "javascript"
342 ## Syntax file headers
344 Syntax file headers are an optimization and it is likely you do not need to
347 Syntax file headers are files that contain only the filetype and the detection
348 regular expressions for a given syntax file. They have a `.hdr` suffix and are
349 used by default only for the pre-installed syntax files. Header files allow micro
350 to parse the syntax files much faster when checking the filetype of a certain
351 file. Custom syntax files may provide header files in `~/.config/micro/syntax` as
352 well but it is not necessary (only do this if you have many (100+) custom syntax
353 files and want to improve performance).