README.md

metadata

title: LaTeX Compiler
emoji: 📄
colorFrom: purple
colorTo: indigo
sdk: docker
pinned: false
license: mit
app_port: 7860

LaTeX Compiler Web App

A full-featured LaTeX compiler web application that converts LaTeX documents to PDF using pdflatex. Built with Flask backend and vanilla JavaScript frontend, deployable on Hugging Face Spaces using Docker.

Features

• 🚀 Web Interface: Upload .tex files or paste LaTeX code directly
• 📄 PDF Generation: Compile LaTeX to PDF using pdflatex
• 🔌 REST API: JSON and file upload endpoints
• 🎨 Modern UI: Responsive design with Tailwind CSS
• 🐳 Docker Ready: Easy deployment with Docker
• 🤗 Hugging Face Compatible: Ready for Hugging Face Spaces

Project Structure

latex-compiler/
├── app.py          # Flask backend server
├── index.html      # Frontend interface
├── Dockerfile      # Docker configuration
└── README.md       # This file (with HF config)

Hugging Face Spaces Deployment

Quick Deploy

1. Create a new Space:

   • Go to Hugging Face Spaces
   • Click "Create new Space"
   • Choose Docker as the SDK
   • Name your space (e.g., latex-compiler)

2. Upload files: Upload all four files to your Space:

   • README.md (this file - must include YAML frontmatter)
   • Dockerfile
   • app.py
   • index.html

