Dynamic OG Images

Customizing the Open Graph Image in Vocs

Vocs has built-in support for dynamic open graph images.

Open graph images are displayed when you share a link on an external platform such as X (formerly Twitter), Slack, Telegram, etc.

Every page in Vocs can come with a accompanying customized OG image. For example, the image for this page looks like:

Quick Start

Use our OG Image API

We've built an OG Image API that you can use to generate OG images for your Vocs documentation.

To use it, simply set the ogImageUrl property in your Vocs config to https://vocs.dev/api/og?logo=%logo&title=%title&description=%description.

vocs.config.ts

import { defineConfig } from 'vocs'
 
export default defineConfig({
  ogImageUrl: 'https://vocs.dev/api/og?logo=%logo&title=%title&description=%description', 
  title: 'Viem'
})

Deploy your own

The easiest way to get up and running with a dynamic OG Image API is to use Vercel's Edge Functions & @vercel/og.

You can get up-and-running right away by cloning & deploying our OG Image API example repository below:

After the project is deployed, change the ogImageUrl in your Vocs config to the URL of your deployed OG Image API.

vocs.config.ts

import { defineConfig } from 'vocs'
 
export default defineConfig({
  ogImageUrl: 'https://<my-project>.vercel.app/api/og?logo=%logo&title=%title&description=%description', 
  title: 'Viem'
})

Configuration

To customize the open graph image for your documentation, you can set the ogImageUrl property in your vocs.config.ts file.

The following template variables are available:

%logo: The URL of the logo image
%title: The title of the page
%description: The description of the page

vocs.config.ts

import { defineConfig } from 'vocs'
 
export default defineConfig({
  ogImageUrl: 'https://vocs.dev/api/og?logo=%logo&title=%title&description=%description', 
  title: 'Viem'
})

Path-based OG Images

You can also specify an object for the ogImageUrl with paths as keys.

This will render a different OG image depending on the path the user is on.

import { defineConfig } from 'vocs'
 
export default defineConfig({
  ogImageUrl: { 
    '/': 'https://vocs.dev/og-image.png', 
    '/docs': 'https://vocs.dev/api/og?logo=%logo&title=%title&description=%description', 
  }, 
  title: 'Viem'
})