# The Markdown++ Language Specification

#### See the general docs for general information about the language and its parser.

### Table of Contents:

- General Elements

- Sections

- Lists

- Inline Styling; Bold and Italics

- Special Characters and Comments

- HTML Embeds, Images, and Rules

## General Elements:

#### Options:

Many elements contain an `options` field, in which CSS options may be placed. All fields within a MD++ `options` section must consist of valid CSS `key:value` pairs separated by semicolons (`;`); these stylistic options will be applied to the MD++ element on which the `options` section was used.

Unless otherwise noted, all CSS attributes that may be applied to the corresponding HTML type of a given MD++ element type (see the section of the documentation for the specific element type) may be applied to that type of MD++ element.

Example: `...{options}` can be filled with `...{fill:red}`

#### Classes:

For convenience when using linked CSS stylesheets, many elements support the specification of one or more CSS classes to apply to the element. Such classes should be specified with space-separation within a `{class}` component of a MD++ element.

Unless otherwise noted, all CSS classes defined by any linked stylesheets may be applied to all relevant elements.

Example (using Bootstrap CSS): `...{class}` can be filled with `...{btn btn-primary}`

#### Blank Lines and Whitespace:

A line with no conent is interpreted as a blank line and is displayed with an HTML `br` element.

All whitespace preceeding the content of a line is ignored, and it is generally advisable to use indentation where possible to make the MD++ source clearer (although this is not required).

## Sections:

Syntax: Start the section with a `+start-section:sectionID{options}{class}` tag (`sectionID` is the HTML name and ID to apply to the new section, `options` is a standard MD++ CSS options section, and `class` is a standard MD++ class section), and end the section with a `>end-section:sectionID` tag. Both tags must be on their own lines.

Restrictions: Sections are permitted both at the root level and within other sections. Note that most MD++ content must be placed within some section. Sections are prohibited within lists and within custom HTML embeds.

Function: Creates a `div`-defined section with the given name and style, allowing for stylistic units of the produced page and direct linking (via `#section`) to the section of interest.

HTML Equivalent: The `div` element.

## Lists:

Syntax: Preceed the list with a `=start-ordered-list`/`=start-unordered-list` tag and succeed the list with a `?end-ordered-list`/`?end-unordered-list` tag, both of which must be on their own lines.

Each list item must be on one line and must begin with a `-` character for both ordered and unordered lists.

Restrictions: Lists may only be placed within existing MD++ sections at any level. List elements may contain links and custom-styled components, but not images, headers, other sections, other links, or HTML embeds. Note also that each line between open and close must begin with `-` and must be a list element (or can be a comment).

Function: Displays the textual contents of the lines between the opening and closing tags that begin with `-`.

HTML Equivalent: `ol` (ordered) or `ul` (unordered)

## Inline Styling:

##### Basic Styles:

Syntax: Wrap the text to be stylized using one of the following indicator sets:

- `*Text to Bold*` for bold text.

- `_Text to Italicize_` for italic text.

- ``The Code`` for `code`.

- `*_Text to Bold Italicize_*` for bold italic text.

Restrictions: Usable within a body text line only, and not within custom-styled text or headings. Code also cannot be combined with bold, italic, or both.

Function: Applies the specified basic style to the wrapped text.

HTML Equivalent: `b`, `i`, `code`, or `b` and `i` tags, respectively.

##### Links:

Links can be added inline within a text line with a tag of the following form: `@link:Text to Display{the-link}{class}@`; `the-link` is the http(s) link to point to and `class` specifies the CSS classes to apply to the link.

##### Custom Inline CSS:

Syntax: `@style:{css-options}[Text to Display]@` within a text line, where `css-options` is a standard MD++ CSS options section giving the CSS display options and `Text to Display` is the text to which the style is to be applied.

Restrictions: Custom-styled text may be placed only within an existing body-text line, and the contents of the stylized text may be plain-text only (no links, images, unescaped special characters, etc.).

Function: Applies the custom style specified by `css-options` to the provided text and includes it within the existing line.

HTML Equivalent: `span` with style applied.

## Special Characters and Comments:

##### Special Characters and Escape:

Syntax: Placing the escape character (`\`) before a special character (`&` , `%` , `+` , `>` , `~` , `;` , `\` , `^` , `*` , `_` , `-` , and `?` ) escapes its effect.

Restrictions: Usable within text/HTML code lines only. Note that escaping an MD++-required control character may result in an unparseable file or other errors, which may not be obvious.

Function: Prevents the parser from interpreting the succeeding character as an MD++ control character and displays it as text instead.

HTML Equivalent: None

##### Comments:

Syntax: A line beginning with the `%` character.

Restrictions: None; usable both within sections and at the global/root level.

Function: Excludes the line from the generated output; however, the line remains within the MD++ source as a descriptive comment.

HTML Equivalent: None

## HTML Embeds, Images, and Rules:

#### HTML Embeds:

Syntax: The block of embedded HTML should be on multiple lines (like standard HTML) and must be preceeded and succeeded with `~`, both on their own lines.

Restrictions: Permitted within sections only, and MD++ syntax is not supported within embedded HTML sections. Embedded HTML may also interfere with MD++ page contents.

Function: Directly includes the provided HTML within the generated page.

HTML Equivalent: None

#### Images:

Syntax: `;[Alt Text][imageID][image-url]{options}` on its own line, where `Alt Text` is the alternative text for the image, `imageID` is the HTML ID of the image, `image-url` is the full URL of the image to display, and `options` is a standard MD++ CSS options section.

Restrictions: Permitted within MD++ sections only.

Function: Displays the specified images with the CSS attributes defined in `options`.

HTML Equivalent: The `img` element.

#### Horizontal Rules:

Syntax: `:{width}` on its own line, where `width` is an integer representing what percentage of the screen's width to cover.

Restrictions: Permitted at all locations.

Function: Produces a horizontal line of fixed thickness.

HTML Equivalent: The `hr` element.