👌 Use reference name by default for internal link cards (#183)

Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
executablebooks · May 22, 2024 · e258b45 · e258b45
1 parent 3374383
commit e258b45
Show file tree

Hide file tree

Showing 6 changed files with 156 additions and 25 deletions.
diff --git a/docs/cards.md b/docs/cards.md
@@ -132,15 +132,14 @@ Try hovering over then clicking on the cards below:
 
 :::{card} Clickable Card (external)
 :link: https://example.com
-:link-alt: example
+:link-alt: example.com
 
-The entire card can be clicked to navigate to <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
-:link-alt: cards-clickable
 
 The entire card can be clicked to navigate to the `cards-clickable` reference target.
 :::
@@ -157,6 +156,30 @@ The entire card can be clicked to navigate to the `cards-clickable` reference ta
 ````
 `````
 
+The **external link** created above is equivalent to using `<https://example.com>`
+(<https://example.com>),
+or if the `link-alt` option is provided, `[alt text](https://example.com)`
+([alt text](https://example.com)).
+
+:::{tip}
+Using URLs as link text makes it harder
+for disabled people and for search engines to digest your web page,
+so it's best to provide link text via the `link-alt` option.
+:::
+
+The **internal link** created above is equivalent to using `` {ref}`cards-clickable` ``
+({ref}`cards-clickable`),
+or if the `link-alt` option is provided, `` {ref}`alt text <cards-clickable>` ``
+({ref}`alt text <cards-clickable>`).
+
+:::{note}
+You cannot add additional links to the clickable card, neither in the card
+title nor in the card body. The entire card becomes a single link to the
+destination you specify, which overrides any other links inside the card.
+:::
+
+
+
 ## Aligning cards
 
 You can use the `text-align` option to align the text in a card,

diff --git a/docs/snippets/myst/card-link.txt b/docs/snippets/myst/card-link.txt
@@ -1,8 +1,18 @@
 (cards-clickable)=
-## 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 (external)
 :link: https://example.com
+:link-alt: example.com
 
 The entire card can be clicked to navigate to <https://example.com>.
 :::
@@ -11,5 +21,13 @@ The entire card can be clicked to navigate to <https://example.com>.
 :link: cards-clickable
 :link-type: ref
 
-The entire card can be clicked to navigate to the `cards` reference target.
+The entire card can be clicked to navigate to the `cards-clickable` reference target.
+:::
+
+:::{card} Clickable Card (internal)
+:link: cards-clickable
+:link-type: ref
+:link-alt: clickable cards
+
+The entire card can be clicked to navigate to the `cards-clickable` reference target.
 :::
diff --git a/docs/snippets/rst/card-link.txt b/docs/snippets/rst/card-link.txt
@@ -1,15 +1,30 @@
 .. _cards-clickable:
 
-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 (external)
     :link: https://example.com
+    :link-alt: 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.
+    The entire card can be clicked to navigate to the ``cards-clickable`` reference target.
+
+.. card:: Clickable Card (internal)
+    :link: cards-clickable
+    :link-type: ref
+    :link-alt: clickable cards
+
+    The entire card can be clicked to navigate to the ``cards-clickable`` reference target.
diff --git a/sphinx_design/cards.py b/sphinx_design/cards.py
@@ -78,7 +78,7 @@ def run_with_defaults(self) -> list[nodes.Node]:
         return [self.create_card(self, self.arguments, self.options)]
 
     @classmethod
-    def create_card(  # noqa: PLR0912, PLR0915
+    def create_card(  # noqa: PLR0915
         cls, inst: SphinxDirective, arguments: Optional[list], options: dict
     ) -> nodes.Node:
         """Run the directive."""
@@ -170,19 +170,16 @@ def create_card(  # noqa: PLR0912, PLR0915
 
         if "link" in options:
             link_container = PassthroughTextElement()
-            _classes = ["sd-stretched-link"]
-            _rawtext = options.get("link-alt") or ""
-            if options.get("link-alt"):
-                _classes.append("sd-hide-link-text")
+            _classes = ["sd-stretched-link", "sd-hide-link-text"]
+            _rawtext = options.get("link-alt") or options["link"]
             if options.get("link-type", "url") == "url":
                 link = nodes.reference(
                     _rawtext,
                     "",
+                    nodes.inline(_rawtext, _rawtext),
                     refuri=options["link"],
                     classes=_classes,
                 )
-                if options.get("link-alt"):
-                    link.append(nodes.inline(_rawtext, _rawtext))
             else:
                 options = {
                     # TODO the presence of classes raises an error if the link cannot be found
@@ -191,7 +188,7 @@ def create_card(  # noqa: PLR0912, PLR0915
                     "refdoc": inst.env.docname,
                     "refdomain": "" if options["link-type"] == "any" else "std",
                     "reftype": options["link-type"],
-                    "refexplicit": True,
+                    "refexplicit": "link-alt" in options,
                     "refwarn": True,
                 }
                 link = addnodes.pending_xref(

diff --git a/tests/test_snippets/snippet_post_card-link.xml b/tests/test_snippets/snippet_post_card-link.xml
@@ -3,9 +3,17 @@
         <title>
             Heading
         <target refid="cards-clickable">
-        <section ids="cards-clickable id1" names="cards\ clickable cards-clickable">
+        <section ids="clickable-cards cards-clickable" names="clickable\ cards cards-clickable">
             <title>
-                Cards Clickable
+                Clickable cards
+            <paragraph>
+                Using the 
+                <literal>
+                    link
+                 and 
+                <literal>
+                    link-type
+                 options, you can turn an entire card into a clickable link. Try hovering over then clicking on the cards below:
             <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm 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">
@@ -17,7 +25,37 @@
                             https://example.com
                         .
                 <PassthroughTextElement>
-                    <reference classes="sd-stretched-link" refuri="https://example.com">
+                    <reference classes="sd-stretched-link sd-hide-link-text" refuri="https://example.com">
+                        <inline>
+                            https://example.com
+            <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm 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">
+                        <PassthroughTextElement>
+                            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 sd-hide-link-text" refuri="https://example.com">
+                        <inline>
+                            example.com
+            <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm 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">
+                        <PassthroughTextElement>
+                            Clickable Card (internal)
+                    <paragraph classes="sd-card-text">
+                        The entire card can be clicked to navigate to the 
+                        <literal>
+                            cards-clickable
+                         reference target.
+                <PassthroughTextElement>
+                    <reference classes="sd-stretched-link sd-hide-link-text" internal="True" refid="cards-clickable">
+                        <inline classes="std std-ref">
+                            Clickable cards
             <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm 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">
@@ -26,8 +64,9 @@
                     <paragraph classes="sd-card-text">
                         The entire card can be clicked to navigate to the 
                         <literal>
-                            cards
+                            cards-clickable
                          reference target.
                 <PassthroughTextElement>
-                    <reference classes="sd-stretched-link" internal="True" refid="cards-clickable">
+                    <reference classes="sd-stretched-link sd-hide-link-text" internal="True" refid="cards-clickable">
                         <inline classes="std std-ref">
+                            clickable cards
diff --git a/tests/test_snippets/snippet_pre_card-link.xml b/tests/test_snippets/snippet_pre_card-link.xml
@@ -3,9 +3,17 @@
         <title>
             Heading
         <target refid="cards-clickable">
-        <section ids="cards-clickable id1" names="cards\ clickable cards-clickable">
+        <section ids="clickable-cards cards-clickable" names="clickable\ cards cards-clickable">
             <title>
-                Cards Clickable
+                Clickable cards
+            <paragraph>
+                Using the 
+                <literal>
+                    link
+                 and 
+                <literal>
+                    link-type
+                 options, you can turn an entire card into a clickable link. Try hovering over then clicking on the cards below:
             <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm 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">
@@ -17,7 +25,37 @@
                             https://example.com
                         .
                 <PassthroughTextElement>
-                    <reference classes="sd-stretched-link" refuri="https://example.com">
+                    <reference classes="sd-stretched-link sd-hide-link-text" refuri="https://example.com">
+                        <inline>
+                            https://example.com
+            <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm 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">
+                        <PassthroughTextElement>
+                            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 sd-hide-link-text" refuri="https://example.com">
+                        <inline>
+                            example.com
+            <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm 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">
+                        <PassthroughTextElement>
+                            Clickable Card (internal)
+                    <paragraph classes="sd-card-text">
+                        The entire card can be clicked to navigate to the 
+                        <literal>
+                            cards-clickable
+                         reference target.
+                <PassthroughTextElement>
+                    <pending_xref classes="sd-stretched-link sd-hide-link-text" refdoc="index" refdomain="std" refexplicit="False" reftarget="cards-clickable" reftype="ref" refwarn="True">
+                        <inline>
+                            cards-clickable
             <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm 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">
@@ -26,8 +64,9 @@
                     <paragraph classes="sd-card-text">
                         The entire card can be clicked to navigate to the 
                         <literal>
-                            cards
+                            cards-clickable
                          reference target.
                 <PassthroughTextElement>
-                    <pending_xref classes="sd-stretched-link" refdoc="index" refdomain="std" refexplicit="True" reftarget="cards-clickable" reftype="ref" refwarn="True">
+                    <pending_xref classes="sd-stretched-link sd-hide-link-text" refdoc="index" refdomain="std" refexplicit="True" reftarget="cards-clickable" reftype="ref" refwarn="True">
                         <inline>
+                            clickable cards