Skip to content
HiDeoo

Generate Open Graph images for Starlight using the Cloudinary Astro SDK

- Updated on -

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

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:

.env
PUBLIC_CLOUDINARY_CLOUD_NAME=abcdefghi

Customize head route data

To add the og:image and twitter:image meta tags containing the URL of the generated Open Graph image to each documentation page, a route data middleware can be used. Such middleware can customize the head route data which is an array of all tags to include in the <head> of a page used by Starlight when rendering a page.

The route data middleware 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 middleware generate the URL of the Open Graph image for the current page based on the Cloudinary public ID of the image and transform it using a blur effect and text overlays for the title and description of the page.

src/routeData.ts
import { defineRouteMiddleware } from '@astrojs/starlight/route-data'
import { getCldOgImageUrl } from 'astro-cloudinary/helpers'


export const onRequest = defineRouteMiddleware((context) => {
  // Grab the current page entry and site title from the page data.
  const { entry, siteTitle } = context.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,
      },
    ],
  })


  // Add the `<meta/>` tags for the Open Graph images.
  head.push({
    tag: 'meta',
    attrs: { property: 'og:image', content: ogImageUrl.href },
  })
  head.push({
    tag: 'meta',
    attrs: { name: 'twitter:image', content: ogImageUrl.href },
  })
})

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

Configure Starlight

To use the route data middleware, configure it in the astro.config.mjs file.

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


export default defineConfig({
  integrations: [
    starlight({
      // Use the route data middleware to add the Open Graph images.
      routeMiddleware: './src/routeData.ts',
      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:

src/content/docs/getting-started.md
---
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:

Open Graph image for the Starlight getting-started page generated using the Cloudinary Astro SDK

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