Русский
Перейти
Язык
Перейти
Рецепты

Создать страницу

Опубликовать markdown-документ страницей в нужном разделе, убедиться, что она действительно открывается, обновить её на месте и поставить на своё место в дереве документации.

Markdown
Открыть в ИИ

Всё делает одна ручка: POST /pages/markdown создаёт страницу, если её нет, и обновляет, если она есть. Ответы ниже — настоящие: их получила английская версия этой самой страницы при публикации на тестовом сайте.

1. Написать документ

Страница — markdown-документ с YAML-шапкой (frontmatter). Обязательно только name; url ставит страницу в дерево (все сегменты, кроме последнего, уже должны существовать), lang задаёт язык и ограничивает поиск существующей страницы. Внешний вид задаёт frame: — оболочка, в которой страница печатается, например frame: article. Больше для вида ничего не нужно: template в v2 игнорируется, в ответ приходит предупреждение template_ignored.

---
name: "Create a page"
excerpt: "Publish a markdown document as a page in the right section."
slug: "sozdat-stranicu"
status: "draft"
url: "/docs/recepty/sozdat-stranicu/"
lang: "en"
frame: "obolochka-dokumentaciya"
---

## 1. Write the document

A page is a markdown document with YAML frontmatter.

H1 в тексте не пишите: заголовок из name печатает оболочка. Начинайте с ##. Всё, что понимает конвертер, описано в синтаксисе markdown, все поля шапки — на странице страницы и markdown.

2. Опубликовать черновиком

Тело запроса — просто {"markdown": "…"}, сайт задаётся полем blog_id или заголовком X-OnPress-Blog-Id. jq --rawfile сохраняет переводы строк файла как есть.

curl -s -X POST -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -H "X-OnPress-Blog-Id: 233" "$BASE/pages/markdown" \
  -d "$(jq -n --rawfile md page.md '{markdown: $md}')"
{
  "success": true,
  "updated": false,
  "id": 6351,
  "status": "draft",
  "lang": "en",
  "parent": 6349,
  "url": "/docs/recepty/sozdat-stranicu/",
  "link": null,
  "visible": false,
  "translations": { "en": 6351 },
  "frame": { "id": "af33214f168f8efd", "slug": "obolochka-dokumentaciya", "meta_key": "_onpress_frame" },
  "lang_changed": { "changed": true, "from": null, "to": "en" },
  "warnings": [
    "page is not published (status \"draft\"), the address does not serve it"
  ],
  "preview_url": "https://test.onpress.pro/?page_id=6351",
  "…": "…"
}

3. Прочитать ответ

Ответ — состояние страницы после записи, а не эхо запроса. На вопрос «получилось ли» отвечают четыре поля:

ПолеЧто говорит
updatedfalse — создана новая страница, true — перезаписана существующая
linkпубличный адрес; null, пока адреса нет (черновик, на проверке)
visibletrue, только если статус publish, над страницей нет неопубликованных предков и она действительно видна в своём языке
warningsвсё, что не так, но не уронило запрос, в том числе почему visible равно false

Сохраните id: впишите его в шапку строкой id: 6351, и каждая следующая публикация пойдёт прямо в эту страницу. Если вы прислали template, предупреждение template_ignored значит, что поле не применили вовсе: вид задаёт фрейм, а сайдбар — шаг 5.

4. Опубликовать и обновить на месте

Поменяйте status на publish, поправьте текст и отправьте тот же документ ещё раз. С id в шапке страница обновляется напрямую; без него она ищется по slug + lang (а url, если задан, сужает поиск до одной ветки дерева). В обоих случаях получится та же страница, теперь с updated: true.

{
  "success": true,
  "updated": true,
  "id": 6351,
  "status": "publish",
  "lang": "en",
  "parent": 6349,
  "url": "/docs/recepty/sozdat-stranicu/",
  "link": "https://test.onpress.pro/docs/recepty/sozdat-stranicu/",
  "visible": true,
  "translations": { "en": 6351 },
  "frame": { "id": "af33214f168f8efd", "slug": "obolochka-dokumentaciya", "meta_key": "_onpress_frame" },
  "warnings": [],
  "preview_url": null,
  "…": "…"
}

На многоязычном сайте всегда передавайте lang. Без него страница с тем же слагом на другом языке тоже считается совпадением и будет перезаписана; несколько совпадений без id — это 409 ambiguous_page со списком кандидатов, и ничего не пишется. Несуществующий сегмент url — 422 parent_not_found: сначала создайте родителя.

5. Поставить на место в дереве документации

Пункт сайдбара документации — это страница с метой _wp_page_template = templates/docs.php, по ней тема их и отбирает. v2 эту мету больше не пишет, поэтому только что опубликованную страницу в сайдбар ставит сам сайдбар:

curl -s -X POST -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  "$BASE/docs/sidebar/items/6351/show" -d '{"blog_id": 233}'

Странице, которая уже в сайдбаре, ничего этого не нужно: повторная публикация мету не трогает.

Новая страница встаёт среди соседей по menu_order. Порядок внутри одной ветки задаёт POST /docs/sidebar/reorder. Полная форма перечисляет порядок ветки; неназванные соседи идут следом за названными и возвращаются в appended.

curl -s -X POST -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  "$BASE/docs/sidebar/reorder" -d '{"blog_id": 233, "parent": 101, "order": [103, 102, 104]}'
{
  "success": true,
  "blog_id": 233,
  "parent": 101,
  "order": [103, 102, 104, 106],
  "appended": [106],
  "updated": 4,
  "notified": 4
}

Чтобы передвинуть одну страницу, отправьте {"id": 6351, "after": <сосед>}, либо before, либо position с отсчётом от нуля; тогда в ответе будут id, её новый menu_order и итоговый order. В другую ветку reorder не переносит: страница другого родителя в order — это 409 not_a_sibling. Смена родителя меняет адрес страницы, и со старого редиректа нет — подробнее в сайдбаре документации.

Проверка

link из последнего ответа отвечает 200 и показывает текст. visible равно true, warnings пуст. GET /docs/sidebar?blog_id=233&lang=en показывает страницу под её родителем. Повторная публикация того же файла возвращает updated: true и тот же id — никаких копий с -2.

См. также