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
11 Micro comes with a number of colorschemes by default. Here is the list:
15 These should work and look nice in most terminals. I recommend these
18 * `monokai`: this is the monokai colorscheme; you may recognize it as Sublime
19 Text's default colorscheme. It requires true color to look perfect, but the
20 256 color approximation looks very good as well. It's also the default
27 * `bubblegum`: a light colorscheme
31 These may vary widely based on the 16 colors selected for your terminal.
33 * `simple`: this is the simplest colorscheme. It uses 16 colors which are set by
35 * `solarized`: You should have the solarized color palette in your terminal to use this colorscheme properly.
37 * `cmc-paper`: cmc-16, but on a white background. (Actually light grey
38 on most ANSI (16-color) terminals)
39 * `geany`: Colorscheme based on geany's default highlighting.
43 These require terminals that support true color and require `MICRO_TRUECOLOR=1` (this is an environment variable).
45 * `solarized-tc`: this is the solarized colorscheme for true color.
46 * `atom-dark-tc`: this colorscheme is based off of Atom's "dark" colorscheme.
47 * `cmc-tc`: A true colour variant of the cmc theme. It requires true color to
48 look its best. Use cmc-16 if your terminal doesn't support true color.
49 * `gruvbox-tc`: The true color version of the gruvbox colorscheme
50 * `github-tc`: The true color version of the Github colorscheme
52 To enable one of these colorschemes just press CtrlE in micro and type
53 `set colorscheme solarized`. (or whichever one you choose). You can also use
54 `set colorscheme monochrome` if you'd prefer to have just the terminal's default
55 foreground and background colors. Note: This provides no syntax highlighting!
57 See `help gimmickcolors` for a list of some true colour themes that are more
58 just for fun than for serious use. (Though feel free if you want!)
61 ## Creating a Colorscheme
63 Micro's colorschemes are also extremely simple to create. The default ones ca
65 [here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes).
67 They are only about 18-30 lines in total.
69 Basically to create the colorscheme you need to link highlight groups with
70 actual colors. This is done using the `color-link` command.
72 For example, to highlight all comments in green, you would use the command:
75 color-link comment "green"
78 Background colors can also be specified with a comma:
81 color-link comment "green,blue"
84 This will give the comments a blue background.
86 If you would like no foreground you can just use a comma with nothing in front:
89 color-link comment ",blue"
92 You can also put bold, or underline in front of the color:
95 color-link comment "bold red"
100 There are three different ways to specify the color.
102 Color terminals usually have 16 colors that are preset by the user. This means
103 that you cannot depend on those colors always being the same. You can use those
104 colors with the names `black, red, green, yellow, blue, magenta, cyan, white`
105 and the bright variants of each one (brightblack, brightred...).
107 Then you can use the terminals 256 colors by using their numbers 1-256 (numbers
108 1-16 will refer to the named colors).
110 If the user's terminal supports true color, then you can also specify colors
111 exactly using their hex codes. If the terminal is not true color but micro is
112 told to use a true color colorscheme it will attempt to map the colors to the
113 available 256 colors.
115 Generally colorschemes which require true color terminals to look good are
116 marked with a `-tc` suffix and colorschemes which supply a white background are
117 marked with a `-paper` suffix.
121 Here is a list of the colorscheme groups that you can use:
123 * default (color of the background and foreground for unhighlighted text)
135 * statusline (Color of the statusline)
136 * tabbar (Color of the tabbar that lists open files)
137 * indent-char (Color of the character which indicates tabs if the option is
143 * current-line-number
146 * divider (Color of the divider between vertical splits)
148 Colorschemes must be placed in the `~/.config/micro/colorschemes` directory to
153 In addition to the main colorscheme groups, there are subgroups that you can
154 specify by adding `.subgroup` to the group. If you're creating your own custom
155 syntax files, you can make use of your own subgroups.
157 If micro can't match the subgroup, it'll default to the root group, so it's
158 safe and recommended to use subgroups in your custom syntax files.
160 For example if `constant.string` is found in your colorscheme, micro will us
161 that for highlighting strings. If it's not found, it will use constant instead.
162 Micro tries to match the largest set of groups it can find in the colorscheme
163 definitions, so if, for examle `constant.bool.true` is found then micro will use
164 that. If `constant.bool.true` is not found but `constant.bool` is found micro
165 will use `constant.bool`. If not, it uses `constant`.
167 Here's a list of subgroups used in micro's built-in syntax files.
169 * comment.bright (Some filetypes have distinctions between types of comments)
172 * constant.bool.false
174 * constant.specialChar
176 * constant.string.url
177 * identifier.class (Also used for functions)
180 * preproc.shebang (The #! at the beginning of a file that tells the os what
181 script interpreter to use)
182 * symbol.brackets (`{}()[]` and sometimes `<>`)
183 * symbol.operator (Color operator symbols differently)
184 * symbol.tag (For html tags, among other things)
185 * type.keyword (If you want a special highlight for keywords like `private`)
187 In the future, plugins may also be able to use color groups for styling.
192 The syntax files is written in yaml-format and specify how to highlight
195 Micro's builtin syntax highlighting tries very hard to be sane, sensible and
196 provide ample coverage of the meaningful elements of a language. Micro has
197 syntax files built in for over 100 languages now! However, there may be
198 situations where you find Micro's highlighting to be insufficient or not to your
199 liking. The good news is that you can create your own syntax files, and place them
200 in `~/.config/micro/syntax` and Micro will use those instead.
202 ### Filetype definition
204 You must start the syntax file by declaring the filetype:
210 #### Detect definition
212 Then you must provide information about how to detect the filetype:
219 Micro will match this regex against a given filename to detect the filetype. You
220 may also provide an optional `header` regex that will check the first line of
221 the file. For example:
225 filename: "\\.ya?ml$"
231 Next you must provide the syntax highlighting rules. There are two types of
232 rules: patterns and regions. A pattern is matched on a single line and usually a
233 single word as well. A region highlights between two patterns over multiple
234 lines and may have rules of its own inside the region.
236 Here are some example patterns in Go:
240 - special: "\\b(break|case|continue|default|go|goto|range|return)\\b"
241 - statement: "\\b(else|for|if|switch)\\b"
242 - preproc: "\\b(package|import|const|var|type|struct|func|go|defer|iota)\\b"
245 The order of patterns does matter as patterns lower in the file will overwrite
246 the ones defined above them.
248 And here are some example regions for Go:
255 - constant.specialChar: "%."
256 - constant.specialChar: "\\\\[abfnrtv'\\\"\\\\]"
257 - constant.specialChar: "\\\\([0-7]{3}|x[A-Fa-f0-9]{2}|u[A-Fa-f0-9]{4}|U[A-Fa-f0-9]{8})"
263 - todo: "(TODO|XXX|FIXME):?"
269 - todo: "(TODO|XXX|FIXME):?"
272 Notice how the regions may contain rules inside of them. Any inner rules that
273 are matched are then skipped when searching for the end of the region. For
274 example, when highlighting `"foo \" bar"`, since `\"` is matched by an inner
275 rule in the region, it is skipped. Likewise for `"foo \\" bar`, since `\\` is
276 matched by an inner rule, it is skipped, and then the `"` is found and the
277 string ends at the correct place.
279 You may also explicitly mark skip regexes if you don't want them to be
280 highlighted. For example:
292 You may also include rules from other syntax files as embedded languages. For
293 example, the following is possible for html:
300 - include: "javascript"