Skip to content

uwuclxdy/agenticat / skills/maud

Maud Rust `html!` macro reference (0.27).

Maud (Rust HTML Macro)

Load before writing or reviewing an html! template, a Render impl, or a web handler that returns Markup. Rules target maud 0.27.0 (released 2025-02-02); a rule marked (since x.y) does not apply on a maud pin older than x.y: write the form that version documents.

Maud is a compile-time HTML macro (html!); markup lives inline in Rust, type-checked at compile time. There are no template files.

In the code blocks a // WRONG: comment shows a stale form; the live code next to it is the form to write.

Setup

[dependencies]
maud = "0.27"
  • Runs on stable Rust (since 0.22.1) and on nightly, where error messages are better. Never add #![feature(proc_macro_hygiene)]. MSRV is not documented.
  • Default features: none. json and salvo are not features of 0.27.0 (unreleased upstream): never enable them.

Rendering API

html! { ... } returns a Markup value. Markup is a type alias for PreEscaped<String>, a wrapper around an already-escaped HTML string.

OperationResultNotes
html! { ... }MarkupThe macro takes one argument, the template.
markup.into_string()StringConsumes the Markup, hands back the built string.
(DOCTYPE) inside html!emits <!DOCTYPE html>maud::DOCTYPE is a constant holding that string.
use maud::{html, DOCTYPE}; // WRONG: use maud::html!;
let name = "Lyra";
// WRONG: html!(out, { p { "hi" } })   no buffer argument (removed in 0.11)
let page = html! {
    (DOCTYPE) // WRONG: <!DOCTYPE html>
    html {
        head { meta charset="utf-8"; title { "My site" } }
        body { p { "Hi, " (name) "!" } }
    }
};
let text: String = page.into_string(); // WRONG: page.to_html(), format!("{page}")
  • Markup has no Display impl: get the String with .into_string().
  • There is no html_to! or write-into-buffer macro, and html_debug! was removed in 0.25. To append to an existing String, call Render::render_to (see Custom Rendering and Composition).

