Контент для разных аудиторий

Используйте блоки visibility, чтобы хранить в одном Markdown-источнике пояснения для людей и инструкции для AI-агентов.

Контент вне блока visibility доступен обеим аудиториям. Значение human отмечает контент только для обычной документации, а agent — только для машиночитаемых представлений:

Этот абзац доступен всем.

:::visibility human
Чтобы создать проект, нажмите кнопку в правом верхнем углу.
:::

:::visibility agent
Чтобы создать проект, отправьте `POST /projects` с обязательными полями.
:::

В обычный HTML, Markdown и статически сгенерированный llms-full.txt попадают общий контент и блоки human. Когда llms-full.txt отдаётся через Docs Viewer, добавьте ?audience=agent, чтобы получить общий контент и блоки agent. По умолчанию Viewer возвращает человеческую версию. Сами маркеры директивы в результат не включаются.

Поддерживаются только точные значения human и agent в нижнем регистре. YFM-линтер считает отсутствующее или некорректное значение ошибкой, а рендеринг остаётся fail-closed и не выводит содержимое такого блока.

При локализации переводятся оба варианта, а маркеры visibility сохраняются.

Машиночитаемые представления

Обычная HTML-страница, её Markdown-компаньон и llms-full.txt, отданный через Viewer, по умолчанию возвращают контент для людей. Добавьте ?audience=agent, чтобы получить агентскую версию, или ?audience=human, чтобы выбрать человеческую версию явно. Если в статье есть специфичный контент для противоположной аудитории, ответ Markdown-компаньона содержит HTTP-заголовок Link с rel="alternate" и URL этой версии.

JSON API документа поддерживает параметр аудитории и для отрендеренного, и для исходного контента, например ?format=json&audience=agent и ?format=json&content=raw&audience=agent. Ответ содержит:

• audience — аудитория, применённая к полю content.
• audienceSpecificContent — типы специфичных блоков, найденных в статье, в стабильном порядке human, agent. Например, [] означает, что специфичных блоков нет, а ["human", "agent"] — что присутствуют оба типа.