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 Ctrl-E in micro to bring up the command
14 set colorscheme monokai
17 (or whichever colorscheme you choose).
19 Micro comes with a number of colorschemes by default. Modern terminals tend to
20 have three different kinds of color support. The most common is 256 color where
21 the terminal provides 256 standardized colors (except the first 16 may be configured
22 by the user). A 256-color theme requires a terminal with 256 color support and
25 A 16-color theme uses the 16 user-configurable colors (or 16 default colors on
26 old terminals). These colorschemes are guranteed to work, but won't look great
27 unless the 16 colors are configured to the user's liking. Using a 16-color theme
28 will also preserve the terminal's theme because the terminal usually uses its 16
29 colors for prompts or other coloring.
31 Some terminals support "true color" with 16 million colors (using standard RGB values).
32 There is no one standard for this color support among terminals so this method
33 is not guaranteed to work. Usually truecolor must also be enabled by the user. The
34 colorschemes using true color will look exactly as intended. If true color is not
35 supported, a true color colorscheme will approximate its colors to 256-color.
37 Here is the list of colorschemes:
41 These should work and look nice in most terminals. I recommend these
44 * `monokai` (also the `default` colorscheme)
54 These may vary widely based on the 16 colors selected for your terminal.
57 * `solarized` (must have the solarized color palette in your terminal to use this colorscheme properly)
64 These require terminals that support true color and require `MICRO_TRUECOLOR=1` (this is an environment variable).
66 * `solarized-tc`: this is the solarized colorscheme for true color.
67 * `atom-dark-tc`: this colorscheme is based off of Atom's "dark" colorscheme.
68 * `cmc-tc`: A true colour variant of the cmc theme. It requires true color to
69 look its best. Use cmc-16 if your terminal doesn't support true color.
70 * `gruvbox-tc`: The true color version of the gruvbox colorscheme
71 * `github-tc`: The true color version of the Github colorscheme
73 ## Creating a Colorscheme
75 Micro's colorschemes are also extremely simple to create. The default ones can
76 be found [here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes).
78 They are only about 18-30 lines in total.
80 Basically to create the colorscheme you need to link highlight groups with
81 actual colors. This is done using the `color-link` command.
83 For example, to highlight all comments in green, you would use the command:
86 color-link comment "green"
89 Background colors can also be specified with a comma:
92 color-link comment "green,blue"
95 This will give the comments a blue background.
97 If you would like no foreground you can just use a comma with nothing in front:
100 color-link comment ",blue"
103 You can also put bold, or underline in front of the color:
106 color-link comment "bold red"
111 There are three different ways to specify the color.
113 Color terminals usually have 16 colors that are preset by the user. This means
114 that you cannot depend on those colors always being the same. You can use those
115 colors with the names `black, red, green, yellow, blue, magenta, cyan, white`
116 and the bright variants of each one (brightblack, brightred...).
118 Then you can use the terminals 256 colors by using their numbers 1-256 (numbers
119 1-16 will refer to the named colors).
121 If the user's terminal supports true color, then you can also specify colors
122 exactly using their hex codes. If the terminal is not true color but micro is
123 told to use a true color colorscheme it will attempt to map the colors to the
124 available 256 colors.
126 Generally colorschemes which require true color terminals to look good are
127 marked with a `-tc` suffix and colorschemes which supply a white background are
128 marked with a `-paper` suffix.
132 Here is a list of the colorscheme groups that you can use:
134 * default (color of the background and foreground for unhighlighted text)
146 * statusline (Color of the statusline)
147 * tabbar (Color of the tabbar that lists open files)
148 * indent-char (Color of the character which indicates tabs if the option is
154 * current-line-number
157 * divider (Color of the divider between vertical splits)
159 Colorschemes must be placed in the `~/.config/micro/colorschemes` directory to
164 In addition to the main colorscheme groups, there are subgroups that you can
165 specify by adding `.subgroup` to the group. If you're creating your own custom
166 syntax files, you can make use of your own subgroups.
168 If micro can't match the subgroup, it'll default to the root group, so it's
169 safe and recommended to use subgroups in your custom syntax files.
171 For example if `constant.string` is found in your colorscheme, micro will us
172 that for highlighting strings. If it's not found, it will use constant instead.
173 Micro tries to match the largest set of groups it can find in the colorscheme
174 definitions, so if, for examle `constant.bool.true` is found then micro will use
175 that. If `constant.bool.true` is not found but `constant.bool` is found micro
176 will use `constant.bool`. If not, it uses `constant`.
178 Here's a list of subgroups used in micro's built-in syntax files.
180 * comment.bright (Some filetypes have distinctions between types of comments)
183 * constant.bool.false
185 * constant.specialChar
187 * constant.string.url
188 * identifier.class (Also used for functions)
191 * preproc.shebang (The #! at the beginning of a file that tells the os what
192 script interpreter to use)
193 * symbol.brackets (`{}()[]` and sometimes `<>`)
194 * symbol.operator (Color operator symbols differently)
195 * symbol.tag (For html tags, among other things)
196 * type.keyword (If you want a special highlight for keywords like `private`)
198 In the future, plugins may also be able to use color groups for styling.
203 The syntax files is written in yaml-format and specify how to highlight
206 Micro's builtin syntax highlighting tries very hard to be sane, sensible and
207 provide ample coverage of the meaningful elements of a language. Micro has
208 syntax files built in for over 100 languages now! However, there may be
209 situations where you find Micro's highlighting to be insufficient or not to your
210 liking. The good news is that you can create your own syntax files, and place them
211 in `~/.config/micro/syntax` and Micro will use those instead.
213 ### Filetype definition
215 You must start the syntax file by declaring the filetype:
221 #### Detect definition
223 Then you must provide information about how to detect the filetype:
230 Micro will match this regex against a given filename to detect the filetype. You
231 may also provide an optional `header` regex that will check the first line of
232 the file. For example:
236 filename: "\\.ya?ml$"
242 Next you must provide the syntax highlighting rules. There are two types of
243 rules: patterns and regions. A pattern is matched on a single line and usually a
244 single word as well. A region highlights between two patterns over multiple
245 lines and may have rules of its own inside the region.
247 Here are some example patterns in Go:
251 - special: "\\b(break|case|continue|default|go|goto|range|return)\\b"
252 - statement: "\\b(else|for|if|switch)\\b"
253 - preproc: "\\b(package|import|const|var|type|struct|func|go|defer|iota)\\b"
256 The order of patterns does matter as patterns lower in the file will overwrite
257 the ones defined above them.
259 And here are some example regions for Go:
266 - constant.specialChar: "%."
267 - constant.specialChar: "\\\\[abfnrtv'\\\"\\\\]"
268 - constant.specialChar: "\\\\([0-7]{3}|x[A-Fa-f0-9]{2}|u[A-Fa-f0-9]{4}|U[A-Fa-f0-9]{8})"
274 - todo: "(TODO|XXX|FIXME):?"
280 - todo: "(TODO|XXX|FIXME):?"
283 Notice how the regions may contain rules inside of them. Any inner rules that
284 are matched are then skipped when searching for the end of the region. For
285 example, when highlighting `"foo \" bar"`, since `\"` is matched by an inner
286 rule in the region, it is skipped. Likewise for `"foo \\" bar`, since `\\` is
287 matched by an inner rule, it is skipped, and then the `"` is found and the
288 string ends at the correct place.
290 You may also explicitly mark skip regexes if you don't want them to be
291 highlighted. For example:
303 You may also include rules from other syntax files as embedded languages. For
304 example, the following is possible for html:
311 - include: "javascript"