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

MARKDOWN

:::{card} Card Title

Card content
:::

RST

.. card:: Card Title

    Card content

Card headers and footers

Add a header and/or footer to a card with the card-header and card-footer directives. They always render in their slots — the header at the top and the footer at the bottom of the card — regardless of where they appear within the card body (the recommended order is header, then body, then footer):

Header

Card Title

Card content

Footer

Syntax

MARKDOWN

::::{card} Card Title

:::{card-header}
Header
:::

Card content

:::{card-footer}
Footer
:::
::::

RST

.. card:: Card Title

    .. card-header::

        Header

    Card content

    .. card-footer::

        Footer

For a single line of content, the header and footer options are a convenient short-hand (they accept inline markup, and compose with the card body):

A header

Card Title

Card content

A 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:

Title

Text

Header

Title

Content

Footer

Header

Title

Content

Footer

Syntax

MARKDOWN

:::::{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:

:::{card-header}
Header
:::

Content

:::{card-footer}
Footer
:::
::::

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

:::{card-header}
Header
:::

Content

:::{card-footer}
Footer
:::
::::

:::::

RST

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

        .. card-header::

            Header

        Content

        .. card-footer::

            Footer

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

        .. card-header::

            Header

        Content

        .. card-footer::

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

Clickable Card (external, new tab)

The entire card can be clicked to open https://example.com in a new tab.

example.com (opens in a new tab)

Clickable Card (internal)

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

Clickable cards

Syntax

MARKDOWN

(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 (external, new tab)
:link: https://example.com
:link-alt: example.com (opens in a new tab)
:link-new-tab:

The entire card can be clicked to open <https://example.com> in a new tab.
:::

:::{card} Clickable Card (internal)
:link: cards-clickable
:link-type: ref

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

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

    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 (external, new tab)
    :link: https://example.com
    :link-alt: example.com (opens in a new tab)
    :link-new-tab:

    The entire card can be clicked to open https://example.com in a new tab.

.. card:: Clickable Card (internal)
    :link: cards-clickable
    :link-type: ref

    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.

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

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` (Clickable cards), or if the link-alt option is provided, {ref}`alt text <cards-clickable>` (alt text).

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.

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

MARKDOWN

::::{card-carousel} 2

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

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

RST

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

link-new-tab

Flag. When set, the card link opens in a new browser tab (target="_blank", rel="noreferrer noopener"). Works with all link-type values; has no effect without link. Sphinx renders the rel attribute only from version 7.4; browsers already treat target="_blank" links as noopener. It affects only HTML-based output (HTML, EPUB); other formats ignore it. Tell readers the link opens a new tab, for example in link-alt. To open every external link in a new tab, site-wide, see the sphinx-new-tab-link extension.

shadow

The size of the shadow below the card: none, sm (default), md, lg.

header

Inline-markup short-hand for a single-line header (equivalent to a card-header directive; the two are mutually exclusive).

footer

Inline-markup short-hand for a single-line footer (equivalent to a card-footer directive; the two are mutually exclusive).

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

Legacy separator syntax

Deprecated since version 0.8: Prefer the card-header / card-footer directives (above). The ^^^ / +++ separators are deprecated: they scan the card’s raw source lines, so a ^^^ or +++ line inside nested content (for example a code block) is mistaken for a separator, and they have no meaning to non-Python MyST tools.

Historically, a card header and footer were delimited within the body itself: all content before the first line of three-or-more ^^^ became the header, and all content after the final line of three-or-more +++ became the footer.

Header

Card Title

Card content

Footer

This syntax is still recognised by default, but emits a deprecation warning (once per document). The rewrite is mechanical:

Legacy separators	Header / footer directives
Header above a ^^^ line	a card-header directive
Footer below a +++ line	a card-footer directive

MyST

:::{card} Card Title
Header
^^^
Body
+++
Footer
:::

becomes

::::{card} Card Title

:::{card-header}
Header
:::

Body

:::{card-footer}
Footer
:::
::::

reStructuredText

.. card:: Card Title

   Header
   ^^^
   Body
   +++
   Footer

becomes

.. card:: Card Title

   .. card-header::

      Header

   Body

   .. card-footer::

      Footer

Important

Migrate, then flip the flag While the legacy separators are enabled (the default), the raw-line scan runs on every card, so a stray column-0 ^^^ or +++ — even inside a code block, and even in a card that has already migrated to the card-header / card-footer directives — is still treated as a separator (mis-splitting the card and emitting a mixed-syntax warning). The single-parse robustness is only realized once the separators are turned off.

The recommended order is therefore migrate first, then flip the flag: convert every card to the directives, then set sd_card_legacy_separators = False in your conf.py.

With sd_card_legacy_separators = False, ^^^ / +++ lines are no longer scanned — but they do not reliably render as literal text, so migrate before flipping:

• in MyST, a bare +++ line is a block break and silently disappears;

• in reStructuredText, a ^^^ / ++++ line can raise a docutils CRITICAL “Unexpected section title or transition” error.

Note

Builds that treat warnings as errors The deprecation warning is on by default, so a build run with -W (or --fail-on-warning) fails while any document still uses ^^^ / +++. There are two remedies:

1. migrate those cards to the card-header / card-footer directives (above); or

2. keep the legacy syntax for now and silence the warning in your conf.py:

   suppress_warnings = ["design.card_legacy"]
   

Timeline: deprecated now (default on) → default off at 1.0 → removed at 2.0.