Раздел документации

Результат: раздел /docs/ с левым деревом страниц (поиск, раскрытие, мобильная шторка), правым оглавлением, ссылками «назад — вперёд» и кнопкой Copy с «Explore with AI». Ровно так устроена документация, которую вы читаете.

1. Фрейм docs

Дерево документации строится из страниц, собираемых фреймом документации сайта. Платформа находит его по слагу docs (или по опции сайта onpress_docs_frame, которую API не правит) — назовите фрейм именно так. Раздел документации на сайте один: onpress/docs-nav в любом фрейме показывает страницы фрейма docs, а не страницы своего фрейма.

docs.html:

<div class="opdoc__layout">
  <!-- onpress/docs-nav {"shell":"drawer"} /-->

  <header class="opdoc__navbar">
    <!-- frame/site__header /-->
    <!-- onpress/docs-nav {"shell":"toggle"} /-->
  </header>

  <div class="opdoc__shell">
    <!-- onpress/docs-nav {"shell":"sidebar"} /-->

    <div class="opdoc__main">
      <div class="opdoc__content">
        <header class="opdoc__header">
          <a class="opdoc__eyebrow" data-op-bind='{"text":"page.parent_title","href":"page.parent_url"}'></a>
          <h1 class="opdoc__title" data-op-bind='{"text":"page.title"}'></h1>
          <div class="opdoc__actions"><!-- onpress/share-ai {"view":"docs"} /--></div>
        </header>

        <div class="opdoc__body"><!-- onpress/content /--></div>

        <!-- onpress/pager /-->
      </div>

      <div class="opdoc__aside"><!-- onpress/outline {"levels":"2-3"} /--></div>
    </div>
  </div>

  <!-- frame/site__footer /-->
</div>

Что здесь что:

onpress/docs-nav трижды — мобильная шторка, кнопка её открытия и боковая колонка; дерево одно и то же, обвязка разная;
заголовок страницы выводит фрейм (page.title), поэтому в теле страниц #-заголовок не пишется;
над заголовком — ссылка на родителя (page.parent_title), у страниц верхнего уровня её нет;
onpress/outline {"levels":"2-3"} — оглавление по H2 и H3;
onpress/pager — предыдущая и следующая страница в порядке дерева;
site__header и site__footer — общие шапка и подвал сайта (см. сайт с нуля); если их нет, уберите эти блоки.

curl -s -X POST "$API/site/$SITE/frames" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d "$(jq -n --rawfile html docs.html '{slug: "docs", html: $html}')" \
  | jq -c '{slug: .frame.slug, renders_on_request, live_reasons, warnings}'

Фрейм зависит от страницы (onpress/content, onpress/docs-nav и остальные) — страницы документации всегда собираются на запросе, статических копий у них нет. Классы opdoc__* — классы шаблона документации темы: на сайте с темой v2 они уже оформлены; свою вёрстку допишите в собственный CSS.

2. Корень раздела

docs.md:

---
name: "Документация"
slug: "docs"
url: "/docs/"
lang: "ru"
frame: "docs"
nav_label: "Документация"
excerpt: "Всё о продукте: от первого запуска до справочника."
---

Здесь собрано всё, что нужно для работы.

## Разделы

- [Быстрый старт](/docs/bystryj-start/)
- [Настройка](/docs/nastrojka/)

3. Страницы раздела

Каждая страница — markdown с тем же фреймом и родителем /docs/. Длинные заголовки сокращайте в дереве ключом nav_label:

bystryj-start.md:

---
name: "Быстрый старт: первые десять минут"
slug: "bystryj-start"
url: "/docs/bystryj-start/"
lang: "ru"
frame: "docs"
nav_label: "Быстрый старт"
excerpt: "Что сделать в первые десять минут."
---

Первый абзац.

## Установка

Текст раздела.

## Первый запуск

Текст раздела.

nastrojka.md — по тому же образцу с slug: "nastrojka", url: "/docs/nastrojka/".

Публикуйте сначала корень, потом детей: родитель должен существовать, иначе 422 parent_not_found.

for p in docs bystryj-start nastrojka; do
  curl -s -X POST "$API/site/$SITE/pages/markdown" \
    -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
    -d "$(jq -n --rawfile md "$p.md" '{markdown: $md}')" \
    | jq -c '{id, url, how: .printed.how, warnings}'
done

nav_label — свой ключ страницы: API сохраняет его в данные страницы, дерево читает его оттуда, а ответ публикации называет его в data_keys (свои ключи).

4. Порядок в дереве

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

DOCS=$(curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/pages/docs?markdown=false" | jq .page.id)
curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/docs/sidebar?lang=ru" \
  | jq --argjson p "$DOCS" '.tree[] | select(.id == $p) | [.children[] | {id, title}]'

curl -s -X POST "$API/site/$SITE/docs/sidebar/reorder" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d "{\"parent\": $DOCS, \"order\": [\"nastrojka\", \"bystryj-start\"]}" | jq -c '{order, appended}'

Пункты в order — id, слаги или пути. Подробно — сайдбар документации.

5. Проверка

DOMAIN=$(curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/settings" | jq -r .settings.domain)
for u in /docs/ /docs/bystryj-start/ /docs/nastrojka/; do
  printf '%s %s\n' "$(curl -s -o /dev/null -w '%{http_code}' "https://$DOMAIN$u")" "$u"
done
curl -s "https://$DOMAIN/docs/bystryj-start/" | grep -o 'id="[a-z-]*"' | head

Все три адреса — 200. У заголовков H2 появились якоря (id="ustanovka", id="pervyj-zapusk"), на них ведёт оглавление. Если адрес на многоязычном сайте с языком не по умолчанию — он начинается с префикса языка (/ru/docs/), берите его из поля link ответа публикации.

Дальше

Разделы и подразделы — страницы с детьми: дерево раскрывает активную ветку.
Черновики (status: draft) видны в дереве только вошедшим редакторам — удобно готовить страницы заранее.
Спрятать пункт, не снимая страницу: POST /docs/sidebar/items/{ref}/hide.
Перенос страницы в другую ветку — рецепт переноса.