Elements and Text

  • Element with content: name { ... }; text and nested elements go inside. Angle-bracket HTML does not parse.
  • Void element: end with ;, no body (br;). Maud emits HTML5 <br>, not <br />. br {} renders <br></br>; br /; is a compile error (since 0.23).
  • Text is a double-quoted Rust string literal with backslash escapes. Bare words, numbers (42) and chars ('a') are compile errors: quote them or splice them. Raw strings (r#"..."#) suit long or quote-heavy text.
  • Names take hyphens and colons: custom elements, data-*, ARIA, xml:lang, on:click.
  • Comment with //. <!-- --> does not parse; to emit one, splice (PreEscaped("<!-- note -->")).
  • "Type-checked" covers Rust splice types only. Maud validates no element or attribute name and no content-model nesting (a div inside a p compiles): any Rust ident compiles as a tag, typos included.
use maud::html;
let poem = html! {
    // WRONG: <h1>Poem</h1>               angle brackets
    h1 { "Poem" }
    // WRONG: p { Rock, you are a rock. }  unquoted text
    p {
        strong { "Rock," } " you are a rock."
        br; // WRONG: br {}   br /;
        "Gray, you are gray,"
    }
    link rel="stylesheet" href="poetry.css";
    pre { r#"Raw "string": no escapes needed."# }
};

Attributes

  • Value: name="value", always quoted. href=about.html does not parse. class: "x" compiles and renders a broken attribute named class:x.
  • Boolean or empty attribute: bare name (checked), no =. disabled=true is a compile error. The checked? suffix (required before 0.22.2) still parses: never write it.
  • Toggle a boolean attribute or a class with a bool in brackets: disabled[locked], p.cute[n > 50]. Never duplicate the element under @if to add or drop one.
  • Optional value (since 0.23): title=[opt] takes an Option. Some(v) renders title="v", None omits the attribute. title=(opt) does not compile. Bare [cond] toggles presence; =[opt] sets a value.
  • Class and id shorthand: .class, #id, chained (.big.scary) and mixed with named attributes. Put a space before #: input#go; fails on Rust 2021 and later.
  • No tag name before a .class or #id means div (since 0.21): write #main { ... }. div #main { ... } compiles too.
  • Quote a class name that holds a symbol or starts with a digit: ."w-1/2". A hyphenated name (.col-sm-2) needs no quotes.
  • In an edition-2024 crate (Rust 1.85) a quoted id with no space after # (#"pinkie-123") is reserved syntax and does not compile: write # "pinkie-123" or id="pinkie-123".
  • Write each named attribute once. A repeat (class="a" class="b") is no error in 0.27: both render and the browser keeps the first. Only a second #id is rejected. Merge classes instead: .a.b.
  • An attribute name that is not a Rust identifier goes in quotes (since 0.26): "@click"="open = true".
use maud::html;
let (locked, n, tip): (bool, u32, Option<&str>) = (true, 95, None);
let form = html! {
    // WRONG: a href=about.html { .. }      li class: "x" { .. }
    a href="about.html" { "About" }
    // WRONG: input disabled=true;          input checked?;
    input type="checkbox" name="cupcakes" checked;
    input type="submit" disabled[locked];
    // WRONG: input#go;                     class="big" class="scary"
    input #go .big.scary type="button" value="Launch";
    // WRONG: p title=(tip) { .. }          an Option does not splice
    p.cute[n > 50] title=[tip] { "Squee!" }
    #main {
        .tip { "No tag name: a div." }
        ."w-1/2" { "Quoted class name." }
    }
    button "@click"="open = true" { "Open" }
};

Splices

  • (expr) inserts a runtime value, HTML-escaped. It is the only interpolation: {{name}} or ${name} inside a string literal renders as that literal text.
  • A splice takes any maud::Render type (strings, integers, floats, char) and any Display type (since 0.25, still escaped). Implement Render only to override that default.
  • A splice borrows its expression: splice a String variable bare, with no .clone().
  • &T, Box<T>, Cow<str> and Arc<T> (the Arc impl since 0.26) splice as they are: no .clone() first.
  • Never call .to_string() just to splice. maud::display(x) (since 0.24) renders any value through its Display impl.
  • An Option does not splice: use @if let or attr=[opt].
  • A splice holds one expression. Statements such as let need a block: ({ let x = ..; expr }).
  • In an attribute: title=(value). To join literal and splice, wrap the parts in braces: href={ (BASE) "/path" }, no format!.
  • In an id or class: #(id), .{ "color-" (severity) }, not class=(format!(..)).
use maud::html;
const GITHUB: &str = "https://github.com";
let best_pony = "Pinkie Pie";
let numbers = [1, 2, 3, 4];
let (id, severity) = ("rarity", "critical");
let page = html! {
    // WRONG: p { "Hi, {{best_pony}}!" }    renders the braces as text
    p { "Hi, " (best_pony) "!" }
    p title=(best_pony) { "I have " (numbers.len()) " numbers, the first is " (numbers[0]) }
    p { ({ let total: i32 = numbers.iter().sum(); total * 2 }) }
    // WRONG: a href=(format!("{GITHUB}/lambda-fairy/maud")) { .. }
    a href={ (GITHUB) "/lambda-fairy/maud" } { "Fork me on GitHub" }
    aside #(id) {
        p.{ "color-" (severity) } { "This is the worst! Possible! Thing!" }
    }
};

