Open Graph Images

Open Graph images appear in link previews generated by various social media sites, collaboration apps, chat programs, and more. This guide explains how to set up and enable Open Graph images on your Stainless Docs Platform site.

Basic usage

To enable Open Graph images for your documentation pages, use the ogImage option in your Stainless Docs Platform config. This automatically generates Open Graph images using your pages’ title and description metadata.

1. Install the required package

   pnpm i @takumi-rs/image-response

2. Enable `ogImage` in your `astro.config.ts` file

   astro.config.ts

   ...
   export default defineConfig({
     ...
     integrations: [
       stainlessDocs({
         ...
         ogImage: {},
       }),
     ],
     ...
   });

3. Set `site` within your astro config

   For the Open Graph images to have correct URLs, you need to set the site property in your astro.config.ts file:

   astro.config.ts

   export default defineConfig({
     ...
     site: 'https://www.your-domain.com/',
     ...
   });

Customize the Open Graph image

Use a custom logo

By default, the plugin will use the logo defined in your stainless.config.ts file. If you are using a separate dark and light mode logo, the plugin will default to the light mode logo.

To use a custom logo for all Open Graph images, pass the logo option:

astro.config.ts

export default defineConfig({
  integrations: [
    stainlessDocs({
      ...
      ogImage: {
        logo: './src/assets/og-logo.png',
      },
    }),
  ],
  ...
});

Add a background image

By default, no background image is used. To add a custom background image to all Open Graph images, pass the backgroundImage option:

astro.config.ts

export default defineConfig({
  integrations: [
    stainlessDocs({
      ...
      ogImage: {
        backgroundImage: {
          src: './src/assets/og-background.png',
          style: {
            opacity: 0.3,
            height: '100%',
            width: '100%',
            left: 0,
            top: 0,
          },
        },
      },
    }),
  ],
  ...
});

Change the theme

By default, Open Graph images use a light theme. To generate Open Graph images with a dark theme, pass the theme option:

astro.config.ts

export default defineConfig({
  integrations: [
    stainlessDocs({
      ...
      ogImage: {
        theme: 'dark',
      },
    }),
  ],
  ...
});