@4qwerty7/mathjax-node-page 中文文档教程

Question

mathjax-node-page

此 Node.js 模块构建于 mathjax-node 并提供对较大内容片段的处理

installation

用于

npm install mathjax-node-page

安装 mathjax-node-page及其依赖项。

Usage

mathjax-node-page 导出 mjpage 需要四个参数：

mjpage(input, mjpageConfig, mjnodeConfig, callback)

其中 input 是带有 HTML 或 jsdom 对象的字符串（JSDOM 类应该通过导出的 JSDOM 获取），pageConfig 指定页面范围的选项，mjnodeConfig 需要 mathjax-node 配置选项。

pageConfig 的默认值是

{
    format: ["MathML", "TeX", "AsciiMath"], // determines type of pre-processors to run
    output: '', // global override for output option; 'svg', 'html' or 'mml'
    tex: {}, // configuration options for tex pre-processor, cf. lib/tex.js
    ascii: {}, // configuration options for ascii pre-processor, cf. lib/ascii.js
    singleDollars: false, // allow single-dollar delimiter for inline TeX
    fragment: false, // return body.innerHTML instead of full document
    cssInline: true,  // determines whether inline css should be added
    jsdom: {...}, // jsdom-related options
    displayMessages: false, // determines whether Message.Set() calls are logged
    displayErrors: false, // determines whether error messages are shown on the console
    undefinedCharError: false, // determines whether unknown characters are saved in the error array
    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: {}, // options MathJax configuration, see https://docs.mathjax.org
    errorHandler: (id, wrapperNode, sourceFormula, sourceFormat, errors) => {...} // function to handle rendering error
}

，其中 mjnodeConfig 代表 mathjax-node 配置选项，默认值是。

{
  ex: 6, // ex-size in pixels
  width: 100, // width of math container (in ex) for linebreaking and tags
  useFontCache: true, // use <defs> and <use> in svg output?
  useGlobalCache: false, // use common <defs> for all equations?
  state: mjstate, // track global state
  linebreaks: false, // do linebreaking?
  equationNumbers: "none", // or "AMS" or "all"
  math: "", // the math to typeset
  html: false, // generate HTML output?
  css: false, // generate CSS for HTML output?
  mml: false, // generate mml output?
  svg: false, // generate svg output?
  speakText: true, // add spoken annotations to output?
  timeout: 10 * 1000, // 10 second timeout before restarting MathJax
}

Advanced usage

mathjax-node customization

mathjax-node-page 导出 init 函数，允许您传入自定义 mathjax-node（例如，mathjax-node-svg2png)。

const mjnode = require('mathjax-node-svg2png');
mjpage.init(mjnode);

如果您的自定义 mathjax 节点提供了新的输出选项，您可以通过调用 addOutput 添加它们。 作为第二个参数，您可以传递自定义输出处理程序，这是一个使用转换结果修改 DOM 元素的函数。 默认的输出处理程序行为是将内容写入 wrapper.innerHTML。

mjpage.addOutput('png', (wrapper, data) => {
    wrapper.innerHTML = `<img src="${data}">`;
});
// ...now you can use standard mathjax-node-page API

通过使用空参数调用 init 重置为默认的 mathjax 节点行为。 在调用它之前，确保所有当前的 mathjax-node-page 任务都已完成。

mjpage.init();  // reset back to default mathjax-node

Events

mjpage 运行继承 EventEmitter 的作业并提供以下事件挂钩。 添加相应的事件处理程序以在转换之前/之后操作输入/输出和 DOM。

当作业结束时，所有事件处理程序都会被销毁以防止内存泄漏。

Formula conversion events

• beforeConversion -> handler(parsedFormula): runs before individual formula conversion started, but after initial DOM processing. All the formulas are wrapped in <script type="..."> tags, where @type is one of the following:

const scripts = document.querySelectorAll(`
    script[type="math/TeX"],
    script[type="math/inline-TeX"],
    script[type="math/AsciiMath"],
    script[type="math/MathML"],
    script[type="math/MathML-block"]`
);

• afterConersion -> handler(parsedFormula): runs after individual formula conversion completed and DOM was changed. Formula DOM node is a <span class="mjpage..."> wrapper whose contents are the conversion result.

所有公式转换事件都将 ParsedFormula 实例传递给事件处理程序。

{
    id, // index of formula on the page
    jobID, // mjpage job ID; formulas belonging to the same page run have the same jobID
    node, // DOM node with the formula (contents change before and after conversion)
    sourceFormula, // the source formula
    sourceFormat, // the source formula format (e.g. "inline-TeX")
    outputFormula, // the converted formula result from mathjax-node typeset function; use outputFormula[outputFormat] to get the resulting formula string
    outputFormat // the resulting formula format (e.g. "svg")
}

Page conversion events

• beforeSerialiation -> handler(document, css): runs when converted page DOM was prepared immediately before serialization. Use to manipulate resulting page DOM. The event handler receives document node (jsdom) and page css. Won't trigger if input is a jsdom object.

如果input是一个HTML字符串，mjpage函数回调接收DOM序列化后的结果。
如果input 是一个jsdom 对象，mjpage 函数回调接收jsdom 对象本身。

Error handling

当出现渲染错误时，config.errorHandler 将被调用。 传递了这些参数：

• id: index of formula on the page.
• wrapperNode: The jsdom HTMLElement object where the rendered math should be put.
• sourceFormula: The input math code.
• sourceFormat: The format of input math code -- e.g. inline-TeX or TeX.
• errors: A array of strings of MathJax-Node returned errors.

修改 wrapperNode 对象以向用户显示一些错误消息。 默认的错误处理函数是使用 console.log 打印错误。

Example

mjpage(input, {
    format: ["TeX"]
}, {
    svg: true
}, function(output) {
    // output is your final result
})
.on('afterConversion', function(parsedFormula) {
    // manipulate parsed result and DOM at your will
    // see description of parsedFormula object above
});

CLI

mathjax-node-page 安装 CLI 工具。 运行 mjpage 打印使用说明。

Example

const mjpage = require('../lib/main.js').mjpage;
const fs = require('fs');
const input = fs.readFileSync('input.html');

mjpage(input, {format: ["TeX"]}, {svg: true}, function(output) {
    console.log(output); // resulting HTML string
});