github/zyedidia.micro
2
0
Fork 0
mirror of https://github.com/zyedidia/micro.git synced 2026-03-29 22:27:13 +09:00
Code Issues Packages Projects Releases Wiki Activity

More plugin docs and improve doc formatting

Browse Source
This commit is contained in:
Zachary Yedidia
2020-02-08 18:31:06 -05:00
parent 6514b77e0d
commit 57c34e2248
12 changed files with 404 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
runtime/help/colors.md
View File

@@ -3,7 +3,8 @@
This help page aims to cover two aspects of micro's syntax highlighting engine:
* How to create colorschemes and use them.
* How to create syntax files to add to the list of languages micro can highlight.
* How to create syntax files to add to the list of languages micro can
highlight.
## Colorschemes
@@ -24,32 +25,34 @@ 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
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`.
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.
* 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.
* true-color: Some terminals support displaying "true color" with 16 million
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.
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.
Here is the list of colorschemes:
@@ -71,16 +74,18 @@ themes the most.
These may vary widely based on the 16 colors selected for your terminal.
* `simple`
* `solarized` (must have the solarized color palette in your terminal to use this colorscheme properly)
* `solarized` (must have the solarized color palette in your terminal to use
this colorscheme properly)
* `cmc-16`
* `cmc-paper`
* `geany`
### True color
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.
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.
* `solarized-tc`: this is the solarized colorscheme for true color.
* `atom-dark-tc`: this colorscheme is based off of Atom's "dark" colorscheme.
@@ -92,9 +97,11 @@ true color in micro, the environment variable `MICRO_TRUECOLOR` must be set to 1
## Creating a Colorscheme
Micro's colorschemes are also extremely simple to create. The default ones can
be found [here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes).
be found
[here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes).
Custom colorschemes should be placed in the `~/.config/micro/colorschemes` directory.
Custom colorschemes should be placed in the `~/.config/micro/colorschemes`
directory.
A number of custom directives are placed in a `.micro` file. Colorschemes are
typically only 18-30 lines in total.
@@ -193,9 +200,9 @@ safe and recommended to use subgroups in your custom syntax files.
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
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`.
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`.
Here's a list of subgroups used in micro's built-in syntax files.
@@ -228,9 +235,9 @@ languages.
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
syntax files built in for over 100 languages now! However, there may be
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.
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.
### Filetype definition
@@ -249,9 +256,9 @@ detect:
filename: "\\.go$"
```
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:
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:
```
detect:
@@ -262,8 +269,8 @@ detect:
### Syntax rules
Next you must provide the syntax highlighting rules. There are two types of
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
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
lines and may have rules of its own inside the region.
Here are some example patterns in Go:
@@ -346,8 +353,8 @@ 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
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).
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).