Add a render option to render the image as <figure>

src/html.rs

@@ -860,6 +860,9 @@ impl<'o, 'c: 'o> HtmlFormatter<'o, 'c> {
             NodeValue::Image(ref nl) => {
                 // Unreliable sourcepos.
                 if entering {
+                    if self.options.render.figure_with_caption {
+                        self.output.write_all(b"<figure>")?;
+                    }
                     self.output.write_all(b"<img")?;
                     if self.options.render.experimental_inline_sourcepos {
                         self.render_sourcepos(node)?;
@@ -877,6 +880,14 @@ impl<'o, 'c: 'o> HtmlFormatter<'o, 'c> {
                         self.escape(nl.title.as_bytes())?;
                     }
                     self.output.write_all(b"\" />")?;
+                    if self.options.render.figure_with_caption {
+                        if !nl.title.is_empty() {
+                            self.output.write_all(b"<figcaption>")?;
+                            self.escape(nl.title.as_bytes())?;
+                            self.output.write_all(b"</figcaption>")?;
+                        }
+                        self.output.write_all(b"</figure>")?;
+                    }
                 }
             }
             #[cfg(feature = "shortcodes")]

src/parser/mod.rs

@@ -875,6 +875,22 @@ pub struct RenderOptions {
     /// assert_eq!(str::from_utf8(&buf).unwrap(), "```\nhello\n```\n");
     /// ```
     pub prefer_fenced: bool,
+
+    /// Render the image as a figure element with the title as its caption.
+    ///
+    /// ```rust
+    /// # use comrak::{markdown_to_html, Options};
+    /// let mut options = Options::default();
+    /// let input = "![image](https://example.com/image.png \"this is an image\")";
+    ///
+    /// assert_eq!(markdown_to_html(input, &options),
+    ///            "<p><img src=\"https://example.com/image.png\" alt=\"image\" title=\"this is an image\" /></p>\n");
+    ///
+    /// options.render.figure_with_caption = true;
+    /// assert_eq!(markdown_to_html(input, &options),
+    ///            "<p><figure><img src=\"https://example.com/image.png\" alt=\"image\" title=\"this is an image\" /><figcaption>this is an image</figcaption></figure></p>\n");
+    /// ```
+    pub figure_with_caption: bool,
 }
 
 #[non_exhaustive]

src/tests/core.rs

@@ -128,6 +128,26 @@ fn ignore_setext_heading() {
     );
 }
 
+#[test]
+fn figure_with_caption_with_title() {
+    html_opts!(
+        [render.figure_with_caption],
+        concat!("![image](https://example.com/image.png \"this is an image\")\n"),
+        concat!("<p><figure><img src=\"https://example.com/image.png\" alt=\"image\" title=\"this is an image\" /><figcaption>this is an image</figcaption></figure></p>\n"),
+    );
+}
+
+#[test]
+fn figure_with_caption_without_title() {
+    html_opts!(
+        [render.figure_with_caption],
+        concat!("![image](https://example.com/image.png)\n"),
+        concat!(
+            "<p><figure><img src=\"https://example.com/image.png\" alt=\"image\" /></figure></p>\n"
+        ),
+    );
+}
+
 #[test]
 fn html_block_1() {
     html_opts!(