# Link cards

> Design how your website's links look when someone shares them in Lamma.

A link card is a small layout built from a fixed set of pieces. Websites use one to design how their links look when someone shares them in Lamma, and [webhooks](https://lammapp.sa/developers/webhooks) can post them. Cards can only show text, pictures and link buttons: nothing on a card runs code in Lamma.

## Adding a card to your website

Put one `<script>` with the type `application/vnd.lamma.card+json` inside your page's `<head>`:

```html
<head>
  <meta property="og:title" content="Patch 2 is out">
  <script type="application/vnd.lamma.card+json">
  {
    "accent": "#4fc38a",
    "items": [
      { "type": "section", "text": "## New version out!\nThe dungeon is tougher.",
        "aside": { "type": "link", "label": "Open", "url": "/patch/2" } },
      { "type": "gallery", "images": [{ "src": "/shots/map.png", "alt": "World map" }, { "src": "/shots/lake.png" }] },
      { "type": "divider" },
      { "type": "links", "links": [{ "label": "Patch notes", "url": "/notes" }] }
    ]
  }
  </script>
</head>
```

Lamma reads the first such script when it fetches your page for a link preview. Relative links and pictures resolve against the page's URL. If the page has no card, or the card breaks a rule below, the link gets a normal preview from its Open Graph tags, so keep those too. Cards refresh with previews, every few hours.

Pages that already declare a Discord component embed get a card without changes. If a page has both, Lamma's own card wins.

## Pieces

| `type` | Fields | Shows |
| --- | --- | --- |
| `text` | `text` | Formatted text, with the same Markdown as messages: headings `#` to `###`, bold, italics, underline, strikethrough, spoilers, code, quotes, lists and plain links. No HTML |
| `section` | `text`, `aside` | Text with a picture (`{ "type": "image", "src", "alt", "spoiler" }`) or a link button (`{ "type": "link", "label", "url" }`) beside it |
| `gallery` | `images`: 1 to 6 of `{ "src", "alt", "spoiler" }` | A grid of pictures that open in Lamma's image viewer |
| `divider` | `line` (default `true`), `space` (`small` or `large`) | A line, or just space |
| `links` | `links`: 1 to 5 of `{ "label", "url" }` | A row of link buttons |

`accent` (`#rgb` or `#rrggbb`) colours the card's edge.

## Limits

- The JSON is at most 16 KB, with 1 to 20 items, and not only dividers.
- Each `text` is 1 to 2,000 characters, with at most 4,000 characters of text and button labels in the whole card.
- Button labels are up to 80 characters, and alt text up to 300.
- Button links are `http` or `https`. Pictures must be `https`, with at most 6 different pictures per card.
- An unknown `type`, a wrong field type or a broken limit makes the whole card invalid. A website falls back to its normal preview, and a webhook gets `400`.

## How Lamma shows cards

- Every button opens through Lamma's leaving-Lamma warning, like links in messages.
- Website cards are labelled "Website card" with the hostname of the shared link, and each button shows the hostname it leads to, so a page can't pass itself off as Lamma or another site.
- Pictures are fetched once by Lamma (PNG, JPEG, WebP or GIF, up to 1 MB each) and served from Lamma, never loaded from your site by people's browsers.
- AutoMod checks the text, labels, links and alt text on cards. A card that breaks a server's rules isn't shown there, and the link keeps its normal preview.