MooseDocs Configuration
In order to use the MooseDocs build
command, one or more configuration files are required. By default the moosedocs.py
script looks for any file in the same directory as itself with a name that ends with "config.yml" (the --config
option can be used to specify the files directly). As the extension suggests, these must be YAML files. The configurations must each contain a Content
section, and optionally the additional sections described here to fine-tune your MooseDocs build.
Content
The content section is typically a list of directories that contain the markdown content that is desired to be rendered to HTML, as shown below. It is possible to use environment variables within the list. In particular, MOOSE_DIR
and ROOT_DIR
are always available, where ROOT_DIR
is the directory of your application.
Content:
- doc/content
- ${MOOSE_DIR}/framework/doc/content
The path may also include *
and **
wildcards. The *
wildcard will match any single directory or filename. For example, doc/content/*/minimal
will include all sub-directories of the content directory that contain a minimal
directory. The **
wildcard allows for arbitrary levels of nesting. For example doc/content/**/minimal
will include the minimal
directory for any directory below the content directory, regardless of depth.
Content Across Multiple Configurations
For the case of multiple configuration files, redundant content is not permitted. That is, any two configurations may not specify the same file of any type—directories are the only exception. The content of each is added to a shared pool so the complete, combined list of files will be available to all translators. Importantly, the respective configurations of content files will be honored during translation allowing different pages to use different readers, renderers, executioners, and extensions, which provides an extraordinary amount of flexibility about how your website is built.
As a good example of how to resolve content conflicts, consider the main MOOSE website along with the MOOSE Workshop. It is possible to build the main site configuration by itself by running the following commands:
cd modules/doc
./moosedocs.py build --config config.yml
Or the workshop configuration by
cd tutorials/darcy_thermo_mech/doc
./moosedocs.py build
However, these two configurations specify some of the same content. Thus, we made use of the YAML !include
syntax to create a separate workshop configuration specialized for a combined build and it is shown in Listing 1. In this file, we made sure to not add any files already added by the main site configuration, which left only the actual workshop pages. All of the media, bibliographies, JavaScript, etc., that it needs will still be available in the combined build. Then the configurations of the Executioner, Renderer, and Extensions were simply imported from the original file.
Content:
workshop:
root_dir: !include tutorials/darcy_thermo_mech/doc/config.yml Content workshop root_dir
content:
- workshop/**
Executioner: !include tutorials/darcy_thermo_mech/doc/config.yml Executioner
Renderer: !include tutorials/darcy_thermo_mech/doc/config.yml Renderer
Extensions: !include tutorials/darcy_thermo_mech/doc/config.yml Extensions
(modules/doc/workshop_config.yml)If you find yourself creating autolinks across pages from different configurations and you are concerned about them failing when only building one of those configurations, consider using the alternative
setting (see the AutoLink Extension page for more information).
Advanced Content
There is also a more advanced interface for the content, but it is required to explain how these directories are used. When building content all relevant files (e.g., markdown) are extracted from the supplied list of directories into a set, with the path relative to the supplied directory. This unique set of files is then copied to the destination directory of the build, with markdown files being rendered to html first. For example, the following illustrates how the multiple source files are combined in the destination directory.
doc/content/index.md -> ${HOME}/.local/share/moose/site/index.html
${MOOSE_DIR}/framework/doc/content/utilities/index.md -> ${HOME}/.local/share/moose/site/utilties/index.md
In the advanced mode the root location can be specified for each location, in this case the content configuration section contains a dictionary of dictionaries as shown below. The top-level key is an arbitrary name, the second level has two keys available: "root_dir" and "content". The root_dir is the directory to include and "content" is a list of folders and/or files within the root_dir to consider.
Content:
app:
root_dir: doc/content
framework:
root_dir: ${MOOSE_DIR}/framework/doc/content/utilities
content:
- MooseDocs
Given the above configuration, the files within the MooseDocs folder are now included directly within the destination folder (i.e., the "utilities" directory is removed) as shown below.
doc/content/index.md -> ${HOME}/.local/share/moose/site/index.html
${MOOSE_DIR}/framework/doc/content/utilities/MooseDocs/setup.md -> ${HOME}/.local/share/moose/site/MooseDocs/setup.md
Extensions
The Extensions section is used to enable non-default or custom extensions as well as change the configuration for existing extensions. The list of default extensions is shown in Listing 2. For example, the following snippet changes the settings for the Common Extension extension. Note, the first level key name ("globals") is arbitrary and the "type" key name under that is required. The value matches with the python package loaded, as in Listing 2.
Extensions:
globals:
type: MooseDocs.extensions.common
shortcuts: !include framework/doc/globals.yml
The various extensions as well as links to the documentation for each extension, which includes the available configuration options, is found on the specification page.
DEFAULT_EXTENSIONS = ['MooseDocs.extensions.core',
'MooseDocs.extensions.shortcut',
'MooseDocs.extensions.floats',
'MooseDocs.extensions.command',
'MooseDocs.extensions.include',
'MooseDocs.extensions.style',
'MooseDocs.extensions.media',
'MooseDocs.extensions.listing',
'MooseDocs.extensions.table',
'MooseDocs.extensions.autolink',
'MooseDocs.extensions.devel',
'MooseDocs.extensions.package',
'MooseDocs.extensions.alert',
'MooseDocs.extensions.katex',
'MooseDocs.extensions.appsyntax',
'MooseDocs.extensions.bibtex',
'MooseDocs.extensions.common',
'MooseDocs.extensions.layout',
'MooseDocs.extensions.config',
'MooseDocs.extensions.materialicon',
'MooseDocs.extensions.acronym',
'MooseDocs.extensions.content',
'MooseDocs.extensions.graph',
'MooseDocs.extensions.heading',
'MooseDocs.extensions.gallery',
'MooseDocs.extensions.navigation',
'MooseDocs.extensions.template',
'MooseDocs.extensions.comment',
'MooseDocs.extensions.special',
'MooseDocs.extensions.ifelse',
'MooseDocs.extensions.pysyntax',
'MooseDocs.extensions.modal',
'MooseDocs.extensions.datetime',
'MooseDocs.extensions.algorithm',
'MooseDocs.extensions.gitutils']
(python/MooseDocs/common/load_config.py)Renderer
The Renderer section allows for the type of renderer to be selected, the default is the MaterializeRenderer
. This is the only complete renderer object and it does have many available options, please refer to the source code for the available options. An example Renderer section is shown below.
Renderer:
type: MooseDocs.base.MaterializeRenderer
favicon: media/moose.ico
(modules/doc/config.yml)Reader
The Reader section allows the reader object to be defined, by default the MarkdownReader
objects is used. Currently, this is the only type of reader and there are no configuration options, so this section is not necessary.