Guides

OG Images

Understand runtime OG image rendering and customize the image template.

Docus Plus generates an Open Graph image for the landing page and documentation pages. The page metadata contains an absolute og:image URL that points to the runtime image route. Social platforms request that URL separately when they generate a link preview.

How rendering works

The layer uses Nuxt SEO's OG image module and a Takumi Vue template. When a page calls defineOgImage, the page metadata points to a URL under /_og/. The server renders that route to a PNG using the page's title, description, headline, site identity, and the selected template.

This happens at runtime. The application therefore needs a server deployment and must be built with the supported command:

pnpm build

The layer does not support static pnpm generate deployments or zero-runtime OG images. The server must remain available when crawlers request the /_og/ image URL.

Requirements

Configure the public site URL so the generated metadata contains an absolute image URL:

envs/.env.production

NUXT_PUBLIC_SITE_URL=https://docs.example.com

The runtime must be able to serve the Nuxt OG image route. For Cloudflare deployments, add the required caching and runtime configuration described in the Nuxt SEO guides for Cloudflare and runtime caching.

Override the template

To change the generated design—for example, to add a logo—copy the layer template into the consuming application at:

app/components/OgImage/Docs.takumi.vue

The Docs.takumi.vue component is used for both the landing page and documentation OG images. The copied component becomes the consumer override, so the layer can continue to receive updates without overwriting your design.

Start with the layer template and adapt the markup. A minimal custom template looks like this:

app/components/OgImage/Docs.takumi.vue

<script lang="ts" setup>
const { title, description, headline } = defineProps<{
  title?: string;
  description?: string;
  headline?: string;
}>();

const appConfig = useAppConfig();
const { name: siteName } = useSiteConfig();
const primaryColor = appConfig.ui?.colors?.primary ?? "emerald";
</script>

<template>
  <div class="w-full h-full flex flex-col justify-between bg-neutral-950 px-[80px] py-[60px]">
    <!-- Radial glow top-right: wide soft layer -->
    <div
      class="absolute top-0 right-0 w-[1000px] h-[1000px] bg-[radial-gradient(circle_at_top_right,rgba(255,255,255,0.10)_0%,rgba(255,255,255,0.01)_40%,transparent_50%)]"
    />
    <!-- Radial glow top-right: tight bright core -->
    <div
      class="absolute top-0 right-0 w-[350px] h-[350px] bg-[radial-gradient(circle_at_top_right,rgba(255,255,255,0.08)_0%,rgba(255,255,255,0.02)_25%,transparent_45%)]"
    />

    <div class="flex-1 flex flex-col justify-center items-start">
      <span
        v-if="headline"
        :class="`uppercase text-[16px] m-0 mb-8 tracking-[0.05em] text-${primaryColor}-500 rounded-md px-3 py-1.5 border-1 border-${primaryColor}-500/50 bg-${primaryColor}-500/10 inline-block`"
        style="
          font-family:
            JetBrains Mono,
            ui-monospace,
            monospace;
        "
      >
        {{ headline }}
      </span>
      <h1
        v-if="title"
        class="m-0 mb-6 text-[50px] font-bold text-white leading-[1.1] w-full max-w-[900px] wrap-break-word"
        style="font-family: Figtree, sans-serif"
      >
        {{ title?.slice(0, 60) }}
      </h1>
      <p
        v-if="description"
        class="m-0 text-[28px] text-neutral-400 leading-[1.4] w-full max-w-[900px] wrap-break-word"
        style="font-family: Figtree, sans-serif"
      >
        {{ description?.slice(0, 200) }}
      </p>
    </div>

    <div class="flex">
      <div
        :class="`text-[18px] font-normal rounded-lg pr-5 py-2 text-${primaryColor}-500`"
        style="font-family: Figtree, sans-serif"
      >
        {{ siteName }}
      </div>
    </div>
  </div>
</template>

Use an absolute, publicly reachable logo URL or an asset supported by the OG image runtime. Keep the template self-contained: it runs in the server image renderer, not in the browser application.

Use custom fonts

Declare the font family in the template and register it globally through @nuxt/fonts:

nuxt.config.ts

export default defineNuxtConfig({
  fonts: {
    families: [{ name: "Figtree", weights: [400, 700], global: true }]
  }
});

The family name in the component must match the configured font family. If the font cannot be discovered at build time, the renderer falls back to Inter.

Use the OG image developer tools for visual iteration, then request the generated /_og/ URL from the running production server to confirm the runtime can render the final image.

Scalar API

Publish an interactive API reference and searchable API content from an OpenAPI document.

Server Utils

Manage the Docus Plus cache and monitor its health with the built-in server utilities.

OG Images

How rendering works

Requirements

Override the template

Use custom fonts

Keep in touch with the latest