A macro for writing HTML templates.

This crate, along with its sister maud_macros, lets you generate HTML markup from within Rust. It exposes a single macro, html!, which compiles your markup to specialized Rust code.

Dependencies

To get started, add maud and maud_macros to your Cargo.toml:

[dependencies]
# ...
maud = "*"
maud_macros = "*"

Example

#![feature(plugin)]
#![allow(unstable)]

extern crate maud;
#[plugin] #[no_link] extern crate maud_macros;

fn main() {
    let name = "Lyra";
    let markup = html! {
        p { "Hi, " $name "!" }
    };
    assert_eq!(markup.render(), "<p>Hi, Lyra!</p>");
}

Syntax

Note: The markup you see below has been cleaned up a bit. In reality, Maud doesn't add extra whitespace to the HTML it generates.

Literals

html! {
    "Oatmeal, are you crazy?\n"
    "<script>alert(\"XSS\")</script>\n"
    $$"<script>alert(\"XSS\")</script>\n"
}

Oatmeal, are you crazy?
<script>alert("XSS")</script>
<script>alert("XSS")</script>

Literal strings use the same syntax as Rust. Wrap them in double quotes, and use a backslash for escapes.

By default, HTML special characters are escaped automatically. Add a $$ prefix to disable this escaping. (This is a special case of the splice syntax described below.)

Elements

html! {
    h1 "Pinkie's Brew"
    p {
        "Watch as I work my gypsy magic"
        br /
        "Eye of a newt and cinnamon"
    }
    p small em "squee"
}

<h1>Pinkie's Brew</h1>
<p>
  Watch as I work my gypsy magic
  <br>
  Eye of a newt and cinnamon
</p>
<p><small><em>squee</em></small></p>

Write an element using curly braces (p {}).

Terminate a void element using a slash (br /).

If the element has only a single child, you can omit the brackets (h1 "Pinkie's Brew"). This shorthand works with nested elements too.

Attributes

html! {
    form method="POST" {
        label for="waffles" "Do you like waffles?"
        input name="waffles" type="checkbox" checked=! /
    }
}

<form method="POST">
  <label for="waffles">Do you like waffles?</label>
  <input name="waffles" type="checkbox" checked>
</form>

Add attributes using the syntax attr="value". Attributes must be quoted: they are parsed as string literals.

To declare an empty attribute, use ! for the value: checked=!.

Splices

let best_pony = "Pinkie Pie";
let numbers = [1, 2, 3, 4];
let secret_message = "Surprise!";
let pre_escaped = "<p>Pre-escaped</p>";
html! {
    h1 { $best_pony " says:" }
    p {
        "I have " $numbers.len() " numbers, "
        "and the first one is " $numbers[0]
    }
    p title=$secret_message {
        "1 + 1 = " $(1 + 1)
    }
    $$pre_escaped
}

<h1>Pinkie Pie says:</h1>
<p>I have 4 numbers, and the first one is 1</p>
<p title="Surprise!">1 + 1 = 2</p>
<p>Pre-escaped</p>

Use $(expr) syntax to splice a Rust expression into the output. The expression may evaluate to anything that implements std::fmt::Display.

You can omit the brackets if it's just a variable ($var), indexing operation ($var[0]), method call ($var.method()), or property lookup ($var.property).

As with literals, expression values are escaped by default. Use a $$ prefix to disable this behavior.