Feat/link card icon

.changeset/rich-days-add.md

@@ -0,0 +1,20 @@
+---
+'@astrojs/starlight': minor
+'@astrojs/starlight-markdoc': minor
+---
+
+Adds support for icons in the title of `<LinkCard>` components.
+
+You can now add one of [Starlight's built-in icons](https://starlight.astro.build/reference/icons/#all-icons) to the [`<LinkCard>` component](https://starlight.astro.build/components/link-cards/):
+
+```diff lang="mdx"
+<LinkCard
+	title="Internationalization"
+	href="/guides/i18n/"
+	description="Configure Starlight to support multiple languages."
++	icon="translate"
++	iconPlacement="start"
+/>
+```
+
+Read more about the new properties in the ["Add a link icon" guide](https://starlight.astro.build/components/link-cards/#add-a-link-icon).

docs/src/content/docs/components/link-cards.mdx

@@ -93,6 +93,51 @@ import { LinkCard } from '@astrojs/starlight/components';
 
 </Preview>
 
+### Add a link icon
+
+Include an icon in a link card using the [`icon`](#icon) attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons).
+
+The [`iconPlacement`](#iconplacement) attribute can be used to place the icon before the text by setting it to `start` (defaults to `end`).
+
+
+<Preview>
+
+```mdx {7-8}
+import { LinkCard } from '@astrojs/starlight/components';
+
+<LinkCard
+	title="Internationalization"
+	href="/guides/i18n/"
+	description="Configure Starlight to support multiple languages."
+	icon="translate"
+	iconPlacement="start"
+/>
+```
+
+<Fragment slot="markdoc">
+
+```markdoc {5-6}
+{% linkcard
+	 title="Internationalization"
+	 href="/guides/i18n/"
+	 description="Configure Starlight to support multiple languages."
+	 icon="translate"
+	 iconPlacement="start" /%}
+```
+
+</Fragment>
+
+<LinkCard
+	slot="preview"
+	title="Internationalization"
+	href="/guides/i18n/"
+	description="Configure Starlight to support multiple languages."
+	icon="translate"
+	iconPlacement="start"
+/>
+
+</Preview>
+
 ### Group link cards
 
 Display multiple link cards side-by-side when there’s enough space by grouping them using the [`<CardGrid>`](/components/card-grids/) component.
@@ -123,3 +168,16 @@ The URL to link to when the card is interacted with.
 **type:** `string`
 
 An optional description to display below the title.
+
+### `icon`
+
+**type:** `string`
+
+A link card can include an `icon` attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons).
+
+### `iconPlacement`
+
+**type:** `'start' | 'end'`
+**default:** `'end'`
+
+Determines the placement of the icon in relation to the link card title.

packages/markdoc/index.mjs

@@ -260,6 +260,16 @@ export const StarlightMarkdocPreset = {
 					type: String,
 					required: true,
 				},
+				icon: {
+					type: String,
+					required: false,
+				},
+				iconPlacement: {
+					type: String,
+					required: false,
+					default: 'end',
+					matches: ['start', 'end'],
+				},
 			},
 		},
 		steps: {

packages/starlight/user-components/LinkCard.astro

@@ -1,19 +1,26 @@
 ---
 import Icon from './Icon.astro';
 import type { HTMLAttributes } from 'astro/types';
+import type { StarlightIcon } from '../components-internals/Icons.ts';
 
 interface Props extends Omit<HTMLAttributes<'a'>, 'title'> {
 	title: string;
 	description?: string;
+	icon?: StarlightIcon | undefined;
+	iconPlacement?: 'start' | 'end' | undefined;
 }
 
-const { title, description, ...attributes } = Astro.props;
+const { title, description, icon, iconPlacement = 'end', ...attributes } = Astro.props;
 ---
 
 <div class="sl-link-card">
 	<span class="sl-flex stack">
 		<a {...attributes}>
-			<span class="title" set:html={title} />
+			<span class="sl-flex title-wrapper">
+				{icon && iconPlacement === 'start' && <Icon name={icon} size="1.2rem" />}
+				<span class="title" set:html={title} />
+				{icon && iconPlacement === 'end' && <Icon name={icon} size="1.2rem" />}
+			</span>
 		</a>
 		{description && <span class="description" set:html={description} />}
 	</span>
@@ -56,6 +63,16 @@ const { title, description, ...attributes } = Astro.props;
 			font-size: var(--sl-text-lg);
 		}
 
+		.title-wrapper {
+			align-items: center;
+			gap: 0.5rem;
+			color: var(--sl-color-white);
+		}
+
+		.title-wrapper :global(svg) {
+			flex-shrink: 0;
+		}
+
 		.description {
 			color: var(--sl-color-gray-3);
 			line-height: 1.5;