feat: new RenderWithAlt trait

Princesseuh · Princesseuh · commit 36da26dfe573 · 2025-09-30T04:16:21.000+02:00
diff --git a/.sampo/changesets/ancient-guardian-tuulikki.md b/.sampo/changesets/ancient-guardian-tuulikki.md
@@ -0,0 +1,5 @@
+---
+maudit: patch
+---
+
+Add a new RenderWithAlt trait for rendering images, enforcing the usage of alt when trying to render to a String
diff --git a/crates/maudit/src/assets.rs b/crates/maudit/src/assets.rs
@@ -10,7 +10,7 @@ pub mod image_cache;
 mod script;
 mod style;
 mod tailwind;
-pub use image::{Image, ImageFormat, ImageOptions};
+pub use image::{Image, ImageFormat, ImageOptions, ImagePlaceholder, RenderWithAlt};
 pub use script::Script;
 pub use style::{Style, StyleOptions};
 pub use tailwind::TailwindPlugin;
diff --git a/crates/maudit/src/assets/image.rs b/crates/maudit/src/assets/image.rs
@@ -432,3 +432,19 @@ fn thumbhash_to_png(thumbhash_rgba: &(usize, usize, Vec<u8>)) -> Vec<u8> {
 
     bytes
 }
+
+/// Trait to render an image with an alt text.
+pub trait RenderWithAlt {
+    fn render(&self, alt: &str) -> String;
+}
+
+impl RenderWithAlt for Image {
+    fn render(&self, alt: &str) -> String {
+        let (width, height) = self.dimensions();
+
+        format!(
+            r#"<img src="{}" width="{}" height="{}" loading="lazy" decoding="async" alt="{}"/>"#,
+            self.url, width, height, alt
+        )
+    }
+}
diff --git a/crates/maudit/src/route.rs b/crates/maudit/src/route.rs
@@ -737,7 +737,10 @@ pub mod prelude {
         CachedRoute, DynamicRouteContext, FullRoute, Page, PageContext, PageParams, Pages,
         PaginatedContentPage, PaginationPage, RenderResult, Route, RouteExt, paginate,
     };
-    pub use crate::assets::{Asset, Image, ImageFormat, ImageOptions, Script, Style, StyleOptions};
+    pub use crate::assets::{
+        Asset, Image, ImageFormat, ImageOptions, ImagePlaceholder, RenderWithAlt, Script, Style,
+        StyleOptions,
+    };
     pub use crate::content::{
         ContentContext, ContentEntry, Entry, EntryInner, MarkdownContent, RouteContent,
     };
diff --git a/crates/maudit/src/templating/maud_ext.rs b/crates/maudit/src/templating/maud_ext.rs
@@ -2,7 +2,7 @@ use maud::{Markup, Render, html};
 
 use crate::{
     GENERATOR,
-    assets::{Asset, Image, Script, Style},
+    assets::{Asset, Script, Style},
     route::RenderResult,
 };
 
@@ -22,15 +22,6 @@ impl Render for Script {
     }
 }
 
