---
title: "OG Images"
description: "Every docs page gets a social sharing image (OG image) generated at build time. This page covers the fields the built-in template reads, generating images for custom pages, replacing the template, and what happens when the feature is off."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/guide/og-image"
---
# OG Images

> Every docs page gets a social sharing image (OG image) generated at build time. This page covers the fields the built-in template reads, generating images for custom pages, replacing the template, and what happens when the feature is off.

## How it works

OG images are provided by [nuxt-og-image](https://github.com/nuxt-modules/og-image). The feature is on by default and its dependencies ship with the layer, so nothing extra is needed.

- Docs pages, the home page, the releases page and the showcase page all call the built-in `NuxtSeo.takumi` template and set `og:image` and `twitter:image`;
- The layer enables `ogImage.zeroRuntime`: images are rendered to static files by the Takumi renderer during prerendering and never generated on the fly in production, so only prerendered pages have OG images;
- `ogImage.buildCache` is enabled, so images are cached on disk and later builds reuse the results for unchanged pages.

::u-color-mode-image{alt="OG image generated for a docs page" class="rounded-md border border-default" dark="/screenshots/og-image-dark.png" light="/screenshots/og-image-light.png"}
::

## Template fields

The built-in `NuxtSeo.takumi` template lives in `layer/app/components/OgImage/NuxtSeo.takumi.vue` and accepts these props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `'title'` | Main title, up to three lines |
| `description` | `string` | - | Text below the title |
| `siteName` | `string` | - | Site name at the top |
| `colorMode` | `'light' \| 'dark'` | `'light'` | Color scheme |
| `isPro` | `boolean` | - | Switch to a purple accent |
| `width` | `number` | `1200` | Image width |
| `height` | `number` | `600` | Image height |

Docs pages fill these fields from the page frontmatter:

| Field | Value |
| --- | --- |
| `title` | `seo.title`, falling back to `title` |
| `description` | `seo.description`, falling back to `description` |
| `siteName` | `site.name` from the site config |

Set `seo.title` and `seo.description` in the frontmatter, and the sharing image and search results use the same title and description.

## Custom pages

For custom Vue pages under `app/pages/`, call `defineOgImage` inside an `import.meta.server` branch. Link to the page from a prerendered page so the crawler can discover it, or add its path to `nitro.prerender.routes`.

```vue [app/pages/showcase.vue]
<script setup lang="ts">
const title = 'Showcase'
const description = 'Docs sites built with Movk Nuxt Docs'

useSeoMeta({ title, description })

if (import.meta.server) {
  defineOgImage('NuxtSeo.takumi', {
    title,
    description,
    siteName: useSiteConfig().name
  })
}
</script>
```

## Replace the template

The template is a regular component. Create a file with the same name, `NuxtSeo.takumi.vue`, under `app/components/OgImage/` in your project to override the layer's implementation; every page then uses the new template:

```vue [app/components/OgImage/NuxtSeo.takumi.vue]
<script setup lang="ts">
defineProps<{
  title?: string
  description?: string
  siteName?: string
}>()
</script>

<template>
  <div class="w-full h-full flex flex-col justify-between p-16 bg-[#f6f3ee] text-[#1a1a1a]">
    <span class="text-[28px] tracking-[0.2em] uppercase text-[#c8392f]">{{ siteName }}</span>
    <div class="flex flex-col gap-6">
      <h1 class="text-[72px] font-bold leading-tight m-0">{{ title }}</h1>
      <p v-if="description" class="text-[30px] opacity-70 m-0">{{ description }}</p>
    </div>
  </div>
</template>
```

The `.takumi` part of the file name selects the Takumi renderer, so keep that suffix. For the CSS and markup the renderer supports, follow [nuxt-og-image](https://github.com/nuxt-modules/og-image) and the layer's built-in template.

> [!TIP]
> 
> To give a single custom page a different design, create a component with another name (such as 
> 
> OgImage/Feature.takumi.vue
> 
> ) and call 
> 
> defineOgImage('Feature.takumi', { ... })
> 
>  on that page. Built-in pages are unaffected.

## Turn OG images off

If you do not need sharing images, or want shorter builds, turn the feature off in `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movkNuxtDocs: {
    ogImage: false
  }
})
```

With it off, `nuxt-og-image` is not registered and `defineOgImage` is replaced by a no-op: calls in the layer and in your own pages stay in place and do nothing, so there is no need to remove them or add conditions. See [Feature Flags](https://docs.mhaibaraai.cn/en/docs/guide/features) for the other switches.


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
