markup.rs

A blazing fast, type-safe template engine for Rust.

markup.rs is a template engine for Rust powered by procedural macros which parses the template at compile time and generates optimal Rust code to render the template at run time. The templates may embed Rust code which is type checked by the Rust compiler enabling full type-safety.

Features

Fully type-safe with inline highlighted errors when using editor extensions like rust-analyzer.
Less error-prone and terse syntax inspired by Haml, Slim, and Pug.
Zero unsafe code.
Zero runtime dependencies.
⚡ Blazing fast. The fastest in this benchmark among the ones which do not use unsafe code, the second fastest overall.

Install

[dependencies]
markup = "0.15.0"

Framework Integration

We have integration examples for the following web frameworks:

Axum
Rocket

Quick Example

markup::define! {
    Home<'a>(title: &'a str) {
        @markup::doctype()
        html {
            head {
                title { @title }
                style {
                    "body { background: #fafbfc; }"
                    "#main { padding: 2rem; }"
                }
            }
            body {
                @Header { title }
                #main {
                    p {
                        "This domain is for use in illustrative examples in documents. You may \
                        use this domain in literature without prior coordination or asking for \
                        permission."
                    }
                    p {
                        a[href = "https://www.iana.org/domains/example"] {
                            "More information..."
                        }
                    }
                }
                @Footer { year: 2020 }
            }
        }
    }

    Header<'a>(title: &'a str) {
        header {
            h1 { @title }
        }
    }

    Footer(year: u32) {
        footer {
            "(c) " @year
        }
    }
}

fn main() {
    println!(
        "{}",
        Home {
            title: "Example Domain"
        }
    )
}

Output

<!DOCTYPE html><html><head><title>Example Domain</title><style>body { background: #fafbfc; }#main { padding: 2rem; }</style></head><body><header><h1>Example Domain</h1></header><div id="main"><p>This domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission.</p><p><a href="https://www.iana.org/domains/example">More information...</a></p></div><footer>(c) 2020</footer></body></html>

Output (manually prettified)

<!doctype html>
<html>
  <head>
    <title>Example Domain</title>
    <style>
      body {
        background: #fafbfc;
      }
      #main {
        padding: 2rem;
      }
    </style>
  </head>
  <body>
    <header><h1>Example Domain</h1></header>
    <div id="main">
      <p>
        This domain is for use in illustrative examples in documents. You may
        use this domain in literature without prior coordination or asking for
        permission.
      </p>
      <p>
        <a href="https://www.iana.org/domains/example">More information...</a>
      </p>
    </div>
    <footer>(c) 2020</footer>
  </body>
</html>

Syntax Reference (WIP)

markup::define! and markup::new!

There are two ways to define templates: markup::define! and markup::new!.

markup::define! defines a template with named arguments. These templates cannot access variables from outer scope. The templates can have generic parameters. Under the hood, markup::define! compiles to a Rust struct that implements markup::Render and std::fmt::Display traits.

Code
markup::define! { Hello<'a>(name: &'a str) { "Hello, " @name "!" } HelloGeneric<T: std::fmt::Display>(name: T) { "Hello, " @name.to_string() "!" } } // The template can now be printed directly or written to a stream: println!("{}", Hello { name: "World" }); writeln!(&mut std::io::stdout(), "{}", HelloGeneric { name: "World 2" }).unwrap(); // The template can also be rendered to a String: let string = Hello { name: "World 3" }.to_string(); println!("{}", string);
Output
Hello, World! Hello, World 2! Hello, World 3!

Code

markup::define! {
    Hello<'a>(name: &'a str) {
        "Hello, " @name "!"
    }
    HelloGeneric<T: std::fmt::Display>(name: T) {
        "Hello, " @name.to_string() "!"
    }
}

// The template can now be printed directly or written to a stream:
println!("{}", Hello { name: "World" });
writeln!(&mut std::io::stdout(), "{}", HelloGeneric { name: "World 2" }).unwrap();

// The template can also be rendered to a String:
let string = Hello { name: "World 3" }.to_string();
println!("{}", string);

Output

Hello, World!
Hello, World 2!
Hello, World 3!

markup::new! defines a template without any arguments. These can access variables from outer scope.

Code
let name = "World"; let template = markup::new! { "Hello, " @name "!" }; // The template can now be printed directly or written to a stream: println!("{}", template); writeln!(&mut std::io::stdout(), "{}", template).unwrap(); // The template can also be rendered to a String: let string = template.to_string(); println!("{}", string);
Output
Hello, World! Hello, World! Hello, World!

Code

let name = "World";
let template = markup::new! {
    "Hello, " @name "!"
};

