You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository contains files that provide APIs to call [MathJax](https://github.com/mathjax/mathjax) from
4
-
node.js programs. There is an API for converting individual math
5
-
expressions (in any of MathJax's input formats) into SVG images or MathML
6
-
code, and there is an API for converting HTML snippets containing any of
7
-
MathJax input formats into HTML snippets containing SVG or MathML.
8
-
9
-
See the comments in the individual files for more details.
10
-
11
-
The `bin` directory contains a collection of command-line programs for
12
-
converting among MathJax's various formats. These can be used as examples
13
-
of calling the MathJax API.
3
+
This repository contains a library that provides an API to call [MathJax](https://github.com/mathjax/mathjax) from Node.js programs. The API converts individual math expressions (in any of MathJax's input formats) into HTML (with CSS), SVG or MathML code.
14
4
15
5
Use
16
6
17
-
npm install mathjax-node
7
+
```
8
+
npm install mathjax-node
9
+
```
18
10
19
11
to install mathjax-node and its dependencies.
20
12
21
-
These API's can produce PNG images, but that requires the
22
-
[Batik](http://xmlgraphics.apache.org/batik/download.html) library. It
23
-
should be installed in the `batik` directory. See the README file in that
24
-
directory for more details.
13
+
**Note:**
25
14
26
-
# Getting started
15
+
mathjax-node requires Node.js v4 or later.
16
+
17
+
**Breaking Changes in v1.0:**
18
+
19
+
20
+
mathjax-node v1.0 makes breaking changes to the following features from the pre-releases.
27
21
28
-
mathjax-node provides two libraries, `./lib/mj-single.js` and `./lib/mj-page.js`. Below are two very minimal examples -- be sure to check out the examples in `./bin/` for more advanced configurations.
22
+
-[CHANGED]`lib/mj-single.js` has been renamed to `lib/main.js` (and set as `main` in `package.json`, i.e., `require('mathjax-node')` will load it.
23
+
-[REMOVED]`lib/mj-page.js` (API for processing HTML-fragments) and related CLI tools
24
+
-[REMOVED] speech-rule-engine integration
25
+
-[REMOVED] PNG generation
26
+
-[REMOVED] CLI tools in `bin/`
29
27
30
-
*`./lib/mj-single.js` is optimized for processing single equations.
28
+
These features can easily be recreated in separate modules for greater flexibility. For examples, see
Be sure to also check out other [projects on NPM that depend on mathjax-node](https://www.npmjs.com/browse/depended/mathjax-node).
36
+
37
+
# Getting started
38
+
39
+
mathjax-node provides a library, `./lib/main.js`. Below is a very minimal example for using it - the tests and the examples mentioned above provide more advanced examples.
32
40
33
41
```javascript
34
42
// a simple TeX-input example
35
-
var mjAPI =require("mathjax-node/lib/mj-single.js");
*`./lib/mj-page.js` is optimized for handling full HTML pages.
74
+
mathjax-node exports three methods, `config`, `start`, `typeset`.
56
75
76
+
### `config(options)`
77
+
78
+
The `config` method is used to set _global_ configuration options. Its default options are
57
79
58
80
```javascript
59
-
var mjAPI =require("mathjax-node/lib/mj-page.js");
60
-
var jsdom =require("jsdom").jsdom;
81
+
{
82
+
displayMessages:false, // determines whether Message.Set() calls are logged
83
+
displayErrors:true, // determines whether error messages are shown on the console
84
+
undefinedCharError:false, // determines whether "unknown characters" (i.e., no glyph in the configured fonts) are saved in the error array
85
+
extensions:'', // a convenience option to add MathJax extensions
86
+
fontURL:'https://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS', // for webfont urls in the CSS for HTML output
87
+
MathJax: { } // standard MathJax configuration options, see https://docs.mathjax.org for more detail.
88
+
}
89
+
```
61
90
62
-
vardocument=jsdom("<!DOCTYPE html><html lang='en'><head><title>Test</title></head><body><h1>Let's test mj-page</h1> <p> \\[f: X \\to Y\\], where \\( X = 2^{\mathbb{N}}\\) </p></body></html>");
91
+
**Note.** Changes to these options require a restart of the API using the `start()` method (see below).
The `start` method start (and restarts) mathjax-node. This allows reconfiguration.
96
+
97
+
**Note.** This is done automatically when `typeset` is first called (see below).
98
+
99
+
### `typset(options, callback)`
100
+
101
+
The `typeset` method is the main method of mathjax-node. It expects a configuration object `input` and a `callback`.
102
+
103
+
Once called, `typeset` can be called repeatedly and will optionally store information across calls (see `state` below).
104
+
105
+
The following are the default input options.
106
+
107
+
```javascript
108
+
{
109
+
ex:6, // ex-size in pixels
110
+
width:100, // width of container (in ex) for linebreaking and tags
111
+
useFontCache:true, // use <defs> and <use> in svg output?
112
+
useGlobalCache:false, // use common <defs> for all equations?
113
+
linebreaks:false, // automatic linebreaking
114
+
equationNumbers:"none", // automatic equation numbering ("none", "AMS" or "all")
115
+
116
+
math:"", // the math string to typeset
117
+
format:"TeX", // the input format (TeX, inline-TeX, AsciiMath, or MathML)
118
+
xmlns:"mml", // the namespace to use for MathML
119
+
120
+
html:false, // generate HTML output
121
+
htmlNode:false, // generate HTML output as jsdom node
122
+
css:false, // generate CSS for HTML output
123
+
mml:false, // generate MathML output
124
+
mmlNode:false, // generate MathML output as jsdom node
125
+
svg:false, // generate SVG output
126
+
svgNode:false, // generate SVG output as jsdom node
127
+
128
+
speakText:true, // add textual alternative (for TeX/asciimath the input string, for MathML a dummy string)
129
+
130
+
state: {}, // an object to store information from multiple calls (e.g., <defs> if useGlobalCache, counter for equation numbering if equationNumbers ar )
131
+
timeout:10*1000, // 10 second timeout before restarting MathJax
132
+
}
77
133
```
134
+
135
+
### `callback(result, options)`
136
+
137
+
mathjax-node returns two objects to the `callback`: a `result` object as well as the original input `options`.
138
+
139
+
The `result` object will contain (at most) the following structure:
140
+
141
+
```javascript
142
+
{
143
+
mml:// a string of MathML markup if requested
144
+
mmlNode:// a jsdom node of MathML markup if requested
145
+
html:// a string of HTML markup if requested
146
+
htmlNode:// a jsdom node of HTML markup if requested
147
+
css:// a string of CSS if HTML was requested
148
+
svg:// a string of SVG markup if requested
149
+
svgNode:// a jsdom node of SVG markup if requested
150
+
style:// a string of CSS inline style if SVG requested
151
+
speakText:// a string of speech text if requested
152
+
153
+
state: { // the state object (if useGlobalCache or equationNumbers is set)
154
+
glyphs:// a collection of glyph data
155
+
defs :// a string containing SVG def elements
156
+
AMS: {
157
+
startNumber:// the current starting equation number
158
+
labels:// the set of labels
159
+
IDs:// IDs used in previous equations
160
+
}
161
+
}
162
+
}
163
+
```
164
+
165
+
The `options` contains the configuration object passed to `typeset`; this can be useful for passing other data along or for identifying which `typeset()` call is associated with this `callback` call (in case you use the same `callback` function for more than one `typeset()`).
0 commit comments