# Cards

Display content as a visual card grid. Each card can have a title, text, image, and link — all optional except the title.

## Basic example

```markdown
card: Zero Config
card-text: Write markdown, get a website. No frameworks, no build tools.

card: Three Themes
card-text: Light, dark, and paper modes — designed with intention.

card: SEO Built In
card-text: Meta tags, Open Graph, structured data, sitemap — all auto-generated.

card: Deploy Anywhere
card-text: Cloudflare, GitHub Pages, Vercel, Netlify — or any static host.
```

card: Zero Config
card-text: Write markdown, get a website. No frameworks, no build tools.

card: Three Themes
card-text: Light, dark, and paper modes — designed with intention.

card: SEO Built In
card-text: Meta tags, Open Graph, structured data, sitemap — all auto-generated.

card: Deploy Anywhere
card-text: Cloudflare, GitHub Pages, Vercel, Netlify — or any static host.

## Cards with icons

Use `card-icon:` to display a [Lucide](https://lucide.dev/icons/) icon instead of an image. Great for feature grids and service overviews. See [Icons](/docs/icons) for the full icon system documentation.

```markdown
card: Analytics
card-icon: bar-chart-2
card-text: Track your site performance with built-in analytics.
card-link: Learn more: /features

card: Security
card-icon: shield-check +color:emerald
card-text: Enterprise-grade security out of the box.
card-link: Learn more: /features

card: Global CDN
card-icon: globe +color:sky
card-text: Lightning-fast delivery from edge servers worldwide.
card-link: Learn more: /features
```

card: Analytics
card-icon: bar-chart-2
card-text: Track your site performance with built-in analytics.
card-link: Learn more: /features

card: Security
card-icon: shield-check +color:emerald
card-text: Enterprise-grade security out of the box.
card-link: Learn more: /features

card: Global CDN
card-icon: globe +color:sky
card-text: Lightning-fast delivery from edge servers worldwide.
card-link: Learn more: /features

Add `+color:name` or `+color:#hex` to override the default accent color. `card-icon:` and `card-image:` are mutually exclusive — if both are present, the icon takes precedence.

## Cards with images

Add `card-image:` to display a photo above the card content. Add `card-link:` for a call-to-action link.

```markdown
card: Mountain Lake
card-image: https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=600&h=300&fit=crop
card-text: Crystal clear waters reflecting snow-capped peaks at sunrise.
card-link: View Gallery: /features

card: Forest Trail
card-image: https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&h=300&fit=crop
card-text: Winding paths through ancient redwoods and morning mist.
card-link: Explore: /features

card: Desert Sunset
card-image: https://images.unsplash.com/photo-1509316975850-ff9c5deb0cd9?w=600&h=300&fit=crop
card-text: Golden light painting the canyon walls in warm amber tones.
card-link: Discover: /features

card: Ocean Waves
card-image: https://images.unsplash.com/photo-1505118380757-91f5f5632de0?w=600&h=300&fit=crop
card-text: Turquoise swells breaking against weathered coastal cliffs.
card-link: See More: /features
```

card: Mountain Lake
card-image: https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=600&h=300&fit=crop
card-text: Crystal clear waters reflecting snow-capped peaks at sunrise.
card-link: View Gallery: /features

card: Forest Trail
card-image: https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&h=300&fit=crop
card-text: Winding paths through ancient redwoods and morning mist.
card-link: Explore: /features

card: Desert Sunset
card-image: https://images.unsplash.com/photo-1509316975850-ff9c5deb0cd9?w=600&h=300&fit=crop
card-text: Golden light painting the canyon walls in warm amber tones.
card-link: Discover: /features

card: Ocean Waves
card-image: https://images.unsplash.com/photo-1505118380757-91f5f5632de0?w=600&h=300&fit=crop
card-text: Turquoise swells breaking against weathered coastal cliffs.
card-link: See More: /features

## Image carousel

Add multiple `card-image:` lines to the same card to create an Instagram-style image carousel. The first image displays by default — visitors click the arrows or swipe to cycle through.

```markdown
card: Mountain Views
card-image: https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=600&h=300&fit=crop
card-image: https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&h=300&fit=crop
card-image: https://images.unsplash.com/photo-1509316975850-ff9c5deb0cd9?w=600&h=300&fit=crop
card-text: Three stunning landscapes in one card.

card: Ocean & Sky
card-image: https://images.unsplash.com/photo-1505118380757-91f5f5632de0?w=600&h=300&fit=crop
card-image: https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&h=300&fit=crop
card-text: Coastal scenes to explore.
```

card: Mountain Views
card-image: https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=600&h=300&fit=crop
card-image: https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&h=300&fit=crop
card-image: https://images.unsplash.com/photo-1509316975850-ff9c5deb0cd9?w=600&h=300&fit=crop
card-text: Three stunning landscapes in one card.

card: Ocean & Sky
card-image: https://images.unsplash.com/photo-1505118380757-91f5f5632de0?w=600&h=300&fit=crop
card-image: https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&h=300&fit=crop
card-text: Coastal scenes to explore.

Dot indicators show at the bottom of the image area. Prev/next arrows appear on hover (always visible on mobile). Touch swipe is supported.

## Clickable cards

Any card with a `card-link:` is clickable — the entire card surface acts as a link. There are two forms:

**With a label** — shows a visible text button and makes the whole card clickable:

```markdown
card-link: Learn more: /features
```

**Without a label** — makes the whole card clickable with no visible button:

```markdown
card-link: /features
```

Both forms support link modifiers like `+newtab`. Here's an example using the bare URL form:

```markdown
card: Documentation
card-icon: book-open
card-text: Learn how to build your site from scratch.
card-link: /docs

card: Features
card-icon: sparkles
card-text: See everything sitemd can do.
card-link: /features

card: GitHub
card-icon: github
card-text: View the source and contribute.
card-link: https://github.com/sitemd-cc/sitemd +newtab
```

card: Documentation
card-icon: book-open
card-text: Learn how to build your site from scratch.
card-link: /docs

card: Features
card-icon: sparkles
card-text: See everything sitemd can do.
card-link: /features

card: GitHub
card-icon: github
card-text: View the source and contribute.
card-link: https://github.com/sitemd-cc/sitemd +newtab

## Banner cards

Add `+banner` to a card title to render it as a full page-width hero card. The card breaks out of the content column and spans the full site width.

```markdown
card: Ship Your Site Today +banner
card-image: https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=1200&h=400&fit=crop
card-text: From markdown to production in minutes. No frameworks, no build tools, no complexity.
card-link: Get Started: /docs
```

card: Ship Your Site Today +banner
card-image: https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=1200&h=400&fit=crop
card-text: From markdown to production in minutes. No frameworks, no build tools, no complexity.
card-link: Get Started: /docs

Banner cards work with images, icons, or no visual. Mix them with regular cards in the same block — banner cards render standalone while regular cards stay in the grid.

## Card alignment

Cards inside [alignment fences](/docs/content-alignment) stay at their natural width instead of stretching to fill the row. Use `center:` or `right:` to position a single card or small group:

```markdown
center:
card: Featured Article
card-icon: star
card-text: This card is centered on the page instead of stretching full-width.
card-link: Read More: /blog
/center
```

center:
card: Featured Article
card-icon: star
card-text: This card is centered on the page instead of stretching full-width.
card-link: Read More: /blog
/center

This works with any number of cards. Multiple cards wrap within the alignment:

```markdown
right:
card: Option A
card-icon: check
card-text: First choice.

card: Option B
card-icon: check
card-text: Second choice.
/right
```

right:
card: Option A
card-icon: check
card-text: First choice.

card: Option B
card-icon: check
card-text: Second choice.
/right

## Image modifiers on cards

Card images support the same [image modifiers](/docs/images#modifier-reference) as standard markdown images. Append `+modifier` flags to the `card-image:` URL:

```markdown
card: Mountain Lake
card-image: https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=600&h=300&fit=crop +bw
card-text: Crystal clear waters in monochrome.
card-link: View Gallery: /features

card: Forest Trail
card-image: https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&h=300&fit=crop +sepia
card-text: Winding paths with a vintage feel.
card-link: Explore: /features
```

card: Mountain Lake
card-image: https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=600&h=300&fit=crop +bw
card-text: Crystal clear waters in monochrome.
card-link: View Gallery: /features

card: Forest Trail
card-image: https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&h=300&fit=crop +sepia
card-text: Winding paths with a vintage feel.
card-link: Explore: /features

All modifiers work: `+bw`, `+sepia`, `+circle`, `+square`, `+rect`, `+width:N`, `+height:N`, `+crop:WxH`, `+corner:name`, and `+rotate:N`. Stack multiple modifiers in any order. See the full [modifier reference](/docs/images#modifier-reference).

## Syntax reference

Each card starts with `card:` (the title). Sub-fields are optional and can appear in any order:

| Prefix | What it does |
|---|---|
| `card:` | Starts a new card. Value is the card title (required). |
| `card-text:` | Description text below the title. |
| `card-image:` | Image URL displayed above the card content. Use multiple `card-image:` lines for a carousel. |
| `card-icon:` | [Lucide](https://lucide.dev/icons/) icon displayed above the card content (replaces `card-image:`). Supports `+color:name`. |
| `card-link:` | Makes the whole card clickable. `Label: /slug` also shows a text button. `/slug` alone links without a visible button. |

Consecutive card blocks (separated by single blank lines) form a single grid. Cards render in a responsive 2-column grid on desktop, single column on mobile.

## Auto-generated images

Cards can auto-generate images using the `card-image:` field with `auto-color` or `auto-photo` values. No global settings needed — this is configured per card.

### Color gradients

`auto-color` generates a gradient image seeded from the card title. Works offline, no API calls. Output is 1200x600 PNG.

```markdown
card: Analytics Dashboard
card-image: media/content/cards/analytics-dashboard-786d29e8.png
card-text: Real-time metrics and performance insights.
```

Use the optional `+color:` modifier to guide the gradient hue:

```markdown
card-image: media/content/cards/team-collaboration-d7bd2781.png
card-image: auto-color +color:#ff6600
```

Named colors: red, orange, yellow, lime, green, teal, cyan, blue, indigo, purple, pink, rose.

### Photo search

`auto-photo` fetches a relevant landscape photo from free image sources (Unsplash, Openverse) at 1080px width. No API key needed.

```markdown
card: Mountain Vista
card-image: media/content/cards/api-gateway-2da99fe0.png
card-text: Stunning alpine views.
```

Use the optional `+prompt:` modifier to guide the image search:

```markdown
card-image: auto-photo +prompt:scenic waterfall in forest
```

Without `+prompt:`, the card title and text are used as the search query. Falls back to a gradient if all photo sources fail.

### How auto-image works

When you add `card-image: auto-photo` or `auto-color` and build, the engine:

1. Downloads or generates the image and saves it to `media/content/cards/` with a descriptive filename based on the card title (e.g. `analytics-dashboard-a3f2e8b1.png`)
2. Rewrites the source markdown — replaces the auto directive with the concrete path:
   ```markdown
   card-image: media/content/cards/analytics-dashboard-a3f2e8b1.png
   ```
3. Triggers a hot-reload so the browser shows the new image immediately

The rewrite means the auto directive runs once. Subsequent builds use the saved image path directly — no redundant API calls, no re-downloads. To regenerate, replace the concrete `card-image:` path with `auto-photo` or `auto-color` again.

### Caching

Auto-generated images are cached in `media/content/cards/`. If you need a different image, delete the image file and replace the concrete `card-image:` path with the original `auto-photo` or `auto-color` directive.

### Example

card: Analytics Dashboard
card-image: auto-color
card-text: Real-time metrics and performance insights for your entire stack.
card-link: Learn More: /features

card: Team Collaboration
card-image: auto-color +color:blue
card-text: Shared workspaces, comments, and live editing for distributed teams.
card-link: Learn More: /features

card: API Gateway
card-image: auto-photo
card-text: Route, throttle, and secure your API endpoints from a single control plane.
card-link: Learn More: /features

card: Cloud Storage
card-image: media/content/cards/cloud-storage-0ab92466.png
card-text: Scalable object storage with automatic replication and edge caching.
card-link: Learn More: /features

## Notes

- Cards inside fenced code blocks are displayed as text, not rendered.
- All sub-fields are optional — a card with just `card: Title` renders as a title-only card.
- Any card with `card-link:` is fully clickable. `Label: /slug` also shows a text button; `/slug` alone links without one.
- `card-link:` supports the same modifiers as buttons — `+newtab`, `+outline`, `+color:name`. See [Buttons & Links](/docs/buttons-and-links).
- Images use `object-fit: cover` with a fixed height for consistent grid appearance.
- For author attribution (avatar, bio, social links), use [Author Cards](/docs/author-cards) instead — they render as a horizontal profile strip rather than a grid item.
- For full layout control beyond cards, use [inline HTML](/docs/inline-html).