LaTeX Engine - GitHub Template Repository

A professional LaTeX document compilation template using Docker and GitHub Actions. Use this as a starting point for your own LaTeX projects with automated PDF generation.

🎯 What is This?

This is a GitHub template repository that provides:

• Docker-based LaTeX compilation (no local installation needed)
• Automated PDF generation via GitHub Actions
• Cross-platform support (Windows, macOS, Linux)
• Pre-configured with common LaTeX packages

📄 Document

The main LaTeX document is in main.tex and the compiled PDF is available as main.pdf.

🚀 Using This Template

1. Click "Use this template" button on GitHub
2. Create your new repository
3. Clone it locally
4. Edit main.tex with your content
5. Push to GitHub or compile locally with Docker

⚡ Quick Start

View the Example PDF

Check out main.pdf to see what this template produces. It includes:

• Repository documentation
• Mathematical examples (partial differential equations)
• Demonstration of LaTeX capabilities

🛠️ Compilation Methods

Option 1: Using Docker (Recommended)

Build and run the Docker container to compile the PDF:

# Build the Docker image
docker build -t latex-compiler .

# Run the container to compile the PDF
docker run --rm -v ${PWD}:/workspace latex-compiler

# The PDF will be generated as main.pdf in your current directory

For PowerShell (Windows):

# Build the Docker image
docker build -t latex-compiler .

# Run the container to compile the PDF
docker run --rm -v "%CD%"/workspace latex-compiler

# The PDF will be generated as main.pdf in your current directory

Option 2: Using GitHub Actions (Automatic)

GitHub Actions automatically compiles the PDF whenever you push changes to main.tex:

1. Make changes to main.tex
2. Commit and push to the main or master branch
3. GitHub Actions will automatically:
   • Compile the LaTeX document
   • Generate main.pdf
   • Commit the PDF back to the repository

You can view the workflow progress in the Actions tab of this repository.

Option 3: Local LaTeX Installation

If you have LaTeX installed locally:

pdflatex -interaction=nonstopmode main.tex

You may need to run it twice to resolve all references:

pdflatex -interaction=nonstopmode main.tex
pdflatex -interaction=nonstopmode main.tex

📦 Required LaTeX Packages

The document uses the following LaTeX packages:

• geometry
• setspace
• titlesec
• hyperref
• enumitem
• graphicx
• array
• longtable
• booktabs
• xcolor

These are included in most standard LaTeX distributions (TeX Live, MiKTeX) and in the Docker image.

🤖 GitHub Actions Workflow

The repository includes an automated workflow (.github/workflows/compile-pdf.yml) that:

• Triggers on push to main/master branch when .tex files change
• Compiles the LaTeX document to PDF
• Commits the updated PDF back to the repository
• Can be manually triggered via the Actions tab

📝 Making Changes

1. Edit main.tex with your changes
2. (Optional) Test compilation locally using Docker or LaTeX
3. Commit and push to the repository
4. GitHub Actions will automatically generate the updated PDF

🐛 Troubleshooting

Docker compilation fails

• Ensure Docker is installed and running
• Check that you have sufficient disk space
• Verify the Dockerfile syntax

GitHub Actions fails

• Check the Actions tab for error logs
• Ensure the repository has write permissions for GitHub Actions
• Verify that main.tex is valid LaTeX syntax

LaTeX compilation errors

• Review the error messages in the terminal/logs
• Common issues:
  • Missing packages: Install required LaTeX packages
  • Syntax errors: Check brackets, braces, and special characters
  • Encoding issues: Ensure UTF-8 encoding

📄 License

This specification document is proprietary to the IsiZulu Vocabulary App project.

📧 Contact

For questions about this specification, please contact the development team.

---

Last Updated: December 22, 2025