Marketplace

OG Card

plugin Source

Generate 1200×630 social preview PNGs from Qute SVG templates

Install

Terminal
$ roq add plugin:og-card

Usage

Generate 1200×630 Open Graph preview cards from Qute SVG templates at build time. Injects og-image frontmatter so {#seo /} emits og:image and twitter:card=summary_large_image.

Installation

roq add plugin:og-card

Or add the Maven dependency:

<dependency>
    <groupId>io.quarkiverse.roq</groupId>
    <artifactId>quarkus-roq-plugin-og-card</artifactId>
    <version>${quarkus.roq.version}</version>
</dependency>

Configuration

At least one of collections or include-paths is required:

quarkus.roq.plugin.og-card.collections=posts
quarkus.roq.plugin.og-card.exclude-paths=/posts/tag/
quarkus.roq.plugin.og-card.include-paths=/about/
quarkus.roq.plugin.og-card.template=og-card/default-card.svg
quarkus.roq.plugin.og-card.site-name=My Site
quarkus.roq.plugin.og-card.output-prefix=/og
quarkus.roq.plugin.og-card.max-text-width=-1
  • collections — generate cards for all documents in named collections (e.g. posts → /og/posts/{slug}.png)
  • include-paths — explicit normal pages (e.g. /about/ → /og/about.png)
  • exclude-paths — when using collections, skip path prefixes such as /posts/tag/ (not applied to include-paths)
  • max-text-width — horizontal pixels for text wrapping (-1 auto-computes from card width); reduce when graphics occupy part of the card

Pages with image, img, or picture frontmatter are skipped by default (skip-if-image-set=true). Map title, description, and optional kicker / eyebrow from page frontmatter into the card.

Card template

Place custom templates under templates/og-card/. The plugin passes a card object with pre-wrapped titleLines and descriptionLines for multi-line SVG text:

<text x="72" y="170" font-size="52">
  {#for line in card.titleLines}
  <tspan x="72" dy="{line_isFirst ? '0' : '62'}">{line}</tspan>
  {/for}
</text>

Bundled default: og-card/default-card.svg.

Viewing your cards

In dev mode, open http://localhost:8080/og/about.png.

With generator batch enabled, PNGs are written to target/roq/og/:

QUARKUS_ROQ_GENERATOR_BATCH=true mvn package quarkus:run

For CI and containers, set JAVA_TOOL_OPTIONS=-Djava.awt.headless=true before the build (Batik uses Java2D/AWT).

Documentation