README.md: add "Article Image Carousels" section

1 files changed, 49 insertions, 0 deletions

diff --git a/README.md b/README.md
index 292daa7..e044e31 100644
--- a/README.md
+++ b/README.md
@@ -108,6 +108,55 @@ Notes:
 4. Use the `pe-figure` shortcode for progressive enhanced `figure` tags
    with a fallback image.
 
+## Article Image Carousels
+
+Articles support image "carousels" at the top and bottom of the page
+(carousel is a bit of a misnomer, because the images are currently a
+single row of identical-width columns).
+
+See `content/articles/about.md` for a real example, but in general:
+
+1. Add a `carousel` section to the article front matter with `top` or
+   `bottom` keys.
+2. Add an array of images under `top` or `bottom`.  The parameters for
+   the images are virtually identical to those used by the `pe-figure`
+   shortcode, with the addition of a `link` and `link_tip` keys.
+
+Here is a reasonably complete example:
+
+```yaml
+carousel:
+  # top carousel (shown before content)
+  top:
+    - link: "/files/about/20231001-me-river.jpg"
+      link_tip: "Hi!"
+      css: "image"
+      sources:
+        - "/files/about/20231001-me-river-1024.webp"
+        - src: "/files/about/20231001-me-river-1024.webp"
+          width: 1024
+          height: 879
+    - link: "/files/about/20231110-me-fridge.jpg"
+      link_tip: "Fridge magnets, I guess?"
+      css: "image"
+      sources:
+        - "/files/about/20231110-me-fridge-1024.webp"
+        - src: "/files/about/20231110-me-fridge-1024.jpg"
+          width: 1024
+          height: 879
+
+  # bottom carousel (shown after content)
+  bottom:
+    - link: "/files/about/me-super-cool.jpg"
+      tip: "Younger me... Suave ;)."
+      css: "image"
+      sources:
+        - "/files/about/me-super-cool-1024.webp"
+        - src: "/files/about/me-super-cool-1024.jpg"
+          width: 1024
+          height: 655
+```
+
 ## Deploy Site
 
 To clone site repo: