;
};
A card with a link is a navigation element. It tells readers where to go next or what closely relates to what they just read. A card without a link is just a visual container. Sometimes useful for grouping, but easy to overuse.
Before adding a card, ask whether you want the reader to go somewhere. If yes, cards are the right tool. If you're adding them because they look good, a list or plain text could do the same job with less visual noise. You can still use cards for decoration, but make sure it is intentional and helps users understand your content.
## Where do cards belong?
Cards work best at the boundaries of content. The beginning or end of a page, an overview that points to child pages, or a section that exits into a different part of the docs.
At the end of a guide, cards make the next step explicit and clickable:
```mdx End of a guide theme={null}
You've connected your repository. Next, configure how your site deploys.
Set your build command, output directory, and environment variables.
```
On overview pages, a columns grid of cards gives readers a visual menu of what's inside:
```mdx Overview page theme={null}
Get your first page live.
Link your documentation to a GitHub repository.
Colors, fonts, logo, and layout settings.
Publish your docs to a custom domain.
```
At decision points, cards with descriptive content let readers self-select their path:
```mdx Decision point theme={null}
Start here to create a new Mintlify project from scratch.
Import existing content and configure your new Mintlify site.
```
## Card variations
Image cards work for course indexes, product listings, or anywhere visual differentiation helps users scan. Use them when the image communicates something the title alone doesn't.
```mdx Image card theme={null}
8 lessons
Learn the foundations of a docs-as-code workflow.
```
Horizontal cards create a more compact, list-like layout.
```mdx Horizontal card theme={null}
Full endpoint documentation with request and response schemas.
```
## When not to use cards
Don't use cards as styled bullet lists. If a card has a title but no link or child content in the card, it's probably meant to be an unordered list item.
Don't embed a single card in the middle of a long section of prose. Cards create a visual break. Put them at natural stopping points, not mid-paragraph.
Next up: [Inline links or cards — when to use each one](/courses/components/links-vs-cards) — How to choose the right navigation component based on context and intent.