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.
| Key | Default | Description |
|---|---|---|
| style | None | The style settings that are passed to rendered HTML tag. |
| class | None | The class settings to be passed to rendered HTML tag. |
| id | None | The class settings to be passed to the rendered tag. |
| prepend | None | Text to include prior to each line of the included text. |
| append | Text to include after each line of the included text. | |
| header | None | Text to include prior to the included text. |
| header-newlines | 1 | The number of newlines after the header. |
| footer | Text to include after the included text. | |
| footer-newlines | 1 | The number of newlines before the footer. |
| indent | 0 | The level of indenting to apply to the included text. |
| strip-header | True | When True the MOOSE header is removed for display. |
| fix-moose-header | True | In C/h files within MOOSE the '//*' is used for the header at the top. This breaks the highlighting, this option removes these and replaces them with '//'. |
| strip-extra-newlines | True | Removes extraneous new lines from the text. |
| strip-leading-whitespace | False | When True leading white-space is removed from the included text. |
| line | None | A portion of text that unique identifies a single line to include. |
| re | None | Extract content via a regex, if the 'content' group exists it is used as the desired content; if 'remove' group exists it is extracted; otherwise group 0 is used for the content. |
| re-flags | re.M|re.S|re.U | Python re flags. |
| start | None | A portion of text that unique identifies the starting location for including text, if not provided the beginning of the file is utilized. |
| end | None | A 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. |
| include-start | True | When False the text captured by the 'start' setting is excluded in the displayed text. |
| include-end | False | When True the text captured by the 'end' setting is included in the displayed text. |
| replace | None | List of replacement string pairs: ['foo','bar', 'boom','baam'] replaces 'foo' with 'bar' and 'boom' with 'baam'. |
| optional | False | Toggle the include as optional when the file doesn't exist. |
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 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.
See the warning in Using a Template for a caution about including text that includes template key/value pairs.