diff options
Diffstat (limited to 'SHORTCODES.md')
| -rw-r--r-- | SHORTCODES.md | 62 |
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: `` | +| `{{< 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 |