The Custom OG Images emitter plugin generates social media preview images for your pages. It uses satori to convert HTML/CSS into images, allowing you to create beautiful and consistent social media preview cards for your content.
Note
For information on how to add, remove or configure plugins, see the Configuration page.
Features
Automatically generates social media preview images for each page
Supports both light and dark mode themes
Customizable through frontmatter properties
Fallback to default image when needed
Full control over image design through custom components
Configuration
Info
The baseUrl property in your configuration must be set properly for social images to work correctly, as they require absolute paths.
This plugin accepts the following configuration options:
quartz.config.ts
import { CustomOgImages } from "./quartz/plugins/emitters/ogImage"const config: QuartzConfig = { plugins: { emitters: [ CustomOgImages({ colorScheme: "lightMode", // what colors to use for generating image, same as theme colors from config, valid values are "darkMode" and "lightMode" width: 1200, // width to generate with (in pixels) height: 630, // height to generate with (in pixels) excludeRoot: false, // wether to exclude "/" index path to be excluded from auto generated images (false = use auto, true = use default og image) imageStructure: defaultImage, // custom image component to use }), ], },}
Configuration Options
Option
Type
Default
Description
colorScheme
string
”lightMode”
Theme to use for generating images (“darkMode” or “lightMode”)
width
number
1200
Width of the generated image in pixels
height
number
630
Height of the generated image in pixels
excludeRoot
boolean
false
Whether to exclude the root index page from auto-generated images
imageStructure
component
defaultImage
Custom component to use for image generation
Frontmatter Properties
The following properties can be used to customize your link previews:
Property
Alias
Summary
socialDescription
description
Description to be used for preview.
socialImage
image, cover
Link to preview image.
The socialImage property should contain a link to an image either relative to quartz/static, or a full URL. If you have a folder for all your images in quartz/static/my-images, an example for socialImage could be "my-images/cover.png". Alternatively, you can use a fully qualified URL like "https://example.com/cover.png".
Info
The priority for what image will be used for the cover image looks like the following: frontmatter property > generated image (if enabled) > default image.
The default image (quartz/static/og-image.png) will only be used as a fallback if nothing else is set. If the Custom OG Images emitter plugin is enabled, it will be treated as the new default per page, but can be overwritten by setting the socialImage frontmatter property for that page.
Customization
You can fully customize how the images being generated look by passing your own component to imageStructure. This component takes JSX + some page metadata/config options and converts it to an image using satori. Vercel provides an online playground that can be used to preview how your JSX looks like as a picture. This is ideal for prototyping your custom design.
Fonts
You will also be passed an array containing a header and a body font (where the first entry is header and the second is body). The fonts matches the ones selected in theme.typography.header and theme.typography.body from quartz.config.ts and will be passed in the format required by satori. To use them in CSS, use the .name property (e.g. fontFamily: fonts[1].name to use the “body” font family).
An example of a component using the header font could look like this: