Include Extension

A primary driver behind developing the MooseDocs system was to create a single source for all documentation and allow the same piece of text to be reused in multiple locations and in multiple formats. Therefore, it is possible to include markdown within markdown using the !include command. The available setting for the !include command is given in Table 1.

Table 1: Settings for the !include command.

KeyDefaultDescription
strip-headerTrueWhen True the MOOSE header is removed for display.
strip-extra-newlinesTrueRemoves extraneous new lines from the text.
suffixText to include after each line of the included text.
footer-newlines1The number of newlines before the footer.
re-flagsre.M|re.S|re.UPython re flags.
strip-leading-whitespaceFalseWhen True leading white-space is removed from the included text.
header-newlines1The number of newlines after the header.
headerNoneText to include prior to the included text.
prefixNoneText to include prior to each line of the included text.
include-endFalseWhen True the texted captured by the 'end' setting is included in the displayed text.
endNoneA portion of text that unique identifies the ending location for including text, if not provided the end of the file is used. By default this line is not included in the display.
lineNoneA portion of text that unique identifies a single line to include.
classThe class settings to be passed to rendered HTML tag.
styleThe style settings that are passed to rendered HTML tag.
indent0The level of indenting to apply to the included text.
footerText to include after the included text.
idThe class settings to be passed to the rendered tag.
reNoneExtract content via a regex, if the 'content' group exists it is used as the desired content, otherwise group 0 is used.
fix-moose-headerTrueIn C/h files within MOOSE the '//*' is used for the header at the top. This breaks the higlighting, this option removes these and replaces them with '//'.
startNoneA portion of text that unique identifies the starting location for including text, if not provided the beginning of the file is utilized.
include-startTrueWhen False the texted captured by the 'start' setting is excluded in the displayed text.

Example 1 uses the include command to import the complete content of another file and Example 2 imports a portion of a file using the "re" setting.

Example 1: Example use of the !include command to import a complete file.

!include /include_example.md

This content exists within the "include_example.md" file. Is it.

Example 2: Example use of the !include command to import a portion of another file.

!include /core.md re=(?P<content>^The core.*?)^Syntax

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.