DOCSTOOLS-6553: document audience-specific content

en/project/lint.md

@@ -72,6 +72,7 @@ log-levels:
   YFM020: 'warn'    # Invalid yfm directive
   YFM021: 'warn'    # Empty automatic heading anchor
   YFM022: 'info'    # llms-full.txt max size reached
+  YFM023: 'error'   # Invalid or missing visibility audience
 
 
 # Inline code length
@@ -85,6 +86,8 @@ A detailed description of all rules with the `YFM` prefix can be found [at the l
 
 YFM021 reports headings whose automatic anchor is empty. It relies on the anchors plugin from `@diplodoc/transform`; Diplodoc CLI and the VS Code extension include this plugin by default.
 
+YFM023 reports a missing or invalid audience in a `visibility` block. Supported values are `human` and `agent`.
+
 You can override the logging level in the `.yfmlint` file in the `log-levels` section separately for each rule: `error`, `warn`, `disabled`.
 
 {% note warning %}

en/syntax/audience.md

@@ -0,0 +1,32 @@
+# Audience-specific content
+
+Use `visibility` blocks to keep human-oriented explanations and instructions for AI agents in one Markdown source.
+
+Content outside a `visibility` block is common to both audiences. Use `human` for content shown only in the regular documentation and `agent` for content included only in machine-oriented representations:
+
+```markdown
+This paragraph is available to everyone.
+
+:::visibility human
+Use the button in the upper-right corner to create a project.
+:::
+
+:::visibility agent
+Create a project by sending `POST /projects` with the required fields.
+:::
+```
+
+The regular HTML, Markdown, and statically generated `llms-full.txt` output includes common and `human` content. When `llms-full.txt` is served by Docs Viewer, add `?audience=agent` to receive common and `agent` content. The Viewer defaults to the human variant. The directive markers themselves are not included in either result.
+
+Only the exact lowercase values `human` and `agent` are supported. YFM lint reports an invalid or missing value as an error, while rendering remains fail-closed and omits the invalid block.
+
+During localization, both variants are translated and the `visibility` markers are preserved.
+
+## Machine-readable representations
+
+A regular HTML page, its Markdown companion, and Viewer-served `llms-full.txt` use the human audience by default. Add `?audience=agent` to request the agent variant or `?audience=human` to select the human variant explicitly. If the opposite specific variant exists, a Markdown companion response includes an HTTP `Link` header with `rel="alternate"` and the URL of that variant.
+
+The JSON document API supports the audience parameter for both rendered and raw content, for example `?format=json&audience=agent` and `?format=json&content=raw&audience=agent`. The response contains:
+
+- `audience`: the audience applied to `content`.
+- `audienceSpecificContent`: the specific block types found in the article, in stable `human`, `agent` order. For example, `[]` means that there are no audience-specific blocks and `["human", "agent"]` means that both types are present.

en/toc.yaml

@@ -95,6 +95,8 @@ items:
             href: syntax/term.md
           - name: Content reuse
             href: syntax/includes.md
+          - name: Audience-specific content
+            href: syntax/audience.md
           - name: Additional features
             href: syntax/additional.md
       - name: Additional YFM features

ru/project/lint.md

@@ -72,6 +72,7 @@ log-levels:
   YFM020: 'warn'    # Invalid yfm directive
   YFM021: 'warn'    # Empty automatic heading anchor
   YFM022: 'info'    # llms-full.txt max size reached
+  YFM023: 'error'   # Invalid or missing visibility audience
 
 
 # Inline code length
@@ -85,6 +86,8 @@ YFM001:
 
 YFM021 сообщает о заголовках с пустым автоматическим якорем. Правило использует плагин anchors из `@diplodoc/transform`; Diplodoc CLI и расширение для VS Code подключают его по умолчанию.
 
+YFM023 сообщает об отсутствующей или некорректной аудитории в блоке `visibility`. Поддерживаются значения `human` и `agent`.
+
 Вы можете переопределить уровень логирования в файле `.yfmlint` в секции `log-levels` отдельно для каждого правила: `error`, `warn`, `disabled`.
 
 {% note warning %}

ru/syntax/audience.md

@@ -0,0 +1,32 @@
+# Контент для разных аудиторий
+
+Используйте блоки `visibility`, чтобы хранить в одном Markdown-источнике пояснения для людей и инструкции для AI-агентов.
+
+Контент вне блока `visibility` доступен обеим аудиториям. Значение `human` отмечает контент только для обычной документации, а `agent` — только для машиночитаемых представлений:
+
+```markdown
+Этот абзац доступен всем.
+
+:::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"]` — что присутствуют оба типа.

ru/toc.yaml

@@ -95,6 +95,8 @@ items:
             href: syntax/term.md
           - name: Переиспользование контента
             href: syntax/includes.md
+          - name: Контент для разных аудиторий
+            href: syntax/audience.md
           - name: Дополнительные возможности
             href: syntax/additional.md
       - name: Дополнительные возможности YFM