Frontmatter: все поля

Frontmatter — блок key: value между двумя строками --- в начале markdown. Он задаёт всё, кроме тела страницы: заголовок, адрес, язык, фрейм, SEO, служебные поля.

---
name: "Тарифы"
slug: "tarify"
url: "/company/tarify/"
lang: "ru"
status: "publish"
frame: "article"
excerpt: "Три тарифа и что в них входит."
seo_title: "Тарифы OnPress — цены и возможности"
seo_description: "Сколько стоит OnPress и что входит в каждый тариф."
keyword: "тарифы onpress"
topic: "Цены"
---

Формат

Разбор простейший, и это важно знать заранее:

одна строка — одно поле: ключ: значение. Списков и многострочных значений нет; единственная вложенная форма — ключи под data: (см. свои ключи);
всё после первого двоеточия — значение; двоеточия внутри значения допустимы;
кавычки вокруг значения (двойные или одинарные) снимаются; внутри кавычек можно писать что угодно, включая # и :;
строки, начинающиеся с #, — комментарии;
все значения — строки. Флаги принимают true, 1, yes, on (регистр не важен); всё остальное — ложь;
ключи чувствительны к регистру: Slug — это не slug, а незнакомый ключ.

Блок должен стоять в самом начале текста. Без него публикация создаст страницу без заголовка, слага, языка и фрейма — пишите frontmatter всегда.

Заголовок и адрес

Поле	Что делает
`name`	Заголовок страницы. Теги вырезаются. Синоним — `title` (`name` главнее). Из заголовка собирается слаг, если `slug` не указан
`slug`	Слаг — последний сегмент адреса. Приводится к виду WordPress: нижний регистр, транслитерация кириллицы, пробелы в дефисы. Уникален среди соседей одного языка: занятый получит суффикс `-2`, и ответ скажет об этом в `slug_changed`
`url`	Полный путь страницы: `/company/tarify/`. Все сегменты кроме последнего — существующие страницы-родители (иначе `422 parent_not_found`). Последний сегмент — сама страница, но её слаг берётся из `slug`, а не отсюда. Языковой префикс (`/ru/…`) распознаётся и отбрасывается. Схема и домен — `422 absolute_url_in_path`
`parent`	Id родителя числом, если `url` не указан; `0` — верхний уровень. При `url` игнорируется
`id`	Обновить именно эту страницу. Страница другого языка — `409 lang_mismatch`

Если не указаны ни url, ни parent, при создании страница встаёт на верхний уровень, а при обновлении остаётся там, где была.

Язык и переводы

Поле Что делает

lang Слаг языка сайта (ru, en). Не указан — язык сайта по умолчанию и предупреждение. Язык, которого на сайте нет, — 422 unknown_language со списком. На сайте без Polylang игнорируется с предупреждением

translation_of Оригинал, переводом которого является страница: id, слаг или путь (можно с языковым префиксом). Требует lang, отличный от языка оригинала. Страница вступает в группу переводов оригинала в той же транзакции, что и запись. Подробно — переводы

Поле	Что делает
`lang`	Слаг языка сайта (`ru`, `en`). Не указан — язык сайта по умолчанию и предупреждение. Язык, которого на сайте нет, — `422 unknown_language` со списком. На сайте без Polylang игнорируется с предупреждением
`translation_of`	Оригинал, переводом которого является страница: id, слаг или путь (можно с языковым префиксом). Требует `lang`, отличный от языка оригинала. Страница вступает в группу переводов оригинала в той же транзакции, что и запись. Подробно — переводы

Вид

Поле	Что делает
`frame`	Фрейм страницы: слаг или id, ровно один. Пустое значение снимает фрейм. Список в любой форме (`a, b`, `[a, b]`, `header=…`) — `400 frame_single`. Фрейма нет на этом сайте — `404 frame_not_found`. Поле `frame` в теле запроса перекрывает frontmatter
`template`	Игнорируется. Шаблонов темы в v2 нет, вид задаёт `frame`. Принимается, чтобы не ломать старые скрипты, и даёт предупреждение `template_ignored`

Без фрейма страница на сайте v2 отвечает 404 — ставьте frame в каждой публикации.

Статус и даты

Поле	Что делает
`status`	`publish` (по умолчанию), `draft`, `pending`, `private`, `future`. Любое другое значение — `400 invalid_status`
`date`	Дата публикации в местном времени сайта, `YYYY-MM-DD HH:MM:SS`. Вместе с `status: future` откладывает публикацию. Без `date` новая страница получает текущее время, существующая сохраняет свою дату

Текст вокруг страницы

Поле	Куда пишется
`excerpt`	Выдержка (`post_excerpt`): лид под заголовком, описание в списках. Указана — пишется, `""` — очищается, не указана — не трогается. Отдельно правится `PATCH /pages/{ref}`

SEO

Поле	Куда пишется
`seo_title`	Заголовок для поиска (`<title>`) — поле Yoast. Пишется, только если значение не пустое: очистить его через frontmatter нельзя
`seo_description`	Мета-описание — поле Yoast. То же правило пустого значения
`keyword`	Ключевая фраза Yoast. Заодно ложится обычным метаполем `keyword` (так ведёт себя и первая версия API)

SEO-настройки уровня сайта — шаблоны заголовков, разделитель, карта сайта — на странице SEO.

Служебные поля