-impl Render for Image {
-    fn render(&self) -> Markup {
-        let (width, height) = self.dimensions();
-        html! {
-            img src=(self.url()) width=(width) height=(height) loading="lazy" decoding="async";
-        }
-    }
-}
-
 /// Can be used to create a generator tag in the output HTML. See [`GENERATOR`](crate::GENERATOR).
 pub fn generator() -> Markup {
     html! {
diff --git a/examples/basics/src/main.rs b/examples/basics/src/main.rs
@@ -1,6 +1,6 @@
 mod layout;
 
-use maudit::{BuildOptions, BuildOutput, coronate, routes};
+use maudit::{BuildOptions, BuildOutput, content_sources, coronate, routes};
 
 mod routes {
     mod index;
@@ -10,5 +10,5 @@ mod routes {
 pub use routes::Index;
 
 fn main() -> Result<BuildOutput, Box<dyn std::error::Error>> {
-    coronate(routes![Index], vec![].into(), BuildOptions::default())
+    coronate(routes![Index], content_sources![], BuildOptions::default())
 }
diff --git a/examples/basics/src/routes/index.rs b/examples/basics/src/routes/index.rs
@@ -10,7 +10,7 @@ impl Route for Index {
         let logo = ctx.assets.add_image("images/logo.svg");
 
         layout(html! {
-            (logo)
+            (logo.render("Maudit logo, a crudely drawn crown"))
             h1 { "Hello World" }
         })
     }
diff --git a/examples/image-processing/src/main.rs b/examples/image-processing/src/main.rs
@@ -1,6 +1,6 @@
 mod layout;
 
-use maudit::{BuildOptions, BuildOutput, coronate, routes};
+use maudit::{BuildOptions, BuildOutput, content_sources, coronate, routes};
 
 mod routes {
     mod index;
@@ -10,5 +10,5 @@ mod routes {
 pub use routes::Index;
 
 fn main() -> Result<BuildOutput, Box<dyn std::error::Error>> {
-    coronate(routes![Index], vec![].into(), BuildOptions::default())
+    coronate(routes![Index], content_sources![], BuildOptions::default())
 }
diff --git a/examples/image-processing/src/routes/index.rs b/examples/image-processing/src/routes/index.rs
@@ -18,10 +18,10 @@ impl Route for Index {
         );
 
         layout(html! {
-            (logo)
+            (logo.render("Maudit logo, a crudely drawn crown"))
             h1 { "Hello World" }
             h2 { "Here's a 200x200 walrus:" }
-            (walrus)
+            (walrus.render("A walrus with tusks"))
         })
     }
 }
diff --git a/examples/kitchen-sink/src/main.rs b/examples/kitchen-sink/src/main.rs
@@ -1,4 +1,4 @@
-use maudit::{AssetsOptions, BuildOptions, BuildOutput, coronate, routes};
+use maudit::{AssetsOptions, BuildOptions, BuildOutput, content_sources, coronate, routes};
 
 mod routes {
     mod dynamic;
@@ -12,7 +12,7 @@ mod routes {
 fn main() -> Result<BuildOutput, Box<dyn std::error::Error>> {
     coronate(
         routes![routes::Index, routes::DynamicExample, routes::Endpoint],
-        vec![].into(),
+        content_sources![],
         BuildOptions {
             assets: AssetsOptions {
                 tailwind_binary_path: "../../node_modules/.bin/tailwindcss".into(),
diff --git a/examples/kitchen-sink/src/routes/dynamic.rs b/examples/kitchen-sink/src/routes/dynamic.rs
@@ -28,7 +28,7 @@ impl Route<Params> for DynamicExample {
                 title { "Index" }
             }
             h1 { "Hello, world!" }
-            (image)
+            (image.render("Maudit social card, a crudely drawn crown"))
             p { (params.page) }
         }
     }
diff --git a/examples/kitchen-sink/src/routes/index.rs b/examples/kitchen-sink/src/routes/index.rs
@@ -25,6 +25,7 @@ impl Route for Index {
             h1 { "Index" }
             img src=(image.url()) {}
             script src=(script.url()) {}
+            (image.render("Maudit logo, a crudely drawn crown"))
             a."text-red-500" href=(link_to_first_dynamic) { "Go to first dynamic page" }
         }
     }
diff --git a/examples/oubli-basics/src/main.rs b/examples/oubli-basics/src/main.rs
@@ -1,6 +1,6 @@
 mod layout;
 
-use oubli::{Archetype, BuildOptions, BuildOutput, archetypes, forget, routes};
+use oubli::{Archetype, BuildOptions, BuildOutput, archetypes, content_sources, forget, routes};
 
 mod routes {
     mod index;
@@ -13,7 +13,7 @@ fn main() -> Result<BuildOutput, Box<dyn std::error::Error>> {
     forget(
         archetypes![("Our blog", blog, Archetype::Blog, "content/blog/*.md"),],
         routes![Index],
-        vec![].into(),
+        content_sources![],
         BuildOptions::default(),
     )
 }
diff --git a/examples/oubli-basics/src/routes/index.rs b/examples/oubli-basics/src/routes/index.rs
@@ -14,7 +14,7 @@ impl Route for Index {
             .get_source::<oubli::ArchetypeStoreEntry>("archetype_store");
 
         layout(html! {
-            (logo)
+            (logo.render("Maudit logo, a crudely drawn crown"))
             h1 { "Hello World" }
             @for archetype in &archetype_store.entries {
                 a href=(archetype.id) { (archetype.data(ctx).title) }
diff --git a/website/content/docs/entrypoint.md b/website/content/docs/entrypoint.md
@@ -9,11 +9,11 @@ At the core of a Maudit project is the [`coronate`](https://docs.rs/maudit/lates
 In a `main.rs` file, import the `coronate` function and call it to build your project. Here is an example of a simple Maudit project:
 
 ```rs
-use maudit::{coronate, routes, BuildOptions, BuildOutput};
+use maudit::{coronate, routes, BuildOptions, BuildOutput, content_sources};
 use routes::Index;
 
 fn main() -> Result<BuildOutput, Box<dyn std::error::Error>> {
-  coronate(routes![Index], vec![].into(), BuildOptions::default())
+  coronate(routes![Index], content_sources![], BuildOptions::default())
 }
 ```
 
@@ -24,13 +24,16 @@ All kinds of routes must be passed to the `coronate` function in order for them
 The first argument to the `coronate` function is a `Vec` of all the routes that should be built. For the sake of ergonomics, the `routes!` macro can be used to create this list.
 
 ```rs
+use maudit::{coronate, routes, BuildOptions};
 use routes::Index;
 
-coronate(
-  routes![Index],
-  vec![].into(),
-  BuildOptions::default()
-)
+fn main() {
+  coronate(
+    routes![Index],
+    content_sources![],
+    BuildOptions::default()
+  )
+}
 ```
 
 See the [Routing](/docs/routing) documentation for more information on how to define routes.
diff --git a/website/content/docs/images.md b/website/content/docs/images.md
@@ -16,6 +16,7 @@ To use an image in a page, add it anywhere in your project's directory, and use
 
 ```rs
 use maudit::route::prelude::*;
+use maud::{html};
 
 #[route("/blog")]
 pub struct Blog;
@@ -24,7 +25,11 @@ impl Route for Blog {
   fn render(&self, ctx: &mut PageContext) -> impl Into<RenderResult> {
     let image = ctx.assets.add_image("logo.png");
 
-    format!("", image.url)
+    let (width, height) = image.dimensions();
+    format!("<img src=\"{}\" alt=\"My logo\" width=\"{}\" height=\"{}\" />", image.url(), width, height);
+
+    // A more convenient way to render an image is to use the `render()` method, which generates an img tag for you and enforces accessibility by requiring an alt text.
+    format!("{}", image.render("The logo of my project, a stylized crown"))
   }
 }
 ```
@@ -68,3 +73,29 @@ impl Route for ImagePage {
 ```
 
 Processing images in Markdown files using the standard syntax is currently not supported, but can be achieved using a custom [shortcode](/docs/content/#shortcodes) or [component](/docs/content/#components).
+
+## Placeholders
+
+Maudit supports generating low-quality image placeholders (LQIP) for images. This can be useful to improve the perceived performance of your site by showing a blurred preview of an image while the full image is loading.
+
+To generate a placeholder, use the `placeholder()` method on an [Image](https://docs.rs/maudit/latest/maudit/assets/struct.Image.html) instance, for example returned by `ctx.assets.add_image()` or `ctx.assets.add_image_with_options()`.
+
+```rs
+use maudit::route::prelude::*;
+
+#[route("/image")]
+pub struct ImagePage;
+
+impl Route for ImagePage {
+  fn render(&self, ctx: &mut PageContext) -> impl Into<RenderResult> {
+    let image = ctx.assets.add_image("path/to/image.jpg");
+    let placeholder = image.placeholder();
+
+    format!("<img src=\"{}\" alt=\"Image with placeholder\" style=\"background-image: url('{}'); background-size: cover;\" />", image.url(), placeholder.data_uri())
+  }
+}
+```
+
+Alternatively, it is possible to get the dominant colors of an image using the `average_rgba()` method. This method will return a tuple of four `u8` values representing the red, green, blue, and alpha channels of the average color of the image.
+
+The generation of placeholders is powered by the [ThumbHash](https://evanw.github.io/thumbhash/) library.

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +maudit: patch
 +---
++
 +Add a new RenderWithAlt trait for rendering images, enforcing the usage of alt when trying to render to a String
Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@ impl Route for Index {`
`10`	`10`	`let logo = ctx.assets.add_image("images/logo.svg");`
`11`	`11`
`12`	`12`	`layout(html! {`
`13`		`- (logo)`
	`13`	`+ (logo.render("Maudit logo, a crudely drawn crown"))`
`14`	`14`	`h1 { "Hello World" }`
`15`	`15`	`})`
`16`	`16`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,10 +18,10 @@ impl Route for Index {`
`18`	`18`	`);`
`19`	`19`
`20`	`20`	`layout(html! {`
`21`		`- (logo)`
	`21`	`+ (logo.render("Maudit logo, a crudely drawn crown"))`
`22`	`22`	`h1 { "Hello World" }`
`23`	`23`	`h2 { "Here's a 200x200 walrus:" }`
`24`		`- (walrus)`
	`24`	`+ (walrus.render("A walrus with tusks"))`
`25`	`25`	`})`
`26`	`26`	`}`
`27`	`27`	`}`