OG-изображения страниц

В site OG-изображения генерируются автоматически на основе метаданных страниц. Их можно использовать для превью ссылок в мессенджерах и социальных сетях, а также вставлять как обычные изображения в карточки статей, разделы каталога и другие элементы интерфейса.

Как работает генерация

Обработчик находится в apps/web/src/routes/og/[section]/[slug].png/+server.ts.

Он получает раздел и slug документа, извлекает метаданные через getContentSectionMetadata() и формирует PNG-картинку размером 1200 × 630. Маршруты предварительно перечисляются функцией entries() и генерируются при prerender-сборке.

Для SVX-страниц layout вычисляет OG URL по адресу страницы:

const docOgImage = $derived(
  metadata?.sourceType === 'svx'
    ? new URL(`/og${metadata.href}.png`, siteOrigin).href
    : new URL(siteConfig.ogImage, siteOrigin).href
);

const docOgImage = $derived(
  metadata?.sourceType === 'svx'
    ? new URL(`/og${metadata.href}.png`, siteOrigin).href
    : new URL(siteConfig.ogImage, siteOrigin).href
);

Затем этот URL используется в og:image и twitter:image. Поэтому OG-картинка — это URL, который отдаёт маршрут приложения, а не обязательно отдельный файл в каталоге static.

Использование в HTML и Svelte

Если известен URL страницы, можно использовать соответствующий URL изображения напрямую:

<img
  src="/og/article/mtls.png"
  alt="Руководство по mTLS"
  class="w-full rounded-xl"
  loading="lazy"
/>

<img
  src="/og/article/mtls.png"
  alt="Руководство по mTLS"
  class="w-full rounded-xl"
  loading="lazy"
/>

Замените примерный путь на путь реальной страницы в вашем проекте. Например, для страницы /article/mtls ожидаемый адрес по принятой схеме — /og/article/mtls.png.

Если сайт развёрнут не в корне домена или изображение используется на другом сайте, используйте полный абсолютный URL. Для внешних потребителей URL должен быть доступен публично по HTTPS.

Использование в карточках

Храните URL изображения рядом с данными карточки, чтобы не собирать его из названия статьи:

<script lang="ts">
  const articles = [
    {
      title: 'Руководство по mTLS',
      href: '/article/mtls',
      image: '/og/article/mtls.png'
    }
  ];
</script>

{#each articles as article}
  <a href={article.href} class="block">
    <img
      src={article.image}
      alt=""
      class="w-full rounded-xl"
      loading="lazy"
    />
    <h2>{article.title}</h2>
  </a>
{/each}

<script lang="ts">
  const articles = [
    {
      title: 'Руководство по mTLS',
      href: '/article/mtls',
      image: '/og/article/mtls.png'
    }
  ];
</script>

{#each articles as article}
  <a href={article.href} class="block">
    <img
      src={article.image}
      alt=""
      class="w-full rounded-xl"
      loading="lazy"
    />
    <h2>{article.title}</h2>
  </a>
{/each}

Для больших каталогов лучше формировать данные карточек из манифеста контента и использовать реальный href документа. Это уменьшает дублирование slug и риск несоответствия изображения странице.

Проверка URL

Перед использованием картинки проверьте её в браузере:

1. Откройте страницу документации и скопируйте её canonical URL или pathname.
2. Сформируйте путь OG-изображения по правилу, которое используется в layout: /og + pathname + .png.
3. Откройте полученный URL и убедитесь, что сервер возвращает PNG, а не страницу 404.
4. Если маршрут не найден, проверьте, что документ попадает в манифест раздела и входит в список prerender-страниц.

Не предполагайте, что любой произвольный slug будет работать: обработчик ищет документ в метаданных раздела и возвращает 404, если документ не найден.

OG-картинка и обычное изображение — не одно и то же

• Для превью ссылок: используйте метатеги og:image и twitter:image. Они сообщают мессенджерам и социальным сетям, какую картинку показывать при публикации ссылки.
• Для отображения на странице: вставляйте URL в <img> или компонент изображения. Одного метатега og:image недостаточно, чтобы картинка появилась в интерфейсе.
• Для общей картинки сайта: страницы, для которых не генерируется индивидуальное OG-изображение, используют siteConfig.ogImage.

Когда лучше не использовать OG-картинку

OG-изображение предназначено прежде всего для широкого превью с заголовком. Оно может содержать текст, рассчитанный на формат 1200 × 630, поэтому для маленьких карточек или сложных адаптивных макетов проверьте читаемость и кадрирование. Если нужен отдельный арт-дирекшн, фотография или изображение без текста, лучше подготовить специальный ресурс, а не переиспользовать OG-рендер.