executablebooks · chrisjsewell · Jul 23, 2021 · Jul 23, 2021
diff --git a/docs/cards.md b/docs/cards.md
@@ -10,7 +10,23 @@ It can be formatted with components including headers and footers, titles and im
 Card content
 :::
 
-All content before the first occurrence three or more `^^^` is considered as a header,
+See the [Bootstrap card](https://getbootstrap.com/docs/5.0/layout/grid/) for further details.
+
+`````{dropdown} Syntax
+:icon: code
+:color: light
+
+````{tab-set-code}
+```{literalinclude} ./snippets/myst/card-basic.txt
+:language: markdown
+```
+```{literalinclude} ./snippets/rst/card-basic.txt
+:language: rst
+```
+````
+`````
+
+All content before the first occurrence of three or more `^^^` is considered as a header,
 and all content after the final occurrence of three or more `+++` is considered as a footer:
 
 :::{card} Card Title
@@ -21,19 +37,42 @@ Card content
 Footer
 :::
 
-:::{card} Clickable Card (external)
-:link: https://example.com
+`````{dropdown} Syntax
+:icon: code
+:color: light
 
-The entire card can be clicked to navigate to <https://example.com>.
-:::
+````{tab-set-code}
+```{literalinclude} ./snippets/myst/card-head-foot.txt
+:language: markdown
+```
+```{literalinclude} ./snippets/rst/card-head-foot.txt
+:language: rst
+```
+````
+`````
 
-:::{card} Clickable Card (internal)
-:link: cards
-:link-type: ref
+When using cards in grids (see [`grid-item-card`](./grids.md)) footers can be aligned.
 
-The entire card can be clicked to navigate to the `cards` reference target.
+::::{grid} 2
+:::{grid-item-card} Card Title
+Header
+^^^
+Card content
++++
+Footer
 :::
+:::{grid-item-card} Card Title
+Header
+^^^
+Longer
 
+Card content
++++
+Footer
+:::
+::::
+
+You can also add images to the top and bottom of the card, with the `img-top` and `img-bottom` options:
 
 ::::{grid} 1 2 2 2
 :::{grid-item-card} Card Title
@@ -48,6 +87,41 @@ Footer
 :::
 ::::
 
+(cards-clickable)=
+
+## Clickable cards
+
+Using the `link` and `link-type` options, you can turn an entire card into a clickable link.
+Try hovering over then clicking on the cards below:
+
+:::{card} Clickable Card (external)
+:link: https://example.com
+
+The entire card can be clicked to navigate to <https://example.com>.
+:::
+
+:::{card} Clickable Card (internal)
+:link: cards-clickable
+:link-type: ref
+
+The entire card can be clicked to navigate to the `cards-clickable` reference target.
+:::
+
+`````{dropdown} Syntax
+:icon: code
+:color: light
+
+````{tab-set-code}
+```{literalinclude} ./snippets/myst/card-link.txt
+:language: markdown
+```
+```{literalinclude} ./snippets/rst/card-link.txt
+:language: rst
+```
+````
+`````
+
+## Aligning cards
 
 :::{card} Align Center
 :width: 75%
@@ -73,8 +147,6 @@ Content
 Content
 :::
 
-See the [Bootstrap card](https://getbootstrap.com/docs/5.0/layout/grid/) for further details.
-
 ## `card` options
 
 width

diff --git a/docs/snippets/myst/card-basic.txt b/docs/snippets/myst/card-basic.txt
@@ -0,0 +1,4 @@
+:::{card} Card Title
+
+Card content
+:::
diff --git a/docs/snippets/myst/card-head-foot.txt b/docs/snippets/myst/card-head-foot.txt
@@ -0,0 +1,7 @@
+:::{card} Card Title
+Header
+^^^
+Card content
++++
+Footer
+:::
diff --git a/docs/snippets/myst/card-link.txt b/docs/snippets/myst/card-link.txt
@@ -0,0 +1,15 @@
+(cards-clickable)=
+## Cards Clickable
+
+:::{card} Clickable Card (external)
+:link: https://example.com
+
+The entire card can be clicked to navigate to <https://example.com>.
+:::
+
+:::{card} Clickable Card (internal)
+:link: cards-clickable
+:link-type: ref
+
+The entire card can be clicked to navigate to the `cards` reference target.
+:::
diff --git a/docs/snippets/rst/card-basic.txt b/docs/snippets/rst/card-basic.txt
@@ -0,0 +1,3 @@
+.. card:: Card Title
+
+    Card content
diff --git a/docs/snippets/rst/card-head-foot.txt b/docs/snippets/rst/card-head-foot.txt
@@ -0,0 +1,7 @@
+.. card:: Card Title
+
+    Header
+    ^^^
+    Card content
+    +++
+    Footer
diff --git a/docs/snippets/rst/card-link.txt b/docs/snippets/rst/card-link.txt
@@ -0,0 +1,15 @@
+.. _cards-clickable:
+
+Cards Clickable
+...............
+
+.. card:: Clickable Card (external)
+    :link: https://example.com
+
+    The entire card can be clicked to navigate to https://example.com.
+
+.. card:: Clickable Card (internal)
+    :link: cards-clickable
+    :link-type: ref
+
+    The entire card can be clicked to navigate to the ``cards`` reference target.
diff --git a/tests/test_snippets/snippet_post_card-basic.xml b/tests/test_snippets/snippet_post_card-basic.xml
@@ -0,0 +1,10 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow" design_component="card" is_div="True">
+            <container classes="sd-card-body" design_component="card-body" is_div="True">
+                <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                    Card Title
+                <paragraph classes="sd-card-text">
+                    Card content
diff --git a/tests/test_snippets/snippet_post_card-head-foot.xml b/tests/test_snippets/snippet_post_card-head-foot.xml
@@ -0,0 +1,16 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow" design_component="card" is_div="True">
+            <container classes="sd-card-header" design_component="card-header" is_div="True">
+                <paragraph classes="sd-card-text">
+                    Header
+            <container classes="sd-card-body" design_component="card-body" is_div="True">
+                <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                    Card Title
+                <paragraph classes="sd-card-text">
+                    Card content
+            <container classes="sd-card-footer" design_component="card-footer" is_div="True">
+                <paragraph classes="sd-card-text">
+                    Footer
diff --git a/tests/test_snippets/snippet_post_card-link.xml b/tests/test_snippets/snippet_post_card-link.xml
@@ -0,0 +1,31 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <target refid="cards-clickable">
+        <section ids="cards-clickable id1" names="cards\ clickable cards-clickable">
+            <title>
+                Cards Clickable
+            <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow sd-card-hover" design_component="card" is_div="True">
+                <container classes="sd-card-body" design_component="card-body" is_div="True">
+                    <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                        Clickable Card (external)
+                    <paragraph classes="sd-card-text">
+                        The entire card can be clicked to navigate to 
+                        <reference refuri="https://example.com">
+                            https://example.com
+                        .
+                <PassthroughTextElement>
+                    <reference classes="sd-stretched-link" refuri="https://example.com">
+            <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow sd-card-hover" design_component="card" is_div="True">
+                <container classes="sd-card-body" design_component="card-body" is_div="True">
+                    <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                        Clickable Card (internal)
+                    <paragraph classes="sd-card-text">
+                        The entire card can be clicked to navigate to the 
+                        <literal>
+                            cards
+                         reference target.
+                <PassthroughTextElement>
+                    <reference classes="sd-stretched-link" internal="True" refid="cards-clickable">
+                        <inline classes="std std-ref">
diff --git a/tests/test_snippets/snippet_pre_card-basic.xml b/tests/test_snippets/snippet_pre_card-basic.xml
@@ -0,0 +1,10 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow" design_component="card" is_div="True">
+            <container classes="sd-card-body" design_component="card-body" is_div="True">
+                <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                    Card Title
+                <paragraph classes="sd-card-text">
+                    Card content
diff --git a/tests/test_snippets/snippet_pre_card-head-foot.xml b/tests/test_snippets/snippet_pre_card-head-foot.xml
@@ -0,0 +1,16 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow" design_component="card" is_div="True">
+            <container classes="sd-card-header" design_component="card-header" is_div="True">
+                <paragraph classes="sd-card-text">
+                    Header
+            <container classes="sd-card-body" design_component="card-body" is_div="True">
+                <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                    Card Title
+                <paragraph classes="sd-card-text">
+                    Card content
+            <container classes="sd-card-footer" design_component="card-footer" is_div="True">
+                <paragraph classes="sd-card-text">
+                    Footer
diff --git a/tests/test_snippets/snippet_pre_card-link.xml b/tests/test_snippets/snippet_pre_card-link.xml
@@ -0,0 +1,30 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <target refid="cards-clickable">
+        <section ids="cards-clickable id1" names="cards\ clickable cards-clickable">
+            <title>
+                Cards Clickable
+            <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow sd-card-hover" design_component="card" is_div="True">
+                <container classes="sd-card-body" design_component="card-body" is_div="True">
+                    <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                        Clickable Card (external)
+                    <paragraph classes="sd-card-text">
+                        The entire card can be clicked to navigate to 
+                        <reference refuri="https://example.com">
+                            https://example.com
+                        .
+                <PassthroughTextElement>
+                    <reference classes="sd-stretched-link" refuri="https://example.com">
+            <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow sd-card-hover" design_component="card" is_div="True">
+                <container classes="sd-card-body" design_component="card-body" is_div="True">
+                    <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                        Clickable Card (internal)
+                    <paragraph classes="sd-card-text">
+                        The entire card can be clicked to navigate to the 
+                        <literal>
+                            cards
+                         reference target.
+                <PassthroughTextElement>
+                    <pending_xref classes="sd-stretched-link" refdoc="index" refdomain="std" refexplicit="True" reftarget="cards-clickable" reftype="ref" refwarn="True">