Skip to main content
Inline links and cards both send readers somewhere else, but they send different signals. An inline link says “this is here if you want it.” A card says “this is where you should go next.” Choose based on how much attention the destination deserves. Use an inline link when:
  • The reference fits within a sentence.
  • The destination is supplementary. Readers can keep going without it.
  • The link is one of several possible paths forward.
Example of an inline link
Most readers keep reading. Some open the link for context. The inline format signals that it’s optional.

​
Cards are a call to action

A linked card is a navigation element that’s hard to miss, even for readers who skim. Use one when:
  • There’s a clear next step and you want to make it prominent.
  • Readers need to choose between two to four paths.
  • An overview page points to the pages beneath it.
Before adding a card, ask whether you want the reader to go somewhere. If you only want visual polish, a list or plain text does the job with less noise.

​
Where 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. On overview pages, a grid of cards gives readers a visual menu of what’s inside:
Example of an overview page
At decision points, cards with a short description let readers choose their path:
Example of a decision point
Icon names depend on your site’s icon library, which is set in docs.json. Check that each name exists in the library you use.

​
Card variations

Image cards work for course indexes, product listings, or anywhere an image helps readers tell options apart. Use them when the image communicates something the title alone doesn’t.
Example of an image card
Horizontal cards create a more compact, list-like layout. To make the action explicit, add cta to show a button with your own text.
Example of a horizontal card with a call to action

​
When not to use cards

Don’t use cards as styled bullet lists. If a card has a title but no link, it’s probably a list item. Don’t use cards for supplementary links in the middle of a section. A card interrupts reading and implies the reader should stop and go there. If they can safely keep reading, use an inline link. Don’t use cards to navigate within a page. Mintlify builds a table of contents from your headings, and anchor links handle the rest. Next up: End-of-page navigation patterns—what to put at the bottom of a page to help readers continue.