PEG Markdown Highlight includes a parser for stylesheets that define how different Markdown language elements are to be highlighted. This document describes the syntax of these stylesheets.
Here is a quick, simple example of a stylesheet:
# The first comment lines | ||
# describe the stylesheet. | ||
Style rule → | editor: | |
foreground: ff0000 # red text | ← Comment | |
Attribute name → | font-family: Consolas | ← Attribute value |
EMPH: | ||
font-size: 14 | ||
font-style: bold, underlined |
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/editoreditor-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 textEMPH
, 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 <http://google.com>
)AUTO_LINK_EMAIL
: Implicit email link (like <first.last@google.com>
)IMAGE
: Image definitionREFERENCE
: Reference (like [id]: http://www.google.com
)CODE
: Inline codeEMPH
: Emphasized textSTRONG
: Strong textLIST_BULLET
: Bullet for an unordered list itemLIST_ENUMERATOR
: Enumerator for an ordered list itemH1
: Header, level 1H2
: Header, level 2H3
: Header, level 3H4
: Header, level 4H5
: Header, level 5H6
: Header, level 6BLOCKQUOTE
: Blockquote markerVERBATIM
: Block of codeHRULE
: Horizontal ruleHTML
: HTML tagHTML_ENTITY
: HTML special entity definition (like …
)HTMLBLOCK
: Block of HTMLCOMMENT
: (HTML) CommentNOTE
: NoteThe 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.
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.
The following is a list of the names of predefined attributes, and the values they may be assigned:
foreground-color
(aliases: foreground
and color
)
background-color
(alias: background
)
caret-color
(alias: caret
)
font-size
pt
.+
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
font-style
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.
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
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