The Syntax of PEG Markdown Highlight Stylesheets
================================================
[PEG Markdown Highlight][pmh] includes a parser for stylesheets that define how different Markdown language elements are to be highlighted. This document describes the syntax of these stylesheets.
[pmh]: http://hasseg.org/peg-markdown-highlight/
Example
-------
Here is a quick, simple example of a stylesheet:
|
# The first comment lines |
|
|
# describe the stylesheet. |
|
|
|
|
Style rule → |
editor: |
|
|
foreground: ff0000 |
|
Attribute name → |
font-family: Consolas |
← Attribute value |
|
|
|
|
EMPH: |
|
|
font-size: 14 |
|
|
font-style: bold, underlined |
|
Style Rules
-----------
A stylesheet is composed of one or more *rules*. Rules are separated from each other by **empty lines** like so:
H2:
foreground: ff0000
H3:
foreground: 00ff00
Each begins with the ***name* of the rule**, which is always on its own line, and may be one of the following:
- **`editor`**: Styles that apply to the whole document/editor
- **`editor-current-line`**: Styles that apply to the current line in the editor (i.e. the line where the caret is)
- **`editor-selection`**: Styles that apply to the selected range in the editor when the user makes a selection in the text
- A Markdown element type (like `EMPH`, `REFERENCE` or `H1`): Styles that apply to occurrences of that particular element. The supported element types are:
- **`LINK`:** Explicit link (like `[click here][ref]`)
- **`AUTO_LINK_URL`:** Implicit URL link (like ``)
- **`AUTO_LINK_EMAIL`:** Implicit email link (like ``)
- **`IMAGE`:** Image definition
- **`REFERENCE`:** Reference (like `[id]: http://www.google.com`)
- **`CODE`:** Inline code
- **`EMPH`:** Emphasized text
- **`STRONG`:** Strong text
- **`LIST_BULLET`:** Bullet for an unordered list item
- **`LIST_ENUMERATOR`:** Enumerator for an ordered list item
- **`H1`:** Header, level 1
- **`H2`:** Header, level 2
- **`H3`:** Header, level 3
- **`H4`:** Header, level 4
- **`H5`:** Header, level 5
- **`H6`:** Header, level 6
- **`BLOCKQUOTE`:** Blockquote marker
- **`VERBATIM`:** Block of code
- **`HRULE`:** Horizontal rule
- **`HTML`:** HTML tag
- **`HTML_ENTITY`:** HTML special entity definition (like `…`)
- **`HTMLBLOCK`:** Block of HTML
- **`COMMENT`:** (HTML) Comment
- **`NOTE`:** Note
- **`STRIKE`:** Strike-through
The name may be optionally followed by an assignment operator (either `:` or `=`):
H1:
foreground: ff00ff
H2 =
foreground: ff0000
H3
foreground: 00ff00
The **order of style rules is significant**; it defines the order in which different language elements should be highlighted. *(Of course applications that use PEG Markdown Highlight and the style parser may disregard this and highlight elements in whatever order they desire.)*
After the name of the rule, there can be one or more *attributes*.
Style Attributes
----------------
Attribute assignments are each on their own line, and they consist of the *name* of the attribute as well as the *value* assigned to it. An assignment operator (either `:` or `=`) separates the name from the value:
attribute-name: value
attribute-name= value
Attribute assignment lines **may be indented**.
### Attribute Names and Types
The following is a list of the names of predefined attributes, and the values they may be assigned:
- `foreground-color` *(aliases: `foreground` and `color`)*
- See the *Color Attribute Values* subsection for information about valid values for this attribute.
- `background-color` *(alias: `background`)*
- See the *Color Attribute Values* subsection for information about valid values for this attribute.
- `caret-color` *(alias: `caret`)*
- See the *Color Attribute Values* subsection for information about valid values for this attribute.
- `strike-color` *(alias: `strike`)*
- See the *Color Attribute Values* subsection for information about valid values for this attribute.
- `font-size`
- An integer value for the font size, *in points* (i.e. not in pixels). The number may have a textual suffix such as `pt`.
- If the value begins with `+` or `-`, it is considered *relative* to some base font size (as defined by the host application). For example, the value `3` defines the font size as 3 (absolute) while `+3` defines it as +3 (relative), i.e. 3 point sizes larger than the base font size.
- `font-family`
- A comma-separated list of one or more arbitrary font family names. *(It is up to the application that uses the PEG Markdown Highlight library to resolve this string to actual fonts on the system.)*
- `font-style`
- A comma-separated list of one or more of the following:
- `italic`
- `bold`
- `underlined`
Applications may also include support for any **custom attribute names and values** they desire — attributes other than the ones listed above will be included in the style parser results, with their values stored as strings.
## Color Attribute Values
Colors can be specified either in **RGB** (red, green, blue) or **ARGB** (alpha, red, green, blue) formats. In both, each component is a two-character hexadecimal value (from `00` to `FF`):
foreground: ff00ee # red = ff, green = 00, blue = ee (and implicitly, alpha = ff)
background: 99ff00ee # alpha = 99, red = ff, green = 00, blue = ee
Comments
--------
Each line in a stylesheet may have a comment. The `#` character begins a line comment that continues until the end of the line:
# this line has only this comment
H1: # this line has a style rule name and then a comment
foreground: ff0000 # this line has an attribute and then a comment