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.
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¶
::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
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-17 07:04:37