Leva

A Rust-based tool (CLI app) for generating and compiling LaTeX documents dynamically using TOML configuration files and Tera templates. This tool supports XeLaTeX and LuaLaTeX for PDF generation and includes features like file watching for automatic recompilation.

About

Leva, [abbreviation from German] LaTex Erweiterung zur Vorlage Arbeitsweise, is an attempt to extend LaTex towards even further separation of typesetting semantics from content-related semantics. Leva-rs is a command-line application which implements the first draft of LEVA in Rust.

This tool is designed to automate collaboration between a designer and author, with the presumption that the designer works on providing the LaTex preamble and a few required values to be supplied with a TOML document, while the author provides the content and supplies all the information related to the content [meta-date] via the TOML document. Even if you're not working in a collaborative setting, or within different agencies: using this tool as a writer you can focus on writing the content, which is the primary concern of an author, and as a designer focus on typesetting aspect of the via a template, which is the primary concern of a typesetter.

Features

• Dynamic LaTeX Generation: Use TOML configuration files and Tera templates to generate .tex files.
• PDF Compilation: Compile LaTeX documents to PDF using XeLaTeX or LuaLaTeX.
• File Watching: Automatically recompile documents when changes are detected in the source files.
• Auxiliary File Cleaning: Optionally clean up auxiliary files generated during LaTeX compilation.

Installation

Prerequisites

• Rust: Ensure you have Rust installed. If not, follow the instructions at rustup.rs.
• LaTeX: Install a LaTeX distribution like TeX Live or MiKTeX.

Detail

To use this application, you need to have Rust installed on your system. If you don't have Rust installed, you can follow the official installation guide at https://www.rust-lang.org/tools/install.

In order to compile LaTeX documents, you need to have XeLaTeX or LuaLaTeX installed on your system. These LaTeX engines are not bundled with the application and need to be installed separately. Please make sure you have either XeLaTeX or LuaLaTeX installed and available in your system's PATH before using the press or watch commands.

To install XeLaTeX, you can refer to the official documentation at https://tug.org/xetex/.

To install LuaLaTeX, you can refer to the official documentation at http://www.luatex.org/.

Install via Cargo

Once Rust is installed, you can install the tool directly from crates.io (once published):

cargo install leva

Build from source

Once Rust is installed, you can clone the repository and build the application using the following commands:

git clone <repository-url>
cd <repository-name>
cargo build --release

The built binary will be located in the target/release directory.

Note: Make sure to install the appropriate LaTeX engine based on your requirements and system compatibility.

Usage

Commands

The application provides the following commands:

1. bind: Generate a .tex file from a template and TOML configuration.
2. press: Compile the generated .tex file to PDF using XeLaTeX or LuaLaTeX.
3. watch: Watch for changes in the source files and automatically recompile the document.

Example Workflow

1. Create a TOML Configuration File (config.toml):

   template = "./template.tex"
   content = "./content.tex"
   output = "./output.tex"
   

2. Generate the LaTeX File:

   latex-generator bind ./config.toml
   

   This will generate output.tex based on the provided template and content.

3. Compile to PDF:

   latex-generator press ./config.toml --xelatex
   

   This will compile output.tex to output.pdf using XeLaTeX.

4. Watch for Changes:

   latex-generator watch ./config.toml ./ --xelatex
   

   This will watch the current directory for changes and automatically recompile the document when changes are detected.

Command-Line Options

bind

• config: Path to the TOML configuration file (required).

press

• config: Path to the TOML configuration file (required).
• --xelatex: Use XeLaTeX for compilation.
• --lualatex: Use LuaLaTeX for compilation.
• --auxiliary: Do not clean up auxiliary files.

watch

• config: Path to the TOML configuration file (required).
• directory: Path to the directory to watch for changes (required).
• --xelatex: Use XeLaTeX for compilation.
• --lualatex: Use LuaLaTeX for compilation.

Commands in-depth

Bind

This command generates the LaTeX document by binding the template and content files together through Tera template engine; It requires a TOML configuration file with the following minimal content:

template = "./vorlage.tex" # Default value
content = "./inhalt.tex" # Default value
output = "./output.tex" # Default value

