Core Extension

The core extension is the portion of the MooseDocs language that is designed to mimic markdown syntax. MooseDown is far more strict than traditional markdown implementations. Therefore, the following sections should be read in detail to understand the supported syntax, especially if you are familiar with more general markdown formats.

Syntax is separated into two groups: block and inline. Block content is made of items that make, as the name suggests, blocks of text. Blocks of text include items such as code snippets, quotations, and paragraphs themselves. On the other hand, inline items are those that are applicable to small portions of text (e.g., words). Bold and italics are two examples of inline items.

note:MooseDown is a restricted version of markdown.

To unify content and to create a fast parser a strict, limited set of markdown is being used to define the MooseDocs syntax. The following sections detail the syntax that comprise the syntax.

Settings

In general, most block level syntax and some inline syntax accepts key-value pair settings. Where the settings appear within the syntax varies and is detailed in the following sections. Example 1 show how the settings are specified in Links. However, the settings are applied in a uniform manner. Foremost, the key and value are separated by an equal (=) sign without spaces surrounding. The value may contain spaces, with the space after the equal sign being the exception.

If syntax has settings the key-value pairs, the default value (if any), and a short description will be provided in a table. For example, Table 1 lists the available settings for the fenced code blocks discussed in the Code section.

Example 1: Example use of settings within Links, settings are key-value pairs that are specified with a separating equal sign (no spaces exist on either side).