Поле	Что делает
`topic`	Тема страницы — термин таксономии `topic`. Одно значение: `"SEO, контент"` станет одним термином с запятой в имени, а не двумя
`target`	Метаполе `_onpress_page_target`: страница, на которую эта должна ссылаться (для перелинковки). `""` или `"0"` удаляют
`anchor`	Метаполе `_onpress_page_anchor`: анкор этой ссылки. `""` или `"0"` удаляют
`max_publish_date`	Метаполе `max_publish_date` для своих сценариев. `""` или `"0"` удаляют
`domain`	Только сверка: если домен — другой сайт, чем выбран адресом запроса, — `409 domain_mismatch`. Сайт frontmatter не выбирает никогда
`type`	Только `page`. Любой другой тип — `501 post_type_not_supported`: v2 пишет только страницы
`category`	Игнорируется с предупреждением: у страниц нет рубрик

Флаги публикации

Принимаются и во frontmatter, и в теле запроса; frontmatter главнее.

Флаг	Что делает
`create_missing_parents`	Создать недостающих родителей из `url` пустыми черновиками. Созданные перечисляются в `created_stubs`. Черновик-родитель делает адрес потомка недоступным, пока его не опубликовать
`slug_lookup`	`false` — не искать существующую страницу по слагу; без `id` всегда создаётся новая
`link_soft`	Если `translation_of` не сработал (оригинала нет, у него нет языка, язык совпадает) — всё равно опубликовать страницу, без привязки. Ошибка придёт в `translation_link_error` и `warnings`

Свои ключи

Любой другой ключ пишется метаполем страницы с тем же именем, как есть:

---
name: "Статья"
slug: "statya"
reading_time: "7 минут"
---

Ответ предупредит: frontmatter keys the API does not know were stored as post meta as-is: reading_time — чтобы ошибку в имени документированного поля было видно. Такие ключи запоминаются и возвращаются в выгрузке GET /pages/{ref}/markdown в порядке последней публикации, поэтому круг «выгрузил — поправил — залил» их не теряет. Ключ, убранный из frontmatter, пропадает из выгрузки, но само метаполе остаётся — удалить его API не умеет. Пустое значение не пишется.

Часть своих ключей читает тема, и про них предупреждения нет:

Ключ	Что делает
`nav_label`	короткая подпись страницы в сайдбаре документации: страница «Frontmatter: все поля» показывается в дереве как «Frontmatter»
`header_visibility`, `footer_visibility`	`hide` прячет шапку или подвал оформления темы
`left_aside_type`, `left_aside_page`, `left_aside_menu`, `right_aside_type`	боковые колонки оформления темы
`pinned`	закреплённая заметка

Они пишутся метаполем и возвращаются в выгрузке, как все свои ключи.

Данные страницы для фреймов. Свой ключ можно записать в трёх равноправных формах:

---
rating: 5
data.rating: 5
data:
  rating: 5
---

Любая из них кладёт значение в одну мету rating (в одной публикации выберите одну форму). Форма с data. и вложенная под data: явно говорят, что это данные для вывода, — про них нет предупреждения о незнакомом ключе. Выгрузка возвращает ключ в той форме, в какой его записали; строковые значения берёт в кавычки, как все прочие ключи.

Во фрейме значение читается токеном page.data.rating (алиас page.meta.rating) — в data-op-bind, в match повторителя, во вставке onpress/value и в параметрах вызова фрейма. Отдаются только ключи, пришедшие из frontmatter публикацией; служебные с _ в начале наружу не уходят. Язык страницы читается токеном page.lang. Все токены — в биндах.

Ключи с подчёркиванием в начале — это служебная мета, и через frontmatter пишутся только два вида:

_thumbnail_id — изображение записи, которое выводит вставка onpress/featured-image: _thumbnail_id: 5829 (id вложения из медиатеки). Других способов поставить изображение записи в v2 нет;
_yoast_wpseo_* — постраничные поля Yoast, например _yoast_wpseo_meta-robots-noindex: "1" (закрыть страницу от индексации) или _yoast_wpseo_opengraph-image-id.

Они пишутся без предупреждения и не возвращаются в выгрузке — держите их в исходнике страницы. Любой другой ключ с подчёркиванием (_onpress_frame, _wp_page_template и прочие) не пишется: публикация проходит, а warnings называет пропущенные ключи. Фрейм ставится полем frame.

Что приходит в выгрузке

GET /pages/{ref}/markdown собирает frontmatter из записи в таком порядке: id, name, SEO-поля, keyword, topic, slug, date, status, url, lang, frame (всегда, даже пустым), target, anchor, excerpt, затем свои ключи. Пустые значения ключей не создают — иначе обратная заливка стёрла бы поля пустыми строками.

С ?as=translation_source вместо id приходит translation_of, а status не приходит: файл готов стать переводом после замены lang и текста.

Поля тела запроса

Помимо markdown тело POST /pages/markdown принимает:

Поле	Тип	Что делает
`frame`	string	фрейм страницы, перекрывает frontmatter
`blocks`	array	дополнительные блоки Гутенберга после тела: `core/`, блоки плагина `onpress/` или `{"type":"raw","content":"<!-- wp:… -->"}`; ACF-блоки — `501 acf_block_unsupported`; не массив — `400 blocks_invalid`
`create_missing_parents`, `link_soft`, `slug_lookup`	bool	те же флаги, frontmatter главнее
`faq_autodetect`	bool	собрать раздел `## FAQ` (и его аналоги на других языках) в блок плагина `wp:onpress/faq-items`; по умолчанию выключено. Для новых страниц используйте фрейм `faq` со слотом или вставку `onpress/faq` — см. рецепт FAQ
`faq_markers`	string[]	свои заголовки раздела FAQ для `faq_autodetect`
`template`	string	игнорируется, как и во frontmatter
`dry_run`	bool	не поддерживается: `400 dry_run_not_supported`