// The template can now be printed directly or written to a stream:
println!("{}", template);
writeln!(&mut std::io::stdout(), "{}", template).unwrap();

// The template can also be rendered to a String:
let string = template.to_string();
println!("{}", string);

Output

Hello, World!
Hello, World!
Hello, World!

Expressions

Templates can have bare literal values, which are rendered as is. They can also have expressions (including function and macro calls) preceded by @ sign. All strings are HTML-escaped unless they are wrapped in markup::raw().

Code
markup::define! { Expressions(a: i32, b: i32) { 1 " + " 2 " = " @{1 + 2} '\n' @a " - " @b " = " @{a - b} '\n' @format!("{} * {} = {}", a, b, a * b) '\n' @a " ^ 4 = " @a.pow(4) '\n' // All output is escaped by default. "<>\n" // Escaping can be disabled using `markup::raw()`. @markup::raw("<div></div>") } } println!("{}", Expressions { a: 5, b: 3 });
Output
1 + 2 = 3 5 - 3 = 2 5 * 3 = 15 5 ^ 4 = 625 <> <div></div>

Code

markup::define! {
    Expressions(a: i32, b: i32) {
        1 " + " 2 " = " @{1 + 2} '\n'
        @a " - " @b " = " @{a - b} '\n'
        @format!("{} * {} = {}", a, b, a * b) '\n'
        @a " ^ 4 = " @a.pow(4) '\n'

        // All output is escaped by default.
        "<>\n"
        // Escaping can be disabled using `markup::raw()`.
        @markup::raw("<div></div>")
    }
}

println!("{}", Expressions { a: 5, b: 3 });

Output

1 + 2 = 3
5 - 3 = 2
5 * 3 = 15
5 ^ 4 = 625
&lt;&gt;
<div></div>

Elements

Elements are defined using a CSS selector-like syntax. Elements can contain other nested elements in braces or be followed by a semicolon for self-closing elements.

Code
markup::define! { Elements(name: &'static str) { // Just a div. div {} '\n' // Three nested elements. main { aside { h3 { "Sidebar" } } } '\n' // Self-closing input element. input; '\n' // Element with a name containing dashes. $"my-custom-element" {} '\n' // Element with a dynamic name. ${name} {} } } println!("{}", Elements { name: "span" });
Output
<div></div> <main><aside><h3>Sidebar</h3></aside></main> <input> <my-custom-element></my-custom-element> <span></span>

Code

markup::define! {
    Elements(name: &'static str) {
        // Just a div.
        div {}
        '\n'
        // Three nested elements.
        main {
            aside {
                h3 { "Sidebar" }
            }
        }
        '\n'
        // Self-closing input element.
        input;
        '\n'
        // Element with a name containing dashes.
        $"my-custom-element" {}
        '\n'
        // Element with a dynamic name.
        ${name} {}
    }
}

println!("{}", Elements { name: "span" });

Output

<div></div>
<main><aside><h3>Sidebar</h3></aside></main>
<input>
<my-custom-element></my-custom-element>
<span></span>

Attributes

Attributes are defined after the element name. id and class attributes can be defined using CSS selector-like syntax using # and .. Classes may be specified multiple times using this shorthand syntax. Other attributes are specified in square brackets.

Code
markup::define! { Attributes(id: u32, category: String, data: std::collections::BTreeMap<String, String>) { // A div with an id and two classes. // Note: Starting with Rust 2021, there must be a space between the // element name and `#` due to reserved syntax (https://doc.rust-lang.org/edition-guide/rust-2021/reserving-syntax.html). div #foo.bar.baz {} '\n' // A div with a dynamically computed id and one static and one dynamic class. div #{format!("post-{}", id)}.post.{format!("category-{}", category)} {} '\n' // Boolean attributes are only rendered if true. Specifying no value is the same as `true`. input[checked = true]; '\n' input[checked = false]; '\n' input[checked]; '\n' // `Option` attributes are rendered only if they're `Some`. input[type = Some("text"), minlength = None::<String>]; '\n' // Attribute names can also be expressions wrapped in braces. div[{format!("{}{}", "data-", "post-id")} = id] {} '\n' // Multiple attributes can be added dynamically using the `..` syntax. div[..data.iter().map(\|(k, v)\| (("data-", k), v))] {} } } println!("{}", Attributes { id: 123, category: String::from("tutorial"), data: [ (String::from("foo"), String::from("bar")), (String::from("baz"), String::from("quux")) ].iter().cloned().collect(), });
Output
<div id="foo" class="bar baz"></div> <div id="post-123" class="post category-tutorial"></div> <input checked> <input> <input checked> <input type="text"> <div data-post-id="123"></div> <div data-baz="quux" data-foo="bar"></div>

Code

markup::define! {
    Attributes(id: u32, category: String, data: std::collections::BTreeMap<String, String>) {
        // A div with an id and two classes.
        // Note: Starting with Rust 2021, there must be a space between the
        // element name and `#` due to reserved syntax (https://doc.rust-lang.org/edition-guide/rust-2021/reserving-syntax.html).
        div #foo.bar.baz {}
        '\n'
        // A div with a dynamically computed id and one static and one dynamic class.
        div #{format!("post-{}", id)}.post.{format!("category-{}", category)} {}
        '\n'

        // Boolean attributes are only rendered if true. Specifying no value is the same as `true`.
        input[checked = true];
        '\n'
        input[checked = false];
        '\n'
        input[checked];
        '\n'

        // `Option` attributes are rendered only if they're `Some`.
        input[type = Some("text"), minlength = None::<String>];
        '\n'

        // Attribute names can also be expressions wrapped in braces.
        div[{format!("{}{}", "data-", "post-id")} = id] {}
        '\n'

        // Multiple attributes can be added dynamically using the `..` syntax.
        div[..data.iter().map(|(k, v)| (("data-", k), v))] {}
    }
}

println!("{}", Attributes {
    id: 123,
    category: String::from("tutorial"),
    data: [
        (String::from("foo"), String::from("bar")),
        (String::from("baz"), String::from("quux"))
    ].iter().cloned().collect(),
});

Output

<div id="foo" class="bar baz"></div>
<div id="post-123" class="post category-tutorial"></div>
<input checked>
<input>
<input checked>
<input type="text">
<div data-post-id="123"></div>
<div data-baz="quux" data-foo="bar"></div>

@if and @if let

@if and @if let works similar to Rust.

Code
markup::define! { If(x: u32, y: Option<u32>) { @if x == 1 { "x = 1\n" } else if x == 2 { "x = 2\n" } else { "x is neither 1 nor 2\n" } @if let Some(y) = y { "y = " @y "\n" } else { "y is None\n" } } } println!("{}", If { x: 2, y: Some(2) }); println!("{}", If { x: 3, y: None });
Output
x = 2 y = 2 x is neither 1 nor 2 y is None

Code

markup::define! {
    If(x: u32, y: Option<u32>) {
        @if *x == 1 {
            "x = 1\n"
        } else if *x == 2 {
            "x = 2\n"
        } else {
            "x is neither 1 nor 2\n"
        }

        @if let Some(y) = y {
            "y = " @y "\n"
        } else {
            "y is None\n"
        }
    }
}

println!("{}", If { x: 2, y: Some(2) });
println!("{}", If { x: 3, y: None });

Output

x = 2
y = 2

x is neither 1 nor 2
y is None

@match

@match works similar to Rust, but the branches must be wrapped in braces.

Code
markup::define! { Match(x: Option<u32>) { @match x { Some(1) \| Some(2) => { "x is 1 or 2" } Some(x) if *x == 3 => { "x is 3" } None => { "x is None" } _ => { "x is something else" } } } } println!("{}", Match { x: None }); println!("{}", Match { x: Some(2) }); println!("{}", Match { x: Some(4) });
Output
x is None x is 1 or 2 x is something else

Code

markup::define! {
    Match(x: Option<u32>) {
        @match x {
            Some(1) | Some(2) => {
                "x is 1 or 2"
            }
            Some(x) if *x == 3 => {
                "x is 3"
            }
            None => {
                "x is None"
            }
            _ => {
                "x is something else"
            }
        }
    }
}

println!("{}", Match { x: None });
println!("{}", Match { x: Some(2) });
println!("{}", Match { x: Some(4) });

Output

x is None
x is 1 or 2
x is something else

@for

@for works similar to Rust.

Code
markup::define! { For<'a>(xs: &'a [u32]) { @for (i, x) in xs.iter().enumerate() { @i ": " @x "\n" } } } println!("{}", For { xs: &[1, 2, 4, 8] });
Output
0: 1 1: 2 2: 4 3: 8

Statements

Templates can have statements preceded by @ sign. The most useful such statement is @let to compute a value for later reuse. @fn can be used to define a function. Also supported are @struct, @mod, @impl, @const, @static and more.

Code
markup::define! { Statement(x: i32) { @let double_x = x * 2; @double_x '\n' @fn triple(x: i32) -> i32 { x * 3 } @triple(*x) } } println!("{}", Statement { x: 2 });
Output
4 6

franklx/markup.rs

markup.rs

Features

Install

Framework Integration

Quick Example

Output

Output (manually prettified)

Syntax Reference (WIP)

markup::define! and markup::new!

Expressions

Elements

Attributes

@if and @if let

@match

@for

Statements