MOOSE Markdown Specification (MooseDown)
The following details the MOOSE flavored markdown used for documenting MOOSE and MOOSE-based applications with the MooseDocs system.
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.
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.
|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.|
|Common 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.|
|Graph Extension||Adds plotly support for creating charts.|
|Gallery Extension||Tools for building image galleries.|
|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.|