Cards & LinkCards

Cards are structural layout elements used to highlight features, group related concepts, or guide users to subsequent articles. Starlight provides three interrelated components for this: <Card> (for static information), <LinkCard> (for navigation), and <CardGrid> (for layout alignment).

How to Create Cards

Highlight key topics or create visual landing grids using Starlight cards:

1. Import Card: Import Card from @astrojs/starlight/components.
2. Configure Attributes: Set a title string and an optional Starlight icon name.
3. Add Body Text: Write brief descriptive copy inside the card tags.

Behind the Curtain

Explore the live specimens, the raw markup required to build them, and instructions for authoring these components inside Sveltia CMS.

1. Rendered Specimen

Below are examples of static feature cards and interactive link cards, both wrapped in a grid layout.

Static Feature Cards

Information Architecture

Cards are excellent for introducing high-level concepts at the beginning of a section.

Visual Consistency

They utilize Starlight’s built-in icon set to maintain a uniform design language.

Navigation Link Cards

Explore the Docs-as-Code GuideLearn the philosophy behind Git-backed documentation.

View Starlight Icon ReferenceSee all available icons you can use inside cards.

2. Underlying MDX Code

Notice how <CardGrid> automatically handles the responsive column layout. The stagger prop (e.g., <CardGrid stagger>) can also be added to offset the second column visually.

### Static Feature Cards
<CardGrid>
  <Card icon="open-book" title="Information Architecture">
    Cards are excellent for introducing high-level concepts at the beginning of a section.
  </Card>

  <Card icon="star" title="Visual Consistency">
    They utilize Starlight's built-in icon set to maintain a uniform design language.
  </Card>
</CardGrid>

### Navigation Link Cards
<CardGrid>
  <LinkCard description="Learn the philosophy behind Git-backed documentation." href="/philosophy/docs-as-code/" title="Explore the Docs-as-Code Guide"/>

  <LinkCard description="See all available icons you can use inside cards." href="https://starlight.astro.build/guides/components/#icons" title="View Starlight Icon Reference"/>
</CardGrid>

3. Sveltia CMS Authoring

How writers add this component using the Sveltia CMS interface.

In Rich Text Mode (Visual LinkCard):

1. Click the + (Add Block) button in the editor toolbar.
2. Select Starlight Link Card from the dropdown menu.
3. Choose your target article from the searchable dropdown list to auto-fill the URL, or enter custom titles and descriptions.

In Raw Markdown Mode (CardGrid & Layouts):

1. Type <CardGrid> to open the multi-column layout block.
2. Add your individual <Card> or <LinkCard> tags inside the grid.
3. Ensure you close the block with </CardGrid>.

Pro Tip: For <LinkCard>, you can link to relative internal pages (e.g., href="/components/steps/") or external URLs (e.g., href="https://github.com").

For a complete visual walkthrough of inserting Link Cards in Sveltia CMS, see Inserting Custom Components (CMS Magic).

---

Technical Writing Guidelines

When utilizing cards in this knowledge base, adhere to the following stylistic rules:

• Use the Right Card:
  • Use <Card> if the content is purely informational and the user isn’t expected to click it.
  • Use <LinkCard> if the entire purpose of the card is to route the user to another page.
• Keep Descriptions Brief: The description prop on a <LinkCard> or the body text of a <Card> should be a maximum of two concise sentences.
• End of Article Routing: <LinkCard> is highly recommended at the very bottom of procedural articles (under a “Next Steps” or “Related Guides” heading) to keep readers moving through the documentation.
• Pair with Grids: Always wrap adjacent cards in a <CardGrid>. Without the grid wrapper, cards will stack at 100% width on large screens, which disrupts reading flow.