@achieveai/mathjax-converter-server

A Node.js server that provides comprehensive mathematical notation conversion between LaTeX, MathML, HTML, and SVG formats using both KaTeX and MathJax renderers.

Features

• Multiple Conversion Paths:

  • LaTeX → MathML, HTML, SVG
  • MathML → LaTeX*, HTML, SVG

• Dual Renderer Support:

  • KaTeX: Fast rendering, supports LaTeX → MathML/HTML
  • MathJax: Full-featured, supports all conversions including SVG

• Flexible API: Modern API with backward compatibility

• HTML Entity Decoding: Automatic handling of HTML entities in input

• Error Handling: Comprehensive error reporting

• Interactive Documentation: Built-in API documentation at root endpoint

*Note: MathML to LaTeX conversion is not yet fully implemented and requires additional libraries.

Installation

Local Installation

npm install

Global Installation

npm install -g @achieveai/mathjax-converter-server

Usage

Starting the Server

Local Installation

npm start
# or
npm run dev
# or
node server.js

Global Installation

mathjaxconverter

Configuration via Environment Variables

The server can be configured using environment variables:

• PORT or MATHJAX_PORT: Server port (default: 1337)
• HOST or MATHJAX_HOST: Server host address (default: 0.0.0.0)

# Custom port
PORT=3000 npm start

# Custom host and port
HOST=127.0.0.1 PORT=3000 npm start

# Using MATHJAX-specific variables
MATHJAX_HOST=localhost MATHJAX_PORT=8080 node server.js

# Listen on all interfaces
HOST=0.0.0.0 PORT=3000 npm start

The server runs on http://0.0.0.0:1337 by default (accessible as http://localhost:1337).

API Reference

POST /

Convert mathematical notation between different formats.

Request Body

{
  "from": "latex",          // Input format: "latex" or "mathml"
  "to": "mathml",          // Output format: "mathml", "html", or "svg"
  "input": "x^2 + y^2",    // Input content (or use "latex"/"mathml" field)
  "renderer": "katex",     // Optional: "katex" or "mathjax" (default: katex)
  "displayMode": false,    // Optional: Display mode (default: false)
  "width": 100            // Optional: Width for rendering (MathJax only)
}

Response

Success:

{
  "errs": null,
  "res": {
    "mathml": "<math>...</math>"
  }
}

Error:

{
  "errs": "Error message",
  "res": null
}

Example Requests

LaTeX to MathML (KaTeX)

{
  "from": "latex",
  "to": "mathml",
  "latex": "\\frac{a}{b}",
  "renderer": "katex"
}

LaTeX to SVG (MathJax)

{
  "from": "latex",
  "to": "svg",
  "latex": "\\int_0^1 x^2 dx",
  "renderer": "mathjax"
}

LaTeX to HTML (KaTeX)

{
  "from": "latex",
  "to": "html",
  "latex": "e^{i\\pi} + 1 = 0",
  "renderer": "katex",
  "displayMode": true
}

MathML to HTML (MathJax)

{
  "from": "mathml",
  "to": "html",
  "mathml": "<math><mi>x</mi><mo>+</mo><mi>y</mi></math>",
  "renderer": "mathjax"
}

MathML to SVG (MathJax)

{
  "from": "mathml",
  "to": "svg",
  "mathml": "<math><msqrt><mi>x</mi></msqrt></math>",
  "renderer": "mathjax",
  "width": 150
}

Legacy API Support

The server maintains backward compatibility with the original API format:

Legacy LaTeX Request

{
  "latex": "x^2",
  "displayMode": false
}

Legacy MathML Request

{
  "mathMl": "<math><mi>x</mi></math>",
  "svg": true
}

Conversion Matrix

| From \ To | LaTeX | MathML | HTML | SVG | |-----------|-------|--------|------|-----| | LaTeX | - | ✅ KaTeX/MathJax | ✅ KaTeX/MathJax | ✅ MathJax | | MathML | ⚠️ Limited | - | ✅ MathJax | ✅ MathJax |

Legend:

• ✅ Fully supported
• ⚠️ Limited support (requires additional implementation)
• KaTeX/MathJax: Available in both renderers
• MathJax: Only available in MathJax renderer

Renderer Comparison

KaTeX

• Pros:
  • Very fast rendering
  • Smaller output size
  • Good for web applications
• Cons:
  • Limited to LaTeX input
  • No SVG output support
  • Smaller set of supported LaTeX commands

MathJax

• Pros:
  • Comprehensive LaTeX support
  • Supports both LaTeX and MathML input
  • Can output to SVG, HTML, and MathML
  • More extensive macro support
• Cons:
  • Slower rendering compared to KaTeX
  • Larger output size

Development

Project Structure

MathJaxConverter/
├── server.js           # Main server with routing logic
├── Katex_Server.js     # KaTeX renderer module
├── MathJax_Server.js   # MathJax renderer module
├── package.json        # Dependencies and scripts
├── gulpfile.js        # Build configuration
└── README.md          # This file

Build Package

npm run build

Testing

You can test the API using curl:

# LaTeX to MathML using KaTeX
curl -X POST http://localhost:1337 \
  -H "Content-Type: application/json" \
  -d '{"from":"latex","to":"mathml","latex":"x^2","renderer":"katex"}'

# LaTeX to SVG using MathJax
curl -X POST http://localhost:1337 \
  -H "Content-Type: application/json" \
  -d '{"from":"latex","to":"svg","latex":"\\sum_{i=1}^n i","renderer":"mathjax"}'

Dependencies

• katex: Fast math rendering library
• mathjax-node: Server-side MathJax for comprehensive math rendering
• html-entities: HTML entity encoding/decoding
• gulp: Build automation (dev dependency)

License

MIT

Author

AchieveAI

Contributors

• Mohammed

Support

For support, email [email protected] or visit https://achieve.ai