Generate Open Graph images for Starlight using the Cloudinary Astro SDK

When sharing a link to your Starlight documentation website on social media platforms like Facebook, X (formerly called Twitter), or Discord, Open Graph Data can be used to associate an image to the link using the og:image and twitter:image meta tags.

Such images can not be automatically generated by Starlight with the available route data and added to your pages meta tags. This guide will show one of the possible ways to do so using the Cloudinary Astro SDK which includes a dedicated function to generate Open Graph images using Cloudinary. All Cloudinary features can be used to customize the generated images, including transformations, filters, overlays, and more.

Prerequisites

You will need to have an existing Starlight website and a Cloudinary account.

Install the Cloudinary Astro SDK

Start by installing the astro-cloudinary package:

npm install astro-cloudinary

pnpm add astro-cloudinary

yarn add astro-cloudinary

bun add astro-cloudinary

ni astro-cloudinary

Configure the Cloudinary Astro SDK

The Cloudinary Astro SDK requires a Cloudinary cloud name to be specified using the PUBLIC_CLOUDINARY_CLOUD_NAME environment variable. Your Cloudinary cloud name can be found at the top of the Cloudinary API Key configuration page. You can use any of the Astro-supported approaches to set environment variables.

In the following example, a .env file is used to set the PUBLIC_CLOUDINARY_CLOUD_NAME environment variable:

PUBLIC_CLOUDINARY_CLOUD_NAME=abcdefghi

Override the <Head/> component

To add the og:image and twitter:image meta tags containing the URL of the generated Open Graph image to each documentation page, an override for the <Head/> component can be used.

The override will use the Cloudinary Astro SDK getCldOgImageUrl function to generate the image URL for the current page at the appropriate size and with the desired transformations.

The following custom <Head/> component will replace the built-in one and generate the URL of the Open Graph image for the current page. The image referenced by its Cloudinary public ID will be transformed using a blur effect and text overlays for the title and description of the page.

---
import Default from '@astrojs/starlight/components/Head.astro'
import { getCldOgImageUrl } from 'astro-cloudinary/helpers'

// Grab the current page entry and site title from the page data.
const { entry, siteTitle } = Astro.locals.starlightRoute

// Get the URL of the generated image for the current page.
const ogImageUrl = getCldOgImageUrl({
  // The public ID of the image in Cloudinary.
  src: 'og-background',
  // A blur transformation to apply to the image.
  blur: '1000',
  // Text overlays to add to the image.
  overlays: [
    {
      text: {
        // Add the title of the current page as text.
        text: entry.data.title,
        // Style the title text.
        color: '#020617',
        fontFamily: 'Lato',
        fontSize: 80,
        fontWeight: 'bold',
      },
      // Position the title with some padding.
      crop: 'fit',
      position: { y: -50 },
      width: 1000,
    },
    {
      text: {
        // Add the description of the current page as text.
        text: entry.data.description || siteTitle,
        // Style the description.
        color: '#020617',
        fontFamily: 'Lato',
        fontSize: 55,
        fontWeight: 'bold',
      },
      // Position the description below the title.
      position: { y: 50 },
      crop: 'fit',
      width: 1000,
    },
  ],
})
---

<!-- Render the default <Head/> component. -->
<Default><slot /></Default>

<!-- Render the <meta/> tags for the Open Graph images. -->
<meta property="og:image" content={ogImageUrl} />
<meta name="twitter:image" content={ogImageUrl} />

To learn more about all the available options and transformations, check out the getCldOgImageUrl configuration reference.

Configure Starlight

To use the custom <Head/> component, configure the override in the astro.config.mjs file.

import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'

export default defineConfig({
  integrations: [
    starlight({
      components: {
        // Relative path to the custom component.
        Head: './src/components/Head.astro',
      },
      title: 'My Docs',
    }),
  ],
})

Preview the generated images

The generated Open Graph images can be previewed using opengraph.xyz.

For example, given the following src/content/docs/getting-started.md file:

---
title: Getting started
description: Learn how to get started with Starlight.
---

My documentation page content.

The og:image and twitter:image meta tags will be added to the page and the following Open Graph image will be generated:

Up to you to customize the generated images to match your branding and style using all the available Cloudinary Astro SDK features.