Autofill the title and description in a LinkCard

[ghostdevv]

What version of starlight are you using?

^0.28.6

What is your idea?

Autofill the title and description in a LinkCard when the link is a Starlight page. You would still be able to overwrite it with the props, but it would be handy if they could be autofilled.

I wrote a patch (see below) and so am using it in production currently, in my mdx it looks like this:

import { LinkCard, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
	<LinkCard href="/components/commands" />
	<LinkCard href="/components/events" />
	<LinkCard href="/components/buttons" />
</CardGrid>

and rendered looks like:

This is similar to #965 (Generated Index Component), but differs in that it only autofills the title and description for an internal link that you specify. It doesn't attempt to generate a list of these link cards.

Why is this feature necessary?

Reduces duplication in my docs, which is important as when content is still evolving (i.e. not done) having to remember to propagate changes to multiple places is tricky. I often find myself forgetting where stuff has been duplicated, and then have outdated or stale content.

My usecase for using a LinkCard in this way is that, in one of my documentation pages I need to link to related items as a sort of "further reading" and/or "jumping off point" (if you want to leave this doc page before the end, and jump to another part of your learning)

Do you have examples of this feature in other projects?

I just wrote a quick patch for starlight (via pnpm patch) that adds this, and it's working well so far. If there is interest I'm happy to send over a PR and properly check it for bugs!

patch & my rough implementation idea

diff --git a/user-components/LinkCard.astro b/user-components/LinkCard.astro
index 8cf6fbd90fd6eb128bdcdcd35731a252ef74c44a..aae44bcfe14e02c54b6e676a5cd8492a7796423a 100644
--- a/user-components/LinkCard.astro
+++ b/user-components/LinkCard.astro
@@ -1,13 +1,20 @@
 ---
 import Icon from './Icon.astro';
 import type { HTMLAttributes } from 'astro/types';
+import { getRouteBySlugParam } from '../utils/routing'
 
 interface Props extends Omit<HTMLAttributes<'a'>, 'title'> {
-	title: string;
+	title?: string;
 	description?: string;
 }
 
-const { title, description, ...attributes } = Astro.props;
+const route = getRouteBySlugParam(Astro.props.href.replace(/^\//, ''))
+
+const { title = route?.entry.data.title, description = route?.entry.data.description, ...attributes } = Astro.props;
+
+if (!title) {
+	throw new Error('Starlight LinkCard requires a `title`, and one couldn\'t be determind from your `href`')
+}
 ---
 
 <div class="sl-link-card">

Participation

• I am willing to submit a pull request for this feature.

[delucis]

Thanks for the idea! I’m a bit torn on this one. It’s quite easy to do this without modifying Starlight at all with a small custom component, here’s an example: https://stackblitz.com/edit/github-hvevka?file=src%2FAutoLinkCard.astro,src%2Fcontent%2Fdocs%2Findex.mdx

So that makes me wonder if baking in this “magic” behaviour is a good idea. It risks begging the question of support for non-docs pages etc.

Flipside to that is that there are some subtle nuances here like for example fallback content etc. in translated sites that might be hard for people to get perfect if they’re less familiar with the Starlight codebase. So yeah, not 100% sure what’s best. Would be good to hear some more user feedback.