[google](https://www.google.com style=color:teal;)

google

Block Syntax

Block level content, as the name suggest, are blocks of text. In all cases, blocks must begin and end with empty lines (with the exception of the start and end of the file). This restriction allows for special characters such as the hash (#) to be used at the start of a line without conflicting with heading creation (see Headings). Additionally, this allows content and settings to be spanned across multiple lines.

Code

Code blocks or snippets—as shown in Example 2—are created by enclosing the code for display in triple back-ticks (`), this is commonly referred to as fenced code blocks. Two requirements exist for creating the code blocks:

  1. the back-ticks must be proceeded by an empty line and

  2. the back-ticks must start at the beginning of a line.

Settings for code blocks are defined by key-value pairings that follow the back-ticks; Table 1 lists the available settings for code blocks.

Example 2: Basic fenced code block.

```language=bash
export METHOD=opt
```

export METHOD=opt

Table 1: Available settings for fenced code blocks.

KeyDefaultDescription
styleThe style settings that are passed to rendered HTML tag.
classThe class settings to be passed to rendered HTML tag.
languagetextThe code language to use for highlighting.
idThe class settings to be passed to the rendered tag.

Quotations

Quotation blocks are created by starting a line with the > character, with a single trailing space as shown in Example 3. Then each additional line that belongs within the quotation must also begin with a > character. Within the quotations any valid markdown is acceptable, as shown in Example 4.

Example 3: Basic block quote.

> This is a quotation.

This is a quotation.

Example 4: Nested content in block quotes.

> Quotations begin with the `<` character and may
> contain any valid markdown content, include quotes and code as shown here.
>
> > This begins another quotation, which also contains a fenced code block.
> >
> > ```language=python
> > for i in range(10):
> >   print i
> > ```
>
> Since quotations are block content they must end with an empty line,
> therefore the nested quote above must contain an empty line.

Quotations begin with the < character and may contain any valid markdown content, include quotes and code as shown here.

This begins another quotation, which also contains a fenced code block.


for i in range(10):
  print i

Since quotations are block content they must end with an empty line, therefore the nested quote above must contain an empty line.

Headings

Headings can range from level one to six and are specified using the hash (#) character, where the number of hashes indicate the heading level (see core.html#heading-basic-example). The following is required to define a heading:

  1. the hash(es) must be followed by a single space,

  2. the hash(es) must not be proceeded by a space.

Settings, as listed in Example 6, are be applied after the heading title text and as shown in Example 7 headings may also span multiple lines.

Example 5: Basic use of all six heading levels.

# Level One

## Level Two

### Level Three

#### Level Four

##### Level Five

###### Level Six

Level One

Level Two

Level Three

Level Four

Level Five
Level Six

Example 6: Use of settings within heading.

## Level Two style=font-size:75pt;color:red; id=level-two

Level Two

Example 7: Use of settings within heading.

## A Heading May Span

A Heading May Span

Multiple Lines (this is useful if they are really long) style=font-size:15pt id=level-two

Table 2: Available settings for headings.

KeyDefaultDescription
styleThe style settings that are passed to rendered HTML tag.
classThe class settings to be passed to rendered HTML tag.
idThe class settings to be passed to the rendered tag.

Unordered List

Unordered list items in MooseDown must begin with a dash (-), as shown below in Example 8. As with any block item, a list must be proceeded and followed by an empty line. However, lists have additional behavior that allow for nested content to be included.

  1. An empty line will not stop the list if the following line begins with another list marker (i.e., -), in this case the list continues.

  2. An empty line followed by a non-list marker—everything except a hyphen—will stop the list. Otherwise, a list will stop if two empty lines are encountered, otherwise it will continue to add items to the current list.

List items may contain lists, code, or any other markdown content and the item content may span many lines. The continuation is specified by indenting the content to be included within the item by two spaces, as shown in Example 9.

Example 8: Unordered list basic syntax.

- Item 1
- Item 2
  • Item 1

  • Item 2

Example 9: Lists can contain other markdown content.

- Item with code
  Content can be contained within a list, all valid MooseDown syntax can be used.

  ```
  int combo = 12345;
  ```

- Another item
  • Item with code Content can be contained within a list, all valid MooseDown syntax can be used.

    
    int combo = 12345;
    

  • Another item

  • Foo

    
    bar
    

As mentioned above, lists can contain lists, which can contain lists, etc. A sub-list, which is a list in a list, is created by creating by indenting with at the level of the list item which is should contained. Since lists are block items, it must be begin and end with empty lines. And, since this is a list it also follows the aforementioned rules for list continuation. Example 10 demonstrates the syntax for creating nested lists.

Example 10: Nested unordered lists.

- A
- B

  - B.1
  - B.2

    - B.2.1
    - B.2.2

  - B.3

    - B.3.1

      - B 3.1.1

    - B.3.2

  - B.4

- D
  • A

  • B

    • B.1

    • B.2

      • B.2.1

      • B.2.2

    • B.3

      • B.3.1

        • B 3.1.1

      • B.3.2

    • B.4

  • D

Ordered List

A numbered list work nearly identical to unordered lists (see Unordered List), but start with a numbered followed by a period and a single space. The number used for the first item in the list will be the number used for the start of the list, see Example 11.

Example 11: Example of ordered lists with a starting number and a second with nested content.

42. Foo
1. Bar


1. Another list that contains nested content.

   1. Ordered lists can be nested and contain markdown.

      ```
      code
      ```

  1. Foo

  2. Bar

  1. Another list that contains nested content.

    1. Ordered lists can be nested and contain markdown.

      
      code
      

Shortcuts

It is possible to define shortcuts for use within your document via a shortcut link. The shortcuts are defined using traditional markdown syntax as in Shortcut links. However, these are block items, so to maintain consistent behavior they must be surrounded by blank lines.

Example 12: Markdown shortcut definition.

You can create shortcuts to common items: [foo].

[foo]: bar

You can create shortcuts to common items: foo.

Inline Content

Inline content comprises of formatting, as the name suggest, that occurs within lines of text. Examples include inline code and text formatting such as bold.

Monospace (Inline Code)

Monospaced text is specified by encasing the text with single back-ticks, the content within the back-ticks is reproduced verbatim, thus allowing for MooseDocs syntax to be enclosed within the back-ticks, as in Example 13.

Example 13: Example of monospaced text.

The following MooseDocs `[google]` will show verbatim because it
is enclosed within back-ticks, without the back-ticks [google] creates a link.

[google]: https://www.google.com

The following MooseDocs [google] will show verbatim because it is enclosed within back-ticks, without the back-ticks google creates a link.

Text Formatting

Inline text formatting differs in MooseDocs from traditional markdown in many ways, the reasons for the differences include avoiding reusing the same symbol (i.e., *) for multiple formats, making the syntax suitable to simple parsing of multiline regions, and to support a wide range of formats.

For all formats the starting character must be immediately followed by a non-whitespace character. The starting character must alwo be proceeded by a whitespace, except in the case of the super and subscript which must be proceecded by a non-whitespace character. The ending character must be immediately proceeded by a non-whitespace character. The following table lists the available formats with start and end characters.

NameCharacterMooseDownResult (HTML)
Underline==underline=underline
Strong++strong+strong
Emphasis**emphasis*emphasis
Strikethrough~~strikethrough~strikethrough
Superscript^foo^bar^foobar
Subscript@foo@bar@foobar

The formatting can be arbitrarily nested and span multiple lines within the same paragraph, thus as shown in Example 14, complicated and compound formatting of text is possible.

Example 14: Example inline text formatting in MooseDocs

Yo, dawg I heard you like formatting, so I created =underline
formatted text that contains text with ~stikethrough that
contains +bold formatting with *emphasis that has some^superscript
text with a@subscript@^*+~=, I hope you like it.

Yo, dawg I heard you like formatting, so I created underline formatted text that contains text with stikethrough that contains bold formatting with emphasis that has somesuperscript text with asubscript, I hope you like it.

MooseDocs uses traditional markdown syntax for links; however, it also supports settings within the link (see Example 1). The settings are the expected key-value pairings common to much of the MooseDocs syntax. The available settings for links is include in Table 3.

Links to shortcuts use the typical markdown syntax of a key enclosed in square brackets ([key]), where the key references a shortcut, which are defined as detailed in the Shortcuts section, refer to core.html#shortcut-example for a demonstration of shortcut and shortcut link use.

In addition to linking to Shortcuts created directly, the same syntax is used to reference headings that have an "id" setting applied, see Example 15. When used in this fashion the heading text directly replaces the shortcut link and a link to the heading is created.

Punctuation

When rendering HTML, MooseDocs converts the following punctuation to the correct symbols, the table below lists the conversions that are performed.

MooseDocsHTML
--&ndash
---&mdash