Экспорт JSON для поиска
Соберите содержимое документации в JSON-файл для внешней поисковой системы. CLI формирует общий снимок страниц, независимый от провайдера поиска.
Включить экспорт
Добавьте флаг --search-index к команде сборки:
yfm build -i ./docs -o ./build --search-index
Результат записывается в файл ./build/_search/documents.json. По умолчанию экспорт выключен, дополнительные расширения не нужны.
Экспорт работает только для HTML-сборки без --watch. Флаг не зависит от настроек поиска: снимок можно создать и при выключенном поиске на сайте.
Формат JSON
Файл содержит версию формата schemaVersion и массив documents. Каждый элемент массива описывает одну страницу:
{
"schemaVersion": 1,
"documents": [
{
"id": "1f2fcdd0ccaac9f9a15f4a73a0d9c00fb787bac300f9959aeca48795d5bcc816",
"path": "en/guide.md",
"url": "en/guide.html",
"lang": "en",
"title": "Guide",
"content": "Hello world & friends.",
"headings": ["Guide"],
"keywords": ["help"],
"tags": ["guide"]
}
]
}
Все поля страницы присутствуют в JSON. Поля headings, keywords и tags содержат массивы строк и могут быть пустыми, остальные поля содержат строки.
| Поле | Значение |
|---|---|
id |
SHA-256 исходного пути path. Идентификатор сохраняется при изменении содержимого, но меняется при переименовании файла. |
path |
Путь исходного файла относительно корня проекта. Разделитель каталогов - /. |
url |
Ссылка на HTML-страницу относительно корня опубликованной документации. Учитывает флаг --skip-html-extension. |
lang |
Язык страницы. |
title |
Название страницы без HTML-разметки. |
content |
Обработанный текст страницы без навигации, HTML-разметки, скриптов и стилей. |
headings |
Название страницы и заголовки разделов без повторов. |
keywords |
Ключевые слова страницы. |
tags |
Публичные теги. Значения, начинающиеся с _, исключаются. |
Проверяйте schemaVersion перед обработкой файла. Домена в url нет: один снимок можно использовать для разных адресов публикации.
Содержимое и исключения
В JSON попадает текст после подстановки переменных, обработки условий и вставок. Экспорт отражает тот вариант документации, который выбран параметрами сборки.
Страницы с noIndex: true исключаются, в том числе если запрет задан для раздела в оглавлении. Скрытые страницы обрабатываются по правилам search.hiddenPolicy.
Для разводящей страницы без HTML-текста экспортируются название и описание из метаданных. Текст блоков такой страницы в content не включается.
Повторная сборка
Каждая сборка с --search-index заменяет снимок целиком. Документы отсортированы по исходному пути. Удалённые и исключённые страницы отсутствуют в новом файле; если подходящих страниц нет, массив documents пуст.
При ошибках обработки документации свежий снимок не записывается. Последующая HTML-сборка без --search-index удаляет ранее созданный снимок из выходного каталога. Одноимённый файл в исходной документации не заменяет результат экспорта.