About Open Graph Images

This post explains how to configure Open Graph (OG) images in the Astro AntfuStyle Theme.

What Are Open Graph Images?#

OG images, short for Open Graph images, are metadata images used by social media platforms to visually represent a webpage when shared. Originating from Facebook’s Open Graph protocol, they make shared content more engaging.

Platforms like Facebook, Twitter, LinkedIn, and Discord use these images. While Twitter uses its own protocol (Twitter Cards), “OG image” is often used as a general term for these images.

Configuring OG Images#

There are four ways to configure OG images in this theme, listed by priority:

Method 1: Specify the ogImage field in Markdown/MDX frontmatter with a custom image saved under public/og-images/. The value should be the path relative to that directory. For example:

---
title: Custom OG Image

# Required file: `public/og-images/custom.png`
# OG image served from: `/og-images/custom.png`
ogImage: custom.png
---

---
title: Custom OG Image

# Required file: `public/og-images/custom/custom.png`
# OG image served from: `/og-images/custom/custom.png`
ogImage: custom/custom.png
---

Method 2: Set ogImage to true or remove the field to automatically generate a page-specific OG image at /og-images/. The generated path is based on the final page URL. Static MDX pages in src/pages/ use their page pathname directly, while routed content collections use the pathnamePrefix configured in collections. For example:

---
title: Blog

# OG image served from: `/og-images/blog.png`
ogImage: true
---

---
title: Getting Started

# Rendered under: `pages/blog/[...slug].astro`
# Configured as: `{ collection: 'blog', pathnamePrefix: '/blog' }`
# OG image served from: `/og-images/blog/getting-started.png`
ogImage: true

# Rendered under: `pages/writing/[...slug].astro`
# Configured as: `{ collection: 'blog', pathnamePrefix: '/writing' }`
# OG image served from: `/og-images/writing/getting-started.png`
ogImage: true
---

Method 3: Set ogImage to fallback to prevent page-specific generation and use the fallback image instead. The fallback image is generated based on the fallbackTitle and fallbackBgType configuration options and served from /og-images/og-image.png.

---
title: Getting Started

# OG image served from: `/og-images/og-image.png`
ogImage: fallback
---

Method 4: Set ogImage to false to disable OG image metadata for that page. The page will not generate a page-specific image, will not use the fallback image, and will not output og:image, twitter:image, or JSON-LD image.

Template for Auto-Generated OG Images#

The template (located in src/utils/og-image/template/markup.ts) for auto-generated OG images is processed by satori-html. It takes three parameters:

• authorOrBrand: Defined by FEATURES.ogImage[1].authorOrBrand and displayed above the title. This value is also used for the fallback OG image.
• title: Set in the Markdown/MDX frontmatter for posts and pages. If missing, empty, or identical to authorOrBrand, it falls back to FEATURES.ogImage[1].fallbackTitle. The fallback OG image also uses fallbackTitle.
• bgType: Set in the Markdown/MDX frontmatter for posts and pages. If missing, false, or invalid, it falls back to FEATURES.ogImage[1].fallbackBgType. The fallback OG image also uses fallbackBgType.

For details on how to replace the logo in the template, refer to Advanced Configuration - Customizing Logo.

Below are the OG images generated with bgType set to plum, rose, dot, and particle:

How This Theme Automatically Generates OG Images#

This theme uses the src/pages/og-images/[...slug].png.ts endpoint to generate OG images from structured content metadata. The endpoint always registers the fallback OG image path /og-images/og-image.png.

For page-specific images, it collects static MDX pages from the pages collection and routed content entries from the collections configured in src/config.ts. Each content entry is resolved to its final page URL using pathnamePrefix, and that URL is then mapped to the corresponding OG image path.

ogImage: [
  true,
  {
    authorOrBrand: `${SITE.title}`,
    fallbackTitle: `${SITE.description}`,
    fallbackBgType: 'plum',
    collections: [
      { collection: 'blog', pathnamePrefix: '/blog' },
      { collection: 'changelog', pathnamePrefix: '/changelog' },
      { collection: 'shorts', pathnamePrefix: '/shorts' },
    ],
  },
],

collection is the data source, while pathnamePrefix is the URL prefix where entries from that collection are rendered. For example, { collection: 'articles', pathnamePrefix: '/writing' } maps an articles entry with id hello to /writing/hello/, and then to /og-images/writing/hello.png.

Only entries with ogImage: true, a valid title, and no draft or redirect field get page-specific endpoint targets. Entries with ogImage: 'fallback', ogImage: false, or a custom image string do not register page-specific targets.

Extra Tips#

Auto-generated OG images are compressed with sharp. For custom images, consider manual compression.

public/og-images is only for explicitly configured custom images. If a file in public/og-images matches the path of an auto-generated endpoint, including public/og-images/og-image.png, the build warns and skips generating that endpoint to avoid an output conflict. Delete the static file to let the endpoint generate it, or set ogImage to that filename to intentionally use the static image.

If you want to globally disable OG image generation and OG image metadata, set FEATURES.ogImage to false or [false, {...}] in src/config.ts.

Thank you for reading. Happy coding! 💃