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 colorschemes and use them.
+* How to create syntax files to add to the list of languages micro can highlight.
## Colorschemes
-Micro comes with a number of colorschemes by default. Here is the list:
-
-* simple: this is the simplest colorscheme. It uses 16 colors which are set by
- your terminal
-
-* mc: A 16-color theme based on the look and feel of GNU Midnight Commander.
- This will look great used in conjunction with Midnight Commander.
-
-* nano: A 16-color theme loosely based on GNU nano's syntax highlighting.
-
-* monokai: this is the monokai colorscheme; you may recognize it as Sublime
- Text's default colorscheme. It requires true color to look perfect, but the
- 256 color approximation looks very good as well. It's also the default
- colorscheme.
-
-* zenburn: The 'zenburn' colorscheme and works well with 256 color terminals
-
-* solarized: this is the solarized colorscheme. You should have the solarized
- color palette in your terminal to use it.
-
-* solarized-tc: this is the solarized colorscheme for true color; just make sure
- your terminal supports true color before using it and that the MICRO_TRUECOLOR
- environment variable is set to 1 before starting micro.
+To change your colorscheme, press Ctrl-e in micro to bring up the command
+prompt, and type:
-* atom-dark-tc: this colorscheme is based off of Atom's "dark" colorscheme. It
- requires true color to look good.
-
-* cmc-16: A very nice 16-color theme. Written by contributor CaptainMcClellan
- (Collin Warren.) Licensed under the same license as the rest of the themes.
-
-* cmc-paper: Basically cmc-16, but on a white background. (Actually light grey
- on most ANSI (16-color) terminals)
+```
+set colorscheme twilight
+```
-* cmc-tc: A true colour variant of the cmc theme. It requires true color to
+(or whichever colorscheme you choose).
+
+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
+ 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.
+
+* 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.
+
+Here is the list of colorschemes:
+
+### 256 color
+
+These should work and look nice in most terminals. I recommend these
+themes the most.
+
+* `monokai` (also the `default` colorscheme)
+* `zenburn`
+* `gruvbox`
+* `darcula`
+* `twilight`
+* `railscast`
+* `bubblegum`
+
+### 16 color
+
+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)
+* `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.
+
+* `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.
-
-* codeblocks: A colorscheme based on the Code::Blocks IDE's default syntax
- highlighting.
-
-* codeblocks-paper: Same as codeblocks, but on a white background. (Actually
- light grey)
-
-* github-tc: A colorscheme based on Github's syntax highlighting. Requires true
- color to look its best.
-
-* paper-tc: A nice minimalist theme with a light background, good for editing
- documents on. Requires true color to look its best. Not to be confused with
- `-paper` suffixed themes.
-
-* geany: Colorscheme based on geany's default highlighting.
-
-* geany-alt-tc: Based on an alternate theme bundled with geany.
-
-* flamepoint-tc: A fire inspired, high intensity true color theme written by
- CaptainMcClellan. As with all the other `-tc` suffixed themes, it looks its
- best on a
-
-To enable one of these colorschemes just press CtrlE in micro and type
-`set colorscheme solarized`. (or whichever one you choose). You can also use
-`set colorscheme monochrome` if you'd prefer to have just the terminal's default
-foreground and background colors. Note: This provides no syntax highlighting!
-
-See `help gimmickcolors` for a list of some true colour themes that are more
-just for fun than for serious use. (Though feel free if you want!)
-
+* `gruvbox-tc`: The true color version of the gruvbox colorscheme
+* `github-tc`: The true color version of the Github colorscheme
## Creating a Colorscheme
-Micro's colorschemes are also extremely simple to create. The default ones ca
-be found
-[here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes).
+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).
+
+Custom colorschemes should be placed in the `~/.config/micro/colorschemes` directory.
-They are only about 18-30 lines in total.
+A number of custom directives are placed in a `.micro` file. Colorschemes are
+typically only 18-30 lines in total.
-Basically to create the colorscheme you need to link highlight groups with
+To create the colorscheme you need to link highlight groups with
actual colors. This is done using the `color-link` command.
For example, to highlight all comments in green, you would use the command:
* identifier.var
* preproc.shebang (The #! at the beginning of a file that tells the os what
script interpreter to use)
-* symbol.brackets ({}()[] and sometimes <>)
+* symbol.brackets (`{}()[]` and sometimes `<>`)
* 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`)
## Syntax files
-The syntax files is written in yaml-format and specify how to highlight
+The syntax files are written in yaml-format and specify how to highlight
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 int for over 100 languages now. However, there may be
+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. Good news is you can create syntax files (.micro extension), place them
+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
filetype: go
```
-#### Detect definition
+### Detect definition
Then you must provide information about how to detect the filetype:
header: "%YAML"
```
-#### Syntax rules
+### 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
rules:
- include: "css"
```
+
+## 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
+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).
projects / micro.git / blobdiff