Добавляем Schema.org в Docusaurus для GEO

От SEO к GEO (Generative Engine Optimization)

Мы в Pingera, как и любая технически подкованная команда, постоянно работаем над улучшением наших инструментов и следим за тем, как наш контент индексируется поисковыми системами. Но после взрывного роста больших языковых моделей и ИИ инструментов правила игры изменились кардинально. Речь уже не только о классическом SEO (Search Engine Optimization), а о GEO — Generative Engine Optimization.

GEO — это оптимизация контента для того, чтобы он был максимально понятен и точно использовался генеративными AI-моделями. Наша техническая документация, расположенная на docs.pingera.ru и построенная на популярном фреймворке Docusaurus, — важный актив. Именно здесь инженеры находят ответы на вопросы об интеграциях, API и тонкостях мониторинга. Поэтому мы задались вопросом: как убедиться, что LLM-инструменты, такие как YandexGPT и Google Gemini, будут давать максимально точные ответы, ссылаясь на нашу документацию? Ведь при наличии AI Overview ответа от поисковика пользователи кликнут на ссылку всего в 8% случаев (даже если она первая).

Говорим с AI на его языке

Schema.org разметка перешла из разряда «неплохо бы иметь» в «обязательно, и вчера». Это не просто набор тегов для «красивых сниппетов» в поиске. Это семантический каркас, который даёт явные и недвусмысленные подсказки о смысле и структуре нашего контента.

Ключевые фигуры в индустрии прямо указывают на это:

• Fabrice Canel (Microsoft Bing): «Schema Markup помогает Large Language Models Microsoft понимать и интерпретировать контент веб‑страниц».
• Google Search Central: «Вы можете существенно помочь нашим системам, предоставив явные и недвусмысленные подсказки о значении и структуре страницы через включение структурированных данных».

Бенчмарк-исследование компании Data World показало, что LLM, основанные на Knowledge Graphs со структурированными данными, достигают уровня точности ответов на 300% выше по сравнению с моделями, работающими только с сырым текстом. Это трёхкратное превосходство в точности, которое невозможно игнорировать.

Для нас это стало сигналом: внедрение структурированных данных — это технический императив для обеспечения качества ответов об API и наших продуктах.

Как внедрить Schema.org в Docusaurus

Фреймворк Docusaurus не имеет встроенного гибкого механизма для генерации сложной JSON-LD разметки. Тут мы и расскажем, какие изменения нужны, чтобы разметка появилась.

Шаг 1. Глобальные Схемы: Organization и WebSite

Мы начали с добавления базовой информации о компании и сайте, используя массив headTags в файле docusaurus.config.js. Это самый простой способ внедрить статические глобальные схемы, которые описывают нашу организацию и сайт документации.

			// docusaurus.config.js (фрагмент)

  headTags: [
    {
      tagName: 'script',
      attributes: {
        type: 'application/ld+json',
      },
      innerHTML: JSON.stringify({
        '@context': 'https://schema.org',
        '@type': 'Organization',
        '@id': 'https://pingera.ru/#organization',
        'name': 'Pingera',
        'url': 'https://pingera.ru',
        'logo': 'https://static.tildacdn.com/tild3866-3862-4631-b636-356562363133/logo-horizontal-blac.png',
      }),
    },
    {
      tagName: 'script',
      attributes: {
        type: 'application/ld+json',
      },
      innerHTML: JSON.stringify({
        '@context': 'https://schema.org',
        '@type': 'WebSite',
        '@id': 'https://docs.pingera.ru/#website',
        'url': 'https://docs.pingera.ru',
        'name': 'Документация Pingera',
        'description': 'Документация платформы мониторинга Pingera',
        'publisher': {
          '@id': 'https://pingera.ru/#organization',
        },
        'inLanguage': 'ru-RU',
      }),
    },
  ],
// ... остальная часть конфигурации

		

Шаг 2. Динамические Схемы: TechArticle и BreadcrumbList

Для создания схем, которые должны динамически меняться для каждой страницы (например, заголовок, URL, дата), мы использовали Swizzling — инструмент для кастомизации Docusaurus.

Оборачивание компонента DocItem: Мы запустили swizzle в режиме обертывания (wrap), чтобы не нарушать логику основного компонента:

			npm run swizzle @docusaurus/theme-classic DocItem -- --wrap
		

1. Это создало файл src/theme/DocItem/index.js.
2. Реализация логики в src/theme/DocItem/index.js: Внутри этого файла мы получаем метаданные страницы (metadata) и frontMatter и используем их для генерации схем TechArticle и BreadcrumbList.
3. Схема TechArticle динамически заполняется заголовком, описанием, датой последнего обновления, явно указывая на технический тип контента.
4. Схема BreadcrumbList генерируется на основе пермалинка страницы, обеспечивая полный иерархический путь, который критически важен для LLM.

			// src/theme/DocItem/index.js (Полная реализация)

import React from 'react';
import DocItem from '@theme-original/DocItem';
import Head from '@docusaurus/Head';

