2016-07-28 22:52:31 +03:00
|
|
|
# Colors
|
|
|
|
|
|
|
|
This help page aims to cover two aspects of micro's syntax highlighting engine:
|
|
|
|
|
2020-01-02 23:10:28 +03:00
|
|
|
* How to create colorschemes and use them.
|
2020-02-09 02:31:06 +03:00
|
|
|
* How to create syntax files to add to the list of languages micro can
|
|
|
|
highlight.
|
2017-10-11 16:16:53 +03:00
|
|
|
|
2017-03-27 18:11:51 +03:00
|
|
|
## Colorschemes
|
2016-07-28 22:52:31 +03:00
|
|
|
|
2020-02-07 03:26:27 +03:00
|
|
|
To change your colorscheme, press CtrlE in micro to bring up the command
|
2018-02-20 23:11:31 +03:00
|
|
|
prompt, and type:
|
2019-09-02 21:40:50 +03:00
|
|
|
|
2018-02-20 23:11:31 +03:00
|
|
|
```
|
2020-01-02 23:10:28 +03:00
|
|
|
set colorscheme twilight
|
2018-02-20 23:11:31 +03:00
|
|
|
```
|
2019-09-02 21:40:50 +03:00
|
|
|
|
2018-02-20 23:11:31 +03:00
|
|
|
(or whichever colorscheme you choose).
|
|
|
|
|
2020-01-02 23:10:28 +03:00
|
|
|
Micro comes with a number of colorschemes by default. The colorschemes that you
|
|
|
|
can display will depend on what kind of color support your terminal has.
|
|
|
|
|
|
|
|
Modern terminals tend to have a palette of 16 user-configurable colors (these
|
|
|
|
colors can often be configured in the terminal preferences), and additional
|
|
|
|
color support comes in three flavors.
|
|
|
|
|
|
|
|
* 16-color: A colorscheme that uses the 16 default colors will always work but
|
2020-02-09 02:31:06 +03:00
|
|
|
will only look good if the 16 default colors have been configured to the
|
|
|
|
user's liking. Using a colorscheme that only uses the 16 colors from the
|
|
|
|
terminal palette will also preserve the terminal's theme from other
|
|
|
|
applications since the terminal will often use those same colors for other
|
|
|
|
applications. Default colorschemes of this type include `simple` and
|
|
|
|
`solarized`.
|
|
|
|
|
|
|
|
* 256-color: Almost all terminals support displaying an additional 240 colors
|
|
|
|
on top of the 16 user-configurable colors (creating 256 colors total).
|
|
|
|
Colorschemes which use 256-color are portable because they will look the
|
|
|
|
same regardless of the configured 16-color palette. However, the color
|
|
|
|
range is fairly limited due to the small number of colors available.
|
|
|
|
Default 256-color colorschemes include `monokai`, `twilight`, `zenburn`,
|
|
|
|
`darcula` and more.
|
2020-01-02 23:10:28 +03:00
|
|
|
|
|
|
|
* true-color: Some terminals support displaying "true color" with 16 million
|
2020-02-09 02:31:06 +03:00
|
|
|
colors using standard RGB values. This mode will be able to support
|
|
|
|
displaying any colorscheme, but it should be noted that the user-configured
|
|
|
|
16-color palette is ignored when using true-color mode (this means the
|
|
|
|
colors while using the terminal emulator will be slightly off). Not all
|
|
|
|
terminals support true color but at this point most do. True color
|
|
|
|
support in micro is off by default but can be enabled by setting the
|
|
|
|
environment variable `MICRO_TRUECOLOR` to 1. In addition your terminal
|
|
|
|
must support it (usually indicated by setting `$COLORTERM` to `truecolor`).
|
|
|
|
True-color colorschemes in micro typically end with `-tc`, such as
|
|
|
|
`solarized-tc`, `atom-dark-tc`, `material-tc`, etc... If true color is not
|
|
|
|
enabled but a true color colorscheme is used, micro will do its best to
|
|
|
|
approximate the colors to the available 256 colors.
|
2019-09-02 21:40:50 +03:00
|
|
|
|
|
|
|
Here is the list of colorschemes:
|
2016-07-28 22:52:31 +03:00
|
|
|
|
2018-01-03 06:46:24 +03:00
|
|
|
### 256 color
|
2017-03-01 17:30:35 +03:00
|
|
|
|
2018-01-03 06:46:24 +03:00
|
|
|
These should work and look nice in most terminals. I recommend these
|
|
|
|
themes the most.
|
2017-03-01 17:30:35 +03:00
|
|
|
|
2019-09-02 21:40:50 +03:00
|
|
|
* `monokai` (also the `default` colorscheme)
|
2018-01-03 06:46:24 +03:00
|
|
|
* `zenburn`
|
2018-01-08 05:02:24 +03:00
|
|
|
* `gruvbox`
|
2018-01-03 06:46:24 +03:00
|
|
|
* `darcula`
|
|
|
|
* `twilight`
|
2018-01-08 05:02:24 +03:00
|
|
|
* `railscast`
|
2019-09-02 21:40:50 +03:00
|
|
|
* `bubblegum`
|
2017-03-01 17:30:35 +03:00
|
|
|
|
2018-01-08 05:02:24 +03:00
|
|
|
### 16 color
|
|
|
|
|
|
|
|
These may vary widely based on the 16 colors selected for your terminal.
|
|
|
|
|
2019-09-02 21:40:50 +03:00
|
|
|
* `simple`
|
2020-02-09 02:31:06 +03:00
|
|
|
* `solarized` (must have the solarized color palette in your terminal to use
|
|
|
|
this colorscheme properly)
|
2018-01-08 05:02:24 +03:00
|
|
|
* `cmc-16`
|
2019-09-02 21:40:50 +03:00
|
|
|
* `cmc-paper`
|
|
|
|
* `geany`
|
2018-01-08 05:02:24 +03:00
|
|
|
|
2018-01-03 06:46:24 +03:00
|
|
|
### True color
|
2017-03-01 17:30:35 +03:00
|
|
|
|
2020-02-09 02:31:06 +03:00
|
|
|
True color requires your terminal to support it. This means that the
|
|
|
|
environment variable `COLORTERM` should have the value `truecolor`, `24bit`,
|
|
|
|
or `24-bit`. In addition, to enable true color in micro, the environment
|
|
|
|
variable `MICRO_TRUECOLOR` must be set to 1.
|
2017-03-01 17:30:35 +03:00
|
|
|
|
2018-01-03 06:46:24 +03:00
|
|
|
* `solarized-tc`: this is the solarized colorscheme for true color.
|
|
|
|
* `atom-dark-tc`: this colorscheme is based off of Atom's "dark" colorscheme.
|
|
|
|
* `cmc-tc`: A true colour variant of the cmc theme. It requires true color to
|
|
|
|
look its best. Use cmc-16 if your terminal doesn't support true color.
|
|
|
|
* `gruvbox-tc`: The true color version of the gruvbox colorscheme
|
|
|
|
* `github-tc`: The true color version of the Github colorscheme
|
2017-03-01 17:30:35 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
## Creating a Colorscheme
|
2017-03-01 17:30:35 +03:00
|
|
|
|
2018-02-20 23:11:31 +03:00
|
|
|
Micro's colorschemes are also extremely simple to create. The default ones can
|
2020-02-09 02:31:06 +03:00
|
|
|
be found
|
|
|
|
[here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes).
|
2016-07-28 22:52:31 +03:00
|
|
|
|
2020-02-09 02:31:06 +03:00
|
|
|
Custom colorschemes should be placed in the `~/.config/micro/colorschemes`
|
|
|
|
directory.
|
2020-01-02 23:10:28 +03:00
|
|
|
|
|
|
|
A number of custom directives are placed in a `.micro` file. Colorschemes are
|
|
|
|
typically only 18-30 lines in total.
|
2016-07-28 22:52:31 +03:00
|
|
|
|
2020-01-02 23:10:28 +03:00
|
|
|
To create the colorscheme you need to link highlight groups with
|
2017-10-11 16:16:53 +03:00
|
|
|
actual colors. This is done using the `color-link` command.
|
2016-07-28 22:52:31 +03:00
|
|
|
|
|
|
|
For example, to highlight all comments in green, you would use the command:
|
|
|
|
|
|
|
|
```
|
|
|
|
color-link comment "green"
|
|
|
|
```
|
|
|
|
|
|
|
|
Background colors can also be specified with a comma:
|
|
|
|
|
|
|
|
```
|
|
|
|
color-link comment "green,blue"
|
|
|
|
```
|
|
|
|
|
|
|
|
This will give the comments a blue background.
|
|
|
|
|
|
|
|
If you would like no foreground you can just use a comma with nothing in front:
|
|
|
|
|
|
|
|
```
|
|
|
|
color-link comment ",blue"
|
|
|
|
```
|
|
|
|
|
|
|
|
You can also put bold, or underline in front of the color:
|
|
|
|
|
|
|
|
```
|
|
|
|
color-link comment "bold red"
|
|
|
|
```
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
There are three different ways to specify the color.
|
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
Color terminals usually have 16 colors that are preset by the user. This means
|
|
|
|
that you cannot depend on those colors always being the same. You can use those
|
|
|
|
colors with the names `black, red, green, yellow, blue, magenta, cyan, white`
|
|
|
|
and the bright variants of each one (brightblack, brightred...).
|
2016-07-28 22:52:31 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
Then you can use the terminals 256 colors by using their numbers 1-256 (numbers
|
|
|
|
1-16 will refer to the named colors).
|
2016-07-28 22:52:31 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
If the user's terminal supports true color, then you can also specify colors
|
|
|
|
exactly using their hex codes. If the terminal is not true color but micro is
|
|
|
|
told to use a true color colorscheme it will attempt to map the colors to the
|
|
|
|
available 256 colors.
|
2016-07-28 22:52:31 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
Generally colorschemes which require true color terminals to look good are
|
|
|
|
marked with a `-tc` suffix and colorschemes which supply a white background are
|
|
|
|
marked with a `-paper` suffix.
|
2016-07-28 22:52:31 +03:00
|
|
|
|
|
|
|
---
|
|
|
|
|
2016-08-12 21:17:28 +03:00
|
|
|
Here is a list of the colorscheme groups that you can use:
|
|
|
|
|
|
|
|
* default (color of the background and foreground for unhighlighted text)
|
|
|
|
* comment
|
|
|
|
* identifier
|
|
|
|
* constant
|
|
|
|
* statement
|
2017-01-20 22:32:34 +03:00
|
|
|
* symbol
|
2016-08-12 21:17:28 +03:00
|
|
|
* preproc
|
|
|
|
* type
|
|
|
|
* special
|
|
|
|
* underlined
|
|
|
|
* error
|
|
|
|
* todo
|
2017-10-11 16:16:53 +03:00
|
|
|
* statusline (Color of the statusline)
|
|
|
|
* tabbar (Color of the tabbar that lists open files)
|
|
|
|
* indent-char (Color of the character which indicates tabs if the option is
|
|
|
|
enabled)
|
2016-08-12 21:17:28 +03:00
|
|
|
* line-number
|
|
|
|
* gutter-error
|
|
|
|
* gutter-warning
|
|
|
|
* cursor-line
|
2016-09-08 00:17:51 +03:00
|
|
|
* current-line-number
|
|
|
|
* color-column
|
2017-03-01 17:30:35 +03:00
|
|
|
* ignore
|
2017-10-11 16:16:53 +03:00
|
|
|
* divider (Color of the divider between vertical splits)
|
2016-08-12 21:17:28 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
Colorschemes must be placed in the `~/.config/micro/colorschemes` directory to
|
|
|
|
be used.
|
2016-08-12 21:17:28 +03:00
|
|
|
|
2017-03-01 17:30:35 +03:00
|
|
|
---
|
|
|
|
|
|
|
|
In addition to the main colorscheme groups, there are subgroups that you can
|
2017-10-11 16:16:53 +03:00
|
|
|
specify by adding `.subgroup` to the group. If you're creating your own custom
|
|
|
|
syntax files, you can make use of your own subgroups.
|
2017-03-01 17:30:35 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
If micro can't match the subgroup, it'll default to the root group, so it's
|
|
|
|
safe and recommended to use subgroups in your custom syntax files.
|
2017-03-01 17:30:35 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
For example if `constant.string` is found in your colorscheme, micro will us
|
|
|
|
that for highlighting strings. If it's not found, it will use constant instead.
|
|
|
|
Micro tries to match the largest set of groups it can find in the colorscheme
|
2020-02-09 02:31:06 +03:00
|
|
|
definitions, so if, for examle `constant.bool.true` is found then micro will
|
|
|
|
use that. If `constant.bool.true` is not found but `constant.bool` is found
|
|
|
|
micro will use `constant.bool`. If not, it uses `constant`.
|
2017-03-01 17:30:35 +03:00
|
|
|
|
|
|
|
Here's a list of subgroups used in micro's built-in syntax files.
|
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
* comment.bright (Some filetypes have distinctions between types of comments)
|
2017-03-01 17:30:35 +03:00
|
|
|
* constant.bool
|
|
|
|
* constant.bool.true
|
|
|
|
* constant.bool.false
|
|
|
|
* constant.number
|
|
|
|
* constant.specialChar
|
|
|
|
* constant.string
|
|
|
|
* constant.string.url
|
2017-10-11 16:16:53 +03:00
|
|
|
* identifier.class (Also used for functions)
|
2017-03-01 17:30:35 +03:00
|
|
|
* identifier.macro
|
|
|
|
* identifier.var
|
2017-10-11 16:16:53 +03:00
|
|
|
* preproc.shebang (The #! at the beginning of a file that tells the os what
|
|
|
|
script interpreter to use)
|
2017-11-08 08:23:18 +03:00
|
|
|
* symbol.brackets (`{}()[]` and sometimes `<>`)
|
2017-10-11 16:16:53 +03:00
|
|
|
* symbol.operator (Color operator symbols differently)
|
|
|
|
* symbol.tag (For html tags, among other things)
|
|
|
|
* type.keyword (If you want a special highlight for keywords like `private`)
|
2017-03-01 17:30:35 +03:00
|
|
|
|
|
|
|
In the future, plugins may also be able to use color groups for styling.
|
2016-07-28 22:52:31 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
|
2017-03-27 18:11:51 +03:00
|
|
|
## Syntax files
|
2016-07-28 22:52:31 +03:00
|
|
|
|
2019-09-13 18:07:11 +03:00
|
|
|
The syntax files are written in yaml-format and specify how to highlight
|
2017-10-11 16:16:53 +03:00
|
|
|
languages.
|
2016-07-28 22:52:31 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
Micro's builtin syntax highlighting tries very hard to be sane, sensible and
|
|
|
|
provide ample coverage of the meaningful elements of a language. Micro has
|
2017-11-08 08:23:18 +03:00
|
|
|
syntax files built in for over 100 languages now! However, there may be
|
2020-02-09 02:31:06 +03:00
|
|
|
situations where you find Micro's highlighting to be insufficient or not to
|
|
|
|
your liking. The good news is that you can create your own syntax files, and
|
|
|
|
place them in `~/.config/micro/syntax` and Micro will use those instead.
|
2017-03-01 17:30:35 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
### Filetype definition
|
2017-03-27 01:58:08 +03:00
|
|
|
|
|
|
|
You must start the syntax file by declaring the filetype:
|
2016-08-12 21:17:28 +03:00
|
|
|
|
|
|
|
```
|
2017-03-27 01:58:08 +03:00
|
|
|
filetype: go
|
2016-08-12 21:17:28 +03:00
|
|
|
```
|
|
|
|
|
2020-01-02 23:10:28 +03:00
|
|
|
### Detect definition
|
2016-08-12 21:17:28 +03:00
|
|
|
|
2017-03-27 18:11:51 +03:00
|
|
|
Then you must provide information about how to detect the filetype:
|
2016-08-12 21:17:28 +03:00
|
|
|
|
2017-03-27 01:58:08 +03:00
|
|
|
```
|
|
|
|
detect:
|
|
|
|
filename: "\\.go$"
|
|
|
|
```
|
|
|
|
|
2020-02-09 02:31:06 +03:00
|
|
|
Micro will match this regex against a given filename to detect the filetype.
|
|
|
|
You may also provide an optional `header` regex that will check the first line
|
|
|
|
of the file. For example:
|
2017-03-27 01:58:08 +03:00
|
|
|
|
|
|
|
```
|
|
|
|
detect:
|
|
|
|
filename: "\\.ya?ml$"
|
|
|
|
header: "%YAML"
|
|
|
|
```
|
2016-08-12 21:17:28 +03:00
|
|
|
|
2020-01-02 23:10:28 +03:00
|
|
|
### Syntax rules
|
2016-08-12 21:17:28 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
Next you must provide the syntax highlighting rules. There are two types of
|
2020-02-09 02:31:06 +03:00
|
|
|
rules: patterns and regions. A pattern is matched on a single line and usually
|
|
|
|
a single word as well. A region highlights between two patterns over multiple
|
2017-10-11 16:16:53 +03:00
|
|
|
lines and may have rules of its own inside the region.
|
2016-08-12 21:17:28 +03:00
|
|
|
|
2017-03-27 01:58:08 +03:00
|
|
|
Here are some example patterns in Go:
|
2016-08-12 21:17:28 +03:00
|
|
|
|
|
|
|
```
|
2017-03-27 01:58:08 +03:00
|
|
|
rules:
|
|
|
|
- special: "\\b(break|case|continue|default|go|goto|range|return)\\b"
|
|
|
|
- statement: "\\b(else|for|if|switch)\\b"
|
|
|
|
- preproc: "\\b(package|import|const|var|type|struct|func|go|defer|iota)\\b"
|
2016-08-12 21:17:28 +03:00
|
|
|
```
|
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
The order of patterns does matter as patterns lower in the file will overwrite
|
|
|
|
the ones defined above them.
|
2017-03-27 01:58:08 +03:00
|
|
|
|
|
|
|
And here are some example regions for Go:
|
|
|
|
|
|
|
|
```
|
|
|
|
- constant.string:
|
|
|
|
start: "\""
|
2017-03-28 03:53:08 +03:00
|
|
|
end: "\""
|
2017-03-27 01:58:08 +03:00
|
|
|
rules:
|
|
|
|
- constant.specialChar: "%."
|
|
|
|
- constant.specialChar: "\\\\[abfnrtv'\\\"\\\\]"
|
|
|
|
- constant.specialChar: "\\\\([0-7]{3}|x[A-Fa-f0-9]{2}|u[A-Fa-f0-9]{4}|U[A-Fa-f0-9]{8})"
|
|
|
|
|
|
|
|
- comment:
|
|
|
|
start: "//"
|
|
|
|
end: "$"
|
|
|
|
rules:
|
|
|
|
- todo: "(TODO|XXX|FIXME):?"
|
|
|
|
|
|
|
|
- comment:
|
|
|
|
start: "/\\*"
|
|
|
|
end: "\\*/"
|
|
|
|
rules:
|
|
|
|
- todo: "(TODO|XXX|FIXME):?"
|
|
|
|
```
|
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
Notice how the regions may contain rules inside of them. Any inner rules that
|
|
|
|
are matched are then skipped when searching for the end of the region. For
|
|
|
|
example, when highlighting `"foo \" bar"`, since `\"` is matched by an inner
|
|
|
|
rule in the region, it is skipped. Likewise for `"foo \\" bar`, since `\\` is
|
|
|
|
matched by an inner rule, it is skipped, and then the `"` is found and the
|
|
|
|
string ends at the correct place.
|
2017-03-27 01:58:08 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
You may also explicitly mark skip regexes if you don't want them to be
|
|
|
|
highlighted. For example:
|
2017-03-28 03:53:08 +03:00
|
|
|
|
|
|
|
```
|
|
|
|
- constant.string:
|
|
|
|
start: "\""
|
|
|
|
end: "\""
|
|
|
|
skip: "\\."
|
|
|
|
rules: []
|
|
|
|
```
|
2017-03-27 01:58:08 +03:00
|
|
|
|
|
|
|
#### Includes
|
2016-08-12 21:17:28 +03:00
|
|
|
|
2017-10-11 16:16:53 +03:00
|
|
|
You may also include rules from other syntax files as embedded languages. For
|
|
|
|
example, the following is possible for html:
|
2016-08-12 21:17:28 +03:00
|
|
|
|
|
|
|
```
|
2017-03-27 01:58:08 +03:00
|
|
|
- default:
|
|
|
|
start: "<script.*?>"
|
|
|
|
end: "</script.*?>"
|
|
|
|
rules:
|
|
|
|
- include: "javascript"
|
|
|
|
|
|
|
|
- default:
|
|
|
|
start: "<style.*?>"
|
|
|
|
end: "</style.*?>"
|
|
|
|
rules:
|
|
|
|
- include: "css"
|
2016-08-12 21:17:28 +03:00
|
|
|
```
|
2020-01-02 23:10:28 +03:00
|
|
|
|
|
|
|
## Syntax file headers
|
|
|
|
|
|
|
|
Syntax file headers are an optimization and it is likely you do not need to
|
|
|
|
worry about them.
|
|
|
|
|
|
|
|
Syntax file headers are files that contain only the filetype and the detection
|
|
|
|
regular expressions for a given syntax file. They have a `.hdr` suffix and are
|
2020-02-09 02:31:06 +03:00
|
|
|
used by default only for the pre-installed syntax files. Header files allow
|
|
|
|
micro to parse the syntax files much faster when checking the filetype of a
|
|
|
|
certain file. Custom syntax files may provide header files in
|
|
|
|
`~/.config/micro/syntax` as well but it is not necessary (only do this if you
|
|
|
|
have many (100+) custom syntax files and want to improve performance).
|