返回 marp
math-typesetting.md
根目录 / website / docs / guide / math-typesetting.md
1 # Math typesetting
2
3 [Many Markdown tools support math rendering](https://github.com/cben/mathdown/wiki/math-in-markdown). We have [Pandoc's Markdown style](https://pandoc.org/MANUAL.html#math) math typesetting support. Marp renders math using [MathJax] (or, alternatively, [KaTeX]).
4
5 [katex]: https://katex.org/
6 [mathjax]: https://www.mathjax.org/
7
8 ### Inline math
9
10 Surround your formula with a single dollar character `$...$`.
11
12 ```markdown
13 Render inline math such as $ax^2+bc+c$.
14 ```
15
16 ### Math block
17
18 Surround the formula with double dollar characters `$$...$$`. Math in the block element will render with centering. The math in the block element will also scale down automatically if it is sticking out from the horizontal border of the slide (only in supported themes).
19
20 <!-- prettier-ignore-start -->
21
22 ```markdown
23 $$ I_{xx}=\int\int_Ry^2f(x,y)\cdot{}dydx $$
24
25 $$
26 f(x) =
27 \int_{-\infty}^\infty
28 \hat f(\xi)\,e^{2 \pi i \xi x}
29 \,d\xi
30 $$
31 ```
32 <!-- prettier-ignore-end -->
33
34 ```markdown:marp
35 ## Inline math
36
37 Render inline math such as $ax^2+bc+c$.
38
39 ## Math block
40
41 $$ I_{xx}=\int\int_Ry^2f(x,y)\cdot{}dydx $$
42
43 $$
44 f(x) =
45 \int_{-\infty}^\infty
46 \hat f(\xi)\,e^{2 \pi i \xi x}
47 \,d\xi
48 $$
49 ```
50
51 > This feature is inherited from [Marp Core](https://github.com/marp-team/marp-core).
52
53 ## [MathJax]
54
55 By default, Marp uses **[MathJax]** to render math typesetting.
56
57 ### Declare to use MathJax
58
59 Set [`math` global directive](/docs/guide/directives#global-directives) as `mathjax`.
60
61 ```markdown
62 ---
63 math: mathjax
64 ---
65
66 Render inline math such as $ax^2+bc+c$.
67 ```
68
69 For the determined rendering of slide, we recommend always to declare math library to use in the slide. No definition of math directive may bring inconsistent rendering result depending on the version of Marp Core.
70
71 ## [KaTeX]
72
73 **[KaTeX]** is an alternative library to render math typesettings in Marp, and it was former default.
74
75 By defining `math` global directive as `katex`, you can continue to render math with KaTeX.
76
77 ### Enable KaTeX
78
79 Set [`math` global directive](/docs/guide/directives#global-directives) as `katex`.
80
81 ```markdown
82 ---
83 math: katex
84 ---
85
86 Render inline math such as $ax^2+bc+c$.
87 ```
88
89 ### Define global macro
90
91 In KaTeX rendering, macros defined by `\def` will persist only in a local math environment. To persist defined macro for subsequent math environments in Markdown, use `\gdef` (`\global\def`) instead.
92
93 ```markdown
94 $$
95 % macroA can use only in this math block.
96 \def\macroA{{\color{red}A}}
97
98 % macroB has defined globally so you can use it after here.
99 \gdef\macroB{{\color{blue}B}}
100
101 \macroA + \macroB
102 $$
103
104 ---
105
106 $$
107 % macroA cannot use, but macroB can.
108 \macroA + \macroB
109 $$
110 ```
111
112 [See the detail of supported macro functions in KaTeX documentation](https://katex.org/docs/supported.html#macros).
113
114 ### Configuration
115
116 KaTeX options can be configured in [Marp Core's constructor option](https://github.com/marp-team/marp-core#constructor-options). You should use [Marp CLI](https://github.com/marp-team/marp-cli) if you need to set a custom configuration in Marp conversion.
117
118 ```javascript
119 // marp.config.js
120 module.exports = {
121 options: {
122 math: {
123 lib: 'katex',
124 katexFontPath: 'https://example.com/assets/katex-fonts/'
125 katexOption: {
126 errorColor: '#ff0000',
127 macros: {
128 '\\RR': '\\mathbb{R}',
129 },
130 },
131 },
132 },
133 }
134 ```
135
136 ```bash
137 marp -c marp.config.js marp-math.md
138 ```
139
140 [See the details of KaTeX option in the documentation.](https://katex.org/docs/options.html)
141
142 ### mhchem extension
143
144 [mhchem](https://mhchem.github.io/MathJax-mhchem/) is an extension for writing chemical equations. To enable mhchem in Marp, you should use a Marp CLI configuration file and follow [a guide of KaTeX for Node.js](https://katex.org/docs/node.html#using-mhchem-extension).
145
146 ```javascript
147 // marp.config.js
148 const katex = require('katex')
149 require('katex/dist/contrib/mhchem.js') // modify katex module
150 ```
151
152 ```bash
153 marp -c marp.config.js marp-mhchem.md
154 ```
155
156 A common mistake is [using a client-side `<script>` to load the extension](https://github.com/KaTeX/KaTeX/tree/master/contrib/mhchem#usage). _This will not work because Marp's rendering will be completed within Node.js, not the browser._ See also: [marp-team/marp#99](https://github.com/marp-team/marp/discussions/99)
157
158 ### Known issues for KaTeX rendering
159
160 - KaTeX rendering requires fetching Web Fonts from [jsDelivr](https://www.jsdelivr.com/) CDN. If you are in offline or the limited network by proxy, the slide may not render math.
161 - Safari does not shrink down the big math block rendered by KaTeX. ([marp-team/marp-core#159](https://github.com/marp-team/marp-core/issues/159))
162 - Rendering of `\tag{}` is incompatible with the math block. ([marp-team/marp-core#236](https://github.com/marp-team/marp-core/issues/236))
163
163 lines MARKDOWN