Control Flow

  • Every control keyword takes an @ prefix: @if, @else, @for, @while, @match, @let. A bare if / for / while / match / let inside html! is a compile error.
  • Braces are mandatory on every @if, @else, @for and @while body. @else is optional.
  • Render an Option with @if let plus @else; never .unwrap() or .expect(..) inside a splice.
  • @for pat in iter { ... } loops over any iterator, a .map(..) chain after in included. Never build the items with .map(|x| html! { .. }); no {{#each}}.
  • @while cond { ... } and @while let PAT = EXPR { ... } both work (since 0.13).
  • @match arms use => and accept full Rust patterns: or-patterns (A | B), bindings, ranges, destructuring, guards (pat if cond =>). An arm body is one element, one literal, one splice, an @ control flow (@if, @for), or a { ... } block. Prefer @match over an @if / @else if chain that tests each variant.
  • @let x = expr; declares a variable inside html! (since 0.14), most useful inside loops. It accepts any Rust let pattern, type ascription included.
  • @match and @if also work as an attribute or class value, no @let detour: span class=@match n { 1 => "one", _ => "many" } { (n) }, p.@if n == 0 { "empty" } @else { "full" } { (n) }.
use maud::html;
let role = "editor";
let nick: Option<&str> = Some("Pinkie Pie");
let names = ["Applejack", "Rarity", "Fluttershy"];
let mut queue = vec![1, 2].into_iter();
let page = html! {
    // WRONG: if role == "admin" { .. }         bare keyword
    // WRONG: @if role == "admin" h1 { .. }     branch without braces
    @if role == "admin" {
        h1 { "Super secret to-do list" }
    } @else if role == "editor" {
        p { "Drafts only." }
    } @else {
        p { "Nothing to see here; move along." }
    }
    // WRONG: p { "Hello, " (nick.unwrap()) "!" }   panics on None
    p { "Hello, " @if let Some(nick) = nick { (nick) } @else { "stranger" } "!" }
    ol {
        // WRONG: for name in &names { .. }      let shout = ..;
        @for name in &names {
            @let shout = name.to_uppercase();
            li { (name) " shouts " b { (shout) } }
        }
    }
    @while let Some(n) = queue.next() { span { (n) } }
    @match names.len() {
        0 => p { "Nobody here." },
        1 | 2 => "A quiet day.",
        n if n > 10 => { p { (n) " ponies: a crowd." } },
        _ => p { "A few ponies." },
    }
};

Escaping and Raw HTML

  • Splices and text are escaped by default. Maud escapes exactly four characters: &, <, >, ". Single quotes pass through unescaped (since 0.13).
  • Never escape a value yourself before splicing it: it renders as visible &amp; entities.
  • maud::PreEscaped(x) renders its inner value verbatim. Wrap only markup that is already sanitized or built by the program; on untrusted input it is an XSS hole. Never wrap an ordinary value in it.
  • A raw HTML string spliced bare is escaped; untrusted HTML (rendered Markdown, rich text) is sanitized first: PreEscaped(ammonia::clean(&dirty)).
  • Escaping is not context-aware: the same four characters are escaped everywhere, which is safe for HTML text only. Check the scheme of an outside URL before splicing it into href or src.
  • Encode a value bound for script, style or an on* attribute for that context before the splice: a bare splice gets HTML escaping only, PreEscaped passes </script> through, and maud 0.27 ships no such encoder.
  • PreEscaped<T> wraps any T (since 0.26) but splices only when T: AsRef<str>.
use maud::{html, PreEscaped};
let comment = "<script>alert(1)</script>"; // untrusted
let link = "javascript:alert(1)"; // untrusted
let icon = "<svg></svg>"; // built by the program
let href = if link.starts_with("https://") { link } else { "#" };
let page = html! {
    // WRONG: p { (PreEscaped(comment)) }   runs the script
    p { (comment) } // &lt;script&gt;alert(1)&lt;/script&gt;
    // WRONG: a href=(link) { .. }          escaping keeps `javascript:` intact
    a href=(href) { "Profile" }
    (PreEscaped(icon))
};

Custom Rendering and Composition

The Render Trait

Write a maud::Render impl to teach maud how to splice your own type. The trait has two methods, each with a default impl that calls the other:

  • fn render(&self) -> Markup: override for the simple case.
  • fn render_to(&self, buffer: &mut String): override to write straight into the output buffer, without an intermediate Markup.

Rules:

  • Override at least one. An impl that overrides neither compiles and recurses forever.
  • Neither method takes a writer or returns fmt::Result.
  • A render_to override does its own escaping: raw writes into buffer land unescaped. Write through maud::Escaper, which escapes as it writes.
  • render and render_to are sync-only; there is no async Render trait and no streaming variant. Resolve async data (a DB or HTTP call) to a value before entering html! and splice the resolved value.
  • Maud exports no RenderOnce trait (removed in 0.15; the name survives in horrorshow).
use maud::{html, Escaper, Markup, Render};
use std::fmt::Write as _;

struct Css(&'static str);
impl Render for Css {
    // WRONG: impl Render for Css {}   no method overridden: infinite recursion
    fn render(&self) -> Markup {
        html! { link rel="stylesheet" type="text/css" href=(self.0); }
    }
}

struct Debugged<T>(T);
impl<T: std::fmt::Debug> Render for Debugged<T> {
    fn render_to(&self, output: &mut String) {
        // WRONG: write!(output, "{:?}", self.0)   unescaped
        let mut escaper = Escaper::new(output);
        write!(escaper, "{:?}", self.0).expect("writing to a String cannot fail");
    }
}

let page = html! { (Css("site.css")) p { (Debugged(vec!["<b>"])) } };

Components Are Just Functions

  • A partial or component is a plain function returning Markup. Compose by splicing the call: (header(title)). There is no partial! macro and no include syntax.
  • Type a parameter that carries markup as Markup, never String or &str: a string of HTML splices escaped.
  • Splicing a Markup value never re-escapes it, so nesting components is safe.
use maud::{html, Markup, DOCTYPE};

fn header(title: &str) -> Markup {
    html! { head { title { (title) } } }
}

// WRONG: fn page(title: &str, body: String) -> Markup
fn page(title: &str, body: Markup) -> Markup {
    html! {
        (DOCTYPE)
        html {
            (header(title))
            body { (body) }
        }
    }
}

let markup = page("Home", html! { h1 { "Hello" } });

Web Frameworks

Turn on the matching feature flag and Markup implements the framework's response trait. A handler then returns Markup directly. Tide is the exception: its feature converts Markup into a tide::Response, so the closure returns Ok(html! { .. }).

maud = { version = "0.27", features = ["axum"] }
FrameworkFeature flagTrait Markup implementsFramework version
defaultn/an/anothing enabled
Actix-webactix-webactix_web::Responderactix-web ^4
AxumaxumIntoResponseaxum 0.8 (axum-core ^0.5, http ^1)
RocketrocketRocket's Responderrocket ^0.5
Warpwarpwarp::Replywarp ^0.3.6
Poempoempoem::IntoResponsepoem ^3
Tidetide (removed upstream after 0.27.0)From<PreEscaped<String>> for tide::Responsetide ^0.16.0
Submillisecondsubmillisecond (since 0.27)IntoResponsesubmillisecond ^0.4.1
Rouillenonenonen/a
  • Pair maud 0.27 with the framework version in the table: the Markup impl targets that version only (axum 0.7 pairs with maud 0.26).
  • Never hand-write a response impl for Markup, and never return .into_string() from a handler whose framework has a feature.
  • A framework with no feature: pass the Markup to its response constructor (Rouille: Response::html(..)); call .into_string() only where it needs a String.
  • Versions follow maud 0.27.0's manifest; verify against the crate's Cargo.toml when exact ranges matter.
// fragment
// Axum; also Poem (under `#[handler]`) and Submillisecond (a plain `fn` listed in `router!`)
async fn hello() -> Markup { html! { h1 { "Hello" } } }
// WRONG: async fn hello() -> String { html! { .. }.into_string() }   axum sends text/plain

// Actix-web: wrap the return in a Result
#[get("/")]
async fn index() -> actix_web::Result<Markup> { Ok(html! { h1 { "Hello" } }) }

// Rocket: the route returns Markup, the launch fn returns `_`
#[get("/<name>")]
fn greet(name: &str) -> Markup { html! { h1 { "Hello, " (name) "!" } } }
#[rocket::launch]
fn launch() -> _ { rocket::build().mount("/", routes![greet]) }

// Warp: a filter, not an `async fn`
let route = warp::any().map(|| html! { h1 { "Hello" } });

// Tide: the closure returns Ok(..); a bare `-> Markup` handler does not compile
app.at("/").get(|_req: tide::Request<()>| async move { Ok(html! { h1 { "Hello" } }) });

// Rouille: no feature flag
Response::html(html! { h1 { "Hello" } })

Checklist

Run over every html! block, Render impl and handler in the diff:

  • No angle brackets, no unquoted text, no hand-written <!DOCTYPE html>: elements use braces, text is quoted, the doctype is (DOCTYPE).
  • Every void element ends with ;: no {} body, no /.
  • Every if, else, for, while, match and let carries @; every @if/@else/@for/@while body has braces.
  • Dynamic values are (expr) splices: no {{x}} or ${x} in a string literal, no .clone() or .to_string() just to splice, no format! just to join a literal and a splice (a format! with a format spec, {:.2}, is fine).
  • No .unwrap() or .expect(..) in a splice: @if let with @else, or attr=[opt].
  • Literal attribute values are quoted, splices are =(value) or =[opt]; boolean attributes are bare or [cond], never =true; attr concatenation is wrapped in { }; no attribute is written twice; a space precedes #id.
  • PreEscaped wraps only sanitized or program-built markup; outside URLs are scheme-checked; values bound for script, style or on* are encoded for that context.
  • Every impl Render overrides render or render_to; a render_to override writes through Escaper.
  • Components are functions returning Markup; markup parameters are typed Markup.
  • Handlers return Markup (Tide: Ok(html! { .. }) from the closure), not .into_string(); the framework feature is on where the table lists one (Rouille has none) and the framework version matches the table; no json or salvo feature.
  • Async data is resolved before html!; Markup reaches a String through .into_string().

To update: re-verify every rule against the book and the API docs below, then diff for changes.

Book: https://maud.lambda.xyz API docs: https://docs.rs/maud

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall