# Authoring mathematical formulae | David Young Blog
Cleanwhite theme now has built-in support for authoring mathematical or chemical equations

## Authoring mathematical and chemical equations

Cleanwhite theme now has built-in KaTeX\KaTeXKATE​X support, so that you can easily include complex mathematical formulae into your web page, either inline or centred on its own line. The theme uses Hugo’s embedded instance of the KaTeX display engine to render mathematical markup to HTML at build time. With this server side rendering of formulae, the same output is produced, regardless of your browser or your environment.

LaTeX\LaTeXLATE​X is a high-quality typesetting system for the production of technical and scientific documentation. Due to its excellent math typesetting capabilities, TeX\TeXTE​X became the de facto standard for the communication and publication of scientific documents, especially if these documents contain a lot of mathematical formulae. Designed and mostly written by Donald Knuth, the initial version was released in 1978. Dating back that far, LaTeX\LaTeXLATE​X has `pdf` as its primary output target and is not particularly well suited for producing HTML output for the Web. Fortunately, with KaTeX\KaTeXKATE​X there exists a fast and easy-to-use JavaScript library for TeX\TeXTE​X math rendering on the web, which is embedded into Hugo as of Hugo version v0.132.0.

As already mentioned above, mathematical or chemical equations can be shown either inline or in display mode:

### Inline formulae

The following code sample produces a text line with three inline formulae:

    When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c= 0\) and they are \(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\).

When a≠0 a \ne 0a=0, there are two solutions to a x 2+bx+c=0 ax^2 + bx + c= 0ax2+bx+c=0 and they are x=−b±b 2−4 ac2 a x = {-b \pm \sqrt{b^2-4ac} \over 2a}x=2a−b±b2−4ac
​​.

### Formulae in display mode

The following code sample produces an introductory text line followed by a formula numbered as `(1)` residing on its own line:

    The probability of getting \(k\) heads when flipping \(n\) coins is:
    \[
    \tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
    \]

As an alternative to the standard syntax used above, formulae can also be authored using a GLFM math block:

    The probability of getting \(k\) heads when flipping \(n\) coins is:

    ```math
    \tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
    ```

Both standard syntax and `math` block render to the same formula:

The probability of getting k kk heads when flipping n nn coins is:

P(E)=(nk)pk(1−p)n−k(1)\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}P(E)=(kn​)pk(1−p)n−k(1)

This wiki page provides in-depth information about typesetting mathematical formulae using the LaTeX\LaTeXLATE​X typesetting system.

### Activating KaTeX support

#### Enable `passthrough` extension

All you have to do is to enable and configure the goldmark `passthrough` extension inside your `hugo.toml`/`hugo.yaml`/`hugo.json`. You may want to edit the definition of the delimiters to meet your own needs. For details, see the official Hugo docs.

    [markup]
      [markup.goldmark]
        [markup.goldmark.extensions]
          [markup.goldmark.extensions.passthrough]
            enable = true
            [markup.goldmark.extensions.passthrough.delimiters]
              block = [['\[', '\]'], ['$$', '$$']]
              inline = [['\(', '\)']]

Internally, cleanwhite theme creates and uses Hugo’s `render-passthrough` hook when generating math equations at build-time. This hook is part of the theme, no need for any user action.

#### Media types for download of KaTeX fonts

Just for your information, no need for any action from you as user: KaTeX brings its own font files for rendering mathematical formulae. In order to enable the download of these font files locally during build time, two additional media types had to be created by adding the lines below to the `hugo.toml` configuration file of the cleanwhite theme:

    mediaTypes:
      font/woff:
        suffixes:
        - woff
      font/woff2:
        suffixes:
        - woff2

With the `passthrough` extension enabled and the media types defined, support of KaTeX\KaTeXKATE​X is automatically enabled when you author a `math` code block on your page or when you add a mathematical formula to your page using one of the passthrough delimiter pairs defined above.

### Display of Chemical Equations and Physical Units

mhchem is a LaTeX\LaTeXLATE​X package for typesetting chemical molecular formulae and equations. Fortunately, KaTeX\KaTeXKATE​X provides the `mhchem` extension that makes the `mhchem` package accessible when authoring content for the web. As of hugo version v0.144.0, the `mhchem` extension is enabled in Hugo’s embedded KaTeX instance by default, therefore you can easily include chemical equations into your page. An equation can be shown either inline or can reside on its own line. The following code sample produces a text line including an inline chemical equation:

    *Precipitation of barium sulfate:* \(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\)

Precipitation of barium sulfate: SO X4 X 2−+Ba X 2+→BaSO X4↓\ce{SO4^2- + Ba^2+ -> BaSO4 v}SOX4​X2−+BaX2+
​BaSOX4​↓

More complex equations can be displayed on their own line using the block delimiters defined:

    \[
    \tag*{(2)} \ce{Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}
    \]

Alternatively, you can use a code block adorned with `chem` in order to render the equation:

    ```chem
    \tag*{(2)} \ce{Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}
    ```

Both standard syntax and `chem` block renders to the same equation:

Zn X 2+⇌+2 H X++2 OH X−Zn(OH)X2↓amphoteric hydroxide⇌+2 H X++2 OH X−[Zn(OH)X4]X 2−tetrahydroxozincate(2) \tag*{(2)} \ce{Zn^2+ <=>[+ 2OH-][+ 2H+] $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$ <=>[+ 2OH-][+ 2H+] $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$} ZnX2++2OHX−
+2HX+​amphoteric hydroxideZn(OH)X2​↓​+2OHX−
+2HX+​tetrahydroxozincate[Zn(OH)X4​]X2−​(2)

The manual for mchem’s input syntax provides in-depth information about typesetting chemical formulae and physical units using the `mhchem` tool.

Use of `mhchem` is not limited to the authoring of chemical equations. By using the included `\pu` command, pretty looking physical units can be written with ease, too. The following code sample produces two text lines with four numbers plus their corresponding physical units:

    * Scientific number notation: \(\pu{1.2e3 kJ}\) or \(\pu{1.2E3 kJ}\) \\
    * Divisions: \(\pu{123 kJ/mol}\) or \(\pu{123 kJ//mol}\)

- Scientific number notation: 1.2⋅103 kJ\pu{1.2e3 kJ}1.2⋅103 kJ or 1.2×103 kJ\pu{1.2E3 kJ}1.2×103 kJ
- Divisions: 123 kJ/mol\pu{123 kJ/mol}123 kJ/mol or 123 kJmol\pu{123 kJ//mol}123 molkJ​

For a complete list of options when authoring physical units, have a look at the section on physical units in the `mhchem` documentation.

「真诚赞赏，手留余香」

David Young

真诚赞赏，手留余香

使用微信扫描二维码完成支付

- ← Previous Post

##### CATALOG

##### FEATURED TAGS

docker istio kubernetes microservice security service mesh tips

##### FRIENDS

- Linda的博客