stapix

diff --git a/README.md b/README.md
@@ -27,8 +27,8 @@ $ stapix config.yml
 ```
 
 The configuration file `config.yml` should consist of a list of file-paths
-pointing to the images the user wants in the gallery and text alternatives for
-each image, such as in the following example:
+pointing to the images the user wants in the gallery and text alternatives
+(visual descriptions) for each image, such as in the following example:
 
 ```yaml
 - path: ./path/to/first.jpg
@@ -38,6 +38,24 @@ each image, such as in the following example:
 ...
 ```
 
+Each entry on the list may additionally contain a field named `caption`
+containing additional information to be displayed in the captions of the
+corresponding image, as in the following example:
+
+```yaml
+- path: ./path/to/third.jpg
+  alt: "Text alternative for the first photo"
+  caption: "The third picture of the gallery"
+```
+
+For best accessibility, the `alt` field should contain a concise visual
+description of the picture in question (including subjects, colors and scenery)
+to be displayed by screen readers, while the `caption` field should contain
+_additional_ information on the picture (such as the location or date when it
+was taken) to be displayed for all users. _The `alt` and `caption` attributes
+should not be the same!_ See
+<https://www.htmhell.dev/adventcalendar/2022/22/> for further details.
+
 ## Installation
 
 stapix can be installed via Cargo by cloning this directory, as in:

diff --git a/src/main.rs b/src/main.rs
@@ -321,8 +321,12 @@ fn render_pic_page(pic: &Picture) -> io::Result<()> {
     write_nav(&mut f)?;
 
     writeln!(f, "<main>")?;
-    writeln!(f, "<figure aria-label=\"{name}\">",
-             name = Escaped(&pic.file_name))?;
+    if pic.caption.is_some() {
+        writeln!(f, "<figure>")?;
+    } else {
+        writeln!(f, "<figure aria-label=\"File {name}\">",
+                 name = Escaped(&pic.file_name))?;
+    }
     writeln!(f, "<div id=\"picture-container\">")?;
     writeln!(
         f,
@@ -331,6 +335,11 @@ fn render_pic_page(pic: &Picture) -> io::Result<()> {
         file_name = Escaped(&pic.file_name)
     )?;
     writeln!(f, "</div>")?;
+    if let Some(caption) = &pic.caption {
+        writeln!(f, "<figcaption>")?;
+        writeln!(f, "{}", Escaped(&caption))?;
+        writeln!(f, "</figcaption>")?;
+    }
     writeln!(f, "</figure>")?;
     writeln!(f, "</main>")?;
 

diff --git a/src/picture.rs b/src/picture.rs
@@ -10,6 +10,7 @@ pub struct Picture {
     pub path: PathBuf,
     pub file_name: String,
     pub alt: String,
+    pub caption: Option<String>,
 }
 
 impl<'de> Deserialize<'de> for Picture {
@@ -21,9 +22,14 @@ impl<'de> Deserialize<'de> for Picture {
         struct Info {
             path: String,
             alt: String,
+            caption: Option<String>,
         }
 
-        let Info { path: path_str, alt, } = Info::deserialize(deserializer)?;
+        let Info {
+            path: path_str,
+            alt,
+            caption,
+        } = Info::deserialize(deserializer)?;
 
         let mut path = PathBuf::new();
         path.push(path_str.clone());
@@ -33,6 +39,7 @@ impl<'de> Deserialize<'de> for Picture {
                 path: path.clone(),
                 alt: alt.trim().to_string(),
                 file_name: String::from(file_name),
+                caption: caption.clone(),
             })
         } else {
             Err(D::Error::invalid_value(