alethea

Overview

alethea is a Rust templating approach designed to keep templates simple, expressive, and fully aligned with the Rust language itself.

Instead of introducing a new syntax, it allows you to write templates using native Rust constructs, reducing cognitive overhead and increasing flexibility.

Goals

Eliminate std::string-style complexity:
- Avoid manual string building (push_str, etc.) in most cases.
- Keep templates focused on structure rather than concatenation.
Reduce the learning curve and use Rust directly inside templates:
- No new syntax to learn—just Rust.
- Avoid limitations commonly found in traditional template engines.
- Reuse existing powerful Rust features like format! and standard library utilities, including padding and alignment.
- Behavior should be predictable if you already know Rust.
Ensure compile-time template safety:
- Catch errors early during compilation.
- Enable more reliable and maintainable templates.
Treat input data as read-only:
- Templates should not modify their inputs.
- Any attempt to mutate inputs will fail at compile time.
Keep composition simple:
- Provide clear and straightforward template inheritance.
- Support nested templates for better structure and reuse.

Quick Start

Add alethea to your Cargo.toml:

[dependencies]
alethea = "0.1.0"

HTML Template Definition Example

use alethea::{append_to_template, new_template};

new_template! {
    animals_html(animals) {
        append_to_template! {
r#"
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Pet Cards</title>
        <script src="https://cdn.tailwindcss.com"></script>
    </head>
    <body class="bg-gray-100 p-10">
        <h1 class="text-3xl font-bold text-center mb-10">Our Pets</h1>
        <div class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-6">
"#
        }

        for animal in $animals.iter() {
            append_to_template! {
                format!(
r#"
            <!-- Card -->
            <div class="bg-white rounded-xl shadow-md overflow-hidden hover:shadow-xl transition">
                <img class="w-full h-40 object-cover" src="{}" alt="Animal">
                <div class="p-4">
                    <h2 class="text-lg font-semibold">{}</h2>
                    <p class="text-gray-500 text-sm mb-2">{}</p>
                    <p class="text-gray-600 text-sm mb-4">{}</p>
                    <button class="bg-green-500 text-white px-4 py-2 rounded-lg hover:bg-green-600">
                        Adopt
                    </button>
                </div>
            </div>
"#,
                    animal.image_url, animal.species, animal.description, animal.name)
            }
        }

        append_to_template! {
r#"
        </div>
    </body>
</html>
"#
        }
    }
}

/*
    Usage example :
    
    let animal_html = animals_html!(animals: animals);

    // Write the string directly to the file, panic on error
    fs::write(
        "examples/htmlgen_basic/output_html/animals.html",
        &animal_html,
    )
    .unwrap();

*/

Examples

For more complete and advanced use cases (including template inheritance), check the repository.

The examples/ directory contains small projects demonstrating how to use alethea in real scenarios, including:

Web frameworks like Axum, Actix, and Rocket
Standalone HTML rendering
File generation

Running an example

cargo run --manifest-path examples/<example>/Cargo.toml