docs: add 'og:image:alt' metadata

[julien-deramond]

Description

This PR adds a metadata in Starlight documentation to improve the accessibility of Twitter cards when this documentation is shared on this platform, or other cards on different social media platforms.

Feel free to drop this PR if this is a topic that has already been discussed, or if you think this is not necessary. In this case, don't spend too much time on my PR :)

Important

After a discussion based on #2137, this PR will only implement og:image:alt, and Twitter will use this as a fallback

Twitter/X platform

Let's consider this page: https://astro.build/blog/astro-4120/.
It contains the following metadata:

<meta name="twitter:image" content="https://astro.build/_astro/og_image_4_12.DvriEbIV.webp">
<meta name="twitter:image:alt" content="Astro 4.12: Server Islands">

When shared on Twitter (see https://x.com/astrodotbuild/status/1813994888427684008), if you inspect the Twitter card, you'll see that the image has an alternative text, which is good for a11y:

<img alt="Astro 4.12: Server Islands" draggable="true" src="https://pbs.twimg.com/card_img/1813989406337904640/UEz_mzB7?format=jpg&amp;name=small" class="css-9pa8cd">

Let's consider our own Starlight documentation at https://starlight.astro.build/ja/getting-started/ (for instance).
It contains the following metadata:

<meta property="twitter:image" content="https://starlight.astro.build/og.jpg?v=1">

The image is the following:

But there's no twitter:image:alt.
When shared on Twitter (see https://x.com/NewGyu/status/1814669986096685126), if you inspect the Twitter card, you'll see that the image doesn't have any alternative text:

<img alt="" draggable="true" src="https://pbs.twimg.com/card_img/1814058933243318272/eD3h0-Rh?format=jpg&amp;name=small" class="css-9pa8cd">

It's probably debatable whether a Twitter card image is decorative or not, and should have an alt text or not. However, our Starlight documentation image contains text that, if important, should be accessible to everyone, so via a screen reader too, as it is an information.

This is the reason why I'm suggesting this enhancement.

Other social media platforms

For other social media platforms, they mostly use Open Graph, and it also supports the alternative text for images with og:image:alt. So this is basically the same explanation for the same concept

Translate or not translate?

I've forced the following English text: "Make your docs shine with Starlight".
The reason is that I'd say we should have the exact same information as in the thumbnail (which is not translated).
But that's debatable. Maybe we can translate it for screen readers users only, for once, they would have the most precise information :)

[changeset-bot]

⚠️ No Changeset found

Latest commit: ada448c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	ada448c
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/669fee58e71dbb00088563bd
😎 Deploy Preview	https://deploy-preview-2143--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[delucis]

Thanks @julien-deramond — I think this is a reasonable change!

As an aside: I’m honestly not sure what on earth Twitter is doing with any of this. Looking at the astro.build example, the markup looks something like this:

<a
	href="..."
	aria-label="astro.build Astro 4.12: Server Islands | Astro"
	role="link"
>
	<div aria-label="Astro 4.12: Server Islands">
		<img alt="Astro 4.12: Server Islands" src="...">
	</div>
	<span>Astro 4.12: Server Islands | Astro</span>
</a>

Two aria-labels, an unnecessary role, an alt, and then actual text…

Nevertheless, this seems like a reasonable change to make.

One question: do you happen to know if both the twitter:image:alt and og:image:alt variants are required? Or would Twitter use the og: one if available?

[julien-deramond]

As an aside: I’m honestly not sure what on earth Twitter is doing with any of this. Looking at the astro.build example, the markup looks something like this:
Two aria-labels, an unnecessary role, an alt, and then actual text…

Yeah, and they improved it, apparently. I stumbled upon a post where it was mentioned that the alt text was inside an HTML element with an aria-hidden=true before 🙃

One question: do you happen to know if both the twitter:image:alt and og:image:alt variants are required? Or would Twitter use the og: one if available?

There are apparently fallback rules (that I haven't tested) here: https://developer.x.com/en/docs/twitter-for-websites/cards/overview/markup

Property	OpenGraph fallback
twitter:image	og:image
twitter:image:alt	og:image:alt

We could rely on the og:* fallback as it seems to work. If we do that, for consistency, maybe we should drop twitter:image, twitter:title, etc. On one hand, it would reduce the size of the pages.
But my own personal feeling would be to keep them both, as we would never know in the future if things change, if the fallback works differently, etc.

What do you think?

[delucis]

#2137 coincidentally removes most of the existing twitter:* tags, so I think I’m OK with removing them. Apart from the twitter:card one, they all seem to map back to the more standard og:* ones, so I think I’d only use the twitter:* ones if for some reason I wanted more control for different tags on Twitter from elsewhere.

[julien-deramond]

Oh, I didn't notice #2137, funny coincidence. I can understand the logic behind getting rid of twitter:* (except twitter:card that is important). The Astro/Starlight community is big, so if there's an update, we can trust it to create some PRs to put it back if necessary.

I've subscribed to #2137. Whenever it's merged, I'll update my PR, no problem, to keep only the og:image:alt.

[delucis]

Thanks for the quick update — looks great!

Also, didn’t address this earlier, but given we have the one static OG image, I think a non-translated alternative text makes sense too.