ray/hextra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add optional alt parameter to card shortcode (#899)

Browse Source 
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
This commit is contained in:
Xin
2026-01-04 17:23:33 +00:00
committed by GitHub
parent 9466af337f
commit a128fabaf1
3 changed files with 49 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/content/docs/guide/shortcodes/cards.md
View File

@@ -6,15 +6,15 @@ linkTitle: Cards
## Example ## Example
{{< cards >}} {{< cards >}}
{{< card link="../callout" title="Callout" icon="warning" >}} {{< card link="../callout" title="Callout" icon="warning" >}}
{{< card link="../callout" title="Card with tag" icon="tag" tag="custom tag">}} {{< card link="../callout" title="Card with tag" icon="tag" tag="custom tag">}}
{{< card link="/" title="No Icon" >}} {{< card link="/" title="No Icon" >}}
{{< /cards >}} {{< /cards >}}
{{< 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="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/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="Local Image" image="images/space.jpg" subtitle="Image under assets directory, processed by Hugo." method="Resize" options="600x q80 webp" >}}
{{< /cards >}} {{< /cards >}}
## Usage ## Usage
@@ -32,28 +32,30 @@ linkTitle: Cards
{{</* card link="/" title="Image Card" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash Landscape" */>}} {{</* card link="/" title="Image Card" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash Landscape" */>}}
{{</* card link="/" title="Local Image" image="/images/card-image-unprocessed.jpg" subtitle="Raw image under static directory." */>}} {{</* 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="Local Image" image="images/space.jpg" subtitle="Image under assets directory, processed by Hugo." method="Resize" options="600x q80 webp" */>}}
{{</* card link="/" title="Custom Alt Text" image="images/space.jpg" alt="A beautiful view of space with stars and galaxies" subtitle="Image with custom alt text for accessibility." */>}}
{{</* /cards */>}} {{</* /cards */>}}
``` ```
## Card Parameters ## Card Parameters
| Parameter | Description | | Parameter | Description |
|-------------|----------------------------------------------------------------------------------------| | ---------- | -------------------------------------------------------------------------- |
| `link` | URL (internal or external). | | `link` | URL (internal or external). |
| `title` | Title heading for the card. | | `title` | Title heading for the card. |
| `subtitle` | Subtitle heading (supports Markdown). | | `subtitle` | Subtitle heading (supports Markdown). |
| `icon` | Name of the icon. See [icons]({{% relRef "icon" %}}) for more information. | | `icon` | Name of the icon. See [icons]({{% relRef "icon" %}}) for more information. |
## Image Card ## Image Card
Additionally, the card supports adding image and processing through these parameters: Additionally, the card supports adding image and processing through these parameters:
| Parameter | Description | | Parameter | Description |
|--------------|----------------------------------------------------| | ------------ | ------------------------------------------------------------------- |
| `image` | Specifies the image URL for the card. | | `image` | Specifies the image URL for the card. |
| `method` | Sets Hugo's image processing method. | | `alt` | Alternative text for the image (defaults to title if not provided). |
| `options` | Configures Hugo's image processing options. | | `method` | Sets Hugo's image processing method. |
| `imageStyle` | Used to fill the style attribute of the image tag. | | `options` | Configures Hugo's image processing options. |
| `imageStyle` | Used to fill the style attribute of the image tag. |
Card supports three kinds of images: 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. Card supports adding tags which could be useful to show extra status information.
| Parameter | Description | | Parameter | Description |
|-------------|----------------------------------------------------------------------------------------| | ----------- | -------------------------------------------------------------------------------------- |
| `tag` | Text in tag. | | `tag` | Text in tag. |
| `tagColor` | Color of the tag. See [badges]({{% relRef "others/#badges" %}}) for more information. | | `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. | | `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. | | `tagBorder` | Border of the tag. See [badges]({{% relRef "others/#badges" %}}) for more information. |
{{< cards >}} {{< cards >}}
{{< card link="../callout" title="Card with default tag" tag="tag text" >}} {{< 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 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 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="../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/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="/" title="Image Card" image="images/space.jpg" subtitle="Image" tag="tag text" tagColor="purple" tagIcon="sparkles" tagBorder=false >}}
{{< /cards >}} {{< /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. 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" >}} {{< cards cols="1" >}}
{{< card link="/" title="Top Card" >}} {{< card link="/" title="Top Card" >}}
{{< card link="/" title="Bottom Card" >}} {{< card link="/" title="Bottom Card" >}}
{{< /cards >}} {{< /cards >}}
{{< cards cols="2" >}} {{< cards cols="2" >}}
{{< card link="/" title="Left Card" >}} {{< card link="/" title="Left Card" >}}
{{< card link="/" title="Right Card" >}} {{< card link="/" title="Right Card" >}}
{{< /cards >}} {{< /cards >}}
``` ```
@@ -122,4 +124,3 @@ You can specify the maximum number of columns for cards to span by passing the `
{{</* card link="/" title="Right Card" */>}} {{</* card link="/" title="Right Card" */>}}
{{</* /cards */>}} {{</* /cards */>}}
``` ```

3
layouts/_partials/shortcodes/card.html
View File

@@ -3,6 +3,7 @@
{{- $icon := .icon -}} {{- $icon := .icon -}}
{{- $subtitle := .subtitle -}} {{- $subtitle := .subtitle -}}
{{- $image := .image -}} {{- $image := .image -}}
{{- $alt := .alt | default $title -}}
{{- $width := .width -}} {{- $width := .width -}}
{{- $height := .height -}} {{- $height := .height -}}
{{- $imageStyle := .imageStyle -}} {{- $imageStyle := .imageStyle -}}
@@ -29,7 +30,7 @@
> >
{{- with $image -}} {{- with $image -}}
<img <img
alt="{{ $title }}" alt="{{ $alt }}"
class="hextra-card-image" class="hextra-card-image"
loading="lazy" loading="lazy"
decoding="async" decoding="async"

29
layouts/_shortcodes/card.html
View File

@@ -1,25 +1,27 @@
{{- /* {{- /*
A shortcode to create a card. A shortcode to create a card.
@param {string} link The link to the card. @param {string} link The link to the card.
@param {string} title The title of the card. @param {string} title The title of the card.
@param {string} icon The icon of the card. @param {string} icon The icon of the card.
@param {string} subtitle The subtitle of the card. @param {string} subtitle The subtitle of the card.
@param {string} tag The tag of the card. @param {string} tag The tag of the card.
@param {string} tagColor The color of the tag. @param {string} tagColor The color of the tag.
@param {string} image The image of the card. @param {string} image The image of the card.
@param {string} method The method to process the image. @param {string} alt The alt text for the image (defaults to title if not provided).
@param {string} options The options to process the image. @param {string} method The method to process the image.
@param {string} imageStyle The style of the image. @param {string} options The options to process the image.
@param {string} imageStyle The style of the image.
@example {{< card link="/" title="Image Card" }} @example {{< card link="/" title="Image Card"
}}
*/ -}} */ -}}
{{- $link := .Get "link" -}} {{- $link := .Get "link" -}}
{{- $title := .Get "title" -}} {{- $title := .Get "title" -}}
{{- $icon := .Get "icon" -}} {{- $icon := .Get "icon" -}}
{{- $subtitle := .Get "subtitle" -}} {{- $subtitle := .Get "subtitle" -}}
{{- $image := .Get "image" -}} {{- $image := .Get "image" -}}
{{- $alt := .Get "alt" | default $title -}}
{{- $width := 0 -}} {{- $width := 0 -}}
{{- $height := 0 -}} {{- $height := 0 -}}
{{- $imageStyle := .Get "imageStyle" -}} {{- $imageStyle := .Get "imageStyle" -}}
@@ -58,6 +60,7 @@ A shortcode to create a card.
"icon" $icon "icon" $icon
"subtitle" $subtitle "subtitle" $subtitle
"image" $image "image" $image
"alt" $alt
"width" $width "width" $width
"height" $height "height" $height
"imageStyle" $imageStyle "imageStyle" $imageStyle