consolidated duplicated shortcodes. Initial fix of the content files. Manual review needed

1 files changed, 52 insertions, 10 deletions

diff --git a/SHORTCODES.md b/SHORTCODES.md
index fdfec6f..a7e86c8 100644
--- a/SHORTCODES.md
+++ b/SHORTCODES.md
@@ -47,10 +47,12 @@ Display a responsive image with optional caption and automatic lazy-loading. Ima
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| src | Yes | Path or URL to the image file |
-| alt | No | Alt text for accessibility |
+| src | Conditional | Path or URL to the image file (required unless inner content is provided) |
+| alt | No | Alt text for accessibility (default: "Image") |
 | caption | No | Optional caption displayed below the image |
-| class | No | Custom CSS classes (default: "w-full h-auto rounded-lg border border-border/30"). Overrides all defaults when specified. |
+| class | No | CSS classes for the `<img>` element (default: "w-full h-auto rounded-lg border border-border"). Overrides all defaults when specified. |
+| link | No | URL to wrap the image in a clickable link |
+| figure-class | No | CSS classes applied to the outer `<figure>` element (e.g., for centering or custom layout) |
 
 ### Example
 
@@ -69,6 +71,16 @@ With custom sizing and styling:
 {{< image src="/images/mountain.jpg" alt="Mountain landscape" class="w-2/3 mx-auto rounded-lg shadow-lg border-2 border-accent" >}}
 ```
 
+With link:
+```
+{{< image src="/images/mountain.jpg" alt="Mountain landscape" link="https://github.com/example" caption="Click to view project" >}}
+```
+
+Centered image with figure-class:
+```
+{{< image src="/images/mountain.jpg" alt="Mountain landscape" caption="Alpine view" figure-class="text-center" >}}
+```
+
 ### Common CSS Classes for Image Sizing
 
 Use Tailwind CSS utility classes to customize image appearance:
@@ -175,13 +187,15 @@ Embed responsive HTML5 video player with support for WebM, MP4, and other web vi
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| src | Yes | Path or URL to the video file (supports .webm, .mp4, .ogv) |
-| width | No | Video width (default: 100%, can be px or % values) |
-| height | No | Video height (default: auto) |
+| src | Conditional | Path or URL to the video file (required if `id` is not provided; supports .webm, .mp4, .ogv) |
+| id | Conditional | YouTube video ID (required if `src` is not provided; triggers YouTube embed mode) |
+| title | No | Descriptive title for accessibility (default: "Video"; used as iframe title attribute) |
+| width | No | Video width (default: 100%, can be px or % values; video mode only) |
+| height | No | Video height (default: auto; video mode only) |
 | class | No | Custom CSS classes for styling |
-| autoplay | No | Set to "true" to autoplay (default: false) |
-| loop | No | Set to "true" for looping playback (default: false) |
-| muted | No | Set to "true" to mute by default (default: false) |
+| autoplay | No | Set to "true" to autoplay (default: false; video mode only) |
+| loop | No | Set to "true" for looping playback (default: false; video mode only) |
+| muted | No | Set to "true" to mute by default (default: false; video mode only) |
 
 ### Example
 
@@ -205,6 +219,16 @@ External video URL:
 {{< video src="https://example.com/video.mp4" width="100%" >}}
 ```
 
+YouTube embed (recommended for privacy and performance):
+```
+{{< video id="dQw4w9WgXcQ" title="Example YouTube video" >}}
+```
+
+YouTube with custom sizing:
+```
+{{< video id="dQw4w9WgXcQ" title="Example YouTube video" class="max-w-2xl mx-auto" >}}
+```
+
 ### Page Bundle Videos
 
 Videos stored in the same directory as your article's `index.md` are automatically resolved:
@@ -414,7 +438,25 @@ The following shortcodes are planned for future releases:
 - **Tabs**: Tabbed content sections for organizing related information
 - **Code**: Enhanced code blocks with syntax highlighting and line numbers
 - **Audio**: Audio player for podcast episodes and sound files
-- **YouTube/Vimeo**: Privacy-friendly embedded video players
+
+## Deprecated Shortcodes
+
+The following shortcodes have been consolidated and are no longer available:
+
+| Deprecated | Replacement | Migration |
+|-----------|------------|-----------|
+| `{{< figure >}}` | `{{< image >}}` | Use `{{< image >}}` with the `figure-class` parameter for styling the figure element |
+| `{{< img >}}` | `{{< image >}}` | Directly replace with `{{< image >}}` and add proper `alt` text |
+| `{{< gal-img >}}` | Markdown syntax inside `{{< gallery >}}` | Replace `{{< gal-img ... >}}` calls with standard markdown: `![alt](src)` |
+| `{{< youtube ID >}}` | `{{< video id="ID" >}}` | Change `{{< youtube ID >}}` to `{{< video id="ID" title="Description" >}}` |
+
+### Why These Changes?
+
+The consolidation reduces maintenance overhead and provides better functionality:
+- **`image` shortcode** now supports all image display modes with flexible parameters
+- **`video` shortcode** unifies local video and YouTube embeds in one interface
+- **`gallery` shortcode** uses standard markdown image syntax for better clarity
+- **WCAG AA compliance** improved with required `title` attributes on YouTube iframes
 
 ## Accessibility Notes