feat: add figure shortcode and documentation

Ported figure shortcode from previous theme. Wraps content in semantic <figure> element with optional title, caption, attribution, and link support.

Typical usage:
{{< figure caption="Image caption" attr="Photo by Someone" >}}
{{< img src="image.jpg" alt="Description" >}}
{{< /figure >}}

Also updated CONTENT_GUIDE with comprehensive usage examples and parameters.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

2 files changed, 81 insertions, 0 deletions

diff --git a/CONTENT_GUIDE.md b/CONTENT_GUIDE.md
index a261053..834a8f4 100644
--- a/CONTENT_GUIDE.md
+++ b/CONTENT_GUIDE.md
@@ -570,6 +570,60 @@ With link to profile:
 
 ---
 
+### Figure Shortcode
+
+The `figure` shortcode wraps images or other content in a semantic `<figure>` element with optional title, caption, attribution, and link. Use it to add context and styling around images.
+
+**Usage:**
+```hugo
+{{< figure caption="Image caption" attr="Photo by Someone" >}}
+{{< img src="image.jpg" alt="Description" >}}
+{{< /figure >}}
+```
+
+**Parameters:**
+- Content between tags — Inner content (typically an `img` shortcode)
+- `class` (optional) — CSS class for the figure element
+- `link` (optional) — URL to wrap the entire figure in a link
+- `target` (optional) — Link target (_blank, _self, etc.)
+- `rel` (optional) — Link rel attribute
+- `title` (optional) — Optional title displayed above the image
+- `caption` (optional) — Caption text (supports Markdown)
+- `attr` (optional) — Attribution text (supports Markdown)
+- `attrlink` (optional) — URL to link the attribution to
+
+**Examples:**
+
+Simple figure with caption:
+```hugo
+{{< figure caption="Kubernetes cluster architecture" >}}
+{{< img src="k8s-architecture.jpg" alt="Kubernetes cluster" >}}
+{{< /figure >}}
+```
+
+With title and attribution:
+```hugo
+{{< figure title="System Design" caption="A simplified view of the microservices architecture" attr="Diagram by John Doe" >}}
+{{< img src="architecture.jpg" alt="Architecture diagram" >}}
+{{< /figure >}}
+```
+
+With linked attribution:
+```hugo
+{{< figure caption="Beautiful sunset at Bryce Canyon" attr="Photo by Jane Smith" attrlink="https://example.com/jane" >}}
+{{< img src="bryce-canyon.jpg" alt="Sunset at Bryce Canyon" >}}
+{{< /figure >}}
+```
+
+Figure with clickable link:
+```hugo
+{{< figure link="https://example.com/full-image" target="_blank" caption="Click to view full resolution" >}}
+{{< img src="preview.jpg" alt="Preview image" >}}
+{{< /figure >}}
+```
+
+---
+
 ## Troubleshooting
 
 ### Article doesn't appear on site
diff --git a/layouts/shortcodes/figure.html b/layouts/shortcodes/figure.html
new file mode 100644
index 0000000..81f86de
--- /dev/null
+++ b/layouts/shortcodes/figure.html
@@ -0,0 +1,27 @@
+{{/*
+    * This version of the figure shortcode needs to be closed and doesn't
+    * add an image itself, but relies on the img.html shortcode to provide
+    * a responsive image instead.
+    */}}
+<figure{{ with .Get "class" }} class="{{ . }}"{{ end }}>
+    {{- if .Get "link" -}}
+        <a href="{{ .Get "link" }}"{{ with .Get "target" }} target="{{ . }}"{{ end }}{{ with .Get "rel" }} rel="{{ . }}"{{ end }}>
+    {{- end -}}
+    {{- .Inner -}}
+    {{- if .Get "link" }}</a>{{ end -}}
+    {{- if or (or (.Get "title") (.Get "caption")) (.Get "attr") -}}
+        <figcaption>
+            {{ with (.Get "title") -}}
+                <h4>{{ . }}</h4>
+            {{- end -}}
+            {{- if or (.Get "caption") (.Get "attr") -}}<p>
+                {{- .Get "caption" | markdownify -}}
+                {{- with .Get "attrlink" }}
+                    <a href="{{ . }}">
+                {{- end -}}
+                {{- .Get "attr" | markdownify -}}
+                {{- if .Get "attrlink" }}</a>{{ end }}</p>
+            {{- end }}
+        </figcaption>
+    {{- end }}
+</figure>