From 13c4f567dd2c4321221a89ae9a698056a54396cf Mon Sep 17 00:00:00 2001 From: Sergey Zolotonos Date: Tue, 8 Sep 2026 18:39:34 +0300 Subject: [PATCH 1/4] docs: describe audience-specific content DOCSTOOLS-6553 --- en/syntax/audience.md | 32 ++++++++++++++++++++++++++++++++ en/toc.yaml | 2 ++ ru/syntax/audience.md | 32 ++++++++++++++++++++++++++++++++ ru/toc.yaml | 2 ++ 4 files changed, 68 insertions(+) create mode 100644 en/syntax/audience.md create mode 100644 ru/syntax/audience.md diff --git a/en/syntax/audience.md b/en/syntax/audience.md new file mode 100644 index 00000000..96cf1b9c --- /dev/null +++ b/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 `humans` for content shown only in the regular documentation and `agents` for content included only in machine-oriented representations: + +```markdown +This paragraph is available to everyone. + +:::visibility humans +Use the button in the upper-right corner to create a project. +::: + +:::visibility agents +Create a project by sending `POST /projects` with the required fields. +::: +``` + +The regular HTML and Markdown output includes common and `humans` content. Agent-oriented output, such as `llms-full.txt`, includes common and `agents` content. The directive markers themselves are not included in either result. + +Only the exact lowercase values `humans` and `agents` are supported. An invalid or missing value is reported as an error and the block is omitted. + +During localization, both variants are translated and the `visibility` markers are preserved. + +## Machine-readable representations + +A Markdown companion uses 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, the response includes an HTTP `Link` header with `rel="alternate"` and the URL of that variant. + +For the JSON document API, combine agent selection with raw content: `?format=json&content=raw&audience=agent`. The response contains: + +- `audience`: 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. +- `contentAudience`: the audience applied to `content`. diff --git a/en/toc.yaml b/en/toc.yaml index 18502103..0d9e8d97 100644 --- a/en/toc.yaml +++ b/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 diff --git a/ru/syntax/audience.md b/ru/syntax/audience.md new file mode 100644 index 00000000..cbbc0ddd --- /dev/null +++ b/ru/syntax/audience.md @@ -0,0 +1,32 @@ +# Контент для разных аудиторий + +Используйте блоки `visibility`, чтобы хранить в одном Markdown-источнике пояснения для людей и инструкции для AI-агентов. + +Контент вне блока `visibility` доступен обеим аудиториям. Значение `humans` отмечает контент только для обычной документации, а `agents` — только для машиночитаемых представлений: + +```markdown +Этот абзац доступен всем. + +:::visibility humans +Чтобы создать проект, нажмите кнопку в правом верхнем углу. +::: + +:::visibility agents +Чтобы создать проект, отправьте `POST /projects` с обязательными полями. +::: +``` + +В обычный HTML и Markdown попадают общий контент и блоки `humans`. В представления для агентов, например `llms-full.txt`, попадают общий контент и блоки `agents`. Сами маркеры директивы в результат не включаются. + +Поддерживаются только точные значения `humans` и `agents` в нижнем регистре. Отсутствующее или некорректное значение считается ошибкой, а содержимое блока не выводится. + +При локализации переводятся оба варианта, а маркеры `visibility` сохраняются. + +## Машиночитаемые представления + +Markdown-компаньон по умолчанию возвращает контент для людей. Добавьте `?audience=agent`, чтобы получить агентскую версию, или `?audience=human`, чтобы выбрать человеческую версию явно. Если в статье есть специфичный контент для противоположной аудитории, ответ содержит HTTP-заголовок `Link` с `rel="alternate"` и URL этой версии. + +Для JSON API документа выбор агентской аудитории используется вместе с исходным контентом: `?format=json&content=raw&audience=agent`. Ответ содержит: + +- `audience` — типы специфичных блоков, найденных в статье, в стабильном порядке `human`, `agent`. Например, `[]` означает, что специфичных блоков нет, а `["human", "agent"]` — что присутствуют оба типа. +- `contentAudience` — аудитория, применённая к полю `content`. diff --git a/ru/toc.yaml b/ru/toc.yaml index c70bee27..30cc9150 100644 --- a/ru/toc.yaml +++ b/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 From 2987e0eac4b527d80ab216660ddf4f1f1cb3139c Mon Sep 17 00:00:00 2001 From: Sergey Zolotonos Date: Wed, 9 Sep 2026 18:25:04 +0300 Subject: [PATCH 2/4] docs: document singular visibility audiences --- en/project/lint.md | 3 +++ en/syntax/audience.md | 14 +++++++------- ru/project/lint.md | 3 +++ ru/syntax/audience.md | 14 +++++++------- 4 files changed, 20 insertions(+), 14 deletions(-) diff --git a/en/project/lint.md b/en/project/lint.md index 568e35f2..e520c9b6 100644 --- a/en/project/lint.md +++ b/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 %} diff --git a/en/syntax/audience.md b/en/syntax/audience.md index 96cf1b9c..0f1400d9 100644 --- a/en/syntax/audience.md +++ b/en/syntax/audience.md @@ -2,31 +2,31 @@ 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 `humans` for content shown only in the regular documentation and `agents` for content included only in machine-oriented representations: +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 humans +:::visibility human Use the button in the upper-right corner to create a project. ::: -:::visibility agents +:::visibility agent Create a project by sending `POST /projects` with the required fields. ::: ``` -The regular HTML and Markdown output includes common and `humans` content. Agent-oriented output, such as `llms-full.txt`, includes common and `agents` content. The directive markers themselves are not included in either result. +The regular HTML and Markdown output includes common and `human` content. Agent-oriented output, such as `llms-full.txt`, includes common and `agent` content. The directive markers themselves are not included in either result. -Only the exact lowercase values `humans` and `agents` are supported. An invalid or missing value is reported as an error and the block is omitted. +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 Markdown companion uses 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, the response includes an HTTP `Link` header with `rel="alternate"` and the URL of that variant. +A regular HTML page and its Markdown companion 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. -For the JSON document API, combine agent selection with raw content: `?format=json&content=raw&audience=agent`. The response contains: +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 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. - `contentAudience`: the audience applied to `content`. diff --git a/ru/project/lint.md b/ru/project/lint.md index c180321b..37ba8427 100644 --- a/ru/project/lint.md +++ b/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 %} diff --git a/ru/syntax/audience.md b/ru/syntax/audience.md index cbbc0ddd..922cc73b 100644 --- a/ru/syntax/audience.md +++ b/ru/syntax/audience.md @@ -2,31 +2,31 @@ Используйте блоки `visibility`, чтобы хранить в одном Markdown-источнике пояснения для людей и инструкции для AI-агентов. -Контент вне блока `visibility` доступен обеим аудиториям. Значение `humans` отмечает контент только для обычной документации, а `agents` — только для машиночитаемых представлений: +Контент вне блока `visibility` доступен обеим аудиториям. Значение `human` отмечает контент только для обычной документации, а `agent` — только для машиночитаемых представлений: ```markdown Этот абзац доступен всем. -:::visibility humans +:::visibility human Чтобы создать проект, нажмите кнопку в правом верхнем углу. ::: -:::visibility agents +:::visibility agent Чтобы создать проект, отправьте `POST /projects` с обязательными полями. ::: ``` -В обычный HTML и Markdown попадают общий контент и блоки `humans`. В представления для агентов, например `llms-full.txt`, попадают общий контент и блоки `agents`. Сами маркеры директивы в результат не включаются. +В обычный HTML и Markdown попадают общий контент и блоки `human`. В представления для агентов, например `llms-full.txt`, попадают общий контент и блоки `agent`. Сами маркеры директивы в результат не включаются. -Поддерживаются только точные значения `humans` и `agents` в нижнем регистре. Отсутствующее или некорректное значение считается ошибкой, а содержимое блока не выводится. +Поддерживаются только точные значения `human` и `agent` в нижнем регистре. YFM-линтер считает отсутствующее или некорректное значение ошибкой, а рендеринг остаётся fail-closed и не выводит содержимое такого блока. При локализации переводятся оба варианта, а маркеры `visibility` сохраняются. ## Машиночитаемые представления -Markdown-компаньон по умолчанию возвращает контент для людей. Добавьте `?audience=agent`, чтобы получить агентскую версию, или `?audience=human`, чтобы выбрать человеческую версию явно. Если в статье есть специфичный контент для противоположной аудитории, ответ содержит HTTP-заголовок `Link` с `rel="alternate"` и URL этой версии. +Обычная HTML-страница и её Markdown-компаньон по умолчанию возвращают контент для людей. Добавьте `?audience=agent`, чтобы получить агентскую версию, или `?audience=human`, чтобы выбрать человеческую версию явно. Если в статье есть специфичный контент для противоположной аудитории, ответ Markdown-компаньона содержит HTTP-заголовок `Link` с `rel="alternate"` и URL этой версии. -Для JSON API документа выбор агентской аудитории используется вместе с исходным контентом: `?format=json&content=raw&audience=agent`. Ответ содержит: +JSON API документа поддерживает параметр аудитории и для отрендеренного, и для исходного контента, например `?format=json&audience=agent` и `?format=json&content=raw&audience=agent`. Ответ содержит: - `audience` — типы специфичных блоков, найденных в статье, в стабильном порядке `human`, `agent`. Например, `[]` означает, что специфичных блоков нет, а `["human", "agent"]` — что присутствуют оба типа. - `contentAudience` — аудитория, применённая к полю `content`. From 5ee488cc73c43c6c1a7fb38c5dbd6b622689cb6e Mon Sep 17 00:00:00 2001 From: Sergey Zolotonos Date: Fri, 11 Sep 2026 11:44:05 +0300 Subject: [PATCH 3/4] docs: clarify audience response metadata DOCSTOOLS-6553 --- en/syntax/audience.md | 4 ++-- ru/syntax/audience.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/en/syntax/audience.md b/en/syntax/audience.md index 0f1400d9..8e83783d 100644 --- a/en/syntax/audience.md +++ b/en/syntax/audience.md @@ -28,5 +28,5 @@ A regular HTML page and its Markdown companion use the human audience by default 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 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. -- `contentAudience`: the audience applied to `content`. +- `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. diff --git a/ru/syntax/audience.md b/ru/syntax/audience.md index 922cc73b..c7e41c1e 100644 --- a/ru/syntax/audience.md +++ b/ru/syntax/audience.md @@ -28,5 +28,5 @@ JSON API документа поддерживает параметр аудитории и для отрендеренного, и для исходного контента, например `?format=json&audience=agent` и `?format=json&content=raw&audience=agent`. Ответ содержит: -- `audience` — типы специфичных блоков, найденных в статье, в стабильном порядке `human`, `agent`. Например, `[]` означает, что специфичных блоков нет, а `["human", "agent"]` — что присутствуют оба типа. -- `contentAudience` — аудитория, применённая к полю `content`. +- `audience` — аудитория, применённая к полю `content`. +- `audienceSpecificContent` — типы специфичных блоков, найденных в статье, в стабильном порядке `human`, `agent`. Например, `[]` означает, что специфичных блоков нет, а `["human", "agent"]` — что присутствуют оба типа. From a4ed5c80c6c6a640a4b51de557f7098f64e071de Mon Sep 17 00:00:00 2001 From: Sergey Zolotonos Date: Fri, 11 Sep 2026 12:07:15 +0300 Subject: [PATCH 4/4] docs: describe llms-full audience selection --- en/syntax/audience.md | 4 ++-- ru/syntax/audience.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/en/syntax/audience.md b/en/syntax/audience.md index 8e83783d..1fef2bd6 100644 --- a/en/syntax/audience.md +++ b/en/syntax/audience.md @@ -16,7 +16,7 @@ Create a project by sending `POST /projects` with the required fields. ::: ``` -The regular HTML and Markdown output includes common and `human` content. Agent-oriented output, such as `llms-full.txt`, includes common and `agent` content. The directive markers themselves are not included in either result. +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. @@ -24,7 +24,7 @@ During localization, both variants are translated and the `visibility` markers a ## Machine-readable representations -A regular HTML page and its Markdown companion 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. +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: diff --git a/ru/syntax/audience.md b/ru/syntax/audience.md index c7e41c1e..ca4054ed 100644 --- a/ru/syntax/audience.md +++ b/ru/syntax/audience.md @@ -16,7 +16,7 @@ ::: ``` -В обычный HTML и Markdown попадают общий контент и блоки `human`. В представления для агентов, например `llms-full.txt`, попадают общий контент и блоки `agent`. Сами маркеры директивы в результат не включаются. +В обычный HTML, Markdown и статически сгенерированный `llms-full.txt` попадают общий контент и блоки `human`. Когда `llms-full.txt` отдаётся через Docs Viewer, добавьте `?audience=agent`, чтобы получить общий контент и блоки `agent`. По умолчанию Viewer возвращает человеческую версию. Сами маркеры директивы в результат не включаются. Поддерживаются только точные значения `human` и `agent` в нижнем регистре. YFM-линтер считает отсутствующее или некорректное значение ошибкой, а рендеринг остаётся fail-closed и не выводит содержимое такого блока. @@ -24,7 +24,7 @@ ## Машиночитаемые представления -Обычная HTML-страница и её Markdown-компаньон по умолчанию возвращают контент для людей. Добавьте `?audience=agent`, чтобы получить агентскую версию, или `?audience=human`, чтобы выбрать человеческую версию явно. Если в статье есть специфичный контент для противоположной аудитории, ответ Markdown-компаньона содержит HTTP-заголовок `Link` с `rel="alternate"` и URL этой версии. +Обычная 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`. Ответ содержит: