✨ NEW: Add card option img-background (#17)

Author: chrisjsewell

docs/cards.md

@@ -73,21 +73,59 @@ Footer
 :::
 ::::
 
-You can also add images to the top and bottom of the card, with the `img-top` and `img-bottom` options:
+## Card images
 
-::::{grid} 1 2 2 2
-:::{grid-item-card} Card Title
-:img-top: images/banner.png
-:img-bottom: images/banner.png
+You can also add an image as the background of a card or at the top/bottom of the card, with the `img-background`, `img-top`, `img-bottom` options:
+
+:::::{grid} 2 3 3 4
+
+::::{grid-item}
+
+:::{card} Title
+:img-background: images/particle_background.jpg
+:class-card: sd-text-black
+
+Text
+:::
+
+::::
+
+::::{grid-item-card} Title
+:img-top: images/particle_background.jpg
 
 Header
 ^^^
-Card content
+Content
 +++
 Footer
-:::
 ::::
 
+::::{grid-item-card} Title
+:img-bottom: images/particle_background.jpg
+
+Header
+^^^
+Content
++++
+Footer
+::::
+
+:::::
+
+`````{dropdown} Syntax
+:icon: code
+:color: light
+
+````{tab-set-code}
+```{literalinclude} ./snippets/myst/card-images.txt
+:language: markdown
+```
+```{literalinclude} ./snippets/rst/card-images.txt
+:language: rst
+```
+````
+`````
+
 (cards-clickable)=
 
 ## Clickable cards
@@ -208,6 +246,9 @@ margin
 text-align
 : Default horizontal text alignment: left, right, center or justify
 
+img-background
+: A URI (relative file path or URL) to an image to be placed below the content.
+
 img-top
 : A URI (relative file path or URL) to an image to be placed above the content.
 

docs/css_classes.md

@@ -111,7 +111,7 @@ Note, for grids the special gutter classes `sd-g-{screen-size}-{spacing}` are us
 
 ## Colors
 
-Colors can be set using [CSS variable](./css_variables.md), they are defined for the semantic color names: primary, secondary, success, warning, danger, info, light, dark, and muted.
+Colors can be set using [CSS variable](./css_variables.md), they are defined for the semantic color names: `primary`, `secondary`, `success`, `warning`, `danger`, `info`, `light`, `dark`, and `muted`, and specific colors `black` and `white`.
 
 - `sd-bg-{name}`
 - `sd-bg-text-{name}`

docs/images/banner.png

@@ -1,5 +1,5 @@
 ```{article-info}
-:avatar: ebp-logo.png
+:avatar: images/ebp-logo.png
 :avatar-link: https://executablebooks.org/
 :avatar-outline: muted
 :author: Executable Books

docs/images/particle_background.jpg

@@ -0,0 +1,34 @@
+:::::{grid} 2 3 3 4
+
+::::{grid-item}
+
+:::{card} Title
+:img-background: images/particle_background.jpg
+:class-card: sd-text-black
+
+Text
+:::
+
+::::
+
+::::{grid-item-card} Title
+:img-top: images/particle_background.jpg
+
+Header
+^^^
+Content
++++
+Footer
+::::
+
+::::{grid-item-card} Title
+:img-bottom: images/particle_background.jpg
+
+Header
+^^^
+Content
++++
+Footer
+::::
+
+:::::

docs/snippets/myst/article-info.txt

@@ -1,5 +1,5 @@
 .. article-info::
-    :avatar: ebp-logo.png
+    :avatar: images/ebp-logo.png
     :avatar-link: https://executablebooks.org/
     :avatar-outline: muted
     :author: Executable Books

docs/snippets/myst/card-images.txt

@@ -0,0 +1,27 @@
+.. grid:: 2 3 3 4
+
+    .. grid-item::
+
+        .. card:: Title
+            :img-background: images/particle_background.jpg
+            :class-card: sd-text-black
+
+            Text
+
+    .. grid-item-card:: Title
+        :img-top: images/particle_background.jpg
+
+        Header
+        ^^^
+        Content
+        +++
+        Footer
+
+    .. grid-item-card:: Title
+        :img-bottom: images/particle_background.jpg
+
+        Header
+        ^^^
+        Content
+        +++
+        Footer

docs/snippets/rst/article-info.txt

@@ -57,6 +57,7 @@ class CardDirective(SphinxDirective):
         "text-align": text_align,
         "img-top": directives.uri,
         "img-bottom": directives.uri,
+        "img-background": directives.uri,
         "link": directives.uri,
         "link-type": make_choice(["url", "any", "ref", "doc"]),
         "shadow": make_choice(["none", "sm", "md", "lg"]),
@@ -91,19 +92,33 @@ def create_card(
         )
         inst.set_source_info(card)
 
+        container = card
+        if "img-background" in options:
+            card.append(
+                nodes.image(
+                    uri=options["img-background"],
+                    classes=["sd-card-img"],
+                    alt="background image",
+                )
+            )
+            overlay = create_component("card-overlay", ["sd-card-img-overlay"])
+            inst.set_source_info(overlay)
+            card += overlay
+            container = overlay
+
         if "img-top" in options:
             image_top = nodes.image(
                 "",
                 uri=options["img-top"],
                 alt="card-img-top",
                 classes=["sd-card-img-top"],
             )
-            card.append(image_top)
+            container.append(image_top)
 
         components = cls.split_content(inst.content, inst.content_offset)
 
         if components.header:
-            card.append(
+            container.append(
                 cls._create_component(
                     inst, "header", options, components.header[0], components.header[1]
                 )
@@ -121,10 +136,10 @@ def create_card(
             textnodes, _ = inst.state.inline_text(arguments[0], inst.lineno)
             title.extend(textnodes)
             body.insert(0, title)
-        card.append(body)
+        container.append(body)
 
         if components.footer:
-            card.append(
+            container.append(
                 cls._create_component(
                     inst, "footer", options, components.footer[0], components.footer[1]
                 )
@@ -137,7 +152,7 @@ def create_card(
                 alt="card-img-bottom",
                 classes=["sd-card-img-bottom"],
             )
-            card.append(image_bottom)
+            container.append(image_bottom)
 
         if "link" in options:
             link_container = PassthroughTextElement()
@@ -162,7 +177,7 @@ def create_card(
                 link = addnodes.pending_xref("", nodes.Text(""), **options)
             inst.set_source_info(link)
             link_container += link
-            card.append(link_container)
+            container.append(link_container)
 
         return card