Войти
Управление
Markdown
Открыть в ИИ

Сайдбар документации

Сайдбар документации — левое меню раздела документации. Его выводит фрейм docs, а меняется оно через один эндпоинт /docs/sidebar: он читает и пишет ровно то меню, которое видит посетитель, второго места, где оно хранится, нет.

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

Откуда берётся меню

Фрейм docs выводит сайдбар блоком onpress/repeat из пользовательских данных. В этой документации таких меню два: menu.docs — руководства, menu.api — справочник API. Меню — обычный список: группа с подписью и пунктами в items, у пункта title, url и вложенные пункты в children.

[
  { "title": "СУЩНОСТИ", "items": [
    { "title": "Фреймы", "url": "/docs/v2/ru/guides/frames/", "children": [
      { "title": "Блоки onpress/", "url": "/docs/v2/ru/guides/frames/inserts/" }
    ] }
  ] }
]

Имена меню, язык и названия ключей /docs/sidebar берёт из самого фрейма, поэтому на другом сайте меню может называться иначе — ответ GET его назовёт.

Меню не меняет страницы. Подпись пункта — не заголовок страницы, перенос пункта в другую группу не меняет адрес страницы, убранный пункт не снимает страницу с публикации. Статус страницы меняется через страницы.

Прочитать

Прочитайте меню запросом GET /docs/sidebar: в ответе menus — по меню на раздел с пунктами в items, а в broken — ссылки, которые ведут на удалённую или неопубликованную страницу. Например, справочник API:

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/docs/sidebar?menu=menu.api"

У каждого меню есть sha256 — версия. Передайте её в записи полем if_sha256, и запрос не затрёт правку, которую кто-то сделал после вашего чтения: ответ будет 409 sidebar_changed.

Добавить страницу

Новая страница в сайдбар сама не попадает. Опубликуйте её, затем добавьте пунктом запросом POST /docs/sidebar/items/{страница}/show. Например, страница «Коды ошибок» под пунктом «Ошибки и проблемы»:

curl -s -X POST "$API/site/$SITE/docs/sidebar/items/6300/show" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"parent": "/docs/v2/ru/guides/errors/", "title": "Коды ошибок"}'

Без parent пункт встанет под ближайший пункт, чей адрес — начало адреса страницы. Без title подписью станет заголовок страницы. Место среди соседей задают after, before или position.

Переставить

Задайте порядок пунктов одной ветки запросом POST /docs/sidebar/reorder: названные пункты встанут первыми, остальные — следом в прежнем порядке. Например, «Фреймы» перед «Страницами» в группе «СУЩНОСТИ»:

curl -s -X POST "$API/site/$SITE/docs/sidebar/reorder" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"parent": "СУЩНОСТИ", "order": ["/docs/v2/ru/guides/frames/"]}'

Пункт называется ссылкой, id страницы или, если это группа, подписью. Сдвинуть один пункт — {"id": "/docs/v2/ru/guides/frames/", "after": "/docs/v2/ru/guides/pages/"}.

Переименовать и перенести

Поменяйте подпись или ветку пункта запросом PATCH /docs/sidebar/items/{пункт}. Слеши в адресе пункта замените тильдами. Например, короткая подпись для страницы о блоках:

curl -s -X PATCH "$API/site/$SITE/docs/sidebar/items/docs~v2~ru~frames~inserts" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"title": "Блоки onpress/"}'

parent переносит пункт в другую группу или под другой пункт, url меняет, куда пункт ведёт. Заголовок и адрес самой страницы остаются прежними.

Убрать

Уберите пункт запросом POST /docs/sidebar/items/{пункт}/hide — вместе с его вложенными пунктами. Страница остаётся опубликованной и открывается по своему адресу. Например:

curl -s -X POST "$API/site/$SITE/docs/sidebar/items/docs~v2~ru~errors~codes/hide" \
  -H "Authorization: Bearer $OP_TOKEN"

Удалили страницу — уберите и пункт. Если забыли, GET /docs/sidebar покажет его в broken.

Положить меню целиком

Когда структура готова, отправьте всё меню одним запросом PUT /docs/sidebar — в той же форме, в какой его отдаёт GET. Чего нет в присланном списке, того не будет в сайдбаре. Сначала посмотрите разницу с dry_run:

curl -s -X PUT "$API/site/$SITE/docs/sidebar" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "menu": "menu.docs",
    "dry_run": true,
    "items": [
      { "title": "", "items": [
        { "title": "Быстрый старт", "url": "/docs/v2/ru/guides/quickstart/" },
        { "title": "Доступ и токен", "url": "/docs/v2/ru/guides/access/" }
      ] }
    ]
  }'

В ответе changes — что добавится, уберётся, переименуется и переедет, tree — меню после записи. Уберите dry_run, чтобы записать. Ссылка на несуществующую или неопубликованную страницу отменяет весь запрос: 409 sidebar_items_unresolved, ничего не записано.

dry_run принимают все записи сайдбара. menu указывать не обязательно: эндпоинт выберет меню по адресам пунктов, а если не сможет — ответит 409 sidebar_menu_ambiguous и перечислит меню.

Сайдбар из страниц

Системный фрейм docs на других сайтах выводит сайдбар блоком onpress/docs-nav — деревом страниц документации. Тогда /docs/sidebar работает со страницами: пункт — страница, вложенность — её родитель, подпись — nav_label страницы или заголовок. Ответ называет режим полем source: dataset — меню из данных, pages — дерево страниц.

В дереве страниц перенос пункта в другую ветку меняет адрес страницы, а старый адрес отвечает 301 на новый. Подробности — в справочнике.

Вопросы и ответы

Опубликовал страницу, а в сайдбаре её нет? Меню из данных само не пополняется: добавьте пункт через show.

Удалил страницу, а пункт остался? Уберите его через hide. Проверить меню целиком — GET /docs/sidebar, поле broken.

Можно ли поправить меню через /data? Да, PUT /data/menu.docs пишет то же меню. /docs/sidebar удобнее: он проверяет ссылки, называет пункты адресами и не затирает чужую правку.