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".

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

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

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