Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 4 commits into from
May 22, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
47bb4a2
👌 IMPROVE: Use reference name by default for internal link cards
gabalafou Mar 21, 2024
13986b9
Merge branch 'main' into docs-link-alt
chrisjsewell May 22, 2024
224c291
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] May 22, 2024
2c9dd09
Update to docs and tests
chrisjsewell May 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 26 additions & 3 deletions docs/cards.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
:::
Expand All @@ -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,
Expand Down
22 changes: 20 additions & 2 deletions docs/snippets/myst/card-link.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:
chrisjsewell marked this conversation as resolved.
Show resolved Hide resolved

:::{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>.
:::
Expand All @@ -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.
:::
19 changes: 17 additions & 2 deletions docs/snippets/rst/card-link.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
13 changes: 5 additions & 8 deletions sphinx_design/cards.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."""
Expand Down Expand Up @@ -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"]
chrisjsewell marked this conversation as resolved.
Show resolved Hide resolved
_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 @@ -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,
chrisjsewell marked this conversation as resolved.
Show resolved Hide resolved
"refwarn": True,
}
link = addnodes.pending_xref(
Expand Down
49 changes: 44 additions & 5 deletions tests/test_snippets/snippet_post_card-link.xml
View file
Open in desktop
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 @@ -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">
Expand All @@ -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
49 changes: 44 additions & 5 deletions tests/test_snippets/snippet_pre_card-link.xml
View file
Open in desktop
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 @@ -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">
Expand All @@ -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
Loading