KaTeX Extension

Rendering math is enabled using KaTeX. The extension adds the ability to create numbered equations as well as reference the equations with traditional shortcut syntax: e.g., [eq-heat].

Table 1: Available configure options for the KatexExtension object.

KeyDefaultDescription
activeTrueToggle for disabling the extension. This only changes the initial active state, use setActive to control at runtime.
prefixEq.The prefix to used when referring to an equation by the \\label content.
macrosNoneMacro definitions to apply to equations.

Block Equations

Numbered and non-numbered equations are defined using the \begin{equation} and \end{equation} environment common to LaTeX mathematics, as shown in Example 1.

Example 1: Example of syntax for creating numbered equations with KaTeX.

!equation id=line-eq
y = a\cdot x + b

To include a non-numbered equation, simply exclude the "id" in the command, as shown in Example 2.

Example 2: Example of syntax for creating non-numbered equations with Katex.

!equation
c^2 = a^2 + b^2

It is possible to reference numbered block equations. First, the equation must contain an "id". Then within the text this label can be used within a shortcut link, e.g. [my-eq] (see Shortcut links).

Equation References

Example 3 provides a complete example of creating and referencing an equation. The prefix is dictated by the extension prefix configuration option (see Table 1).

Example 3: Example that references a labeled, numbered block equation.

[!eqref](eq-label) is a famous equation.

!equation id=eq-label
E = mc^2

It is possible to reference equations on other pages. If the page containing the referenced equation has a top-level heading then that will be used. The filename of the page is used when no heading exists.

Example 4: Example that references a labeled, numbered block equation from another page.

[!eqref](katex.md#eq-label) is a famous equation.

Inline Equations

Inline equations can use traditional LaTeX syntax, i.e., the content is wrapped in single $ or the inline !eq command, as shown in Example 5.

Example 5: Example of an inline LaTeX equation.

This $y=2\phi$ is inline and so it this: [!eq](\phi=\beta^2).

Macros

It is possible to define macros within extension configuration. This is done using the 'macros' configuration parameter (see Table 1). For example, the main configuration file for contains the following allowing for equation in Example 6 to be defined.

MooseDocs.extensions.katex:
    macros: !include modules/doc/katex_macros.yml
(contrib/moose/modules/doc/config.yml)

Example 6: Example use of a macro defined in configuration file.

$\pd{T}{t} = c$