Skip to content

Commit 7395262

Browse files
pkrapkra
authored
[README] add documentation section (#300)
* [README] add documentation section Includes linting. Resolves #298
1 parent c0f7d6b commit 7395262

File tree

1 file changed

+111
-25
lines changed

1 file changed

+111
-25
lines changed

‎README.md‎

Lines changed: 111 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,42 @@
11
# mathjax-node [![Build Status](https://travis-ci.org/mathjax/MathJax-node.svg?branch=develop)](https://travis-ci.org/mathjax/MathJax-node)
22

3-
This repository contains a library that provides an API to call [MathJax](https://github.com/mathjax/mathjax) from
4-
NodeJS programs. The API converts individual math
5-
expressions (in any of MathJax's input formats) into HTML (with CSS), SVG or MathML code.
6-
7-
See the comments in the individual files for more details.
8-
9-
The `bin` directory contains a collection of command-line programs for
10-
converting among MathJax's various formats. These can be used as examples
11-
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.
124

135
Use
146

15-
npm install mathjax-node
7+
```
8+
npm install mathjax-node
9+
```
1610

1711
to install mathjax-node and its dependencies.
1812

19-
20-
**Note:**
13+
**Note:**
2114

2215
mathjax-node requires Node.js v4 or later.
2316

24-
2517
**Breaking Changes in v1.0:**
2618

27-
mathjax-node v1.0 dropped the following features that were present in earlier pre-releases.
2819

29-
* `lib/mj-page.js` (API for processing HTML-fragments) and related CLI tools
30-
* speech-rule-engine integration
31-
* PNG generation
20+
mathjax-node v1.0 makes breaking changes to the following features from the pre-releases.
3221

33-
These features can easily be recreated in separate modules for greate flexibility. For some community examples, see
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/`
3427

35-
* [mathjax-node-page](https://github.com/pkra/mathjax-node-page/)
36-
* [mathjax-node-sre](https://github.com/pkra/mathjax-node-sre)
37-
* [mathjax-node-svg2png](https://github.com/pkra/mathjax-node-svg2png)
28+
These features can easily be recreated in separate modules for greater flexibility. For examples, see
3829

30+
- [mathjax-node-cli](https://github.com/mathjax/mathjax-node-cli/)
31+
- [mathjax-node-page](https://github.com/pkra/mathjax-node-page/)
32+
- [mathjax-node-sre](https://github.com/pkra/mathjax-node-sre)
33+
- [mathjax-node-svg2png](https://github.com/pkra/mathjax-node-svg2png)
34+
35+
Be sure to also check out other [projects on NPM that depend on mathjax-node](https://www.npmjs.com/browse/depended/mathjax-node).
3936

4037
# Getting started
4138

42-
mathjax-node provides a library, `./lib/main.js`. Below is a very minimal example - be sure to check out the examples in `./bin/` for more advanced examples.
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.
4340

4441
```javascript
4542
// a simple TeX-input example
@@ -72,8 +69,97 @@ mjAPI.typeset({
7269
});
7370
```
7471

75-
## Examples
72+
## Documentation
73+
74+
mathjax-node exports three methods, `config`, `start`, `typeset`.
75+
76+
### `config(options)`
77+
78+
The `config` method is used to set _global_ configuration options. Its default options are
79+
80+
```javascript
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+
```
90+
91+
**Note.** Changes to these options require a restart of the API using the `start()` method (see below).
92+
93+
### `start()`
7694

77-
The examples in `./bin/` provide a starting point for more advanced integrations.
95+
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+
}
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+
```
78164

79-
Be sure to also check out other [projects on NPM that depend on mathjax-node ](https://www.npmjs.com/browse/depended/mathjax-node).
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

Comments
 (0)