From a128fabaf1f7676ac3677929bc3836c60c18180a Mon Sep 17 00:00:00 2001 From: Xin <5097752+imfing@users.noreply.github.com> Date: Sun, 4 Jan 2026 17:23:33 +0000 Subject: [PATCH] feat: add optional alt parameter to card shortcode (#899) Add support for custom alt text on card images to improve accessibility. The alt parameter is optional and defaults to the card title if not provided, maintaining backward compatibility with existing implementations. Fixes #896 --- docs/content/docs/guide/shortcodes/cards.md | 61 +++++++++++---------- layouts/_partials/shortcodes/card.html | 3 +- layouts/_shortcodes/card.html | 29 +++++----- 3 files changed, 49 insertions(+), 44 deletions(-) diff --git a/docs/content/docs/guide/shortcodes/cards.md b/docs/content/docs/guide/shortcodes/cards.md index 696a409..d06f7d5 100644 --- a/docs/content/docs/guide/shortcodes/cards.md +++ b/docs/content/docs/guide/shortcodes/cards.md @@ -6,15 +6,15 @@ linkTitle: Cards ## Example {{< cards >}} - {{< card link="../callout" title="Callout" icon="warning" >}} - {{< card link="../callout" title="Card with tag" icon="tag" tag="custom tag">}} - {{< card link="/" title="No Icon" >}} +{{< card link="../callout" title="Callout" icon="warning" >}} +{{< card link="../callout" title="Card with tag" icon="tag" tag="custom tag">}} +{{< card link="/" title="No Icon" >}} {{< /cards >}} {{< cards >}} - {{< card link="/" title="Image Card" image="https://github.com/user-attachments/assets/71b7e3ec-1a8d-4582-b600-5425c6cc0407" subtitle="Internet Image" >}} - {{< card link="/" title="Local Image" image="/images/card-image-unprocessed.jpg" subtitle="Raw image under static directory." >}} - {{< card link="/" title="Local Image" image="images/space.jpg" subtitle="Image under assets directory, processed by Hugo." method="Resize" options="600x q80 webp" >}} +{{< card link="/" title="Image Card" image="https://github.com/user-attachments/assets/71b7e3ec-1a8d-4582-b600-5425c6cc0407" subtitle="Internet Image" >}} +{{< card link="/" title="Local Image" image="/images/card-image-unprocessed.jpg" subtitle="Raw image under static directory." >}} +{{< card link="/" title="Local Image" image="images/space.jpg" subtitle="Image under assets directory, processed by Hugo." method="Resize" options="600x q80 webp" >}} {{< /cards >}} ## Usage @@ -32,28 +32,30 @@ linkTitle: Cards {{}} {{}} {{}} + {{}} {{}} ``` ## Card Parameters -| Parameter | Description | -|-------------|----------------------------------------------------------------------------------------| -| `link` | URL (internal or external). | -| `title` | Title heading for the card. | -| `subtitle` | Subtitle heading (supports Markdown). | -| `icon` | Name of the icon. See [icons]({{% relRef "icon" %}}) for more information. | +| Parameter | Description | +| ---------- | -------------------------------------------------------------------------- | +| `link` | URL (internal or external). | +| `title` | Title heading for the card. | +| `subtitle` | Subtitle heading (supports Markdown). | +| `icon` | Name of the icon. See [icons]({{% relRef "icon" %}}) for more information. | ## Image Card Additionally, the card supports adding image and processing through these parameters: -| Parameter | Description | -|--------------|----------------------------------------------------| -| `image` | Specifies the image URL for the card. | -| `method` | Sets Hugo's image processing method. | -| `options` | Configures Hugo's image processing options. | -| `imageStyle` | Used to fill the style attribute of the image tag. | +| Parameter | Description | +| ------------ | ------------------------------------------------------------------- | +| `image` | Specifies the image URL for the card. | +| `alt` | Alternative text for the image (defaults to title if not provided). | +| `method` | Sets Hugo's image processing method. | +| `options` | Configures Hugo's image processing options. | +| `imageStyle` | Used to fill the style attribute of the image tag. | Card supports three kinds of images: @@ -71,19 +73,19 @@ For more on Hugo's built in image processing commands, methods, and options see Card supports adding tags which could be useful to show extra status information. | Parameter | Description | -|-------------|----------------------------------------------------------------------------------------| +| ----------- | -------------------------------------------------------------------------------------- | | `tag` | Text in tag. | | `tagColor` | Color of the tag. See [badges]({{% relRef "others/#badges" %}}) for more information. | | `tagIcon` | Icon of the tag. See [badges]({{% relRef "others/#badges" %}}) for more information. | | `tagBorder` | Border of the tag. See [badges]({{% relRef "others/#badges" %}}) for more information. | {{< cards >}} - {{< card link="../callout" title="Card with default tag" tag="tag text" >}} - {{< card link="../callout" title="Card with red tag" tag="tag text" tagColor="red" >}} - {{< card link="../callout" title="Card with blue tag" tag="tag text" tagColor="blue" >}} - {{< card link="../callout" title="Card with yellow tag" tag="tag text" tagColor="yellow" tagIcon="sparkles" tagBorder=false >}} - {{< card link="/" title="Image Card" image="/images/card-image-unprocessed.jpg" subtitle="Image" tag="tag text" tagColor="green" >}} - {{< card link="/" title="Image Card" image="images/space.jpg" subtitle="Image" tag="tag text" tagColor="purple" tagIcon="sparkles" tagBorder=false >}} +{{< card link="../callout" title="Card with default tag" tag="tag text" >}} +{{< card link="../callout" title="Card with red tag" tag="tag text" tagColor="red" >}} +{{< card link="../callout" title="Card with blue tag" tag="tag text" tagColor="blue" >}} +{{< card link="../callout" title="Card with yellow tag" tag="tag text" tagColor="yellow" tagIcon="sparkles" tagBorder=false >}} +{{< card link="/" title="Image Card" image="/images/card-image-unprocessed.jpg" subtitle="Image" tag="tag text" tagColor="green" >}} +{{< card link="/" title="Image Card" image="images/space.jpg" subtitle="Image" tag="tag text" tagColor="purple" tagIcon="sparkles" tagBorder=false >}} {{< /cards >}} ``` @@ -102,13 +104,13 @@ Card supports adding tags which could be useful to show extra status information You can specify the maximum number of columns for cards to span by passing the `cols` parameter to the `cards` shortcode. Note that columns will still be collapsed on smaller screens. {{< cards cols="1" >}} - {{< card link="/" title="Top Card" >}} - {{< card link="/" title="Bottom Card" >}} +{{< card link="/" title="Top Card" >}} +{{< card link="/" title="Bottom Card" >}} {{< /cards >}} {{< cards cols="2" >}} - {{< card link="/" title="Left Card" >}} - {{< card link="/" title="Right Card" >}} +{{< card link="/" title="Left Card" >}} +{{< card link="/" title="Right Card" >}} {{< /cards >}} ``` @@ -122,4 +124,3 @@ You can specify the maximum number of columns for cards to span by passing the ` {{}} {{}} ``` - diff --git a/layouts/_partials/shortcodes/card.html b/layouts/_partials/shortcodes/card.html index acd6c93..efebfd8 100644 --- a/layouts/_partials/shortcodes/card.html +++ b/layouts/_partials/shortcodes/card.html @@ -3,6 +3,7 @@ {{- $icon := .icon -}} {{- $subtitle := .subtitle -}} {{- $image := .image -}} +{{- $alt := .alt | default $title -}} {{- $width := .width -}} {{- $height := .height -}} {{- $imageStyle := .imageStyle -}} @@ -29,7 +30,7 @@ > {{- with $image -}}