Open Graph Images

Basic usage

To enable Open Graph images for your documentation pages, use the @stainless-docs/docs-og-image plugin. This plugin automatically generates Open Graph images using your pages title and description metadata.

1. Install the plugin

   pnpm i @stainless-docs/docs-og-image

2. Add the plugin to your `astro.config.ts` file

   astro.config.ts

   ...
   import stainlessDocsOgImage from '@stainless-api/docs-og-image';
   ...
   
   export default defineConfig({
     ...
     integrations: [
       stainlessDocs({
         ...
         plugins: [
           stainlessDocsOgImage(),
         ],
       }),
     ],
     ...
   });

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

   ...
   import stainlessDocsOgImage from '@stainless-api/docs-og-image';
   ...
   
   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 to the plugin:

astro.config.ts

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

Add a background image

By default, the plugin will not use a background image. To add a custom background image to all Open Graph images, pass the backgroundImage option to the plugin:

astro.config.ts

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

Change the theme

By default, the plugin will generate Open Graph images using a light theme. To generate Open Graph images with a dark theme, pass the theme option to the plugin:

astro.config.ts

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