Docsup 116404.diplodoc single source

ru/guides/single-source/index.md

@@ -0,0 +1,68 @@
+# Единый источник
+
+Единый источник — способ организации проекта, который позволяет получить несколько похожих версий документа из одного и того же исходного текста. Например, справки для разных платформ, языков или аудиторий.
+
+Это упрощает обновление проекта и снижает количество ошибок. Повторяющийся текст находится в одном месте, поэтому при обновлении не нужно искать и править все его вхождения.
+
+### Примеры 
+
+Пользователь мобильного приложения [Яндекс Почты](https://yandex.ru/support/yandex-360/customers/mail/ru/web/letter/create/letter-from-mobile?tabs=defaultTabsGroup-002l0bah_android) может найти в справке инструкции, адаптированные [под смартфон](https://yandex.ru/support/yandex-360/customers/mail/ru/web/letter/create/letter-from-mobile?tabs=defaultTabsGroup-002l0bah_android). В то же время пользователь [веб-версии](https://yandex.ru/support/yandex-360/customers/mail/ru/web/letter/create/write-letter) видит инструкции, учитывающие особенности работы с сервисом в браузере. При этом обе версии справки создаются на основе одного исходного текста.
+
+После установки [Яндекс Музыки](https://yandex.ru/support/music/ru/new-template/gettingstart) пользователь может обратиться к справке, чтобы разобраться с работой сервиса. Справка содержит понятные инструкции, адаптированные под [конкретную платформу](https://yandex.ru/support/music/ru/new-template/appmusic).
+
+## Методы работы с единым источником {#methods}
+
+[**Профилирование**](./profiling.md) используется для формирования нескольких похожих документов из одного документа-источника. Текст размечается с помощью [условных операторов](../../syntax/vars.md#conditions) или [переменных](../../syntax/vars.md). При сборке в каждый выходной документ подставляются только нужные фрагменты текста.
+
+  Способ применяется, если общего контента больше, чем уникального.
+
+  {% cut "Пример" %}
+
+  В [справке Яндекс Почты](https://yandex.ru/support/yandex-360/customers/mail/ru/) в одном исходном тексте содержатся инструкции по работе с сервисом. С помощью профилирования из этого текста формируются две версии справки: 
+  * для мобильного приложения включаются фрагменты, описывающие действия, специфичные для смартфона (например, действия для [написания письма](https://yandex.ru/support/yandex-360/customers/mail/ru/web/letter/create/letter-from-mobile?tabs=defaultTabsGroup-nrz4zeaf_android));
+  * для веб-версии включаются фрагменты, описывающие действия, специфичные для браузера (например, [добавление файлов](https://yandex.ru/support/yandex-360/customers/mail/ru/web/letter/attachments)).
+
+  {% endcut %}
+
+**Переиспользование** контента позволяет подставлять повторяющиеся фрагменты текста внутри одного или нескольких документов. 
+
+  Способ применяется, если уникального контента больше, чем общего.
+
+  Переиспользование обеспечивают:
+
+  * [Инклюды](../../syntax/includes.md) — отдельные файлы с текстом, ссылки на которые вставляются в нужном месте текста. При сборке текст из файла подставляется полностью.
+
+    {% cut "Пример" %}
+
+      В [справке Яндекс Музыки](https://yandex.ru/support/music/ru/) некоторые разделы содержат повторяющуюся информацию. Такие блоки оформляются в виде инклюдов и включаются в нужные места текста. Например, [Дополнительные преимущества в сервисах Яндекса](https://yandex.ru/support/music/ru/new-template/gettingstart) и [Что входит в подписку Плюса](https://yandex.ru/support/music/ru/access-and-account/why-is-paid). 
+
+    {% endcut %}
+
+  * [Пресеты переменных](../../project/presets.md) — набор переменных и их значений. При сборке документа в текст подставляется значение переменной в зависимости от условий сборки.
+
+    {% cut "Пример" %}
+
+      В [справке Яндекс Почты](https://yandex.ru/support/yandex-360/customers/mail/ru/) переменная `действие_с_письмом` может иметь разные значения: 
+      * для [мобильного приложения](https://yandex.ru/support/yandex-360/customers/mail/ru/web/letter/create/letter-from-mobile?tabs=defaultTabsGroup-08mm4747_android) — «Нажмите значок  в правом нижнем углу экрана»; 
+      * для [веб-версии](https://yandex.ru/support/yandex-360/customers/mail/ru/web/letter/create/write-letter) — «Чтобы создать новое письмо, в левом верхнем углу экрана нажмите „Написать“».
+
+    {% endcut %}
+
+  * [Вставки оглавлений](../../project/toc.md#includes) — блоки оглавления, которые вставляются в основное оглавление.
+
+    {% cut "Пример" %}
+
+      В [справке Яндекс Почты](https://yandex.ru/support/yandex-360/customers/mail/ru/) основная справка содержит несколько крупных разделов, например, [«Управление контактами»](https://yandex.ru/support/yandex-360/customers/mail/ru/web/abook), [«Настройка почтового ящика»](https://yandex.ru/support/yandex-360/customers/mail/ru/box-settings). Для каждого раздела создается свой блок оглавления, который включает подразделы и ключевые темы. С помощью вставок оглавлений эти блоки включаются в общее оглавление справки, что позволяет пользователям быстро находить нужные разделы и ориентироваться в большом объеме информации.
+
+    {% endcut %}
+
+## Особенности {#peculiaritys}
+
+* Каталоги с изображениями и инклюдами рекомендуется размещать в папках с названием `_assets` и `_includes` соответственно. Символ `_` означает, что папка не будет отображаться в итоговой сборке, но может быть использована как источник.
+
+* Внутри проекта с профилированием можно дополнительно использовать инклюды или пресеты переменных, поэтому способы можно комбинировать.
+
+* Если из одного документа-источника необходимо опубликовать несколько документов на разных доменах, рекомендуется настроить конфигурационные файлы для [профилирования](./profiling.md#configs). В случае переиспользования возможна публикация нескольких документов только на одном домене с разными URL.
+
+Для отладки документации с инклюдами или пресетами переменных, можно использовать локальную сборку YFM. 
+[Пример локальной сборки с переиспользованием](../../project/presets.md#reuse)

ru/guides/single-source/profiling.md

@@ -0,0 +1,169 @@
+# Профилирование
+
+Текст размечается с помощью [условных операторов](../../syntax/vars.md#conditions) или [переменных](../../syntax/vars.md). При сборке в каждый выходной документ подставляются только нужные фрагменты текста.
+
+## Организация проекта
+
+1. В корне проекта создайте папку `common` с исходными файлами.   
+
+1. В корне проекта создайте папки для каждой версии документа. Например, `android` и `ios` для разных платформ.
+
+1. В папках для версий документов настройте [конфигурационные файлы](#configs). 
+
+Пример организации структуры:
+
+```
+project_name
+├── common  # папка с файлами проекта
+│   ├── ru # языковая папка
+│   │   ├── index.md
+│   |   ├── presets.yaml
+│   |   └── toc.yaml
+|   └── en  # языковая папка
+│       ├── index.md
+│       ├── presets.yaml
+│       └── toc.yaml
+├── document_name_1  # Папка собираемого документа, например android, windows или tld-com
+│   ├── .yfm
+├── document_name_2
+│   ├── .yfm
+├── document_name_3
+|   ├── .yfm
+```
+
+## Шаг 1. Добавьте пресеты переменных {#prepare-conditions}
+
+Cоздайте [файл `presets.yaml`](../../project/presets.md). Общий файл располагается в корневой директории проекта и содержит все переменные для каждого условия профилирования.
+
+Значения переменных, которые установлены по умолчанию, поместите в пресет `default`. Он является обязательным.
+
+Уникальные значения поместите в отдельные пресеты для каждого условия профилирования.
+
+{% cut "Пример файла `presets.yaml` для разных платформ" %}
+
+``` yaml
+default: # набор значений по умолчанию
+  locale: ru
+  platform: browser
+
+ios: # набор значений для ios
+  platform: ios
+
+android: # набор значений для android
+  platform: android
+  ```
+
+{% endcut %}
+
+Обычно условия профилирования называют `product`, `platform`, `audience`, но можно использовать и любые другие имена, которые приняты в вашем проекте.
+
+#### Узнайте больше
+
+- [Как работать с переменными](../../syntax/vars.md)
+
+
+## Шаг 2. Разметьте текст документа {#set-conditions-text}
+
+Текст размечается с помощью [условных операторов](../../syntax/vars.md#conditions) или [переменных](../../syntax/vars.md).
+
+{% note warning %}
+
+Если текст размечен с помощью переменных, то в файле `presets.yaml` должны быть пресеты для каждого варианта профилирования. При сборке значения переменных берутся из пресета `default` и пресета, который указан в [конфигурационном файле `.yfm`](../../settings.md#config) в параметре `varsPreset`.
+
+{% endnote %}
+
+Условия для профилирования могут быть составными. Несколько условий объединяются с помощью операторов `or` или `and`.
+
+{% cut "Примеры разметки условными операторами" %}
+
+
+**Три фрагмента, которые отличаются для каждой платформы:**
+
+```
+{% if platform == "ios" %}
+Скачайте приложение в [App Store](https://www.apple.com/ios/app-store/).
+{% endif %}
+
+{% if platform == "android" %}
+Скачайте приложение в [Google Play](https://play.google.com).
+{% endif %}
+
+{% if platform == "browser" %}
+Откройте страницу в браузере.
+{% endif %}
+```
+
+**Фрагмент можно отнести к нескольким платформам:**
+
+```
+{% if platform == "ios" or platform == "android" %}
+Скачайте приложение.
+{% endif %}
+```
+
+**Фрагмент должен отображаться для определенной платформы и только в выбранном регионе:**
+
+```
+{% if platform == "browser" and locale == "ru" %}
+Откройте страницу example.ru.
+{% endif %}
+```
+
+{% endcut %}
+
+
+## Шаг 3. Разметьте оглавление документа {#set-conditions-toc}
+
+[Оглавление документа `toc.yaml`](../../project/toc.md) размечается при помощи условного оператора `when`:
+
+```
+when: условие == "значение"
+```
+
+{% cut "Примеры" %}
+
+**Две страницы, которые отображаются для разных платформ:**
+
+   ```yaml
+   - name: Обзор iOS
+     href: iOS-overview.md
+     when: platform == "ios"
+   - name: Обзор Android
+     href: android-overview.md
+     when: platform == "android"
+   ```
+
+**Одна страница отображается для нескольких платформ:**
+
+```yaml
+- name: Обзор
+  href: overview.md
+  when: platform == "ios" or platform == "android"
+```
+
+**Страница должна отображаться для определенной платформы и только в выбранном регионе:**
+
+```yaml
+- name: Обзор
+  href: overview.md
+  when: platform == "ios" and locale == "ru"
+```
+
+{% endcut %}
+
+[//]: # (TODO: вычитать раздел 4) 
+
+## Шаг 4. Настройте конфигурационные файлы {#configs}
+
+Конфигурационные файлы необходимы для правильной сборки и публикации проекта.
+
+### Файл `.yfm` {#yfm}
+
+В [конфигурационный файл `.yfm`](../../settings.md#config) добавьте следующие параметры сборки:
+
+```yaml
+apply-presets: true
+varsPreset: "имя-пресета"
+```
+
+В поле `varsPreset` укажите имя пресета из [шага 1](#prepare-conditions).

ru/project/presets.md

@@ -50,3 +50,18 @@ input-folder
 
 При сборке файла `faq.md` значения переменных из файла № 1 в приоритете над переменными из файла № 2.
 При сборке файла `quickstart.md` будут учитываться только значения переменных из файла № 2.
+
+## Пример локальной сборки с переиспользованием {#reuse}
+
+Чтобы собрать документ, выполните команду:
+
+```
+yfm -i ./<корневой каталог документа> -o ./<директория с итогом сборки> --varsPreset "<имя пресета>"
+```
+
+Если в вашем документе используются пресеты переменных, для каждого пресета сборку необходимо запускать отдельно.
+
+Если в документе пресетов переменных нет — флаг `--varsPreset` использовать не нужно. В этом случае документ соберется со значением пресетов `default`.
+
+В директории с итогом сборки появится одна папка с файлами в формате `.html` для выбранного пресета. Если запустить сборку с другими значениями в ту же директорию, файлы перезапишутся.
+

ru/toc.yaml

@@ -183,6 +183,11 @@ items:
         href: guides/content-analytics.md
       - name: Настройка личного домена
         href: personal-domain-ya-cloud.md
+      - name: Единый источник
+        href: guides/single-source/index.md
+        items:
+          - name: Профилирование
+            href: guides/single-source/profiling.md
       - name: Автогенерация и интеграция документации
         href: guides/includers.md
         items: