Skip to content

Commit 1f5c334

Browse files
deiningdeining
committed
User guide, LaTeX: typesetting of formulae using standard syntax
1 parent ef13c1f commit 1f5c334

File tree

2 files changed

+132
-45
lines changed

2 files changed

+132
-45
lines changed

‎userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md

Lines changed: 120 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -6,66 +6,134 @@ math: true
66
chem: true
77
---
88

9-
Docsy has built-in support for a number of diagram creation and typesetting tools you can use to add rich content to your site, including \\(\KaTeX\\), Mermaid, Diagrams.net, PlantUML, and MarkMap.
9+
Docsy has built-in support for a number of diagram creation and typesetting tools you can use to add rich content to your site, including \(\KaTeX\), Mermaid, Diagrams.net, PlantUML, and MarkMap.
1010

11-
## \\(\LaTeX\\) support with \\(\KaTeX\\)
11+
## \(\LaTeX\) support with \(\KaTeX\)
1212

13-
[\\(\LaTeX\\)](https://www.latex-project.org/) is a high-quality typesetting system for the production of technical and scientific documentation. Due to its excellent math typesetting capabilities, \\(\TeX\\) 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\\) has `pdf` as its primary output target and is not particularly well suited for producing HTML output for the Web. Fortunately, with [\\(\KaTeX\\)](https://katex.org/) there exists a fast and easy-to-use JavaScript library for \\(\TeX\\) math rendering on the web, which was integrated into the Docsy theme.
13+
[\(\LaTeX\)](https://www.latex-project.org/) is a high-quality typesetting system for the production of technical and scientific documentation. Due to its excellent math typesetting capabilities, \(\TeX\) 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\) has `pdf` as its primary output target and is not particularly well suited for producing HTML output for the Web. Fortunately, with [\(\KaTeX\)](https://katex.org/) there exists a fast and easy-to-use JavaScript library for \(\TeX\) math rendering on the web, which was integrated into the Docsy theme.
1414

15-
With \\(\KaTeX\\) support [enabled](#activating-and-configuring-katex-support) in Docsy, you can include complex mathematical formulae into your web page, either inline or centred on its own line. Since \\(\KaTeX\\) relies on server side rendering, it produces the same output regardless of your browser or your environment. Formulae can be shown either inline or in display mode:
15+
With \(\KaTeX\) support [enabled](#activating-and-configuring-katex-support) in Docsy, you can include complex mathematical formulae into your web page, either inline or centred on its own line. Since \(\KaTeX\) relies on server side rendering, it produces the same output regardless of your browser or your environment. Formulae can be shown either inline or in display mode:
1616

1717
### Inline formulae
1818

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

2121
```tex
22-
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}\\).
22+
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}\).
2323
```
2424

25-
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}\\).
25+
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}\).
2626

2727
### Formulae in display mode
2828

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

