diff --git a/README.md b/README.md index d8a080f0..9cacf4c3 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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. @@ -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: @@ -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. } ``` @@ -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., if useGlobalCache, counter for equation numbering if equationNumbers ar ) + state: {}, // an object to store information from multiple calls (e.g., if useGlobalCache, counter for equation numbering if equationNumbers ar ) timeout: 10 * 1000, // 10 second timeout before restarting MathJax } ``` @@ -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). + diff --git a/package.json b/package.json index 369457cb..8e1c3fbb 100644 --- a/package.json +++ b/package.json @@ -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",