mathrender 0.1.1

Convert LaTeX mathematical expressions to images for web and email

MathRender

Convert LaTeX mathematical expressions to images for web and email.

Features

• Convert LaTeX expressions to HTML with embedded images
• Secure email sending via SendGrid API (no password exposure)
• SMTP support for Gmail, Outlook, and other providers
• Automatic browser preview for easy copying
• High-quality PNG rendering of mathematical expressions
• Simple command-line interface
• Support for both inline ($...$) and display ($$...$$) math

Installation

Prerequisites

You need a LaTeX distribution and dvipng installed on your system:

Ubuntu/Debian:

sudo apt update
sudo apt install texlive-latex-base texlive-latex-extra dvipng

macOS:

# Install MacTeX or BasicTeX
brew install --cask mactex
# OR for a smaller installation:
brew install --cask basictex
sudo tlmgr update --self
sudo tlmgr install dvipng preview

Windows: Install MiKTeX which includes dvipng.

Install mathrender

pip install mathrender

Or install from source:

git clone https://github.com/yourusername/mathrender.git
cd mathrender
pip install -e .

Quick Start

SendGrid Setup (Recommended - More Secure)

1. Get a Free SendGrid Account:

   • Sign up at https://sendgrid.com (free tier: 100 emails/day)
   • Go to Settings → API Keys → Create API Key
   • Copy your API key

2. Set Environment Variable:

   export SENDGRID_API_KEY="SG.xxxxxxxxxxxxxxxxxxxx"
   

3. Send Your First Email:

   mathrender 'The equation $E = mc^2$ is revolutionary!' --sendgrid --to [e-mail]
   

That's it! No email passwords needed - just a secure API key.

Basic Usage

Convert LaTeX expressions and preview in browser:

mathrender 'The integral $$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$ is beautiful.'

This automatically:

1. Converts LaTeX expressions to images
2. Creates an HTML file with embedded images
3. Opens it in your browser
4. You can then copy and paste into Gmail

More Examples

From a file:

mathrender -f document.txt

Save as PNG:

mathrender 'Einstein showed that $E = mc^2$ revolutionized physics.' --png output.png

From stdin:

echo 'The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.' | mathrender

Generate MIME for email systems:

mathrender -f document.txt --mime

Save as .eml file (opens in email clients):

mathrender 'The equation $E = mc^2$ is famous.' --eml output.eml

Send email directly:

# SendGrid (recommended - most secure)
export SENDGRID_API_KEY="SG.xxxxxxxxxxxxxxxxxxxx"
mathrender 'Math: $E = mc^2$' --sendgrid --to [e-mail]

# Or pass API key directly
mathrender -f document.txt --sendgrid --to [e-mail] \
    --sendgrid-api-key 'SG.xxxxxxxxxxxxxxxxxxxx'

# SMTP alternatives (Gmail, Outlook, etc.)
mathrender 'Content' --send --to [e-mail] \
    --smtp-provider gmail --smtp-user [e-mail] --smtp-pass 'app-password'

Command Reference

Basic Usage

mathrender [OPTIONS] [INPUT]

Options:

• -f, --file PATH: Read input from file
• -o, --output PATH: Save output to file (MIME format)
• -p, --png PATH: Save as PNG image file
• --mime: Output MIME content instead of opening HTML
• --eml PATH: Save as .eml file that opens in email clients
• --dpi INTEGER: Image resolution (default: 110)
• --subject TEXT: Email subject line
• --from TEXT: From email address
• --to TEXT: To email address (required for sending)
• --raw: Output raw MIME without base64 encoding

Email Sending Options:

• --sendgrid: Send via SendGrid API (recommended)
• --sendgrid-api-key: SendGrid API key (or use SENDGRID_API_KEY env var)
• --send: Send via SMTP
• --smtp-provider: Use preset for gmail/outlook/yahoo/office365
• --smtp-host: Custom SMTP server hostname
• --smtp-port: Custom SMTP server port
• --smtp-user: SMTP username (usually your email)
• --smtp-pass: SMTP password (use app passwords for Gmail/Outlook)

Check Dependencies

Verify all dependencies are installed:

mathrender --check

How It Works

1. LaTeX Detection: The tool finds LaTeX expressions in your text using common delimiters:

   • Inline math: $...$ or \(...\)
   • Display math: $$...$$ or \[...\]

2. Image Generation: Each expression is:

   • Compiled with LaTeX
   • Converted to PNG with dvipng
   • Optimized for email display

3. HTML Output:

   • Creates HTML with embedded base64 images
   • Opens in your default browser
   • Ready to copy and paste

Tips for Gmail

Copy/Paste Method

1. The HTML preview opens automatically in your browser
2. Select all content (Ctrl+A or Cmd+A)
3. Copy (Ctrl+C or Cmd+C)
4. Paste into Gmail compose window
5. After pasting, you can resize images by clicking and dragging
6. The images are embedded, so recipients don't need to "load images"
7. Works with Gmail's confidential mode

Note: Gmail may strip some styling during paste operations, which can affect image alignment.

EML File Method (Recommended for Perfect Formatting)

If you experience alignment issues with copy/paste, use the .eml file approach:

mathrender 'Your text with $LaTeX$ expressions' --eml email.eml

Then:

1. Double-click the .eml file to open it in your default email client
2. The email will open with all formatting preserved
3. Add recipients and send

This method preserves all styling and ensures perfect image alignment.

Direct Email Sending (No Email Client Needed)

SendGrid API (Recommended - Most Secure)

No password exposure - just use an API key:

Quick Setup:

1. Sign up for free at https://sendgrid.com (100 emails/day free)
2. Create API key: Settings → API Keys → Create API Key
3. Set environment variable:

   export SENDGRID_API_KEY="SG.xxxxxxxxxxxxxxxxxxxx"
   

4. Send emails:

   mathrender 'Your $LaTeX$ content' --sendgrid --to [e-mail]
   

Why SendGrid?

• No password exposure (API keys can be revoked anytime)
• Better deliverability
• Free tier is generous (100 emails/day)
• No 2FA or app passwords needed

SMTP Alternative (Gmail, Outlook, etc.)

If you prefer SMTP:

mathrender 'Content' --send --to [e-mail] \
    --smtp-provider gmail --smtp-user [e-mail] --smtp-pass 'app-password'

Note: SMTP requires app passwords for Gmail/Outlook, which is less secure than API keys.

Troubleshooting

"LaTeX compilation failed"

Make sure you have the required LaTeX packages:

sudo apt install texlive-latex-extra texlive-fonts-recommended

"dvipng: command not found"

Install dvipng:

sudo apt install dvipng

Images appear too large/small

Adjust the DPI setting:

mathrender "your text" --dpi 150

Browser doesn't open automatically

The HTML file is saved to a temporary location. Look for the path in the output:

✓ HTML opened in browser: /tmp/tmpXXXXXX.html

You can manually open this file in your browser.

Development

Setup

git clone https://github.com/yourusername/mathrender.git
cd mathrender
pip install -e .

Running Tests

pytest

License

MIT License - see LICENSE file for details.