Media Extension

The media extension provides the !media markdown command for adding images and videos. As used throughout MooseDocs content, the !media command can optionally create a numbered Float Extension by specifying the "id" setting. A caption may be include by using the "caption" setting.

The configuration options for the media extension are listed in Table 1.

Table 1: Configuration options for the media extension.

Key	Default	Description
active	True	Toggle for disabling the extension. This only changes the initial active state, use setActive to control at runtime.
prefix	Figure	The caption prefix (e.g., Fig.).

Images

The media extension supports including the standard html image extensions: png, gif, jpg, jpeg, and svg. Images are added using the !media command followed by the filename, as shown in Example 1. Table 2 includes the list of available settings for media command for images.

note

The "style" setting may be used, as in the example below, to control the placement and size of the image.

Example 1: Example of the media command with an image.

Markdown
HTML

!media large_media/framework/inl_blue.png style=width:25%;float:right;margin-left:30px;

INL is part of the U.S. Department of Energy's complex of national laboratories. The laboratory
performs work in each of the strategic goal areas of DOE: energy, national security, science and
environment. INL is the nation's leading center for nuclear energy research and development. INL is
the nation's lead laboratory for nuclear energy research, development, demonstration and deployment
and we are engaged in the mission of ensuring the nation's energy security with safe, competitive and
sustainable energy systems and unique national and homeland security capabilities.

Table 2: Settings available for images when using the media 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.
latex_src	None	Image to utilize when rendering with LaTeX
dark_src	None	Image to utilize with dark HTML theme
link	None	Anchor URL to navigate to upon being clicked
caption	None	The caption text for the float object.
prefix	None	The numbered caption label to include prior to the caption text.

Images Generated On-the-fly with Plot Scripts

There are some applications where an image may change very frequently, such as an image generated for regular assessment runs. In this case, it is undesirable to store a new image file in the application repository with each code version. Thus the media extension provides the ability to generate images on-the-fly by providing a python plot script name.

Example 2 gives an example of the python script capability, and Listing 1 displays the plot script used in the example.

Example 2: Example of how to generate a plot on-the-fly from a python script.

Markdown
HTML

!media example_plot.py
       id=example-plot
       caption=Example plot.
       style=width:50%;padding:20px;

Listing 1: Example plot script.

import os
import matplotlib.pyplot as plt
import pandas

os.chdir(os.path.dirname(os.path.realpath(__file__)))

data = pandas.read_csv('example_data.csv')

plt.xlabel("x")
plt.ylabel("y")
plt.plot(data['x'], data['y'])
plt.savefig('example_plot.png')

note:Specifying the image name.

The image name may be specified with the key image_name, e.g.,

!media example_plot.py
       image_name=some_plot.jpg
       id=example-plot
       caption=Example plot.
       style=width:50%;padding:20px;

or if not provided, the image is assumed to have the same base name as the plot script, but with the .png extension instead of .py. In Example 2, the plot script was named example_plot.py, and the image_name key was omitted, so the image name example_plot.png was assumed.

warning:Always change to the plot script's directory.

Note the line

os.chdir(os.path.dirname(os.path.realpath(__file__)))

in the example plot script, which changes the directory to the plot script's directory. Otherwise, the plot script is not necessarily run from the directory containing it, in which case the relative path to the data (e.g., CSV) file would be incorrect, leading to a file-not-found error.

Table 3 lists the available settings for the media plot script command.

Table 3: Settings available for plot scripts when using the media 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.
latex_src	None	Image to utilize when rendering with LaTeX
dark_src	None	Image to utilize with dark HTML theme
link	None	Anchor URL to navigate to upon being clicked
caption	None	The caption text for the float object.
prefix	None	The numbered caption label to include prior to the caption text.
image_name	None	Name of image created by the Python plot script, defaults to the name of the script with .png extension

Videos

Locally stored or hosted videos can be displayed using the !media syntax. This works in the same fashion as for images, but also includes some extra settings as listed in Table 4.

Figure 1: "Big Buck Bunny" is an open-source animated short.

YouTube videos can also be displayed. The embedded youtube URL is simply provided as the media, this URL must contain 'www.youtube.com' and not end with an extension. Similar to locally stored or hosted videos, extra settings are provided as listed in Table 4.

Figure 2: MOOSE training webinar given on June 9–10, 2020.

Table 4: Settings available for videos when using the media 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.
latex_src	None	Image to utilize when rendering with LaTeX
controls	True	Display the video player controls (not compatible with YouTube).
loop	False	Automatically loop the video (not compatible with YouTube).
autoplay	False	Automatically start playing the video (not compatible with YouTube).
tstart	None	Time (sec) to start video.
tstop	None	Time (sec) to stop video.
poster	None	Add a 'poster' image the the video
quicktime	None	Video to utilize Macintosh codecs (for alpha transparencies)
caption	None	The caption text for the float object.
prefix	None	The numbered caption label to include prior to the caption text.

Float Images/Videos

As is the case for many items within the MooseDocs system (i.e., Table Extension), it is possible to create numbered images that may be referenced, as shown in Example 3. The "id" and "caption" settings are available for both images and videos.

Example 3: Example image with caption and numbered prefix.

Markdown
HTML

!media large_media/framework/inl_blue.png
       id=inl-logo
       caption=The Idaho National Laboratory logo.
       style=width:50%;padding:20px;

Float Referencing

Referencing floats is possible using the !ref inline command, from both the same page and other pages:

Example 4: Example of referencing floats.

Markdown
HTML

Float from the same page: [!ref](inl-logo)

Figure from different page: [!ref](graph.md#plotly-ext-config)

Table from different page: [!ref](table.md#table-floating)

Algorithm from different page: [!ref](algorithm.md#bk)

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.

(contrib/moose/python/doc/content/python/MooseDocs/extensions/subdirectory/example_plot.py)

import os
import matplotlib.pyplot as plt
import pandas

os.chdir(os.path.dirname(os.path.realpath(__file__)))

data = pandas.read_csv('example_data.csv')

plt.xlabel("x")
plt.ylabel("y")
plt.plot(data['x'], data['y'])
plt.savefig('example_plot.png')

Images
Images Generated On - the - fly with Plot Scripts
Videos
Float Images / Videos