diff --git a/docs/cards.md b/docs/cards.md index 6c30d54..f9f2e5e 100644 --- a/docs/cards.md +++ b/docs/cards.md @@ -84,6 +84,7 @@ You can also add an image as the background of a card or at the top/bottom of th :::{card} Title :img-background: images/particle_background.jpg :class-card: sd-text-black +:img-alt: your desired alt text Text ::: @@ -92,6 +93,7 @@ Text ::::{grid-item-card} Title :img-top: images/particle_background.jpg +:img-alt: your desired alt text Header ^^^ @@ -102,6 +104,7 @@ Footer ::::{grid-item-card} Title :img-bottom: images/particle_background.jpg +:img-alt: your desired alt text Header ^^^ @@ -257,6 +260,9 @@ img-top img-bottom : A URI (relative file path or URL) to an image to be placed below the content. +img-alt +: Alternative text for the image (that will be used by screen-readers). + link : Turn the entire card into a clickable link to an external/internal target. diff --git a/docs/snippets/myst/card-images.txt b/docs/snippets/myst/card-images.txt index 37e0ea3..b9991c1 100644 --- a/docs/snippets/myst/card-images.txt +++ b/docs/snippets/myst/card-images.txt @@ -5,6 +5,7 @@ :::{card} Title :img-background: images/particle_background.jpg :class-card: sd-text-black +:img-alt: my text Text ::: @@ -13,6 +14,7 @@ Text ::::{grid-item-card} Title :img-top: images/particle_background.jpg +:img-alt: Header ^^^ diff --git a/docs/snippets/rst/card-images.txt b/docs/snippets/rst/card-images.txt index 780213f..d529273 100644 --- a/docs/snippets/rst/card-images.txt +++ b/docs/snippets/rst/card-images.txt @@ -5,11 +5,13 @@ .. card:: Title :img-background: images/particle_background.jpg :class-card: sd-text-black + :img-alt: my text Text .. grid-item-card:: Title :img-top: images/particle_background.jpg + :img-alt: Header ^^^ diff --git a/sphinx_design/cards.py b/sphinx_design/cards.py index 7ff901a..5b03bfb 100644 --- a/sphinx_design/cards.py +++ b/sphinx_design/cards.py @@ -59,6 +59,7 @@ class CardDirective(SphinxDirective): "img-top": directives.uri, "img-bottom": directives.uri, "img-background": directives.uri, + "img-alt": directives.unchanged, "link": directives.uri, "link-type": make_choice(["url", "any", "ref", "doc"]), "link-alt": directives.unchanged, @@ -96,13 +97,15 @@ def create_card( ) inst.set_source_info(card) + img_alt = options.get("img-alt") or "" + container = card if "img-background" in options: card.append( nodes.image( uri=options["img-background"], classes=["sd-card-img"], - alt="background image", + alt=img_alt, ) ) overlay = create_component("card-overlay", ["sd-card-img-overlay"]) @@ -114,7 +117,7 @@ def create_card( image_top = nodes.image( "", uri=options["img-top"], - alt="card-img-top", + alt=img_alt, classes=["sd-card-img-top"] + options.get("class-img-top", []), ) container.append(image_top) @@ -156,7 +159,7 @@ def create_card( image_bottom = nodes.image( "", uri=options["img-bottom"], - alt="card-img-bottom", + alt=img_alt, classes=["sd-card-img-bottom"] + options.get("class-img-bottom", []), ) container.append(image_bottom) diff --git a/sphinx_design/grids.py b/sphinx_design/grids.py index a340d3d..caf7402 100644 --- a/sphinx_design/grids.py +++ b/sphinx_design/grids.py @@ -223,6 +223,7 @@ class GridItemCardDirective(SphinxDirective): "img-background": directives.uri, "img-top": directives.uri, "img-bottom": directives.uri, + "img-alt": directives.unchanged, "link": directives.uri, "link-type": make_choice(["url", "any", "ref", "doc"]), "link-alt": directives.unchanged, @@ -266,6 +267,7 @@ def run(self) -> List[nodes.Node]: "img-background", "img-top", "img-bottom", + "img-alt", "link", "link-type", "link-alt", diff --git a/tests/test_snippets/snippet_post_card-images.xml b/tests/test_snippets/snippet_post_card-images.xml index 868cb88..850caf3 100644 --- a/tests/test_snippets/snippet_post_card-images.xml +++ b/tests/test_snippets/snippet_post_card-images.xml @@ -6,7 +6,7 @@ - background image + my text @@ -16,7 +16,7 @@ Text - card-img-top + Header @@ -43,4 +43,4 @@ Footer - card-img-bottom + diff --git a/tests/test_snippets/snippet_pre_card-images.xml b/tests/test_snippets/snippet_pre_card-images.xml index 868cb88..850caf3 100644 --- a/tests/test_snippets/snippet_pre_card-images.xml +++ b/tests/test_snippets/snippet_pre_card-images.xml @@ -6,7 +6,7 @@ - background image + my text @@ -16,7 +16,7 @@ Text - card-img-top + Header @@ -43,4 +43,4 @@ Footer - card-img-bottom +