3. Configuration: The YAML frontmatter at the top of this README configures your Space: ```yaml

   title: LaTeX Compiler # Your app name emoji: 📄 # Icon for your Space colorFrom: purple # Gradient start color colorTo: indigo # Gradient end color sdk: docker # REQUIRED: Use Docker SDK pinned: false # Pin to your profile license: mit # License type app_port: 7860 # REQUIRED: Port your app runs on

4. Wait for build:

   • Hugging Face will automatically build your Docker image
   • This takes 10-15 minutes due to texlive-full installation
   • Watch the build logs in the "Logs" tab
   • Once complete, your app will be live!

5. Access your Space:

   • Your app will be available at: https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

Important Notes for Hugging Face

• ✅ Port 7860 is REQUIRED - Hugging Face Spaces expects this port
• ✅ Docker SDK is REQUIRED - Must be specified in YAML frontmatter
• ✅ README.md must have YAML frontmatter - Configuration at the top of this file
• ⚠️ Build time is long (~10-15 min) due to texlive-full package size
• ⚠️ First compile may be slower as LaTeX initializes fonts

Local Development

Prerequisites

• Docker installed on your system
• OR Python 3.8+ and texlive-full for non-Docker setup

Run with Docker (Recommended)

1. Build the Docker image:

   docker build -t latex-compiler .
   

2. Run the container:

   docker run -p 7860:7860 latex-compiler
   

3. Access the application: Open your browser and navigate to http://localhost:7860

Run without Docker (Local Development)

1. Install dependencies:

   # Ubuntu/Debian
   sudo apt-get update
   sudo apt-get install python3 python3-pip texlive-full latexmk
   
   # macOS
   brew install python texlive
   
   # Install Python packages
   pip3 install flask flask-cors
   

2. Run the application:

   python3 app.py
   

3. Access the application: Open your browser and navigate to http://localhost:7860

API Documentation

Endpoints

POST /compile

Compile LaTeX code to PDF.

Request Method 1: JSON

curl -X POST http://localhost:7860/compile \
  -H "Content-Type: application/json" \
  -d '{"code": "\\documentclass{article}\\begin{document}Hello World\\end{document}"}' \
  --output output.pdf

Request Method 2: File Upload

curl -X POST http://localhost:7860/compile \
  -F "file=@document.tex" \
  --output output.pdf

Success Response:

• Status: 200 OK
• Content-Type: application/pdf
• Body: PDF binary data

Error Response:

• Status: 400 Bad Request
• Content-Type: application/json

{
  "error": "Compilation failed",
  "log": "LaTeX error log details..."
}

GET /

Serves the web frontend interface.

GET /docs

Displays comprehensive API documentation.

Usage Examples

Python Example

import requests

latex_code = r"""
\documentclass{article}
\usepackage[utf8]{inputenc}

\title{My Document}
\author{John Doe}

\begin{document}
\maketitle

\section{Introduction}
This is a sample document.

\end{document}
"""

response = requests.post(
    'http://localhost:7860/compile',
    json={'code': latex_code}
)

if response.status_code == 200:
    with open('output.pdf', 'wb') as f:
        f.write(response.content)
    print("PDF created successfully!")
else:
    print("Error:", response.json())

JavaScript Example

const latexCode = `
\\documentclass{article}
\\begin{document}
Hello from JavaScript!
\\end{document}
`;

fetch('http://localhost:7860/compile', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({ code: latexCode })
})
.then(response => response.blob())
.then(blob => {
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'output.pdf';
    a.click();
});

File Upload Example

import requests

with open('document.tex', 'rb') as f:
    files = {'file': f}
    response = requests.post(
        'http://localhost:7860/compile',
        files=files
    )

if response.status_code == 200:
    with open('output.pdf', 'wb') as f:
        f.write(response.content)

Using on Hugging Face Spaces

import requests

# Replace with your actual Space URL
SPACE_URL = "https://YOUR_USERNAME-latex-compiler.hf.space"

latex_code = r"""
\documentclass{article}
\begin{document}
Hello from Hugging Face!
\end{document}
"""

response = requests.post(
    f'{SPACE_URL}/compile',
    json={'code': latex_code}
)

if response.status_code == 200:
    with open('output.pdf', 'wb') as f:
        f.write(response.content)

Features & Limitations

Supported

✅ Standard LaTeX packages (texlive-full includes 99% of packages)
✅ Mathematical equations and symbols
✅ Tables, figures, and images (embedded)
✅ Bibliography and citations
✅ Custom document classes
✅ Multiple compilation passes (handled automatically)

Limitations

⚠️ Compilation timeout: 30 seconds
⚠️ Recommended file size: < 10MB
⚠️ Only pdflatex engine (XeLaTeX and LuaLaTeX not included)
⚠️ No support for external file dependencies (images must be embedded or base64)

Troubleshooting

Common Errors

"Compilation failed"

• Check your LaTeX syntax
• View the error log in the web interface
• Ensure all required packages are declared

"Compilation timeout"

• Your document is too complex
• Try simplifying or splitting into smaller documents

"No file selected"

• Ensure you've selected a .tex file before clicking compile

Docker Build Issues

Build fails due to texlive-full size:

# Increase Docker memory limit in Docker Desktop settings
# Recommended: 4GB+ RAM, 10GB+ disk space

Port 7860 already in use:

# Use a different port locally
docker run -p 8080:7860 latex-compiler
# Then access at http://localhost:8080

Hugging Face Spaces Issues

Space stuck in "Building" state:

• Check the build logs for errors
• Ensure Dockerfile is correct
• Verify all files are uploaded
• texlive-full installation takes 10-15 minutes (this is normal)

Space shows "Application Error":

• Check that app_port: 7860 is in README.md frontmatter
• Verify Flask app runs on host 0.0.0.0 and port 7860
• Review Space logs for Python errors

"Connection refused" errors:

• Ensure EXPOSE 7860 is in Dockerfile
• Verify app.run(host='0.0.0.0', port=7860) in app.py

Technical Stack

• Backend: Flask 3.x (Python)
• Frontend: Vanilla JavaScript + Tailwind CSS
• LaTeX Engine: pdflatex (TeX Live 2022)
• Containerization: Docker (Ubuntu 22.04 base)
• Deployment: Hugging Face Spaces (Docker SDK)

Environment Variables (Optional)

You can customize the app with environment variables:

# In Hugging Face Spaces, add these in Settings > Variables
FLASK_ENV=production
MAX_CONTENT_LENGTH=10485760  # 10MB limit

License

MIT License - feel free to use and modify!

Contributing

Contributions welcome! Areas for improvement:

• Add XeLaTeX/LuaLaTeX support
• Implement file caching for faster recompilation
• Add syntax highlighting in code editor
• Support for multi-file LaTeX projects
• Real-time preview with live updates
• Integration with Overleaf-style collaborative editing

Support

• Hugging Face Discussions: Use the Community tab on your Space
• Issues: Report bugs via GitHub or Space discussions
• Documentation: Visit /docs endpoint for API reference
• Examples: Check the Usage Examples section above

Acknowledgments

• Built for the LaTeX community
• Powered by TeX Live and Flask
• Hosted on Hugging Face Spaces

---

Need help? Visit the /docs endpoint or check Hugging Face Spaces documentation at https://huggingface.co/docs/hub/spaces-overview