# Настройка разметки Schema.org в статьях (JSON-LD, микроразметка)
Разметка Schema.org описывает содержимое страницы в машиночитаемом виде: что это за документ, о чём он, когда опубликован и обновлён. Поисковые системы используют её для расширенных сниппетов, а ИИ-сервисы — чтобы точнее понимать и цитировать статью.

## Что такое JSON-LD

JSON-LD (JSON for Linked Data) — формат записи разметки Schema.org в виде JSON-объекта внутри тега `<script type="application/ld+json">`. Разметка не влияет на внешний вид страницы. Google и Яндекс рекомендуют этот формат.

В Swarmica разметка задаётся в поле `jsonld` на вкладке **SEO** редактора статьи, отдельно для каждого языка. Хелпцентр сам оборачивает значение в тег `<script>`, поэтому указывайте только JSON:

```json
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Как настроить SMTP канал для почты в Swarmica",
  "description": "Пошаговая настройка исходящей почты через SMTP в Swarmica.",
  "inLanguage": "ru",
  "datePublished": "2026-05-12",
  "dateModified": "2026-09-01",
  "image": "https://support.example.com/attachments/a/b/abc_a/smtp.png"
}
```

:::caution
Значение поля должно быть корректным JSON, иначе статья не сохранится.
:::

## Что такое микроразметка (microdata)

Микроразметка — альтернативный способ описать данные Schema.org с помощью атрибутов `itemscope`, `itemtype` и `itemprop` прямо в HTML-коде страницы.

Хелпцентр сам выводит часть микроразметки: значения полей `seo_description` и `seo_image` дублируются в метатегах с атрибутом `itemprop`. Добавлять микроразметку в текст статьи не нужно: для корректной работы и отображения статей не рекомендуется использовать в них никакие HTML-вставки (см. [Можно ли расширять статью произвольным HTML](https://support.swarmica.com/article/ru/2043)). Для собственной разметки используйте поле `jsonld`.

## Типы Schema.org для статей базы знаний

| Тип | Когда использовать |
| --- | --- |
| `TechArticle` | Рекомендуемый тип для большинства статей базы знаний: инструкции, решения проблем, описания настроек. |
| `Article` | Общие статьи, не являющиеся технической документацией: новости, обзоры. |
| `HowTo` | Пошаговые инструкции с явно выделенными шагами (`step`). |
| `FAQPage` | Статья содержит список вопросов и ответов, написанных вашей компанией. |
| `QAPage` | Страница с одним вопросом и ответами на него, в том числе от пользователей. |
| `BreadcrumbList` | «Хлебные крошки»: путь к статье через разделы базы знаний. |
| `VideoObject` | Статья содержит видео. |

Типы `Organization` и `WebSite` описывают компанию и сайт целиком, поэтому повторять их в каждой статье не нужно. Добавьте их один раз для всего портала базы знаний: **Настройки → Основные настройки → Управление брендами → <Бренд по умолчанию> → Стили публичного портала базы знаний → Код HTML head**.

В отличие от поля `jsonld` статьи, в этом поле разметку нужно указывать вместе с тегом `<script>`:

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "name": "Название компании",
      "url": "https://example.com",
      "logo": "https://example.com/logo.png"
    },
    {
      "@type": "WebSite",
      "name": "База знаний компании",
      "url": "https://support.example.com/help",
      "inLanguage": ["ru", "en"]
    }
  ]
}
</script>
```

:::tip
Поисковые системы показывают расширенные сниппеты не для всех типов разметки. Например, Google ограничил показ расширенных результатов для `FAQPage` и `HowTo`. Тем не менее такая разметка помогает поисковым системам и ИИ-сервисам понимать структуру статьи.
:::

## Свойства TechArticle

| Свойство | Значение |
| --- | --- |
| `headline` | Заголовок статьи, до 110 символов. |
| `description` | Краткое описание; можно взять из поля `seo_description`. |
| `inLanguage` | Язык статьи: `ru`, `en`. |
| `datePublished`, `dateModified` | Даты публикации и последнего изменения в формате ISO 8601. |
| `image` | Абсолютный адрес изображения из статьи. |
| `about`, `keywords` | Продукт или тема статьи, ключевые слова. |
| `author` | Автор статьи (`Person`) или компания (`Organization`). |

## Несколько объектов в одной статье

Чтобы описать несколько сущностей — например, статью и её «хлебные крошки», — используйте массив `@graph`:

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "TechArticle",
      "headline": "Как настроить SMTP канал для почты в Swarmica",
      "inLanguage": "ru"
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "База знаний", "item": "https://support.example.com/help" },
        { "@type": "ListItem", "position": 2, "name": "Настройка системы", "item": "https://support.example.com/category/1" }
      ]
    }
  ]
}
```

Пример разметки `FAQPage`:

```json
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Можно ли использовать для Telegram прокси кроме SOCKS5?",
      "acceptedAnswer": { "@type": "Answer", "text": "Нет, поддерживается только SOCKS5." }
    }
  ]
}
```

## Рекомендации

*   Разметка должна соответствовать видимому тексту статьи. Не добавляйте в неё вопросы, ответы и факты, которых нет на странице.
*   В JSON-LD указывайте абсолютные адреса — с протоколом и доменом.
*   Обновляйте `dateModified` при существенных изменениях статьи.
*   Заполняйте разметку для каждого языка статьи на языке этой локали.
*   После сохранения проверьте разметку одним из инструментов ниже.

## Инструменты проверки

*   [Schema Markup Validator](https://validator.schema.org/) — проверка разметки на соответствие словарю Schema.org.
*   [Проверка расширенных результатов Google](https://search.google.com/test/rich-results) — показывает, на какие расширенные сниппеты Google может претендовать страница.
*   [Валидатор микроразметки Яндекс Вебмастера](https://webmaster.yandex.ru/tools/microtest/) — проверка разметки для поиска Яндекса.

В инструменты можно передать адрес опубликованной статьи или вставить фрагмент кода.

## Связанные статьи

*   [Настройка SEO-полей статьи (Open Graph, JSON-LD)](https://support.swarmica.com/article/ru/2146)
*   [Использование ИИ-агентов для SEO/GEO/AEO-оптимизации базы знаний](https://support.swarmica.com/article/ru/2148)