Add OG Images to Starlight

This guide will show one possible way to add OG images to Starlight.

Steps by steps

Section titled Steps by steps

1. Start by installing the astro-og-canvas ↗ package:

   npm

   npm add astro-og-canvas

   pnpm

   pnpm add astro-og-canvas

   Yarn

   yarn add astro-og-canvas

   Bun

   bun add astro-og-canvas

2. Create the image endpoint with this code:

   src/pages/og/[...route].ts

   import { getCollection } from 'astro:content'
   import { OGImageRoute } from 'astro-og-canvas'
   
   const entries = await getCollection('docs')
   
   const pages = Object.fromEntries(entries.map(({ data, id }) => [id, { data }]))
   
   export const { getStaticPaths, GET } = OGImageRoute({
     pages,
     param: 'route',
     getImageOptions: (_path, page: (typeof pages)[number]) => {
       return {
         title: page.data.title,
         description: page.data.description,
         border: { width: 32, side: 'inline-start' },
         padding: 80,
         bgGradient: [[24, 24, 27]],
       }
     },
   })

3. Override the <Head/> component:

   src/components/Head.astro

   ---
   import type { Props } from '@astrojs/starlight/props'
   import Default from '@astrojs/starlight/components/Head.astro'
   
   const ogImageUrl = new URL(
     `/og/${Astro.props.id.replace(/\.\w+$/, '.png')}`,
     Astro.site,
   )
   ---
   
   <Default {...Astro.props}><slot /></Default>
   
   <meta property="og:image" content={ogImageUrl} />
   <meta name="twitter:image" content={ogImageUrl} />

4. Configure Starlight in the astro.config.mjs file:

   astro.config.mjs

   // ...
   
   export default defineConfig({
     integrations: [
       starlight({
         components: {
           Head: './src/components/Head.astro',
         },
       }),
     ],
   })

Up to you to customize the image using the various options provided by astro-og-canvas ↗.

Resources

Section titled Resources

1. Add Open Graph images to Starlight ↗