Skip to content

Commit e258b45

Browse files
gabalafouchrisjsewell
gabalafou
and
chrisjsewell
authored
👌 Use reference name by default for internal link cards (#183)
Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
1 parent 3374383 commit e258b45

File tree

6 files changed

+156
-25
lines changed

6 files changed

+156
-25
lines changed

‎docs/cards.md‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -132,15 +132,14 @@ Try hovering over then clicking on the cards below:
132132

133133
:::{card} Clickable Card (external)
134134
:link: https://example.com
135-
:link-alt: example
135+
:link-alt: example.com
136136

137-
The entire card can be clicked to navigate to <https://example.com>.
137+
The entire card can be clicked to navigate to `https://example.com`.
138138
:::
139139

140140
:::{card} Clickable Card (internal)
141141
:link: cards-clickable
142142
:link-type: ref
143-
:link-alt: cards-clickable
144143

145144
The entire card can be clicked to navigate to the `cards-clickable` reference target.
146145
:::
@@ -157,6 +156,30 @@ The entire card can be clicked to navigate to the `cards-clickable` reference ta
157156
````
158157
`````
159158

159+
The **external link** created above is equivalent to using `<https://example.com>`
160+
(<https://example.com>),
161+
or if the `link-alt` option is provided, `[alt text](https://example.com)`
162+
([alt text](https://example.com)).
163+
164+
:::{tip}
165+
Using URLs as link text makes it harder
166+
for disabled people and for search engines to digest your web page,
167+
so it's best to provide link text via the `link-alt` option.
168+
:::
169+
170+
The **internal link** created above is equivalent to using `` {ref}`cards-clickable` ``
171+
({ref}`cards-clickable`),
172+
or if the `link-alt` option is provided, `` {ref}`alt text <cards-clickable>` ``
173+
({ref}`alt text <cards-clickable>`).
174+
175+
:::{note}
176+
You cannot add additional links to the clickable card, neither in the card
177+
title nor in the card body. The entire card becomes a single link to the
178+
destination you specify, which overrides any other links inside the card.
179+
:::
180+
181+
182+
160183
## Aligning cards
161184

162185
You can use the `text-align` option to align the text in a card,

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

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,18 @@
11
(cards-clickable)=
2-
## Cards Clickable
2+
3+
## Clickable cards
4+
5+
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:
6+
7+
:::{card} Clickable Card (external)
8+
:link: https://example.com
9+
10+
The entire card can be clicked to navigate to <https://example.com>.
11+
:::
312

413
:::{card} Clickable Card (external)
514
:link: https://example.com
15+
:link-alt: example.com
616

717
The entire card can be clicked to navigate to <https://example.com>.
818
:::
@@ -11,5 +21,13 @@ The entire card can be clicked to navigate to <https://example.com>.
1121
:link: cards-clickable
1222
:link-type: ref
1323

14-
The entire card can be clicked to navigate to the `cards` reference target.
24+
The entire card can be clicked to navigate to the `cards-clickable` reference target.
25+
:::
26+
27+
:::{card} Clickable Card (internal)
28+
:link: cards-clickable
29+
:link-type: ref
30+
:link-alt: clickable cards
31+
32+
The entire card can be clicked to navigate to the `cards-clickable` reference target.
1533
:::

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

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,30 @@
11
.. _cards-clickable:
22

3-
Cards Clickable
3+
Clickable cards
44
...............
55

6+
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:
7+
8+
.. card:: Clickable Card (external)
9+
:link: https://example.com
10+
11+
The entire card can be clicked to navigate to https://example.com.
12+
613
.. card:: Clickable Card (external)
714
:link: https://example.com
15+
:link-alt: example.com
816

917
The entire card can be clicked to navigate to https://example.com.
1018

1119
.. card:: Clickable Card (internal)
1220
:link: cards-clickable
1321
:link-type: ref
1422

15-
The entire card can be clicked to navigate to the ``cards`` reference target.
23+
The entire card can be clicked to navigate to the ``cards-clickable`` reference target.
24+
25+
.. card:: Clickable Card (internal)
26+
:link: cards-clickable
27+
:link-type: ref
28+
:link-alt: clickable cards
29+
30+
The entire card can be clicked to navigate to the ``cards-clickable`` reference target.

‎sphinx_design/cards.py‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ def run_with_defaults(self) -> list[nodes.Node]:
7878
return [self.create_card(self, self.arguments, self.options)]
7979

8080
@classmethod
81-
def create_card( # noqa: PLR0912, PLR0915
81+
def create_card( # noqa: PLR0915
8282
cls, inst: SphinxDirective, arguments: Optional[list], options: dict
8383
) -> nodes.Node:
8484
"""Run the directive."""
@@ -170,19 +170,16 @@ def create_card( # noqa: PLR0912, PLR0915
170170

171171
if "link" in options:
172172
link_container = PassthroughTextElement()
173-
_classes = ["sd-stretched-link"]
174-
_rawtext = options.get("link-alt") or ""
175-
if options.get("link-alt"):
176-
_classes.append("sd-hide-link-text")
173+
_classes = ["sd-stretched-link", "sd-hide-link-text"]
174+
_rawtext = options.get("link-alt") or options["link"]
177175
if options.get("link-type", "url") == "url":
178176
link = nodes.reference(
179177
_rawtext,
180178
"",
179+
nodes.inline(_rawtext, _rawtext),
181180
refuri=options["link"],
182181
classes=_classes,
183182
)
184-
if options.get("link-alt"):
185-
link.append(nodes.inline(_rawtext, _rawtext))
186183
else:
187184
options = {
188185
# TODO the presence of classes raises an error if the link cannot be found
@@ -191,7 +188,7 @@ def create_card( # noqa: PLR0912, PLR0915
191188
"refdoc": inst.env.docname,
192189
"refdomain": "" if options["link-type"] == "any" else "std",
193190
"reftype": options["link-type"],
194-
"refexplicit": True,
191+
"refexplicit": "link-alt" in options,
195192
"refwarn": True,
196193
}
197194
link = addnodes.pending_xref(

‎tests/test_snippets/snippet_post_card-link.xml‎

Lines changed: 44 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,17 @@
33
<title>
44
Heading
55
<target refid="cards-clickable">
6-
<section ids="cards-clickable id1" names="cards\ clickable cards-clickable">
6+
<section ids="clickable-cards cards-clickable" names="clickable\ cards cards-clickable">
77
<title>
8-
Cards Clickable
8+
Clickable cards
9+
<paragraph>
10+
Using the
11+
<literal>
12+
link
13+
and
14+
<literal>
15+
link-type
16+
options, you can turn an entire card into a clickable link. Try hovering over then clicking on the cards below:
917
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm sd-card-hover" design_component="card" is_div="True">
1018
<container classes="sd-card-body" design_component="card-body" is_div="True">
1119
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
@@ -17,7 +25,37 @@
1725
https://example.com
1826
.
1927
<PassthroughTextElement>
20-
<reference classes="sd-stretched-link" refuri="https://example.com">
28+
<reference classes="sd-stretched-link sd-hide-link-text" refuri="https://example.com">
29+
<inline>
30+
https://example.com
31+
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm sd-card-hover" design_component="card" is_div="True">
32+
<container classes="sd-card-body" design_component="card-body" is_div="True">
33+
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
34+
<PassthroughTextElement>
35+
Clickable Card (external)
36+
<paragraph classes="sd-card-text">
37+
The entire card can be clicked to navigate to
38+
<reference refuri="https://example.com">
39+
https://example.com
40+
.
41+
<PassthroughTextElement>
42+
<reference classes="sd-stretched-link sd-hide-link-text" refuri="https://example.com">
43+
<inline>
44+
example.com
45+
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm sd-card-hover" design_component="card" is_div="True">
46+
<container classes="sd-card-body" design_component="card-body" is_div="True">
47+
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
48+
<PassthroughTextElement>
49+
Clickable Card (internal)
50+
<paragraph classes="sd-card-text">
51+
The entire card can be clicked to navigate to the
52+
<literal>
53+
cards-clickable
54+
reference target.
55+
<PassthroughTextElement>
56+
<reference classes="sd-stretched-link sd-hide-link-text" internal="True" refid="cards-clickable">
57+
<inline classes="std std-ref">
58+
Clickable cards
2159
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm sd-card-hover" design_component="card" is_div="True">
2260
<container classes="sd-card-body" design_component="card-body" is_div="True">
2361
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
@@ -26,8 +64,9 @@
2664
<paragraph classes="sd-card-text">
2765
The entire card can be clicked to navigate to the
2866
<literal>
29-
cards
67+
cards-clickable
3068
reference target.
3169
<PassthroughTextElement>
32-
<reference classes="sd-stretched-link" internal="True" refid="cards-clickable">
70+
<reference classes="sd-stretched-link sd-hide-link-text" internal="True" refid="cards-clickable">
3371
<inline classes="std std-ref">
72+
clickable cards

‎tests/test_snippets/snippet_pre_card-link.xml‎

Lines changed: 44 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,17 @@
33
<title>
44
Heading
55
<target refid="cards-clickable">
6-
<section ids="cards-clickable id1" names="cards\ clickable cards-clickable">
6+
<section ids="clickable-cards cards-clickable" names="clickable\ cards cards-clickable">
77
<title>
8-
Cards Clickable
8+
Clickable cards
9+
<paragraph>
10+
Using the
11+
<literal>
12+
link
13+
and
14+
<literal>
15+
link-type
16+
options, you can turn an entire card into a clickable link. Try hovering over then clicking on the cards below:
917
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm sd-card-hover" design_component="card" is_div="True">
1018
<container classes="sd-card-body" design_component="card-body" is_div="True">
1119
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
@@ -17,7 +25,37 @@
1725
https://example.com
1826
.
1927
<PassthroughTextElement>
20-
<reference classes="sd-stretched-link" refuri="https://example.com">
28+
<reference classes="sd-stretched-link sd-hide-link-text" refuri="https://example.com">
29+
<inline>
30+
https://example.com
31+
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm sd-card-hover" design_component="card" is_div="True">
32+
<container classes="sd-card-body" design_component="card-body" is_div="True">
33+
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
34+
<PassthroughTextElement>
35+
Clickable Card (external)
36+
<paragraph classes="sd-card-text">
37+
The entire card can be clicked to navigate to
38+
<reference refuri="https://example.com">
39+
https://example.com
40+
.
41+
<PassthroughTextElement>
42+
<reference classes="sd-stretched-link sd-hide-link-text" refuri="https://example.com">
43+
<inline>
44+
example.com
45+
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm sd-card-hover" design_component="card" is_div="True">
46+
<container classes="sd-card-body" design_component="card-body" is_div="True">
47+
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
48+
<PassthroughTextElement>
49+
Clickable Card (internal)
50+
<paragraph classes="sd-card-text">
51+
The entire card can be clicked to navigate to the
52+
<literal>
53+
cards-clickable
54+
reference target.
55+
<PassthroughTextElement>
56+
<pending_xref classes="sd-stretched-link sd-hide-link-text" refdoc="index" refdomain="std" refexplicit="False" reftarget="cards-clickable" reftype="ref" refwarn="True">
57+
<inline>
58+
cards-clickable
2159
<container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm sd-card-hover" design_component="card" is_div="True">
2260
<container classes="sd-card-body" design_component="card-body" is_div="True">
2361
<container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
@@ -26,8 +64,9 @@
2664
<paragraph classes="sd-card-text">
2765
The entire card can be clicked to navigate to the
2866
<literal>
29-
cards
67+
cards-clickable
3068
reference target.
3169
<PassthroughTextElement>
32-
<pending_xref classes="sd-stretched-link" refdoc="index" refdomain="std" refexplicit="True" reftarget="cards-clickable" reftype="ref" refwarn="True">
70+
<pending_xref classes="sd-stretched-link sd-hide-link-text" refdoc="index" refdomain="std" refexplicit="True" reftarget="cards-clickable" reftype="ref" refwarn="True">
3371
<inline>
72+
clickable cards

0 commit comments

Comments
 (0)