MOOSE Markdown Specification (MooseDown)

The following details the MOOSE flavored markdown used for documenting MOOSE and MOOSE-based applications with the MooseDocs system.

Motivation

As a short-hand HTML format, markdown is ubiquitous, especially among software developers. However, no standard exists and the original implementation was incomplete. Currently, there are myriad implementations—often deemed "flavors"—of Markdown. CommonMark is a proposed standard. However, this specification is syntactically loose. For example, when defining lists the spacing is can be misleading, see Example 273 and Example 268 shows that some poorly defined behavior still exists and it is stated that the associated rule "should prevent most spurious list captures," which is inadequate for a language.

Additionally, most parsers of this specification do not support custom extensions or adding them is difficulty, from a user perspective, because the parsing strategy used is complex and context dependent.

Originally, MooseDocs used the markdown python package, which worked well in the general sense. However, as the MooseDocs system matured a few short-comings were found. The main problems, with respect to MooseDocs, was the parsing speed, the lack of an AST, and the complexity of adding extensions (i.e., there are too many extension formats). The lack of an AST limited the ability to convert the supplied markdown to other formats (e.g., LaTeX).

For these reasons, among others not mentioned here, yet another markdown flavor was born. MOOSE flavored Markdown ("MooseDown"). The so called MooseDown language is designed to be strict with respect to format as well as easily extendable so that MOOSE-based applications can customize the system to meet their documentation needs. The strictness allows for a simple parsing strategy to be used and promotes uniformity among the MooseDown files.

MooseDocs Extensions

The MooseDocs systems works using extensions, thus allowing for arbitrary languages and syntax to be supported. The MooseDown language is defined using the extensions listed in the following tables. Table 1 provides a list of extensions that are useful for those writing documentation and Table 2 include extension information for developers for new extensions.

Table 1: List of extensions useful for writing "MooseDown".

Extension	Description
Core Extension	Basic markdown syntax such as code blocks, lists, and bold text.
AutoLink Extension	Automatic linking across pages within markdown.
Table Extension	Provides means for implementing tables using traditional markdown format.
KaTeX Extension	Enables use of KaTeX rendered equations.
Bibtex Extension	Enables use of BibTeX citations and bibliographies.
Panoptic Extension	Defines a means for defining global shortcut syntax.
Listing Extension	Provides commands for including source code directly from the repository.
Include Extension	Allows for markdown files to be included in other markdown files.
Alert Extension	Creates alert boxes to draw attention to content.
Media Extension	Extension for including images and movies.
AppSyntax Extension	Enables the use of MOOSE application syntax within markdown files.
Software Quality Assurance Extension	Provides tools for writing software quality documentation using templates.
Layout Extension	Provides tools for creating columns and tabs via markdown.
Acronym Extension	Provides means for defining and listing acronyms across pages.
plotly Extension	Adds plotly support for creating charts.

Table 2: List of extensions useful for writing extensions for "MooseDown".

Extension	Description
Command Extension	Basis for creating extensions that rely on commands (see AppSyntax Extension).
Float Extension	Tools for creating numbered and/or captioned content (see Media Extension).
Devel Extension	Tools for documenting MooseDocs extensions.
Package Extension	Tools for linking to MOOSE environment packages.
Contents Extension	Creates complete list of markdown pages within a directory.

Motivation
MooseDocs Extensions