export default function DocItemWrapper(props) {
  const { metadata, frontMatter } = props.content;

  // Build the TechArticle schema
  const techArticleSchema = {
    '@context': 'https://schema.org',
    '@type': 'TechArticle',
    'headline': metadata.title,
    'description': metadata.description || frontMatter.description || '',
    'url': `https://docs.pingera.ru${metadata.permalink}`,
    'datePublished': metadata.lastUpdatedAt ? new Date(metadata.lastUpdatedAt * 1000).toISOString() : undefined,
    'dateModified': metadata.lastUpdatedAt ? new Date(metadata.lastUpdatedAt * 1000).toISOString() : undefined,
    'author': {
      '@type': 'Organization',
      '@id': 'https://pingera.ru/#organization',
      'name': 'Pingera'
    },
    'publisher': {
      '@type': 'Organization',
      '@id': 'https://pingera.ru/#organization',
      'name': 'Pingera',
      'logo': {
        '@type': 'ImageObject',
        'url': 'https://static.tildacdn.com/tild3866-3862-4631-b636-356562363133/logo-horizontal-blac.png'
      }
    },
    'mainEntityOfPage': {
      '@type': 'WebPage',
      '@id': `https://docs.pingera.ru${metadata.permalink}`
    },
    'inLanguage': 'ru-RU'
  };

  // Build breadcrumb list with complete path including category
  const breadcrumbItems = [];

  // Always start with homepage
  breadcrumbItems.push({
    '@type': 'ListItem',
    'position': 1,
    'name': 'Документация',
    'item': 'https://docs.pingera.ru/'
  });

  // Extract category from URL path
  // e.g., /checks/multistep-api -> "checks" is the category
  const pathSegments = metadata.permalink.split('/').filter(Boolean);
  
  if (pathSegments.length > 1) {
    // Map URL segments to Russian category names
    const categoryMap = {
      'checks': 'Проверки',
      'pages': 'Статус Страницы',
      'getting-started': 'О платформе',
      'devs': 'Разработчикам',
      'api': 'Документация API'
    };
    
    const categorySlug = pathSegments[0];
    const categoryName = categoryMap[categorySlug] || categorySlug;
    
    breadcrumbItems.push({
      '@type': 'ListItem',
      'position': 2,
      'name': categoryName,
      'item': `https://docs.pingera.ru/${categorySlug}`
    });
  }

  // Add current page as final breadcrumb
  breadcrumbItems.push({
    '@type': 'ListItem',
    'position': breadcrumbItems.length + 1,
    'name': metadata.title,
    'item': `https://docs.pingera.ru${metadata.permalink}`
  });

  const breadcrumbSchema = {
    '@context': 'https://schema.org',
    '@type': 'BreadcrumbList',
    'itemListElement': breadcrumbItems
  };

  return (
    <>
      <Head>
        {/* TechArticle Schema */}
        <script type="application/ld+json">
          {JSON.stringify(techArticleSchema)}
        </script>
        {/* BreadcrumbList Schema - only one per page */}
        <script type="application/ld+json">
          {JSON.stringify(breadcrumbSchema)}
        </script>
      </Head>
      <DocItem {...props} />
    </>
  );
}

		

Шаг 3. Устраняем Дублирование: Удаление Дефолтных Хлебных Крошек

Docusaurus по умолчанию генерирует свою собственную JSON-LD для хлебных крошек, что приводит к дублированию и ошибкам валидации. Чтобы этого избежать, мы выполнили Eject компонента DocItem/Layout всё через тот же swizzle:

npm run swizzle @docusaurus/theme-classic DocItem/Layout -- --eject --danger

В файле src/theme/DocItem/Layout/index.js мы удалили импорт и рендеринг компонента DocBreadcrumbs. Это гарантировало, что в HTML страницы остаётся только наша кастомная схема BreadcrumbList.

Тестирование и проверка валидности

Для подтверждения корректности нашей реализации мы использовали два основных инструмента:

1. Google Rich Results Test: Для проверки того, как Google видит наши структурированные данные и какие расширенные сниппеты он может сгенерировать.
2. Schema Markup Validator: Основной инструмент для проверки синтаксической и семантической корректности JSON-LD разметки: https://validator.schema.org/.

Так выглядит валидация разметки на validator.schema.org

Результат и Преимущества

Пока ещё рано говорить о результате, но мы ожидаем следующего:

• Улучшенная Точность AI-ответов (GEO): Наш контент теперь имеет высокий приоритет и точность при формировании AI-ответов.
• Rich Snippets: Расширенные сниппеты с хлебными крошками и датами в результатах поиска улучшили CTR.
• Knowledge Graph: Схема Organization помогает Google отображать информацию о Pingera в панели знаний.
• Техническое Признание Контента: Схема TechArticle сигнализирует поисковым системам, что это специализированный, технический контент.

Заключение

Эпоха, когда SEO ограничивалось ключевыми словами, прошла. Сегодня успех контента в поиске зависит от его семантической чистоты. Schema.org — это не просто инструмент для маркетологов, а технический стандарт, который становится критически важным для каждого разработчика, отвечающего за документацию и качество контента.

Если вы используете Docusaurus или любую другую платформу для документации, не откладывайте внедрение структурированных данных. Ваша цель — не просто быть в поиске, а быть максимально понятным для искусственного интеллекта.