Skip to content

Commit

Permalink
👌 IMPROVE: Use reference name by default for internal link cards
Browse files Browse the repository at this point in the history 
For cards that link to internal references, we can use the associated
name of the reference to supply the link text, so that the link isn't
left blank if `link-alt` is not provided.
  • Loading branch information
@gabalafou
gabalafou committed Mar 21, 2024
1 parent 18fe5df commit 48b95cd
Show file tree
Hide file tree
Showing 6 changed files with 132 additions and 25 deletions.
23 changes: 19 additions & 4 deletions docs/cards.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,21 +136,36 @@ Footer
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)
:::{card} Clickable Card (external) <http://google.com>
:link: https://example.com
:link-alt: example
: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 (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.
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.

`````{dropdown} Syntax
:icon: code
:color: light
Expand Down
14 changes: 12 additions & 2 deletions docs/snippets/myst/card-link.txt
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,25 @@
(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
: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 (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.

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.
13 changes: 11 additions & 2 deletions docs/snippets/rst/card-link.txt
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,24 @@
.. _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
: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 (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.

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.
11 changes: 4 additions & 7 deletions sphinx_design/cards.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -166,19 +166,16 @@ def create_card(

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
Expand All @@ -187,7 +184,7 @@ def create_card(
"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(
Expand Down
48 changes: 43 additions & 5 deletions tests/test_snippets/snippet_post_card-link.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand All @@ -16,8 +24,21 @@
<reference refuri="https://example.com">
https://example.com
.
<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.
<PassthroughTextElement>
<reference classes="sd-stretched-link" refuri="https://example.com">
<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">
Expand All @@ -26,8 +47,25 @@
<paragraph classes="sd-card-text">
The entire card can be clicked to navigate to the
<literal>
cards
cards-clickable
reference target.
<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
<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.
<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
<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.
48 changes: 43 additions & 5 deletions tests/test_snippets/snippet_pre_card-link.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand All @@ -16,8 +24,21 @@
<reference refuri="https://example.com">
https://example.com
.
<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.
<PassthroughTextElement>
<reference classes="sd-stretched-link" refuri="https://example.com">
<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">
Expand All @@ -26,8 +47,25 @@
<paragraph classes="sd-card-text">
The entire card can be clicked to navigate to the
<literal>
cards
cards-clickable
reference target.
<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
<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.
<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="False" 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.

0 comments on commit 48b95cd

Please sign in to comment.