docs: add shortcode documentation to CONTENT_GUIDE

Document the three available shortcodes:
- img: responsive images with LQIP and WebP support
- quote: styled blockquotes with optional source attribution
- gravatar: profile image embedding with optional caption and link

Includes usage examples, parameters, and configuration options.

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

1 files changed, 118 insertions, 0 deletions

diff --git a/CONTENT_GUIDE.md b/CONTENT_GUIDE.md
index 0ed9dbe..a261053 100644
--- a/CONTENT_GUIDE.md
+++ b/CONTENT_GUIDE.md
@@ -452,6 +452,124 @@ image = "image-filename.jpg"
 
 ---
 
+## Hugo Shortcodes
+
+Beyond standard Markdown, the theme includes special shortcodes for enhanced content. Place your content files (images, etc.) in the same folder as the article.
+
+### Responsive Image Shortcode
+
+The `img` shortcode creates responsive, optimized images with lazy loading, WebP format support, and a fade-in LQIP (Low Quality Image Placeholder) effect.
+
+**Usage:**
+```hugo
+{{< img src="image.jpg" alt="Image description" >}}
+```
+
+**Parameters:**
+- `src` (required) — Path to image file (relative to content folder)
+- `alt` (required) — Alt text for accessibility
+- `divClass` (optional) — CSS class to add to the wrapper div
+
+**Configuration:**
+Add to your `hugo.toml` to define responsive image sizes:
+```toml
+[params]
+imageSizes = [640, 900, 1200, 1600]
+```
+
+**Example:**
+```hugo
+{{< img src="kubernetes-architecture.jpg" alt="Kubernetes cluster architecture" >}}
+```
+
+---
+
+### Quote Shortcode
+
+The `quote` shortcode creates styled blockquotes with optional source attribution and links.
+
+**Usage:**
+```hugo
+{{< quote source="Author Name" src="https://example.com" >}}
+This is a meaningful quote.
+{{< /quote >}}
+```
+
+**Parameters:**
+- Content between tags — The quote text
+- `source` (optional) — Author or source name
+- `src` (optional) — URL to link the source to (opens in new tab)
+
+**Examples:**
+
+Simple quote:
+```hugo
+{{< quote >}}
+The obstacle is the way.
+{{< /quote >}}
+```
+
+Quote with attribution:
+```hugo
+{{< quote source="Marcus Aurelius" >}}
+The impediment to action advances action. What stands in the way becomes the way.
+{{< /quote >}}
+```
+
+Quote with link:
+```hugo
+{{< quote source="Paul Graham" src="http://paulgraham.com/wealth.html" >}}
+The way to get rich is to work hard, at something people want.
+{{< /quote >}}
+```
+
+---
+
+### Gravatar Shortcode
+
+The `gravatar` shortcode embeds a Gravatar profile image with optional caption and link.
+
+**Usage:**
+```hugo
+{{< gravatar mail="your@email.com" size=150 caption="My avatar" >}}
+```
+
+**Parameters:**
+- `mail` (optional) — Email address for Gravatar lookup (falls back to `author_email` from config)
+- `size` (optional) — Image size in pixels (default: 200)
+- `class` (optional) — CSS class for the figure element
+- `link` (optional) — URL to wrap the image in a link
+- `target` (optional) — Link target (_blank, _self, etc.)
+- `rel` (optional) — Link rel attribute (e.g., "author")
+- `caption` (optional) — Caption text (supports Markdown)
+- `alt` (optional) — Alt text (uses caption as fallback)
+
+**Configuration:**
+Add to your `hugo.toml` to set your default email:
+```toml
+[params]
+author_email = "your@email.com"
+```
+
+**Examples:**
+
+Simple gravatar with default size:
+```hugo
+{{< gravatar >}}
+```
+
+Custom size and caption:
+```hugo
+{{< gravatar mail="danilo@example.com" size=120 caption="That's me" >}}
+```
+
+With link to profile:
+```hugo
+{{< gravatar mail="danilo@example.com" size=150 link="https://gravatar.com/danilo" target="_blank" rel="author" caption="Click to view my profile" >}}
+```
+
+---
+
 ## Troubleshooting
 
 ### Article doesn't appear on site