Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 43 additions & 32 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# mathjax-node [![Build Status](https://travis-ci.org/mathjax/MathJax-node.svg?branch=develop)](https://travis-ci.org/mathjax/MathJax-node)

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.
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.

Use

Expand All @@ -11,30 +11,9 @@ npm install mathjax-node
to install mathjax-node and its dependencies.

**Note:**
The current version of mathjax-node requires Node.js v6 or later, and uses jsdom version 10.

mathjax-node requires Node.js v4 or later.

**Breaking Changes in v1.0:**


mathjax-node v1.0 makes breaking changes to the following features from the pre-releases.

- [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.
- [REMOVED] `lib/mj-page.js` (API for processing HTML-fragments) and related CLI tools
- [REMOVED] speech-rule-engine integration
- [REMOVED] PNG generation
- [REMOVED] CLI tools in `bin/`

These features can easily be recreated in separate modules for greater flexibility. For examples, see

- [mathjax-node-cli](https://github.com/mathjax/mathjax-node-cli/)
- [mathjax-node-page](https://github.com/pkra/mathjax-node-page/)
- [mathjax-node-sre](https://github.com/pkra/mathjax-node-sre)
- [mathjax-node-svg2png](https://github.com/pkra/mathjax-node-svg2png)

Be sure to also check out other [projects on NPM that depend on mathjax-node](https://www.npmjs.com/browse/depended/mathjax-node).

# Getting started
## Getting started

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.

Expand All @@ -52,8 +31,8 @@ var yourMath = 'E = mc^2';

mjAPI.typeset({
math: yourMath,
format: "TeX", // "inline-TeX", "MathML"
mml:true, // svg:true,
format: "TeX", // or "inline-TeX", "MathML"
mml:true, // or svg:true, or html:true
}, function (data) {
if (!data.errors) {console.log(data.mml)}
// will produce:
Expand All @@ -79,12 +58,12 @@ The `config` method is used to set _global_ configuration options. Its default o

```javascript
{
displayMessages: false, // determines whether Message.Set() calls are logged
displayErrors: true, // determines whether error messages are shown on the console
displayMessages: false, // determines whether Message.Set() calls are logged
displayErrors: true, // determines whether error messages are shown on the console
undefinedCharError: false, // determines whether "unknown characters" (i.e., no glyph in the configured fonts) are saved in the error array
extensions: '', // a convenience option to add MathJax extensions
fontURL: 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/fonts/HTML-CSS', // for webfont urls in the CSS for HTML output
MathJax: { } // standard MathJax configuration options, see https://docs.mathjax.org for more detail.
extensions: '', // a convenience option to add MathJax extensions
fontURL: 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/fonts/HTML-CSS', // for webfont urls in the CSS for HTML output
MathJax: { } // standard MathJax configuration options, see https://docs.mathjax.org for more detail.
}
```

Expand Down Expand Up @@ -130,7 +109,7 @@ The following are the default input options.

speakText: true, // add textual alternative (for TeX/asciimath the input string, for MathML a dummy string)

state: {}, // an object to store information from multiple calls (e.g., <defs> if useGlobalCache, counter for equation numbering if equationNumbers ar )
state: {}, // an object to store information from multiple calls (e.g., <defs> if useGlobalCache, counter for equation numbering if equationNumbers ar )
timeout: 10 * 1000, // 10 second timeout before restarting MathJax
}
```
Expand Down Expand Up @@ -171,3 +150,35 @@ The `result` object will contain (at most) the following structure:
If the `errors` array is non-empty, the Promise will reject, and be passed the `errors` array.

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()`).

## Change History

### Breaking Changes in v2.0:

mathjax-node v2.0 makes breaking changes as follows:

- [CHANGED] mathjax-node now requires version 6 of Node.js (the minimum used to be Node.js version 4).
- [CHANGED] mathjax-node now uses version 10 of jsdom. Since the jsdom API changed from 9 to 10, that means if you used jsdom in your code that calls mathjax-node, you may need to update how you call jsdom.


### Breaking Changes in v1.0:

mathjax-node v1.0 makes breaking changes to the following features from the pre-releases.

- [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.
- [REMOVED] `lib/mj-page.js` (API for processing HTML-fragments) and related CLI tools
- [REMOVED] speech-rule-engine integration
- [REMOVED] PNG generation
- [REMOVED] CLI tools in `bin/`

These features can easily be recreated in separate modules for greater flexibility. For examples, see

- [mathjax-node-cli](https://github.com/mathjax/mathjax-node-cli/)
- [mathjax-node-page](https://github.com/pkra/mathjax-node-page/)
- [mathjax-node-sre](https://github.com/pkra/mathjax-node-sre)
- [mathjax-node-svg2png](https://github.com/pkra/mathjax-node-svg2png)

---

Be sure to also check out other [projects on NPM that depend on mathjax-node](https://www.npmjs.com/browse/depended/mathjax-node).

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "mathjax-node",
"version": "2.0.0",
"version": "2.0.1",
"description": "API's for calling MathJax from node.js",
"keywords": [
"MathJax",
Expand Down