Skip to content

Commit c16ca98

Browse files
committed
Add demo page
1 parent 633babc commit c16ca98

29 files changed

+1108
-648
lines changed

.github/workflows/coverage-badge.yml .github/workflows/demo.yml

+7-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Coverage Badge
1+
name: Demo
22

33
on:
44
push:
@@ -33,11 +33,16 @@ jobs:
3333
- name: Build docs
3434
run: npm run test:coverage-badge
3535

36+
- name: Build pages
37+
run: |
38+
npm run demo:build
39+
cp coverage/badge.svg pages/coverage-badge.svg
40+
3641
- name: Upload static files as artifact
3742
id: deployment
3843
uses: actions/upload-pages-artifact@v3
3944
with:
40-
path: coverage/
45+
path: pages/
4146

4247
deploy:
4348
needs: build

.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ node_modules/
22
npm-debug.log
33
coverage/
44
types/
5+
pages/

.npmignore

+3
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
**/*.config.js
44
coverage/
55
test/
6+
demo/
7+
pages/
8+
scripts/

README.md

+76-86
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,37 @@
11
[![ci](https://github.com/runarberg/markdown-it-math/actions/workflows/ci.yml/badge.svg)](https://github.com/runarberg/markdown-it-math/actions/workflows/ci.yml)
2-
![Coverage](https://runarberg.github.io/markdown-it-math/badge.svg)
2+
![Coverage](https://runarberg.github.io/markdown-it-math/coverage-badge.svg)
33
[![npm](https://img.shields.io/npm/v/markdown-it-math.svg)](https://www.npmjs.com/package/markdown-it-math)
44
[![License](https://img.shields.io/npm/l/markdown-it-math)](https://github.com/runarberg/markdown-it-math/blob/main/LICENSE)
55
[![Downloads](https://img.shields.io/npm/dm/markdown-it-math)](https://npm-stat.com/charts.html?package=markdown-it-math)
66

7-
**Note:** This is a general [markdown-it][markdown-it] math plugin. It
8-
was originally designed to render [MathML][mathml]. If you intend to
9-
use [MathJax][mathjax], [markdown-it-mathjax][markdown-it-mathjax]
10-
might be a better choise.
11-
127
# markdown-it-math
138

9+
**Note** This library defaults to rendering your equation with an
10+
AsciiMath dialect. If you want to use LaTeX, follow the instructions
11+
below.
12+
1413
```md
15-
Pythagoran theorem is $a^2 + b^2 = c^2$.
14+
Pythagorean theorem is $a^2 + b^2 = c^2$.
1615

1716
Bayes theorem:
1817

1918
$$
20-
P(A | B) = (P(B | A)P(A)) / P(B)
19+
P(A | B) = (P(B | A)P(A)) / P(B) .
2120
$$
2221
```
2322

24-
```html
25-
<p>
26-
Pythagoran theorem is
27-
<math>
28-
<msup> <mi>a</mi><mn>2</mn> </msup>
29-
<mo>+</mo>
30-
<msup> <mi>b</mi><mn>2</mn> </msup>
31-
<mo>=</mo>
32-
<msup> <mi>c</mi><mn>2</mn> </msup> </math
33-
>.
34-
</p>
35-
<p>Bayes theorem:</p>
36-
<math>
37-
<mrow>
38-
<mi>P</mi>
39-
<mrow>
40-
<mo fence="true">(</mo>
41-
<mrow><mi>A</mi><mo>|</mo><mi>B</mi></mrow>
42-
<mo fence="true">)</mo>
43-
</mrow>
44-
</mrow>
45-
<mo>=</mo>
46-
<mfrac>
47-
<mrow>
48-
<mi>P</mi>
49-
<mrow>
50-
<mo fence="true">(</mo>
51-
<mrow><mi>B</mi><mo>|</mo><mi>A</mi></mrow>
52-
<mo fence="true">)</mo>
53-
</mrow>
54-
<mi>P</mi>
55-
<mrow>
56-
<mo fence="true">(</mo>
57-
<mi>A</mi>
58-
<mo fence="true">)</mo>
59-
</mrow>
60-
</mrow>
61-
<mrow>
62-
<mi>P</mi>
63-
<mrow>
64-
<mo fence="true">(</mo>
65-
<mi>B</mi>
66-
<mo fence="true">)</mo>
67-
</mrow>
68-
</mrow>
69-
</mfrac>
70-
</math>
71-
```
23+
![Preview of the results from above](example-results.png)
7224

7325
## Installation
7426

7527
```bash
7628
npm install markdown-it-math --save
7729

78-
# Optional (use the default math renderer)
30+
# Optional (use the default AsciiMath renderer)
7931
npm install mathup --save
32+
33+
# Optional (use a LaTeX renderer instead)
34+
npm install temml --save
8035
```
8136

8237
### In a browser
@@ -85,23 +40,28 @@ Use an [importmap][importmap]. Change `/path/to/modules` to the
8540
location of your modules.
8641

8742
```html
88-
<!--mathup is optional -->
43+
<!--mathup or temml are optional -->
8944
<script type="importmap">
9045
{
9146
"imports": {
9247
"markdown-it": "/path/to/modules/markdown-it/index.mjs",
9348
"markdown-it-math": "/path/to/modules/markdown-it-math/index.js",
94-
"mathup": "/path/to/modules/mathup.js"
49+
"mathup": "/path/to/modules/mathup.js",
50+
"temml": "/path/to/modules/temml.mjs"
9551
}
9652
}
9753
</script>
9854
```
9955

100-
**Note** Importing mathup is optional. Only import it if you want to
101-
use the default math renderer.
56+
**Note** Importing [mathup][mathup] or [temml][temml] are
57+
optional. Only import mathup if you want to use it as the default
58+
AsciiMath renderer. Import Temml if you want to use it as the LaTeX
59+
renderer.
10260

10361
## Usage
10462

63+
### With default AsciiMath (mathup) renderer
64+
10565
```js
10666
import markdownIt from "markdown-it";
10767
import markdownItMath from "markdown-it-math";
@@ -125,14 +85,57 @@ md.render(`
12585
A text $1+1=2$ with math.
12686
12787
$$
128-
bf A = [a, b, c
129-
d, e, f
130-
g, h, i]
88+
bf A._(3 xx 3) =
89+
[a_(1 1), a_(1 2), a_(1 3)
90+
a_(2 1), a_(2 2), a_(2 3)
91+
a_(3 1), a_(3 2), a_(3 3)]
92+
$$
93+
`);
94+
```
95+
96+
You may also want to include the stylesheet from mathup. See
97+
[mathup][mathup] for reference and usage instructions about the
98+
default renderer.
99+
100+
### LaTeX (Temml)
101+
102+
```bash
103+
npm install --save temml
104+
```
105+
106+
```js
107+
import markdownIt from "markdown-it";
108+
import markdownItMath from "markdown-it-math";
109+
import temml from "temml";
110+
111+
// Optional, if you want macros to persit across equations.
112+
const macros = {};
113+
114+
const md = markdownIt().use(markdownItMath, {
115+
inlineRenderer: (src) => temml.renderToString(src, { macros }),
116+
blockRenderer: (src) =>
117+
temml.renderToString(src, { displayStyle: true, macros }),
118+
});
119+
```
120+
121+
```js
122+
md.render(`
123+
A text $1+1=2$ with math.
124+
125+
$$
126+
\underset{3 \times 3}{\mathbf{A}} =
127+
\begin{bmatrix}
128+
a_{1 1} & a_{1 2} & c_{1 3} \\
129+
a_{2 1} & a_{2 2} & c_{2 3} \\
130+
a_{3 1} & a_{3 2} & c_{3 3}
131+
\end{bmatrix}
131132
$$
132133
`);
133134
```
134135

135-
(See [mathup][mathup] for reference about the default renderer).
136+
You may also want to include the stylesheets and fonts from Temml. See
137+
[Temml][temml] for reference and usage instructions about the
138+
default renderer.
136139

137140
### Options
138141

@@ -153,21 +156,26 @@ $$
153156
- `inlineRenderer`:
154157
Provide a custom inline math renderer. Accepts the source content, the
155158
parsed markdown-it token, and the markdown-it instance. Default:
159+
156160
```js
157161
import mathup from "mathup";
162+
158163
function defaultInlineRenderer(src, token, md) {
159164
return mathup(src, defaultRendererOptions).toString();
160165
}
161166
```
167+
162168
- `blockCustomElement`:
163169
Specify `"tag-name"` or `["tag-name", { some: "attrs" }]` if you want to
164170
render block expressions to a custom element. Ignored if you provide a
165171
custom renderer.
166172
- `blockRenderer`:
167173
Provide a custom block math renderer. Accepts the source content, the
168174
parsed markdown-it token, and the markdown-it instance. Default:
175+
169176
```js
170177
import mathup from "mathup";
178+
171179
function defaultBlockRenderer(src, token, md) {
172180
return mathup(src, {
173181
...defaultRendererOptions,
@@ -185,7 +193,7 @@ import markdownIt from "markdown-it";
185193
import markdownItMath from "markdown-it-math";
186194

187195
const md = markdownIt().use(markdownItMath, {
188-
renderingOptions: { decimalMark: "," },
196+
defaultRendererOptions: { decimalMark: "," },
189197
});
190198

191199
md.render("$40,2$");
@@ -213,22 +221,6 @@ $$
213221
// <la-tex display="block">\int_{0}^{\infty} E[X]</la-tex>
214222
```
215223

216-
Using [TeXZilla][texzilla] as renderer
217-
218-
```js
219-
import markdownIt from "markdown-it";
220-
import markdownItMath from "markdown-it-math";
221-
import texzilla from "texzilla";
222-
223-
const md = markdownIt().use(markdownItMath, {
224-
inlineRenderer: (str) => texzilla.toMathMLString(str),
225-
blockRenderer: (str) => texzilla.toMathMLString(str, true),
226-
});
227-
228-
md.render("$\\sin(2\\pi)$");
229-
// <p><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mo lspace="0em" rspace="0em">sin</mo><mo stretchy="false">(</mo><mn>2</mn><mi>π</mi><mo stretchy="false">)</mo></mrow><annotation encoding="TeX">\sin(2\pi)</annotation></semantics></math></p>
230-
```
231-
232224
Turning off inline math:
233225

234226
```js
@@ -279,12 +271,10 @@ This expression \[P(x \in X) = 0\] will not render.
279271

280272
[importmap]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap
281273
[jsdelivr]: https://www.jsdelivr.com/
282-
[mathup]: https://runarberg.github.io/mathup/
283-
[mathjax]: https://www.mathjax.org/
274+
[mathup]: https://mathup.xyz/
284275
[mathml]: https://www.w3.org/TR/MathML/
285276
[markdown-it]: https://github.com/markdown-it/markdown-it
286-
[markdown-it-mathjax]: https://www.npmjs.com/package/markdown-it-mathjax
287-
[texzilla]: http://fred-wang.github.io/TeXZilla/
277+
[Temml]: https://temml.org
288278
[why-my-inline-rule-is-not-executed]: https://github.com/markdown-it/markdown-it/blob/master/docs/development.md#why-my-inline-rule-is-not-executed
289279

290280
## Upgrading From v4

demo/eulers-identity.md

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Euler’s identity
2+
3+
In mathematics, **Euler’s identity** (also known as _Euler’s
4+
equation_) is the equality
5+
$$ e^(i pi) + 1 = 0 $$
6+
where
7+
8+
- $e$ is Euler's number, the base of natural logarithms,
9+
- $i$ is the imaginary unit, which by definition satisfies $i^2 = -1$,
10+
and
11+
- $pi$ is pi, the ratio of the circumference of a circle to its
12+
diameter.
13+
14+
Euler’s identity is named after the Swiss mathematician Leonhard
15+
Euler. It is a special case of Euler’s formula $e^(ix) = cos x + i sin
16+
x$ when evaluated for $x=pi$. Euler's identity is considered an
17+
exemplar of mathematical beauty, as it shows a profound connection
18+
between the most fundamental numbers in mathematics. In addition, it
19+
is directly used in a proof that $pi$ is transcendental, which implies
20+
the impossibility of squaring the circle.
21+
22+
## Imaginary exponents
23+
24+
Euler’s identity asserts that $e^(i pi)$ is equal to $-1$. The
25+
expression $e^(i pi)$ is a special case of the expression $e^z$, where
26+
$z$ is any complex number. In general, $e^z$ is defined for complex $z$
27+
by extending one of the definitions of the exponential function from
28+
real exponents to complex exponents. For example, one common
29+
definition is:
30+
31+
$$
32+
e^z = lim_(n->oo) (1 + z/n)^n.
33+
$$
34+
35+
Euler’s identity therefore states that the limit, as $n$ approaches
36+
infinity, of $(1 + (i pi)/n)^n$ is equal to $-1$.
37+
38+
Euler’s identity is a special case of Euler’s formula, which states
39+
that for any real number $x$,
40+
41+
$$ e^(ix) = cos x + i sin x $$
42+
43+
where the inputs of the trigonometric functions sine and cosine are
44+
given in radians.
45+
46+
![Euler's formula for a general angle](https://upload.wikimedia.org/wikipedia/commons/thumb/7/71/Euler%27s_formula.svg/330px-Euler%27s_formula.svg.png)
47+
48+
In particular, when $x = pi$,
49+
50+
$$
51+
e^(i pi) = cos pi + i sin pi.
52+
$$
53+
54+
Since
55+
$$ cos pi = -1 $$
56+
and
57+
$$ sin pi = 0 $$
58+
59+
it follows that
60+
$$ e^(i pi) = -1 + 0i, $$
61+
62+
which yields Euler's identity:
63+
64+
$$ e^(i pi) + 1 = 0. $$
65+
66+
## Generalizations
67+
68+
Euler’s identity is also a special case of the more general identity
69+
that the $n$th roots of unity, for $n > 1$, add up to $0$:
70+
71+
$$
72+
sum_(k=0)^(n-1) e^(2pi i k/n) = 0 .
73+
$$
74+
75+
Euler’s identity is the case where $n = 2$.
76+
77+
A similar identity also applies to quaternion exponential: let ${i, j,
78+
k}$ be the basis quaternions; then,
79+
80+
$$
81+
e^(1/sqrt(3) (i +- j +- k) pi) + 1 = 0 .
82+
$$
83+
84+
More generally, let q be a quaternion with a zero real part and a norm
85+
equal to $1$; that is, $q = ai + bj + ck$, with $a^2 + b^2 + c^2 =
86+
1$. Then one has
87+
88+
$$
89+
e^(q pi) + 1 = 0 .
90+
$$
91+
92+
The same formula applies to octonions, with a zero real part and a
93+
norm equal to $1$. These formulas are a direct generalization of
94+
Euler’s identity, since $i$ and $-i$ are the only complex numbers with
95+
a zero real part and a norm (absolute value) equal to $1$.

demo/fonts/asana/Asana-Math.woff2

249 KB
Binary file not shown.
Binary file not shown.
Binary file not shown.

0 commit comments

Comments
 (0)