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 Title

Card content

See the Material Design and Bootstrap card descriptions for further details.

Syntax
:::{card} Card Title

Card content
:::

.. card:: Card Title

    Card content

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:

Header

Card Title

Card content

Footer

Syntax
:::{card} Card Title
Header
^^^
Card content
+++
Footer
:::

.. card:: Card Title

    Header
    ^^^
    Card content
    +++
    Footer

When using cards in grids (see grid-item-card) footers can be aligned.

Header

Card Title

Card content

Footer

Header

Card Title

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:

your desired alt text
Title

Text

your desired alt text

Header

Title

Content

Footer

Header

Title

Content

Footer

your desired alt text
Syntax
:::::{grid} 2 3 3 4

::::{grid-item}

:::{card} Title
:img-background: images/particle_background.jpg
:class-card: sd-text-black
:img-alt: my text

Text
:::

::::

::::{grid-item-card} Title
:img-top: images/particle_background.jpg
:img-alt:

Header
^^^
Content
+++
Footer
::::

::::{grid-item-card} Title
:img-bottom: images/particle_background.jpg

Header
^^^
Content
+++
Footer
::::

:::::

.. grid:: 2 3 3 4

    .. grid-item::

        .. card:: Title
            :img-background: images/particle_background.jpg
            :class-card: sd-text-black
            :img-alt: my text

            Text

    .. grid-item-card:: Title
        :img-top: images/particle_background.jpg
        :img-alt:

        Header
        ^^^
        Content
        +++
        Footer

    .. grid-item-card:: Title
        :img-bottom: images/particle_background.jpg

        Header
        ^^^
        Content
        +++
        Footer

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:

Clickable Card (external)

The entire card can be clicked to navigate to https://example.com.

example
Clickable Card (internal)

The entire card can be clicked to navigate to the cards-clickable reference target.

cards-clickable
Syntax
(cards-clickable)=
## Cards Clickable

:::{card} Clickable Card (external)
:link: 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

The entire card can be clicked to navigate to the `cards` reference target.
:::

.. _cards-clickable:

Cards Clickable
...............

.. card:: Clickable Card (external)
    :link: 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

    The entire card can be clicked to navigate to the ``cards`` reference target.

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.

Align Center

Content

Align Right

Content

Align Left

Content

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 1

content

card 2

Longer

content

card 3
card 4
card 5
card 6
Syntax
::::{card-carousel} 2

:::{card} card 1
content
:::
:::{card} card 2
Longer

content
:::
:::{card} card 3
:::
:::{card} card 4
:::
:::{card} card 5
:::
:::{card} card 6
:::
::::

.. card-carousel:: 2

    .. card:: card 1

        content

    .. card:: card 2

        Longer

        content

    .. card:: card 3

    .. card:: card 4

    .. card:: card 5

    .. card:: card 6

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).