For an example for how to take advantage of Tera, please see the example directory.

To use the bind command, run the following command:

./<binary-name> bind <config-file>

Replace <binary-name> with the name of the built binary and <config-file> with the path to the TOML configuration file.

Press

This command generates the PDF version of the output file by compiling the LaTeX document. It requires a TOML configuration file with the same content as the bind command.

To use the press command, run the following command:

./<binary-name> press <config-file> [options]

Replace <binary-name> with the name of the built binary, <config-file> with the path to the TOML configuration file, and [options] with any of the following options:

• -x, --xelatex: Compile the LaTeX document using XeLaTeX
• -l, --lualatex: Compile the LaTeX document using LuaLaTeX
• -a, --auxiliary: Do not clean up the auxiliary files of the LaTeX compiler

Watch

This command watches the specified directory for changes and automatically recompiles the document when changes are detected. It requires a TOML configuration file with the same content as the bind command.

To use the watch command, run the following command:

./<binary-name> watch <config-file> <directory> [options]

Replace <binary-name> with the name of the built binary, <config-file> with the path to the TOML configuration file, <directory> with the path to the main directory to watch for changes, and [options] with any of the following options:

• -x, --xelatex: Compile the LaTeX document using XeLaTeX
• -l, --lualatex: Compile the LaTeX document using LuaLaTeX

Configuration

TOML Configuration File

The TOML configuration file specifies the paths to the template, content, and output files:

template = "./template.tex"  # Path to the LaTeX template file
content = "./content.tex"    # Path to the content file
output = "./output.tex"      # Path to the output .tex file (optional, defaults to "output.tex")

Template and Content Files

• Template File: A LaTeX file with placeholders for dynamic content (e.g., {{ config.title }}).
• Content File: A file containing the dynamic content to be injected into the template.

Example

template.tex

\documentclass{article}
\usepackage[utf8]{inputenc}

\title{ {{ config.title }} }
\author{ {{ config.author }} }
\date{ {{ config.date }} }

\begin{document}

\maketitle

{% block content %}{% endblock %}

\end{document}

content.tex

{% extends "./template.tex" %}

{% block content %}

\section{Introduction}

This is my first Latex Document wrapped within a template proccessed by \texttt{LEVA}.

\textbf{LEVA} is simple Rust tool which proccesses LaTex files and replaces placeholders with values from a TOML file using the \texttt{tera} template engine.

\section{Testing}

Should it work now?

{% endblock %}

config.toml

template = "./template.tex"
content = "./content.tex"
output = "./output.tex"
title = "My LaTeX Document"
author = "Jane Doe"
date = "2023-10-05"

Generate and Compile

latex-generator bind ./config.toml
latex-generator press ./config.toml --xelatex

This will generate output.tex and compile it to output.pdf.

Contributing

Contributions are welcome! If you have any suggestions, bug reports, or feature requests, please open an issue or submit a pull request.

Authors

Your feedback and feature requests are highly welcomed. Especially, if you're interested in developing this project further, contact me to arrange a virtual meetup or send me a link to a streaming of your writing session.

Typesetters

The tools is designed to empower you to deliver your work to more authors, and encourage more writers to use LaTex syntax as their default, by reducing the effort and complexity in writing a preamble. Equally, if you're working interested in publishing your template open-source, let's get together.

Declarations

License and Disclaimer

This project is licensed under the AGPL-3.0-only. See the LICENSE file for details.

Copyright (C) 2025 Hossein Rezaei (pen name: Isaak Engineer)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, version 3.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Acknowledgements

This application was built using the following libraries:

• clap - Command-line argument parser for Rust
• log - Logging library for Rust
• notify - File system event notification library for Rust
• tera - Template engine for Rust
• toml - TOML configuration file parser for Rust

Contact

For any inquiries, please contact isaakengineer@schloosser.com

Artificial collaborators

The author benefitted immensely from inputs by DeepSeek both in role as a brainstorming partner and common/best practice suggestions.

The time for translating algorithm to written code in Rust programming language was heavily shortened via Copilot, and DeepSeek (partially).

Happy writing in LaTeX and rendering in PDF!