Update to docs and tests

executablebooks · May 22, 2024 · 2c9dd09 · 2c9dd09
1 parent 224c291
commit 2c9dd09
Show file tree

Hide file tree

Showing 5 changed files with 100 additions and 76 deletions.
diff --git a/docs/cards.md b/docs/cards.md
@@ -134,32 +134,16 @@ Try hovering over then clicking on the cards below:
 :link: https://example.com
 :link-alt: example.com
 
-The entire card can be clicked to navigate to <https://example.com>.
-
-For **external** link cards, if you do not provide `link-alt`, the URL will be
-used as the text of the link. 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 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.
-
-For **internal** link cards, it's unnecessary to provide `link-alt`. The name of
-the section that you are referencing will be used as the link's accessible name.
-For example, this card references `cards-clickable`, so the link title will be
-"Clickable cards" (same as the section heading). If you wish to use a different
-title for the link, you can provide `link-alt` and it will take precedence.
+The entire card can be clicked to navigate to the `cards-clickable` reference target.
 :::
 
-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.
-
 `````{dropdown-syntax}
 
 ````{tab-set-code}
@@ -172,6 +156,30 @@ destination you specify, which overrides any other links inside the card.
 ````
 `````
 
+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
@@ -6,20 +6,28 @@ Using the `link` and `link-type` options, you can turn an entire card into a cli
 
 :::{card} Clickable Card (external)
 :link: https://example.com
-:link-alt: example.com
 
 The entire card can be clicked to navigate to <https://example.com>.
+:::
 
-For **external** link cards, if you do not provide `link-alt`, the URL will be used as the text of the link. 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.
+:::{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-clickable` reference target.
-
-For **internal** link cards, it's unnecessary to provide `link-alt`. The name of the section that you are referencing will be used as the link's accessible name. For example, this card references `cards-clickable`, so the link title will be "Clickable cards" (same as the section heading). If you wish to use a different title for the link, you can provide `link-alt` and it will take precedence.
 :::
 
-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.
+:::{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
@@ -7,18 +7,24 @@ Using the ``link`` and ``link-type`` options, you can turn an entire card into a
 
 .. card:: Clickable Card (external)
     :link: https://example.com
-    :link-alt: example.com
 
     The entire card can be clicked to navigate to https://example.com.
 
-    For **external** link cards, if you do not provide ``link-alt``, the URL will be used as the text of the link. 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.
+.. 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-clickable`` reference target.
 
-    For **internal** link cards, it's unnecessary to provide ``link-alt``. The name of the section that you are referencing will be used as the link's accessible name. For example, this card references ``cards-clickable``, so the link title will be "Clickable cards" (same as the section heading). If you wish to use a different title for the link, you can provide ``link-alt`` and it will take precedence.
+.. card:: Clickable Card (internal)
+    :link: cards-clickable
+    :link-type: ref
+    :link-alt: clickable cards
 
-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.
+    The entire card can be clicked to navigate to the ``cards-clickable`` reference target.
diff --git a/tests/test_snippets/snippet_post_card-link.xml b/tests/test_snippets/snippet_post_card-link.xml
@@ -24,17 +24,20 @@
                         <reference refuri="https://example.com">
                             https://example.com
                         .
+                <PassthroughTextElement>
+                    <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">
-                        For 
-                        <strong>
-                            external
-                         link cards, if you do not provide 
-                        <literal>
-                            link-alt
-                        , the URL will be used as the text of the link. 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 
-                        <literal>
-                            link-alt
-                         option.
+                        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>
@@ -49,23 +52,21 @@
                         <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">
+                        <PassthroughTextElement>
+                            Clickable Card (internal)
                     <paragraph classes="sd-card-text">
-                        For 
-                        <strong>
-                            internal
-                         link cards, it’s unnecessary to provide 
-                        <literal>
-                            link-alt
-                        . The name of the section that you are referencing will be used as the link’s accessible name. For example, this card references 
+                        The entire card can be clicked to navigate to the 
                         <literal>
                             cards-clickable
-                        , so the link title will be “Clickable cards” (same as the section heading). If you wish to use a different title for the link, you can provide 
-                        <literal>
-                            link-alt
-                         and it will take precedence.
+                         reference target.
                 <PassthroughTextElement>
                     <reference classes="sd-stretched-link sd-hide-link-text" internal="True" refid="cards-clickable">
                         <inline classes="std std-ref">
-                            Clickable cards
-            <paragraph>
-                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.
+                            clickable cards
diff --git a/tests/test_snippets/snippet_pre_card-link.xml b/tests/test_snippets/snippet_pre_card-link.xml
@@ -24,17 +24,20 @@
                         <reference refuri="https://example.com">
                             https://example.com
                         .
+                <PassthroughTextElement>
+                    <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">
-                        For 
-                        <strong>
-                            external
-                         link cards, if you do not provide 
-                        <literal>
-                            link-alt
-                        , the URL will be used as the text of the link. 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 
-                        <literal>
-                            link-alt
-                         option.
+                        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>
@@ -49,23 +52,21 @@
                         <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">
+                        <PassthroughTextElement>
+                            Clickable Card (internal)
                     <paragraph classes="sd-card-text">
-                        For 
-                        <strong>
-                            internal
-                         link cards, it’s unnecessary to provide 
-                        <literal>
-                            link-alt
-                        . The name of the section that you are referencing will be used as the link’s accessible name. For example, this card references 
+                        The entire card can be clicked to navigate to the 
                         <literal>
                             cards-clickable
-                        , so the link title will be “Clickable cards” (same as the section heading). If you wish to use a different title for the link, you can provide 
-                        <literal>
-                            link-alt
-                         and it will take precedence.
+                         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">
+                    <pending_xref classes="sd-stretched-link sd-hide-link-text" refdoc="index" refdomain="std" refexplicit="True" reftarget="cards-clickable" reftype="ref" refwarn="True">
                         <inline>
-                            cards-clickable
-            <paragraph>
-                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.
+                            clickable cards