Skip to main content
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:
End of a guide
You've connected your repository. Next, configure how your site deploys.

<Card title="Configure deployments" href="/guides/configure-deployments" icon="settings">
  Set your build command, output directory, and environment variables.
</Card>
On overview pages, a columns grid of cards gives readers a visual menu of what’s inside:
Overview page
<Columns cols={2}>
  <Card title="Quickstart" href="/quickstart" icon="rocket">
    Get your first page live.
  </Card>
  <Card title="Connect GitHub" href="/guides/github" icon="github">
    Link your documentation to a GitHub repository.
  </Card>
  <Card title="Customize your theme" href="/customize/theme" icon="paintbrush">
    Colors, fonts, logo, and layout settings.
  </Card>
  <Card title="Set up your domain" href="/guides/custom-domain" icon="globe">
    Publish your docs to a custom domain.
  </Card>
</Columns>
At decision points, cards with descriptive content let readers self-select their path:
Decision point
<Columns cols={2}>
  <Card title="I'm setting up docs for the first time" href="/guides/new-project" icon="sparkles">
    Start here to create a new Mintlify project from scratch.
  </Card>
  <Card title="I'm migrating from another platform" href="/guides/migrate" icon="move-right">
    Import existing content and configure your new Mintlify site.
  </Card>
</Columns>

​
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.
Image card
<Card title="Git and GitHub for Mintlify" href="/courses/git-github/why-docs-teams-use-git" img="/assets/courses/git.png">
  <span>8 lessons</span>
  Learn the foundations of a docs-as-code workflow.
</Card>
Horizontal cards create a more compact, list-like layout.
Horizontal card
<Card title="API reference" href="/api-reference" icon="code" horizontal>
  Full endpoint documentation with request and response schemas.
</Card>

​
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 — How to choose the right navigation component based on context and intent.