Skip to content

Commit 633babc

Browse files
committed
Accept multitple delimiter pairs
Add a new option for `inlineDelimiters` and `blockDelimiters` which accepts an array of open close pairs. This allows authors to have multiple delimiter pairs which matches many flavors of Markdown, inlcuding GFM. Breaking change: Empty math expressions are no longer renderer. - Depricates: `inlineOpen`, and `inlineClose` in favor of `inlineDelimiters`. - Depricates: `blockOpen`, and `blockClose` in favor of `blockDelimiters`.
1 parent 67b46a2 commit 633babc

File tree

4 files changed

+402
-189
lines changed

4 files changed

+402
-189
lines changed

README.md

Lines changed: 58 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,8 @@ npm install mathup --save
8181

8282
### In a browser
8383

84-
Use an [importmap][importmap]. Change `/path/to/modules` to the location of your modules.
84+
Use an [importmap][importmap]. Change `/path/to/modules` to the
85+
location of your modules.
8586

8687
```html
8788
<!--mathup is optional -->
@@ -107,10 +108,8 @@ import markdownItMath from "markdown-it-math";
107108

108109
// Optional (with defaults)
109110
const options = {
110-
inlineOpen: "$",
111-
inlineClose: "$",
112-
blockOpen: "$$",
113-
blockClose: "$$",
111+
inlineDelimiters: ["$", ["$`", "`$"]]
112+
blockDelimiters: "$$",
114113
defaultRendererOptions,
115114
inlineCustomElement, // see below
116115
inlineRenderer, // see below
@@ -137,12 +136,16 @@ $$
137136

138137
### Options
139138

140-
- `inlineOpen`: The delimiter to start an inline math expression. Default `$`
141-
- `inlineClose`: The delimiter to close an inline math expression. Default `$`
142-
- `blockOpen`: The delimiter to start a block math expression. Default `$$`
143-
- `blockClose`: The delimiter to close a block math expression. Default `$$`
144-
- `defaultRendererOptions`:
145-
The options passed into the default renderer. Ignored if you use a custom renderer. Default `{}`
139+
- `inlineDelimiters`: A string, or an array of strings (or pairs of
140+
strings) specifying delimiters for inline math expressions. If a
141+
string, the same delimiter is used for open and close. If a pair of
142+
strings, the first string opens and the second one closes. Empty
143+
strings or pairs containing empty strings are ignored. If no valid
144+
strings or pairs are provided, it will turn off the rule.
145+
Default ``["$", ["$`", "`$"]]``.
146+
- `blockDelimiters`: Same as above, but for block expressions. Default `"$$"`.
147+
- `defaultRendererOptions`: The options passed into the default
148+
renderer. Ignored if you use a custom renderer. Default `{}`
146149
- `inlineCustomElement`:
147150
Specify `"tag-name"` or `["tag-name", { some: "attrs" }]` if you want to
148151
render inline expressions to a custom element. Ignored if you provide a
@@ -226,34 +229,52 @@ md.render("$\\sin(2\\pi)$");
226229
// <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>
227230
```
228231

232+
Turning off inline math:
233+
234+
```js
235+
import markdownIt from "markdown-it";
236+
import markdownItMath from "markdown-it-math";
237+
238+
const md = markdownIt().use(markdownItMath, {
239+
inlineDelimiters: "",
240+
});
241+
```
242+
243+
```md
244+
Only block math is allowed. $a^2$ will not render into inline math.
245+
246+
But this will render into block math:
247+
248+
$$
249+
a^2
250+
$$
251+
```
252+
229253
Using LaTeX style delimiters:
230254

231255
```js
232256
import markdownIt from "markdown-it";
233257
import markdownItMath from "markdown-it-math";
234258

235259
const md = markdownIt().use(markdownItMath, {
236-
inlineOpen: "\\(",
237-
inlineClose: "\\)",
238-
blockOpen: "\\[",
239-
blockClose: "\\]",
260+
inlineDelimiters: [["\\(", "\\)"]],
261+
blockDelimiters: [["\\[", "\\]"]],
240262
});
241263
```
242264

243265
Note there are restrictions on what inline delimiters you can use,
244266
based on optimization for the markdown-it parser [see here for
245-
details][why-my-inline-rule-is-not-executed]. And block level math
246-
must be on its own lines with newlines separating the math from the
247-
delimiters.
267+
details][why-my-inline-rule-is-not-executed].
268+
269+
Block level math must be on its own lines.
248270

249271
```markdown
250272
Some text with inline math \(a^2 + b^2 = c^2\)
251273

252-
And block math
274+
And block math:
275+
\[e = sum\_(n=0)^oo 1/n!\]
253276

254-
\[
255-
e = sum\_(n=0)^oo 1/n!
256-
\]
277+
This expression \[P(x \in X) = 0\] will not render.
257278
```
258279

259280
[importmap]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap
@@ -270,15 +291,26 @@ e = sum\_(n=0)^oo 1/n!
270291

271292
Version 5 introduced some breaking changes, along with dropping legacy platforms.
272293

294+
- The `inlineOpen`, `inlineClose`, `blockOpen`, and `blockClose` options have
295+
been depricated in favor of `inlineDelimiters` and `blockDelimiters`
296+
respectively.
297+
```diff
298+
markdownIt().use(markdownItMath, {
299+
- inlineOpen: "$",
300+
- inlineClose: "$",
301+
- blockOpen: "$$",
302+
- blockClose: "$$",
303+
+ inlineDelimiters: "$",
304+
+ blockDelimiters: "$$",
305+
});
306+
```
273307
- The default delimiters changed from `$$` and `$$$` for inline and
274308
block math respectively to `$` and `$$`. If you want to keep the
275309
thicker variants, you must set the relevant options:
276310
```js
277311
markdownIt().use(markdownItMath, {
278-
inlineOpen: "$$",
279-
inlineClose: "$$",
280-
blockOpen: "$$$",
281-
blockClose: "$$$",
312+
inlineDelimiters: "$$",
313+
blockDelimiters: "$$$",
282314
});
283315
```
284316
- The options passed into the default mathup renderer has been renamed

0 commit comments

Comments
 (0)