Skip to content

Commit 37ab742

Browse files
chrisjsewellchrisjsewell
authored
📚 DOCS: Improve documentation for cards (#2)
1 parent e38121f commit 37ab742

13 files changed

+247
-11
lines changed

‎docs/cards.md‎

Lines changed: 83 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,23 @@ It can be formatted with components including headers and footers, titles and im
1010
Card content
1111
:::
1212

13-
All content before the first occurrence three or more `^^^` is considered as a header,
13+
See the [Bootstrap card](https://getbootstrap.com/docs/5.0/layout/grid/) for further details.
14+
15+
`````{dropdown} Syntax
16+
:icon: code
17+
:color: light
18+
19+
````{tab-set-code}
20+
```{literalinclude} ./snippets/myst/card-basic.txt
21+
:language: markdown
22+
```
23+
```{literalinclude} ./snippets/rst/card-basic.txt
24+
:language: rst
25+
```
26+
````
27+
`````
28+
29+
All content before the first occurrence of three or more `^^^` is considered as a header,
1430
and all content after the final occurrence of three or more `+++` is considered as a footer:
1531

1632
:::{card} Card Title
@@ -21,19 +37,42 @@ Card content
2137
Footer
2238
:::
2339

24-
:::{card} Clickable Card (external)
25-
:link: https://example.com
40+
`````{dropdown} Syntax
41+
:icon: code
42+
:color: light
2643
27-
The entire card can be clicked to navigate to <https://example.com>.
28-
:::
44+
````{tab-set-code}
45+
```{literalinclude} ./snippets/myst/card-head-foot.txt
46+
:language: markdown
47+
```
48+
```{literalinclude} ./snippets/rst/card-head-foot.txt
49+
:language: rst
50+
```
51+
````
52+
`````
2953

30-
:::{card} Clickable Card (internal)
31-
:link: cards
32-
:link-type: ref
54+
When using cards in grids (see [`grid-item-card`](./grids.md)) footers can be aligned.
3355

34-
The entire card can be clicked to navigate to the `cards` reference target.
56+
::::{grid} 2
57+
:::{grid-item-card} Card Title
58+
Header
59+
^^^
60+
Card content
61+
+++
62+
Footer
3563
:::
64+
:::{grid-item-card} Card Title
65+
Header
66+
^^^
67+
Longer
3668

69+
Card content
70+
+++
71+
Footer
72+
:::
73+
::::
74+
75+
You can also add images to the top and bottom of the card, with the `img-top` and `img-bottom` options:
3776

3877
::::{grid} 1 2 2 2
3978
:::{grid-item-card} Card Title
@@ -48,6 +87,41 @@ Footer
4887
:::
4988
::::
5089

90+
(cards-clickable)=
91+
92+
## Clickable cards
93+
94+
Using the `link` and `link-type` options, you can turn an entire card into a clickable link.
95+
Try hovering over then clicking on the cards below:
96+
97+
:::{card} Clickable Card (external)
98+
:link: https://example.com
99+
100+
The entire card can be clicked to navigate to <https://example.com>.
101+
:::
102+
103+
:::{card} Clickable Card (internal)
104+
:link: cards-clickable
105+
:link-type: ref
106+
107+
The entire card can be clicked to navigate to the `cards-clickable` reference target.
108+
:::
109+
110+
`````{dropdown} Syntax
111+
:icon: code
112+
:color: light
113+
114+
````{tab-set-code}
115+
```{literalinclude} ./snippets/myst/card-link.txt
116+
:language: markdown
117+
```
118+
```{literalinclude} ./snippets/rst/card-link.txt
119+
:language: rst
120+
```
121+
````
122+
`````
123+
124+
## Aligning cards
51125

52126
:::{card} Align Center
53127
:width: 75%
@@ -73,8 +147,6 @@ Content
73147
Content
74148
:::
75149

76-
See the [Bootstrap card](https://getbootstrap.com/docs/5.0/layout/grid/) for further details.
77-
78150
## `card` options
79151

80152
width

‎docs/snippets/myst/card-basic.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
:::{card} Card Title
2+
3+
Card content
4+
:::

‎docs/snippets/myst/card-head-foot.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
:::{card} Card Title
2+
Header
3+
^^^
4+
Card content
5+
+++
6+
Footer
7+
:::

‎docs/snippets/myst/card-link.txt‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
(cards-clickable)=
2+
## Cards Clickable
3+
4+
:::{card} Clickable Card (external)
5+
:link: https://example.com
6+
7+
The entire card can be clicked to navigate to <https://example.com>.
8+
:::
9+
10+
:::{card} Clickable Card (internal)
11+
:link: cards-clickable
12+
:link-type: ref
13+
14+
The entire card can be clicked to navigate to the `cards` reference target.
15+
:::

‎docs/snippets/rst/card-basic.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.. card:: Card Title
2+
3+
Card content

‎docs/snippets/rst/card-head-foot.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. card:: Card Title
2+
3+
Header
4+
^^^
5+
Card content
6+
+++
7+
Footer

‎docs/snippets/rst/card-link.txt‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.. _cards-clickable:
2+
3+
Cards Clickable
4+
...............
5+
6+
.. card:: Clickable Card (external)
7+
:link: https://example.com
8+
9+
The entire card can be clicked to navigate to https://example.com.
10+
11+
.. card:: Clickable Card (internal)
12+
:link: cards-clickable
13+
:link-type: ref
14+
15+
The entire card can be clicked to navigate to the ``cards`` reference target.

‎tests/test_snippets/snippet_post_card-basic.xml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<document source="index">
2+
<section ids="heading" names="heading">
3+
<title>
4+
Heading
5+
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow" design_component="card" is_div="True">
6+
<container classes="sd-card-body" design_component="card-body" is_div="True">
7+
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
8+
Card Title
9+
<paragraph classes="sd-card-text">
10+
Card content

‎tests/test_snippets/snippet_post_card-head-foot.xml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<document source="index">
2+
<section ids="heading" names="heading">
3+
<title>
4+
Heading
5+
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow" design_component="card" is_div="True">
6+
<container classes="sd-card-header" design_component="card-header" is_div="True">
7+
<paragraph classes="sd-card-text">
8+
Header
9+
<container classes="sd-card-body" design_component="card-body" is_div="True">
10+
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
11+
Card Title
12+
<paragraph classes="sd-card-text">
13+
Card content
14+
<container classes="sd-card-footer" design_component="card-footer" is_div="True">
15+
<paragraph classes="sd-card-text">
16+
Footer

‎tests/test_snippets/snippet_post_card-link.xml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
<document source="index">
2+
<section ids="heading" names="heading">
3+
<title>
4+
Heading
5+
<target refid="cards-clickable">
6+
<section ids="cards-clickable id1" names="cards\ clickable cards-clickable">
7+
<title>
8+
Cards Clickable
9+
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow sd-card-hover" design_component="card" is_div="True">
10+
<container classes="sd-card-body" design_component="card-body" is_div="True">
11+
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
12+
Clickable Card (external)
13+
<paragraph classes="sd-card-text">
14+
The entire card can be clicked to navigate to
15+
<reference refuri="https://example.com">
16+
https://example.com
17+
.
18+
<PassthroughTextElement>
19+
<reference classes="sd-stretched-link" refuri="https://example.com">
20+
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow sd-card-hover" design_component="card" is_div="True">
21+
<container classes="sd-card-body" design_component="card-body" is_div="True">
22+
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
23+
Clickable Card (internal)
24+
<paragraph classes="sd-card-text">
25+
The entire card can be clicked to navigate to the
26+
<literal>
27+
cards
28+
reference target.
29+
<PassthroughTextElement>
30+
<reference classes="sd-stretched-link" internal="True" refid="cards-clickable">
31+
<inline classes="std std-ref">

0 commit comments

Comments
 (0)