MathJaxSwift converts and renders math expressions in Swift by incorporating MathJax1 source code and using the JavaScriptCore framework. It wraps the MathJax conversion processes in convenient JavaScript methods described here and exposes them to Swift without using WebKit.
Add the dependency to your package manifest file.
.package(url: "https://github.com/colinc86/MathJaxSwift", from: "3.5.0")Import the package, create a MathJax instance, and convert an input string to a supported output format.
import MathJaxSwift
do {
let mathjax = try MathJax()
let svg = try mathjax.tex2svg("\\text{Hello}, \\TeX{}!")
}
catch {
print("MathJax error: \(error)")
}The example above converts the TeX input to SVG data that renders the following PNG. See the example section for more details.
MathJaxSwift implements the following methods to convert TeX, MathML, and AsciiMath to CommonHTML, MathML, SVG, and speech text.
| Method | Input Format | Output Format |
|---|---|---|
tex2chtml |
TeX | cHTML |
tex2mml |
TeX | MathML |
tex2svg |
TeX | SVG |
tex2speech |
TeX | Speech text |
mml2chtml |
MathML | cHTML |
mml2svg |
MathML | SVG |
mml2speech |
MathML | Speech text |
am2chtml |
AsciiMath | cHTML |
am2mml |
AsciiMath | MathML |
am2svg |
AsciiMath | SVG |
am2speech |
AsciiMath | Speech text |
Initializing an instance of MathJax should not be performed on the main queue to prevent blocking of the UI. You should also attempt to keep a single reference to an instance and submit your function calls to it instead of creating a new MathJax instance each time you need to convert.
import MathJaxSwift
class MyModel {
let mathjax: MathJax
init() throws {
mathjax = try MathJax()
}
func convertTex(_ input: String) throws -> String {
return try mathjax.tex2chtml(input)
}
}You can submit more than a single input string for conversion.
do {
// Some input array of TeX strings
let input: [String] = [ ... ]
// Convert each string in the input array
let responses = try mathjax.tex2svg(input)
for response in responses {
if let error = response.error {
print("Error converting input value: \(error)")
}
else {
print("Got response value: \(response.value)")
}
}
}
catch {
print("MathJax error: \(error)")
}The MathJax instance will return an array of Response types with errors parsed from the response's value and set on the error property.
Each of the methods are also available with an async implementation.
func myAsyncMethod() async throws {
let mml = try await mathjax.tex2mml("\\frac{2}{3}")
print(mml)
}<math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
<mfrac>
<mn>2</mn>
<mn>3</mn>
</mfrac>
</math>You can specify which queue to execute on when calling async methods. The instance will use the .global() queue by default.
func myAsyncMethod() async throws {
let mml = try await mathjax.tex2mml("\\frac{2}{3}", queue: myQueue)
}MathJaxSwift loads all of the necessary JavaScript in to its context to run all of the conversion methods. In the case that you only want to utilize a subset of the package's output formats, you can instruct the MathJax instance to only initialize with your preferred output formats.
do {
// Save some time and don't load the SVG output format.
let mathjax = try MathJax(preferredOutputFormats: [.chtml, .mml])
// Or load speech support along with MML (needed for tex2speech/am2speech).
let speechJax = try MathJax(preferredOutputFormats: [.mml, .speech])
}
catch {
print("Error initializing MathJax: \(error)")
}The benefit of this approach is that, instead of loading all of the necessary JavaScript in to the instance's context upon initialization, it loads the preferred output formats immediately, and then lazily loads any JavaScript in the future that may be required to execute a conversion method.
do {
// We _think_ we only need CommonHTML, so save some time by only loading that
// output format.
let mathjax = try MathJax(preferredOutputFormat: .chtml)
// It's ok to call `tex2mml` even though we set our preferred output format to
// `chtml`!
let mml = try mathjax.tex2mml("\\text{Hello}, \\TeX{}!")
}
catch {
print("MathJax error: \(error)")
}See the Notes section for more details.
MathJaxSwift can convert math expressions to spoken text using the Speech Rule Engine (SRE). This is useful for accessibility and text-to-speech applications.
do {
let mathjax = try MathJax(preferredOutputFormats: [.mml, .speech])
let speech = try mathjax.tex2speech("\\frac{2}{3}")
print(speech) // "two thirds"
let speech2 = try mathjax.tex2speech("x^2 + y^2 = z^2")
print(speech2) // "x squared plus y squared equals z squared"
}
catch {
print("Error: \(error)")
}Speech conversion works by first converting the input to MathML, then passing it through SRE. You can also convert MathML directly:
let mml = try mathjax.tex2mml("\\sqrt{2}")
let speech = try mathjax.mml2speech(mml) // "StartRoot 2 EndRoot"Note: The speech output format must be included in
preferredOutputFormats(or it will be loaded lazily on first use). The.mmlformat is also required since speech conversion uses MathML as an intermediate step for TeX and AsciiMath input.
Document options let you control the document created by MathJax. They apply to every conversion method and let you specify MathJax document-specific options.
// Add to the `skipHtmlTags` array.
var docOptions = DocumentOptions()
docOptions.skipHtmlTags.append("example")
// Process the input using the new options
let output = try! tex2chtml("\\text{Hello, }$\\LaTeX$\\text{!}", documentOptions: docOptions)These options, as with document options, apply to to every conversion method. Although, the options' display property only pertains to methods that take TeX input. They let you set input conversion options such as em and ex sizes, container and line widths, and scale.
// Process the TeX input as a block instead of inline
let convOptions = ConversionOptions(display: true)
let output = try! tex2chtml("\\text{Hello, }$\\LaTeX$\\text{!}", conversionOptions: convOptions)The input and output of each of the conversion methods is configurable through various processor options. For example, if you are calling the tex2svg conversion method, then you can configure the input and output with TexInputProcessorOptions and SVGOutputProcessorOptions, respectively.
let inputOptions = TexInputProcessorOptions(processEscapes: true)
let outputOptions = SVGOutputProcessorOptions(displayIndent: 0.5)
let svg = try! mathjax.tex2svg("\\text{Hello, }\\LaTeX\\text{!}", inputOptions: inputOptions, outputOptions: outputOptions)Each of the conversion methods are throwing methods, but you can also catch errors from MathJax using options.
let documentOptions = DocumentOptions { doc, math, err in
// Do something with the compile error...
}, typesetError: { doc, math, err in
// Do something with the typeset error...
}
let inputOptions = TexInputProcessorOptions { jax, err in
// Do something with the TeX format error...
}To check the version of MathJax that has been loaded, use the static metadata() throws method.
do {
let metadata = try MathJax.metadata()
print(metadata.version)
}
catch {
print("Error getting MathJax version: \(error)")
}You can also use the returned metadata to check the MathJax node module's URL and its SHA-512.
The following example class shows how to
- create a
MathJaxinstance, - set the preferred output to
SVG, - create input, output and conversion options,
- and render the SVG output string from TeX input.
class EquationRenderer {
// A reference to our MathJax instance
private var mathjax: MathJax
// The TeX input processor options - load all packages.
private let inputOptions = TeXInputProcessorOptions(loadPackages: TeXInputProcessorOptions.Packages.all)
// The SVG output processor options - align our display left.
private let outputOptions = SVGOutputProcessorOptions(displayAlign: SVGOutputProcessorOptions.DisplayAlignments.left)
// The conversion options - use block rendering.
private let convOptions = ConversionOptions(display: true)
init() throws {
// We only want to convert to SVG
mathjax = try MathJax(preferredOutputFormat: .svg)
}
/// Converts the TeX input to SVG.
///
/// - Parameter texInput: The input string.
/// - Returns: SVG file data.
func convert(_ texInput: String) async throws -> String {
return try await mathjax.tex2svg(
texInput,
conversionOptions: convOptions,
inputOptions: inputOptions,
outputOptions: outputOptions)
}
}To use the class you could do something like:
let renderer = try EquationRenderer()
let svg = try await renderer.convert("$\\text{Hello, }\\TeX$!")The classes unique to this package (namely MathJax) should be well documented. Documentation about the MathJax options and conversion processes is not included.
Please refer to the official MathJax Documentation for more information.
To get around the limitations of the JSContext class, the package uses Webpack to create bundle files that can be evaluated by the context. The wrapper methods, MathJax, and Webpack dependencies are bundled together in an npm module called mjn.
mjn's main entry point is index.js which exposes the converter classes and functions that utilize MathJax. The files are packed with Webpack and placed in to the mjn/dist/ directory. chtml.bundle.js, mml.bundle.js, and svg.bundle.js files are loaded by the Swift package's module and evaluated by a JavaScript context to expose the functions. The speech.bundle.js file is built separately via node build-speech.js and bundles the Speech Rule Engine with xmldom polyfills for headless JSContext operation.
After making modifications to the converters, rebuild with npm run build executed in the mjn directory for the main bundles, and node build-speech.js for the speech bundle.