346b60358d
73a01565c Remove comment shortcode documentation 0ca7ccd30 Replace usage of comment shortcode with HTML comments fe10d9899 Remove expired new-in labels 11e89dfcb [editorial] Link to proper render-hook page in relref.md 11a581c2f netlify: Hugo 0.142.0 1a4fcf7f7 Miscellaneous edits 2c7a3165f Markdown linting and cleanup 69d7a781b Replace links to glossary terms with custom render hook syntax 441752d2d Refactor glossary lookup portion of link render hook 80109a14f Fix glossary term linking for plural form cd95f0f34 Update link render hook to support glossary links 53eadb430 Remove the glossary template 1d40a7f3b Improve transform.ToMath examples 586970df2 Misc edits 6a06a8de7 Add glossary link shortcode 4171c0eb7 Improve description of masking with non-transparent images 41c8feb64 Fix example of image.Mask filter 704a81656 Add alignx option to images.Text usage example 7c03eb0cc Clarify context in example of using the try statement 56d9c9b71 Refactor glossary of terms 042a6846b Add expiry dates to deprecated methods pages 365ab345f Remove services key from instagram shortcode page b7fe31e07 Reorder options list for images.Text filter 8051ff818 Format directory names, file names, and file paths as code d09a14623 Update version refs for Hugo and Dart Sass 3bb006974 Add NODE_VERSION to Netlify config examples 3a0f2531e Fix typo 7e3198eaf Fix typo cf56452a3 Fix typo a9f51d13e Fix typo 82bfdd8c3 Fix typo a5c41a053 Fix typo abcfed7a5 Fix typo 8c1debf3a Remove outdated new-in badges 809ddf9ef Update theme 63867d56f Use warnf instead of errorf in try-catch example dee3e5f09 Update theme 9791f7057 Remove TODO from comment shortcode examples a346ca1fd Elevate embedded shortcode documentation to its own section 8fa19b50f hugoreleaser.toml => hugoreleaser.yaml 575d60345 Update docs for v0.141.0 a0a442d62 netlify: Hugo 0.141.0 6667cbcd8 Merge commit '81a7b6390036138356773c87a886679c81c524e1' f36fc013e docs: Regen CLI docs 365a47ded tpl/images: Change signature of images.QR to images.QR TEXT OPTIONS ae8f8af0a images.Text: Add "alignx" option for horizontal alignment 8f45ccca6 docs: Regen CLI docs f0e6304f4 Merge commit 'e9fbadacc3f09191e2e19f112a49777eeb8df06c' cb9bec2b2 tpl/images: Add images.QR function git-subtree-dir: docs git-subtree-split: 73a01565c5ba0774d65aa6f2384c44804fefa37d
8.6 KiB
| title | linkTitle | description | categories | keywords | menu | weight | toc | math | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Mathematics in Markdown | Mathematics | Include mathematical equations and expressions in Markdown using LaTeX markup. |
|
|
|
270 | true | true |
{{< new-in 0.122.0 >}}
Overview
Mathematical equations and expressions written in LaTeX are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as MathJax or KaTeX.
For example, with this LaTeX markup:
\[
\begin{aligned}
KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
\end{aligned}
\]
The MathJax display engine renders this:
[ \begin{aligned} KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \ JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2})) \end{aligned} ]
Equations and expressions can be displayed inline with other text, or as standalone blocks. Block presentation is also known as "display" mode.
Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different.
{{% note %}}
You can configure Hugo to render mathematical markup on the client-side using the MathJax or KaTeX display engine, or you can render the markup while building your site with the transform.ToMathfunction.
The first approach is described below.
{{% /note %}}
Setup
Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX markup.
Step 1
Enable and configure the Goldmark passthrough extension in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
{{< code-toggle file=hugo copy=true >}} [markup.goldmark.extensions.passthrough] enable = true
[markup.goldmark.extensions.passthrough.delimiters] block = '[', ']'], ['$$', '$$' inline = '(', ')'
[params] math = true {{< /code-toggle >}}
The configuration above enables mathematical rendering on every page unless you set the math parameter to false in front matter. To enable mathematical rendering as needed, set the math parameter to false in your site configuration, and set the math parameter to true in front matter. Use this parameter in your base template as shown in Step 3.
{{% note %}}
The configuration above precludes the use of the $...$ delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you will need to double-escape the $ symbol when used outside of math contexts to avoid unintended formatting.
See the inline delimiters section for details. {{% /note %}}
To disable passthrough of inline snippets, omit the inline key from the configuration:
{{< code-toggle file=hugo >}} [markup.goldmark.extensions.passthrough.delimiters] block = '[', ']'], ['$$', '$$' {{< /code-toggle >}}
You can define your own opening and closing delimiters, provided they match the delimiters that you set in Step 2.
{{< code-toggle file=hugo >}} [markup.goldmark.extensions.passthrough.delimiters] block = '@@', '@@' inline = '@', '@' {{< /code-toggle >}}
Step 2
Create a partial template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the engines section.
{{< code file=layouts/partials/math.html copy=true >}}
{{< /code >}}
The delimiters above must match the delimiters in your site configuration.
Step 3
Conditionally call the partial template from the base template.
{{< code file=layouts/_default/baseof.html >}}
<head> ... {{ if .Param "math" }} {{ partialCached "math.html" . }} {{ end }} ... </head> {{< /code >}}The example above loads the partial template if you have set the math parameter in front matter to true. If you have not set the math parameter in front matter, the conditional statement falls back to the math parameter in your site configuration.
Step 4
Include mathematical equations and expressions in Markdown using LaTeX markup.
{{< code file=content/math-examples.md copy=true >}}
This is an inline a^*=x-b^* equation.
These are block equations:
a^*=x-b^* a^*=x-b^* [ a^=x-b^ ]
These are also block equations:
a^*=x-b^* a^*=x-b^*
a^=x-b^
{{< /code >}}
If you set the math parameter to false in your site configuration, you must set the math parameter to true in front matter. For example:
{{< code-toggle file=content/math-examples.md fm=true >}} title = 'Math examples' date = 2024-01-24T18:09:49-08:00 [params] math = true {{< /code-toggle >}}
Inline delimiters
The configuration, JavaScript, and examples above use the \(...\) delimiter pair for inline equations. The $...$ delimiter pair is a common alternative, but using it may result in unintended formatting if you use the $ symbol outside of math contexts.
If you add the $...$ delimiter pair to your configuration and JavaScript, you must double-escape the $ when outside of math contexts, regardless of whether mathematical rendering is enabled on the page. For example:
A \\$5 bill _saved_ is a \\$5 bill _earned_.
{{% note %}}
If you use the $...$ delimiter pair for inline equations, and occasionally use the $ symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by this KaTeX limitation.
{{% /note %}}
Engines
MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.11.
{{% note %}}
If you use the $...$ delimiter pair for inline equations, and occasionally use the $ symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by this KaTeX limitation.
See the inline delimiters section for details. {{% /note %}}
To use KaTeX instead of MathJax, replace the partial template from Step 2 with this:
{{< code file=layouts/partials/math.html copy=true >}}
{{< /code >}}The delimiters above must match the delimiters in your site configuration.
Chemistry
Both MathJax and KaTeX provide support for chemical equations. For example:
$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}As shown in Step 2 above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX documentation.