(sd-cards)=
# Cards
Cards contain content and actions about a single subject.
A card is a flexible and extensible content container,
it can be formatted with components including headers and footers, titles and images.
:::{card} Card Title
Card content
:::
See the [Material Design](https://material.io/components/cards) and [Bootstrap card](https://getbootstrap.com/docs/5.0/layout/grid/) descriptions for further details.
`````{dropdown-syntax}
````{tab-set-code}
```{literalinclude} ./snippets/myst/card-basic.txt
:language: markdown
```
```{literalinclude} ./snippets/rst/card-basic.txt
:language: rst
```
````
`````
All content before the first occurrence of three or more `^^^` is considered as a header,
and all content after the final occurrence of three or more `+++` is considered as a footer:
:::{card} Card Title
Header
^^^
Card content
+++
Footer
:::
`````{dropdown-syntax}
````{tab-set-code}
```{literalinclude} ./snippets/myst/card-head-foot.txt
:language: markdown
```
```{literalinclude} ./snippets/rst/card-head-foot.txt
:language: rst
```
````
`````
When using cards in grids (see [`grid-item-card`](./grids.md)) footers can be aligned.
::::{grid} 2
:::{grid-item-card} Card Title
Header
^^^
Card content
+++
Footer
:::
:::{grid-item-card} Card Title
Header
^^^
Longer
Card content
+++
Footer
:::
::::
## Card images
You can also add an image as the background of a card or at the top/bottom of the card, with the `img-background`, `img-top`, `img-bottom` options:
:::::{grid} 2 3 3 4
::::{grid-item}
:::{card} Title
:img-background: images/particle_background.jpg
:class-card: sd-text-black
:img-alt: your desired alt text
Text
:::
::::
::::{grid-item-card} Title
:img-top: images/particle_background.jpg
:img-alt: your desired alt text
Header
^^^
Content
+++
Footer
::::
::::{grid-item-card} Title
:img-bottom: images/particle_background.jpg
:img-alt: your desired alt text
Header
^^^
Content
+++
Footer
::::
:::::
`````{dropdown-syntax}
````{tab-set-code}
```{literalinclude} ./snippets/myst/card-images.txt
:language: markdown
```
```{literalinclude} ./snippets/rst/card-images.txt
:language: rst
```
````
`````
(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`.
:::
:::{card} Clickable Card (internal)
:link: cards-clickable
:link-type: ref
The entire card can be clicked to navigate to the `cards-clickable` reference target.
:::
`````{dropdown-syntax}
````{tab-set-code}
```{literalinclude} ./snippets/myst/card-link.txt
:language: markdown
```
```{literalinclude} ./snippets/rst/card-link.txt
:language: rst
```
````
`````
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,
and also `auto` margins to align the cards horizontally.
:::{card} Align Center
:width: 75%
:margin: 0 2 auto auto
:text-align: center
Content
:::
:::{card} Align Right
:width: 50%
:margin: 0 2 auto 0
:text-align: right
Content
:::
:::{card} Align Left
:width: 50%
:margin: 0 2 0 auto
:text-align: left
Content
:::
(cards:carousel)=
## Card carousels
The `card-carousel` directive can be used to create a single row of fixed width, scrollable cards.
The argument should be a number between 1 and 12, to denote the number of cards to display.
When scrolling a carousel, the scroll will snap to the start of the nearest card:
::::{card-carousel} 2
:::{card} card 1
content
:::
:::{card} card 2
Longer
content
:::
:::{card} card 3
:::
:::{card} card 4
:::
:::{card} card 5
:::
:::{card} card 6
:::
::::
`````{dropdown-syntax}
````{tab-set-code}
```{literalinclude} ./snippets/myst/card-carousel.txt
:language: markdown
```
```{literalinclude} ./snippets/rst/card-carousel.txt
:language: rst
```
````
`````
(cards:options)=
## `card` options
width
: The width that the card should take up (in %): auto, 25%, 50%, 75%, 100%.
margin
: Outer margin of grid.
One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5, auto.
text-align
: Default horizontal text alignment: left, right, center or justify
img-background
: A URI (relative file path or URL) to an image to be placed below the content.
img-top
: A URI (relative file path or URL) to an image to be placed above the content.
img-bottom
: A URI (relative file path or URL) to an image to be placed below the content.
img-alt
: Alternative text for the image (that will be used by screen-readers).
link
: Turn the entire card into a clickable link to an external/internal target.
link-type
: Type of link: `url` (default), `ref`, `doc`, `any`.
link-alt
: Alternative text for the link (that will be used by screen-readers).
shadow
: The size of the shadow below the card: `none`, `sm` (default), `md`, `lg`.
class-card
: Additional CSS classes for the card container element.
class-header
: Additional CSS classes for the header element.
class-body
: Additional CSS classes for the body element.
class-title
: Additional CSS classes for the title element.
class-footer
: Additional CSS classes for the footer element.
class-img-top
: Additional CSS classes for the top image (if present).
class-img-bottom
: Additional CSS classes for the bottom image (if present).