Mathyd: Easy TeX to SVG

December 5, 2021

A few weeks ago I released Mathyd, a Docker image containing an HTTP daemon which converts TeX to SVG.

Mathyd includes a minimal command-line client which reads TeX from standard input and prints the generated SVG to standard output, like so:

# set URL and HMAC secret key
# (note: replace value of MATHYD_HMAC_KEY with your own randomly
# generated one)
export MATHYD_URL="http://whatever.example.com:3000/"
export MATHYD_HMAC_KEY="2dhXA3HTmfEMq2d5"

# render output
bin/mathy < cubic.tex > cubic.svg

 

Given this input file, the command above produces the following result:

The Cubic Formula, rendered by Mathyd.

The Cubic Formula, rendered by Mathyd.

Installation

You can install and run the Mathyd Docker image with a single command:

# run mathyd as a daemon on port 3000
# (note: replace value of MATHYD_HMAC_KEY with your own randomly
# generated one)
docker run --rm -d -e MATHYD_HMAC_KEY="2dhXA3HTmfEMq2d5" -p 3000:3000 pablotron/mathyd:latest

 

Notes:

  • Be sure to generate your own HMAC secret key rather than reusing the key from the examples above.
  • Don’t expose Mathyd via a publicly-accessible URL; it does not support TLS and MathJax may use a lot of memory for large input files. If you really do want to do this, then you’ll need to proxy the Mathyd endpoint behind Apache or nginx on an authenticated, TLS-encrypted URL.

Technical Details

Under the hood, Mathyd is just:

  1. a container running an Express HTTP daemon that exposes a single endpoint that accepts a PUT request containing:

    • A JSON-encoded body of input parameters.
    • A hex-encoded, SHA-256 HMAC of the body and the HMAC secret key in the x-mathyd-hmac-sha256 header.

    The endpoint does the following:

    1. Verifies the body HMAC.
    2. Parses the JSON body and extracts the input parameters, including the source TeX.
    3. Converts the input TeX to SVG (via MathJax).
    4. Returns a JSON-encoded response containing the generated SVG.

  2. A command-line client, written in Ruby, which:

    1. Reads TeX from standard input and serializes it as JSON.
    2. Sends a PUT request to the Mathyd daemon and parses the response.
    3. Extracts the generated SVG from the response and writes it to standard output.

Rationale

I wanted an easy way to generate static math SVGs for web pages from the command-line without installing a blizzard of dependencies and without requiring MathJax on the destination page.

I prefer TeX over other formats because it’s still the least-worst format for complex math formulas.

I prefer SVGs over bitmap images whenever possible because:

  • SVGs scale to any screen size and resolution. This is particularly useful for responsive design.
  • SVGs are supported by all modern browsers, including mobile browsers.

Fun fact: even the animated logo for this page is an SVG.

Note: If you want a web interface to noodle around with TeX, check out Mathy instead.