Cards

The cards extension provides eye-catching card-like controls, to display information that usually includes images.

Zeus

Lorem ipsum dolor sit amet.

Athena

Lorem ipsum dolor sit amet.

Poseidon

Lorem ipsum dolor sit amet.

Artemis

Lorem ipsum dolor sit amet.

Ares

Lorem ipsum dolor sit amet.

Nike

Lorem ipsum dolor sit amet.

Greek Mythology icons made by max.icons from www.flaticon.com

How to use

Edit your mkdocs.yml file to include the extra CSS file from Neoteroi mkdocs-plugins and the neoteroi.cards extension:

extra_css:
  - css/neoteroi-mkdocs.css
  ...

markdown_extensions:
  - neoteroi.cards
  ...

Input object

Examples

JSONYAMLFile sourceURL source

::cards::

[
  {
    "title": "Zeus",
    "content": "Lorem ipsum dolor sit amet.",
    "image": "./img/icons/001-zeus.png"
  },
  {
    "title": "Athena",
    "content": "Lorem ipsum dolor sit amet.",
    "image": "./img/icons/003-athena.png"
  },
  {
    "title": "Poseidon",
    "content": "Lorem ipsum dolor sit amet.",
    "image": "./img/icons/007-poseidon.png"
  },
  {
    "title": "Artemis",
    "content": "Lorem ipsum dolor sit amet.",
    "image": "./img/icons/021-artemis.png"
  },
  {
    "title": "Ares",
    "content": "Lorem ipsum dolor sit amet.",
    "image": "./img/icons/006-ares.png"
  },
  {
    "title": "Nike",
    "content": "Lorem ipsum dolor sit amet.",
    "image": "./img/icons/027-nike.png"
  }
]

::/cards::

::cards::

- title: Zeus
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/001-zeus.png

- title: Athena
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/003-athena.png

- title: Poseidon
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/007-poseidon.png

- title: Artemis
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/021-artemis.png

- title: Ares
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/006-ares.png

- title: Nike
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/027-nike.png

::/cards::

[cards(./settings.yaml)]

[cards(./settings.json)]

# with view options:

[cards image-bg(./settings.yaml)]

[cards(https://www.neoteroi.dev/examples/cards.yaml)]

[cards(https://www.neoteroi.dev/examples/cards.json)]

# with view options:

[cards image-bg(https://www.neoteroi.dev/examples/cards.yaml)]

Schema

classDiagram
direction LR

class CardItem {
    title: str
    url: str | None = None
    content: str | None = None
    icon: str | None = None
    key: str | None = None
    image: str | Image | None = None
}

class Cards {
    items: Array of CardItem
}

Cards --> CardItem

@dataclass
class Image:
    url: str
    height: int | None = None
    width: int | None = None
    alt: str | None = None


@dataclass
class CardItem:
    title: str
    url: str | None = None
    content: str | None = None
    icon: str | None = None
    key: str | None = None
    image: str | Image | None = None


@dataclass
class Cards:
    items: List[CardItem]

Options

Image properties

To control some image properties, specify images as objects:

::cards::

- title: Zeus
  content: Lorem ipsum dolor sit amet.
  image:
    url: ./img/icons/001-zeus.png
    alt: Some alt text

- title: Athena
  content: Lorem ipsum dolor sit amet.
  image:
    url: ./img/icons/003-athena.png
    alt: Some other alt text

::/cards::

It is possible to define alt, height, and width properties for the image.

If not specified, alt is set using the card's title.

Cards with links

Specify a url property in the items to have links in cards.

- title: Zeus
  content: |
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
    incididunt ut labore et dolore magna aliqua.
  image: ./img/icons/001-zeus.png
  url: https://en.wikipedia.org/wiki/Zeus

Zeus

Lorem ipsum dolor sit amet.

Athena

Lorem ipsum dolor sit amet.

Poseidon

Lorem ipsum dolor sit amet.

Artemis

Lorem ipsum dolor sit amet.

Ares

Lorem ipsum dolor sit amet.

Nike

Lorem ipsum dolor sit amet.

Controlling the number of columns

To control the number of columns in the grid, use the cols view option.

cols=4

Zeus

Lorem ipsum dolor sit amet.

Athena

Lorem ipsum dolor sit amet.

Poseidon

Lorem ipsum dolor sit amet.

Artemis

Lorem ipsum dolor sit amet.

Ares

Lorem ipsum dolor sit amet.

Nike

Lorem ipsum dolor sit amet.

cols=2

Zeus

Lorem ipsum dolor sit amet.

Athena

Lorem ipsum dolor sit amet.

Poseidon

Lorem ipsum dolor sit amet.

Artemis

Lorem ipsum dolor sit amet.

Ares

Lorem ipsum dolor sit amet.

Nike

Lorem ipsum dolor sit amet.

cols=1

Zeus

Lorem ipsum dolor sit amet.

Athena

Lorem ipsum dolor sit amet.

Poseidon

Lorem ipsum dolor sit amet.

Artemis

Lorem ipsum dolor sit amet.

Ares

Lorem ipsum dolor sit amet.

Nike

Lorem ipsum dolor sit amet.

Columns and CSS rules

Only values between 1 and 6 are supported out of the box. To handle greater values, also specify a custom CSS rule in your MkDocs settings like the following:

.nt-cards.nt-grid.cols-10 {
    grid-template-columns: repeat(10, 1fr);
}

Using background images

To display images using background images instead of image elements, use the image-bg view option.

::cards:: image-bg

Zeus

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Athena

Lorem ipsum dolor sit amet.

Poseidon

Lorem ipsum dolor sit amet.

Bigger

Zeus

Lorem ipsum dolor sit amet.

Athena

Lorem ipsum dolor sit amet.

Poseidon

Lorem ipsum dolor sit amet.

Artemis

Lorem ipsum dolor sit amet.

Ares

Lorem ipsum dolor sit amet.

Nike

Lorem ipsum dolor sit amet.

Smaller

Zeus

Lorem ipsum dolor sit amet.

Athena

Lorem ipsum dolor sit amet.

Poseidon

Lorem ipsum dolor sit amet.

Artemis

Lorem ipsum dolor sit amet.

Ares

Lorem ipsum dolor sit amet.

Nike

Lorem ipsum dolor sit amet.

Last modified on: 2025-04-01 23:22:49

RP