3131
````markdown
32-
The probability of getting \\(k\\) heads when flipping \\(n\\) coins is:
32+
The probability of getting \(k\) heads when flipping \(n\) coins is:
33+
\[
34+
\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
35+
\]
36+
````
37+
38+
As an alternative to the standard syntax used above, formulae can also be authored using a [GLFM math block](https://docs.gitlab.com/ee/user/markdown.html#math):
39+
40+
````markdown
41+
The probability of getting \(k\) heads when flipping \(n\) coins is:
3342
```math
3443
\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
3544
```
3645
````
46+
Both standard syntax and `math` block renders to the same formula:
3747

38-
The formula itself is written inside a [GLFM math block](https://docs.gitlab.com/ee/user/markdown.html#math). The above code fragment renders to:
39-
40-
The probability of getting \\(k\\) heads when flipping \\(n\\) coins is:
48+
The probability of getting \(k\) heads when flipping \(n\) coins is:
4149
```math
4250
\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
4351
```
4452

4553
{{% alert title="Warning" color="warning" %}}
46-
`math` code blocks are only supported as of hugo version 0.93.
47-
48-
In case of hugo version 0.92 or lower, use this code snippet to display the formula:
49-
```tex
50-
$$
51-
\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
52-
$$
53-
```
54+
`math` code blocks are supported as of hugo version 0.93, using the standard syntax is possible as of hugo version 0.122.
5455
{{% /alert %}}
5556

5657
{{% alert title="Tip" %}}
57-
This [wiki page](https://en.wikibooks.org/wiki/LaTeX/Mathematics) provides in-depth information about typesetting mathematical formulae using the \\(\LaTeX\\) typesetting system.
58+
This [wiki page](https://en.wikibooks.org/wiki/LaTeX/Mathematics) provides in-depth information about typesetting mathematical formulae using the \(\LaTeX\) typesetting system.
5859
{{% /alert %}}
5960

60-
### Activating and configuring \\(\KaTeX\\) support
61+
### \(\LaTeX\) typesetting using standard syntax
62+
63+
As of hugo v0.122, \(\LaTeX\) you can enable typesetting in Markdown using the standard syntax. To do so, you have make use of the goldmark `passthrough` extension inside your `hugo.toml`/`hugo.yaml`/`hugo.json`:
64+
65+
{{< tabpane >}}
66+
{{< tab header="Site configuration file:" disabled=true />}}
67+
{{< tab header="hugo.toml" lang="toml" >}}
68+
[markup]
69+
[markup.goldmark]
70+
[markup.goldmark.extensions]
71+
[markup.goldmark.extensions.passthrough]
72+
enable = true
73+
[markup.goldmark.extensions.passthrough.delimiters]
74+
block = [['\[', '\]'], ['$$', '$$']]
75+
inline = [['\(', '\)']]
76+
{{< /tab >}}
77+
{{< tab header="hugo.yaml" lang="yaml" >}}
78+
markup:
79+
goldmark:
80+
extensions:
81+
passthrough:
82+
enable: true
83+
delimiters:
84+
block:
85+
- - \[
86+
- \]
87+
- - $$
88+
- $$
89+
inline:
90+
- - \(
91+
- \)
92+
{{< /tab >}}
93+
{{< tab header="hugo.json" lang="json" >}}
94+
{
95+
"markup": {
96+
"goldmark": {
97+
"extensions": {
98+
"passthrough": {
99+
"delimiters": {
100+
"block": [
101+
[
102+
"\\[",
103+
"\\]"
104+
],
105+
[
106+
"$$",
107+
"$$"
108+
]
109+
],
110+
"inline": [
111+
[
112+
"\\(",
113+
"\\)"
114+
]
115+
]
116+
},
117+
"enable": true
118+
}
119+
}
120+
}
121+
}
122+
}
123+
{{< /tab >}}
124+
{{< /tabpane >}}
125+
126+
You may alter this definition according to your needs. For details, please refer to the official [hugo docs](https://gohugo.io/content-management/mathematics/#step-1).
127+
128+
### Activating and configuring \(\KaTeX\) support
61129

62130
#### Auto activation
63131

64-
As soon as you use a `math` code block on your page, support of \\(\KaTeX\\) is automatically enabled.
132+
As soon as you use a `math` code block on your page, support of \(\KaTeX\) is automatically enabled.
65133

66-
#### Manual activation (no `math` code block present or hugo 0.92 or lower)
134+
#### Manual activation (use of standard syntax, no `math` code block present)
67135

68-
If you want to use inline formulae and don't have a `math` code block present in your page which triggers auto activation, you need to manually activate \\(\KaTeX\\) support. The easiest way to do so is to add a `math` attribute to the frontmatter of your page and set it to `true`:
136+
If you want to use formulae (block or inline) and don't have a `math` code block present in your page which triggers auto activation, you need to manually activate \(\KaTeX\) support. The easiest way to do so is to add a `math` attribute to the frontmatter of your page and set it to `true`:
69137

70138
{{< tabpane >}}
71139
{{< tab header="Page front matter:" disabled=true />}}
@@ -86,7 +154,7 @@ math: true
86154
{{< /tab >}}
87155
{{< /tabpane >}}
88156

89-
If you use formulae in most of your pages, you can also enable sitewide \\(\KaTeX\\) support inside the Docsy theme. To do so update `hugo.toml`/`hugo.yaml`/`hugo.json`:
157+
If you use formulae in most of your pages, you can also enable sitewide \(\KaTeX\) support inside the Docsy theme. To do so update `hugo.toml`/`hugo.yaml`/`hugo.json`:
90158

91159
{{< tabpane >}}
92160
{{< tab header="Site configuration file:" disabled=true />}}
@@ -110,7 +178,7 @@ params:
110178
{{< /tab >}}
111179
{{< /tabpane >}}
112180

113-
Additionally, you can customize various \\(\KaTeX\\) options inside `hugo.toml`/`hugo.yaml`/`hugo.json`, if needed:
181+
Additionally, you can customize various \(\KaTeX\) options inside `hugo.toml`/`hugo.yaml`/`hugo.json`, if needed:
114182

115183
{{< tabpane >}}
116184
{{< tab header="Site configuration file:" disabled=true />}}
@@ -222,54 +290,61 @@ params:
222290
{{< /tab >}}
223291
{{< /tabpane >}}
224292

225-
For a complete list of options and their detailed description, have a look at the documentation of \\({\KaTeX}\\)'s [Rendering API options](https://katex.org/docs/autorender.html#api) and of \\({\KaTeX}\\)'s [configuration options](https://katex.org/docs/options.html).
293+
{{% alert title="Note" %}}
294+
If you define custom delimiters, please make sure they match with the delimiters defined [above](#latex-typesetting-using-standard-syntax) as passthrough extension.
295+
{{% /alert %}}
296+
297+
For a complete list of options and their detailed description, have a look at the documentation of \({\KaTeX}'s\) [Rendering API options](https://katex.org/docs/autorender.html#api) and of \({\KaTeX}'s\) [configuration options](https://katex.org/docs/options.html).
226298

227299
### Display of Chemical Equations and Physical Units
228300

229-
[mhchem](https://www.ctan.org/pkg/mhchem) is a \\(\LaTeX\\) package for typesetting chemical molecular formulae and equations. Fortunately, \\(\KaTeX\\) provides the `mhchem` [extension](https://github.com/KaTeX/KaTeX/tree/main/contrib/mhchem) that makes the `mhchem` package accessible when authoring content for the web. With `mhchem` extension [enabled](#activating-rendering-support-for-chemical-formulae), 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 a chemical equation:
301+
[mhchem](https://www.ctan.org/pkg/mhchem) is a \(\LaTeX\) package for typesetting chemical molecular formulae and equations. Fortunately, \(\KaTeX\) provides the `mhchem` [extension](https://github.com/KaTeX/KaTeX/tree/main/contrib/mhchem) that makes the `mhchem` package accessible when authoring content for the web. With `mhchem` extension [enabled](#activating-rendering-support-for-chemical-formulae), 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 a chemical equation:
230302

231303
```mhchem
232-
*Precipitation of barium sulfate:* \\(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\\)
304+
*Precipitation of barium sulfate:* \(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\)
233305
```
234306

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

237-
More complex equations need to be displayed on their own line. Use a code block adorned with `chem` in order to achieve this:
309+
More complex equations can be displayed on their own line using the block delimiters defined:
238310

239311
````markdown
240-
```chem
312+
\[
241313
\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-}}$}
242-
```
314+
\]
243315
````
244316

317+
Alternatively, you can use a code block adorned with `chem` in order to render the equation:
318+
319+
````markdown
245320
```chem
246321
\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-}}$}
247322
```
323+
````
248324

249-
{{% alert title="Warning" color="warning" %}}
250-
`chem` code blocks are only supported as of hugo version 0.93.
325+
Both standard syntax and `chem` block renders to the same equation:
251326

252-
In case of hugo version 0.92 or lower, use this code snippet to display the formula:
253-
```tex
254-
$$
327+
\[
255328
\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-}}$}
256-
$$
257-
```
329+
\]
330+
331+
{{% alert title="Warning" color="warning" %}}
332+
`chem` code blocks are supported as of hugo version 0.93, using the standard syntax is possible as of hugo version 0.122.
258333
{{% /alert %}}
259334

260335
{{% alert title="Note" %}}
261336
The [manual](https://mhchem.github.io/MathJax-mhchem/) for mchem’s input syntax provides in-depth information about typesetting chemical formulae and physical units using the `mhchem` tool.
262337
{{% /alert %}}
263338

264-
Use of `mhchem` is not limited to the authoring of chemical equations, 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:
339+
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:
265340

266341
```mhchem
267-
* Scientific number notation: \\(\pu{1.2e3 kJ}\\) or \\(\pu{1.2E3 kJ}\\) \\
268-
* Divisions: \\(\pu{123 kJ/mol}\\) or \\(\pu{123 kJ//mol}\\)
342+
* Scientific number notation: \(\pu{1.2e3 kJ}\) or \(\pu{1.2E3 kJ}\) \\
343+
* Divisions: \(\pu{123 kJ/mol}\) or \(\pu{123 kJ//mol}\)
269344
```
270345

271-
* Scientific number notation: \\(\pu{1.2e3 kJ}\\) or \\(\pu{1.2E3 kJ}\\)
272-
* Divisions: \\(\pu{123 kJ/mol}\\) or \\(\pu{123 kJ//mol}\\)
346+
* Scientific number notation: \(\pu{1.2e3 kJ}\) or \(\pu{1.2E3 kJ}\)
347+
* Divisions: \(\pu{123 kJ/mol}\) or \(\pu{123 kJ//mol}\)
273348

274349
For a complete list of options when authoring physical units, have a look at the [section](https://mhchem.github.io/MathJax-mhchem/#pu) on physical units in the `mhchem` documentation.
275350

@@ -279,7 +354,7 @@ For a complete list of options when authoring physical units, have a look at the
279354

280355
As soon as you use a `chem` code block on your page, rendering support for chemical equations is automatically enabled.
281356

282-
##### Manual activation (no `chem` code block present or hugo 0.92 or lower)
357+
##### Manual activation (use of standard syntax, no `chem` code block present)
283358

284359
If you want to use chemical formulae inline and don't have a `chem` code block present in your page which triggers auto activation, you need to manually activate rendering support for chemical formulae. The easiest way to do so is to add a `chem` attribute to the frontmatter of your page and set it to `true`:
285360

‎userguide/hugo.yaml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,18 @@ markup:
5252
- \)
5353
renderer:
5454
unsafe: true
55+
extensions:
56+
passthrough:
57+
enable: true
58+
delimiters:
59+
block:
60+
- - \[
61+
- \]
62+
- - $$
63+
- $$
64+
inline:
65+
- - \(
66+
- \)
5567
highlight:
5668
noClasses: false # Required for dark-mode
5769

0 commit comments

Comments
 (0)