Open Graph Data can be used by social media platforms like Facebook, X (formerly called Twitter), or Discord to add an image to your Starlight page links when sharing them.
The image URL can be defined using the
twitter:image meta tags.
Starlight does not yet provide a built-in mechanism to automatically generate these images using all the available page data and add the corresponding meta tags to your pages.
This guide will show one possible way to do so using
astro-og-canvas which uses an Astro endpoint to generate the images.
The generated images can be customized using a large set of options including size, colors, fonts, logos, and more.
You will need to have an existing Starlight website.
Start by installing the
astro-og-canvas provides an
OGImageRoute helper that can be used to create an endpoint that will generate the various images for all documentation pages.
To do so, we need to do the following:
- Get a list of all documentation entries from the
docscontent collection used by Starlight.
- Map the entry array to an object with the page ID as key and the frontmatter data as value.
- Pass down the object to the
- Define a
paramoption to match the name of the parameter used in the endpoint path.
- Define a
getImageOptionsfunction called for each page to customize the generated image.
The following example will create the endpoint in a
Visiting the endpoint will now generate an image for the page matching the
For example, visiting
/og/getting-started.png would generate an image for the
Create a custom Astro component to replace the existing
<Head/> built-in component:
The last step is to configure Starlight to use the custom
<Head/> component instead of the built-in one and define the
site Astro option.
site option contains the deploy URL of your documentation website as Open Graph images require a valid URL having the
The following example will configure Starlight in the
Using opengraph.xyz, you can preview the generated images for your documentation pages.
For example, given the following
src/content/docs/getting-started.md file accessible at
The following meta tags will be added to the page:
And the following Open Graph image will be generated:
Up to you to customize the image using the various options provided by
You can find the complete source code of this guide in this StackBlitz example.