Add support for math equations in markdown
Summary
An Enterprise Data Team FY25-Q3 OKR was to define a metic for determining dbt model efficiency. This resulted in the derivation of several formula that need to be documented. While formatted equation rendering can be used in GitLab issues it was found to not be supported in the handbook. Text descriptions of the calculations are also included but as the formula get mode complicated a visual representation of the formula expands clarity and transparency.
Relevant logs and/or screenshots and/or links to examples
Possible solutions
Configure the theme to support math equation rendering following the Hugo documentation:
Other solutions considered but found to be limited.
Using MathML directly in the markdown:
- The result would be HTML in the markdown
- Requires knowledge of specific HTML formatting and symbols or a conversion tool (such as this)
- Even code from conversion tools may still require manual formatting
- Requires large amounts of code, each character or symbol needs html tags
- It is expected that editors of the handbook are not all well versed in editing HTML
Code Examples
Sample formula:
With Hugo configuration
$$E_p = if\ p\ >\ 1\ then\ min\{\frac{p-S_p}p,0\}\ else\ 1$$
Direct MathML HTML (spaces not preserved needs more formatting)
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" class="tml-display" style="display:block math;">
<mrow>
<msub>
<mi>E</mi>
<mi>p</mi>
</msub>
<mo>=</mo>
<mi>i</mi>
<mi>f</mi>
<mtext>
</mtext>
<mi>p</mi>
<mtext>
</mtext>
<mo>></mo>
<mtext>
</mtext>
<mn>1 </mn>
<mtext>
</mtext>
<mi>t</mi>
<mi>h</mi>
<mi>e</mi>
<mi>n</mi>
<mtext>
</mtext>
<mi>m</mi>
<mi>i</mi>
<mi>n</mi>
<mo form="prefix" stretchy="false">{</mo>
<mfrac>
<mrow>
<mi>p</mi>
<mo>−</mo>
<msub>
<mi>S</mi>
<mi>p</mi>
</msub>
</mrow>
<mi>p</mi>
</mfrac>
<mo separator="true">,</mo>
<mn>0</mn>
<mo form="postfix" stretchy="false">}</mo>
<mtext>
</mtext>
<mi>e</mi>
<mi>l</mi>
<mi>s</mi>
<mi>e</mi>
<mtext>
</mtext>
<mn>1</mn>
</mrow>
</math>
Using an SVG of the equation in the markdown:
- Requires a conversion tool (such as this)
- May require editing of the output svg code for proper formatting and scaling for inline or block usage