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, при создании страница встаёт на верхний уровень, а при обновлении остаётся там, где была.

Ключа redirect у страницы нет: редирект — правило сайта, а не поле страницы, см. Редиректы. Присланный ключ не записывается, ответ публикации несёт предупреждение.

Сменили у опубликованной страницы slug или родителя в url (публикация с id) — старый адрес не пропадает: правило 301 на новый заводится само, для страницы и каждого её опубликованного потомка, а ответ перечисляет их в redirects_created. Подробно и как это выключить — автоправила. Смена lang у существующей страницы через публикацию не делается (409 lang_mismatch).

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

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

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; синонимы published, pending_review, scheduled. Любое другое значение — 400 invalid_status. publish или future с датой впереди сохраняется как future — страница запланирована и выйдет сама; future с прошедшей датой — publish. Снять планирование — сохранить страницу со status: draft

date Дата публикации: местное время сайта 2026-10-05 09:00 (секунды и T вместо пробела допустимы) или точный момент — ISO 8601 с Z или смещением (2026-10-05T06:00:00Z, …+03:00), либо unix-секунды. Дата впереди откладывает публикацию, см. отложенная публикация. Без date новая страница получает текущее время, существующая сохраняет свою дату. Не дата — 400 invalid_date

Поле	Что делает
`status`	`publish` (по умолчанию), `draft`, `pending`, `private`, `future`; синонимы `published`, `pending_review`, `scheduled`. Любое другое значение — `400 invalid_status`. `publish` или `future` с датой впереди сохраняется как `future` — страница запланирована и выйдет сама; `future` с прошедшей датой — `publish`. Снять планирование — сохранить страницу со `status: draft`
`date`	Дата публикации: местное время сайта `2026-10-05 09:00` (секунды и `T` вместо пробела допустимы) или точный момент — ISO 8601 с `Z` или смещением (`2026-10-05T06:00:00Z`, `…+03:00`), либо unix-секунды. Дата впереди откладывает публикацию, см. отложенная публикация. Без `date` новая страница получает текущее время, существующая сохраняет свою дату. Не дата — `400 invalid_date`

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

Поле	Куда пишется
`excerpt`	Выдержка (`post_excerpt`): лид под заголовком, описание в списках. Указана — пишется, `""` — очищается, не указана — не трогается. Отдельно правится `PATCH /pages/{ref}`
`image`	Превью страницы: номер вложения из медиатеки или адрес картинки. Своя картинка узнаётся по адресу без скачивания, чужая заливается в медиатеку, повтор того же адреса берёт то же вложение. `""` — снимает превью, нет ключа — не трогает. Превью становится og:image страницы, обложкой во вставке `onpress/featured-image` и картинкой в карточках дочерних страниц. Отдельно правится `PATCH /pages/{ref}` полем `thumbnail`. Отказы — `400 image_invalid`, `404 image_not_found`, `422 image_not_image`
`howto`	Пошаговая разметка HowTo: `auto` (по умолчанию — узел появляется, если в тексте есть инструкция: подзаголовки «Шаг 1…» подряд или нумерованный список от трёх пунктов под подзаголовком со словом «как», «шаг», «how to», «step»), `on` — всегда, от двух шагов, `off` — никогда. `true`/`yes`/`1` — `on`, `false`/`no`/`0`/`none` — `off`. Нет ключа — режим не меняется. Отдельно правится `PATCH /pages/{ref}` полем `howto`. Другое значение — `400 howto_invalid`

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. Все токены — в биндах.

Общий CTA: cta: 1. На сайтах с общим блоком призыва к действию (фрейм site__cta в подвале, набор cta с текстами) блок выводится только на страницах с cta: 1 во frontmatter; без ключа его нет. Фрейм сравнивает значение со строкой 1, поэтому cta: true или cta: yes блок не включат. Снять блок — убрать ключ или поставить cta: 0. Ключ свой, поэтому cta: 1 даёт предупреждение о незнакомом ключе — это нормально; форма data.cta: 1 пишет то же и без предупреждения.

---
name: "Тарифы"
url: "/pricing/"
frame: "pricing"
cta: 1
---

Подпись автора в статье: author: 1. На страницах с фреймом article под заголовком выводится подпись автора из набора author (аватар, имя со ссылкой, роль), а в разметку страницы добавляется автор статьи — только при author: 1; без ключа подписи и автора в разметке нет. Правило то же, что у cta: значение сравнивается со строкой 1, снять — убрать ключ или поставить author: 0. Ключ описанный, предупреждения о незнакомом ключе у него нет. Подробно — фрейм article.

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

_thumbnail_id — старый способ поставить превью номером вложения: _thumbnail_id: 5829. Пишите вместо него image — он принимает и адрес и возвращается в выгрузке; если в одной публикации есть оба, главнее image;
_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, image (адрес файла превью), затем свои ключи. Пустые значения ключей не создают — иначе обратная заливка стёрла бы поля пустыми строками.

С ?as=translation_source вместо id приходит translation_of, а status не приходит: файл готов стать переводом после замены lang и текста. В том же виде frontmatter лежит в поле markdown JSON для перевода — вместе с наборами данных страницы.

Публичная markdown-копия страницы по адресу с .md — другое: frontmatter в ней нет, только заголовок, выдержка и текст.

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

Помимо 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`