Локальная проверка JSON-LD после сборки Astro

JSON-LD не делает статью полезнее и не гарантирует расширенный сниппет. Его задача скромнее: объяснить роботу, что именно находится на странице, какая дата относится к публикации и где лежит автор. Ошибка в структурированных данных обычно не видна читателю, поэтому проверять нужно не исходный компонент, а HTML, который получился после сборки Astro. Ниже — локальный процесс, который можно повторять перед каждым выпуском.

1. Соберите боевую копию страницы

Сначала выполните обычную сборку проекта и работайте с папкой результата. Не подставляйте адрес локального dev-сервера: в нём могут отсутствовать canonical, финальные даты и абсолютные ссылки. Выберите одну статью, одну новость и один материал с пошаговыми действиями, чтобы проверить разные типы сущностей.

В журнале запишите commit, дату сборки и URL каждой страницы. Если сайт использует завершающий слеш, он должен одинаково появиться в canonical, url внутри JSON-LD и sitemap. Несовпадение адресов часто обнаруживается только после деплоя.

2. Найдите и разберите блоки JSON-LD

Локальный скрипт должен искать в готовом HTML все элементы <script type="application/ld+json">, очищать их содержимое от лишних пробелов и пытаться разобрать как обычный JSON. Синтаксическая ошибка — безусловный стоп-релиз: робот может проигнорировать весь блок, а браузер при этом продолжит выглядеть нормально.

После разбора выведите список типов (Article, NewsArticle, HowTo, FAQPage, BreadcrumbList) и количество сущностей. Если одна статья неожиданно содержит два разных Article, найдите источник дублирования в layout и компоненте страницы. Не исправляйте проблему удалением случайного блока, пока не понятно, какой компонент владеет данными.

3. Сверьте видимый текст и метаданные

Для каждой сущности сравните с тем, что видит человек:

• headline совпадает с H1, а не с внутренним именем файла;
• datePublished и dateModified соответствуют видимой дате и часовому поясу;
• автор, издатель и изображение действительно присутствуют на странице;
• url и mainEntityOfPage ведут на один опубликованный адрес;
• описание не обещает того, чего нет в тексте.

Полезная проверка — изменить дату в frontmatter на тестовом коммите, пересобрать проект и убедиться, что она изменилась одновременно в карточке, meta-теге, Open Graph и JSON-LD. Верните рабочую дату после проверки и не оставляйте тестовый timestamp в репозитории.

4. Проверьте тип страницы

Article подходит для обычного авторского материала. NewsArticle используйте только для новости с действительно свежим событием и датой, которую можно подтвердить. Старый текст не становится новостью из-за изменения dateModified.

HowTo допустим, когда на странице видны реальные последовательные шаги. Каждый HowToStep должен иметь действие, а не декоративный заголовок. Если часть инструкции спрятана в аккордеоне и недоступна без клика, проверьте, как она отображается в HTML и не расходится ли со схемой.

FAQPage добавляйте только для видимых вопросов и ответов. Не включайте в JSON-LD обещания выигрыша, медицинские назначения или финансовые гарантии, которых нет в редакционном тексте. Если блок FAQ удалили из интерфейса, удалите и соответствующую сущность.

5. Проверьте хлебные крошки и связи

BreadcrumbList должен повторять фактический путь: главная, рубрика, материал. Номер позиции начинается с единицы и не должен перескакивать. Если на странице несколько сущностей, объединяйте их через @graph и связывайте с одним WebPage или Article, а не копируйте одинаковые поля в каждом блоке.

Проверьте также canonical, Open Graph, Twitter-карточку и sitemap. Локальный валидатор может подтвердить правильный JSON, но только HTTP-запрос показывает, что опубликованный адрес отдаёт именно этот HTML, без редиректа на тестовый домен.

6. Негативные тесты

Намеренно создайте четыре временные ошибки в копии: удалите запятую, замените дату на неверный формат, укажите отсутствующий URL и добавьте шаг, которого нет на странице. Скрипт должен обнаружить каждую ошибку и завершиться с ненулевым кодом. Затем верните корректные значения и повторите сборку. Такой тест показывает, что проверка действительно блокирует выпуск, а не просто печатает красивый отчёт.

Проверка	Ожидаемый результат	Действие при сбое
JSON-синтаксис	все блоки разбираются	остановить сборку
Тип сущности	соответствует формату страницы	исправить schema type
Даты и заголовки	совпадают с видимым текстом	обновить источник данных
URL	абсолютный боевой адрес	убрать localhost и query
HowTo/FAQ	все элементы видимы	убрать лишние пункты

Отчёт, который можно быстро разобрать

Валидатор полезен только тогда, когда по его выводу понятно, что исправлять. Для каждой страницы сохраняйте короткий отчёт: URL, типы сущностей, найденные ошибки, расхождения дат и ссылку на строку HTML. Разделяйте ошибки, предупреждения и информационные сообщения. Предупреждение о возможном сниппете не должно выглядеть так же, как сломанный JSON-синтаксис.

Добавьте сравнение с предыдущей сборкой. Если изменилась только дата, отчёт должен показать именно это; внезапное исчезновение BreadcrumbList или FAQPage требует остановки. Не сравнивайте HTML целиком: хэши скриптов, порядок атрибутов и служебные метки могут меняться без влияния на разметку. Сравнивайте нормализованный набор полей, которые важны роботу и редактору.

Перед выпуском попросите другого участника команды открыть отчёт и найти причину специально внесённой ошибки. Если он видит лишь красную строку без контекста, инструмент не помогает процессу. Укажите рядом ожидаемое исправление и владельца шага: frontmatter, шаблон страницы или генератор sitemap. После исправления отчёт должен исчезнуть из очереди, а не быть отмечен как «прочитанный».

7. Свяжите проверку с выпуском

Запускайте валидатор после npm run build, но до деплоя. После публикации повторите короткую HTTP-проверку одной новой страницы и сравните её с локальным HTML. Только если адрес отвечает корректно, обновился sitemap и дата совпадает, отправляйте URL в IndexNow. Сам по себе JSON-LD не заменяет проверку текста, ссылок и фактов.

Ограничения и ответственность

Локальный инструмент знает только ваши правила и базовую структуру schema.org. Он не решает, полезна ли статья, достоверна ли новость и заслуживает ли страница расширенного результата. Поисковая система может не показать сниппет даже при идеальной разметке. Поэтому разметка — последний технический слой после редакторской проверки, внутренних ссылок и теста опубликованного URL.

Итоговый порядок прост: собрать результат, найти JSON-LD, разобрать синтаксис, сопоставить сущности с видимым текстом, проверить URL и даты, затем открыть страницу по HTTP. Повторяемый локальный тест превращает разметку из ручной догадки в контролируемую часть выпуска.