Docsup 116404.diplodoc single source

ru/guides/single-source/build.md

@@ -0,0 +1,37 @@
+# Локальная сборка YFM с переиспользованием
+
+Для отладки документации с инклюдами или пресетами переменных, можно использовать локальную сборку YFM.
+
+{% note warning %}
+
+В локальной сборке YFM не отображаются дополнительные возможности из npm (plantuml, LaTeX, вставка кода из файла, graphviz);
+
+
+{% endnote %}
+
+## Перед началом {#setup}
+
+1. [Установите Node.js](https://nodejs.org/ru/download/). Одновременно установится менеджер пакетов `npm`: он понадобится для работы локальной сборки.
+
+1. [Установите yfm-docs](https://diplodoc.com/docs/ru/tools/docs/).
+
+1. Проверьте, что yfm-docs установлен правильно. Например, посмотрите номер версии:
+
+   ```
+   yfm --version
+   ```
+
+## Запуск сборки {#run-build}
+
+
+Чтобы собрать документ, выполните команду:
+
+```
+yfm -i ./<корневой каталог документа> -o ./<директория с итогом сборки> --varsPreset "<имя пресета>"
+```
+
+Если в вашем документе используются пресеты переменных, для каждого пресета сборку необходимо запускать отдельно.
+
+Если в документе пресетов переменных нет — флаг `--varsPreset` использовать не нужно. В этом случае документ соберется со значением пресетов `default`.
+
+В директории с итогом сборки появится одна папка с файлами в формате `.html` для выбранного пресета. Если запустить сборку с другими значениями в ту же директорию, файлы перезапишутся.

ru/guides/single-source/ei.md

@@ -0,0 +1,75 @@
+# Единый источник
+
+Единый источник — это способ организации проекта, который позволяет получить несколько похожих версий документа из одного и того же исходного текста. Например, справки для разных платформ, языков или аудиторий.
+
+Единый источник упрощает обновление проекта и снижает количество ошибок. Повторяющийся текст находится в одном месте, поэтому при обновлении не нужно искать и править все его вхождения.
+
+### Примеры 
+
+* [Справка Яндекс Почты](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)
+
+После установки Яндекс Музыки пользователь может обратиться к справке, чтобы разобраться с работой сервиса. Справка содержит понятные инструкции, адаптированные под конкретную платформу. Например, [Xiaomi GetApps](https://global.app.mi.com/details?lo=RU&la=ru&id=ru.yandex.music) или [компьютер](https://music.yandex.ru/download/).
+
+* [Справка Кинопоиска](https://yandex.ru/support/kinopoisk/ru/authorization/get-started)
+
+При просмотре фильма пользователь может выбирать аудиодорожку на нужном ему языке:
+
+![Audio track](../../_images/audio-track.png){width=400}
+
+## Методы работы с единым источником {#methods}
+
+* [**Профилирование**](./profiling.md) используется для формирования нескольких похожих документов из одного документа-источника. Текст размечается с помощью [условных операторов](https://diplodoc.com/docs/ru/syntax/vars#conditions) или [переменных](https://diplodoc.com/docs/ru/syntax/vars). При сборке в каждый выходной документ подставляются только нужные фрагменты текста.
+
+  Способ применяется, если общего контента больше, чем уникального.
+
+  {% 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 %}
+
+* **Переиспользование** контента позволяет подставлять повторяющиеся фрагменты текста внутри одного или нескольких документов. 
+
+    Способ применяется, если уникального контента больше, чем общего. 
+
+    Переиспользование обеспечивают:
+
+    * [Инклюды](./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 %}
+
+    * [Пресеты переменных](./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 %}
+
+    * [Вставки оглавлений](toc_includes.md) — блоки оглавления, которые вставляются в основное оглавление.
+
+      {% 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.

ru/guides/single-source/includes.md

@@ -0,0 +1,49 @@
+# Инклюды
+
+Вы можете вынести повторяющийся контент в отдельный файл и использовать его внутри документационного проекта в качестве страницы, раздела, абзаца или элемента списка.
+
+Переиспользование поможет сократить время работы с текстом: контент хранится в одном месте, а изменения применяются ко всему проекту.
+
+
+## Порядок переиспользования {#steps}
+
+1. Создайте каталог для хранения повторяющегося контента. Инклюды принято размещать в папке `_includes`.
+
+   {% note warning %}
+
+   Файлы для переиспользования должны храниться в каталоге, имя которого начинается с символа `_`.
+
+   {% endnote %}
+
+1. В каталоге `_includes` создайте md-файл с повторяющимся текстом.
+
+1. В файл документа добавьте ссылку на md-файл в место, которое предназначено для вставки:
+
+
+    ```markdown
+    {% include [Описание](../../_includes/file.md) %}
+    ```
+    Если заголовок файла не нужно подставлять, добавьте ключевое слово `notitle`:
+
+    ```markdown
+    {% include notitle [Описание](../../_includes/file.md) %}
+    ```
+
+    Чтобы подставить только один раздел из файла, добавьте к ссылке [якорь на заголовок](https://diplodoc.com/docs/ru/syntax/base#headers) соответствующего раздела:
+
+    ```markdown
+    {% include notitle [Описание](../../_includes/file.md#anchor) %}
+    ```
+
+    * `[Описание]` — описание файла. Информация для авторов документа, не влияет на сборку.
+    * `(../../_includes/file.md)` — путь к файлу.
+
+   {% note info %}
+
+   Если подставляете раздел или абзац, отделите инклюд от основного текста пустой строкой сверху и снизу.
+
+   Подставить одно или несколько предложений как часть абзаца нельзя.
+
+   {% endnote %}
+
+Переиспользованный контент появится при сборке. Относительные ссылки в нем будут перестроены.

ru/guides/single-source/presets.md

@@ -0,0 +1,58 @@
+# Пресеты переменных
+
+Пресеты — это наборы переменных, которые позволяют переиспользовать повторяющийся контент и поддерживать несколько вариантов документации из одних и тех же исходных файлов.
+
+Пресеты объявляются в файле `presets.yaml`. Пресет `default` обязателен и содержит значения переменных по умолчанию. Переменные указываются в формате `<имя_переменной>: <значение>`.
+
+{% cut "Пример файла `presets.yaml`" %}
+
+```yaml
+default: # набор значений по умолчанию
+  locale: ru
+  platform: browser
+
+ios: # набор значений для ios
+  platform: ios
+
+android: # набор значений для android
+  platform: android
+```
+
+{% endcut %}
+
+{% note info %}
+
+Файлов `presets.yaml` может быть несколько. Они будут учитываться в порядке уменьшения приоритета: от ближайшего к текущему файлу до самого близкого к корню проекта.
+
+{% cut "Пример" %}
+
+```
+input-folder
+|-- .yfm
+|-- toc.yaml
+|-- presets.yaml // 2
+|-- index.yaml
+|-- quickstart.md
+|-- pages
+    |-- presets.yaml // 1
+    |-- faq.md
+    |-- how-to.md
+```
+
+-  При сборке файла `faq.md` значения переменных из файла `presets.yaml` № 1 в приоритете над переменными из файла № 2.
+
+-  При сборке файла `quickstart.md` будут учитываться только значения переменных из файла `presets.yaml` № 2.
+
+{% endcut %}
+
+{% endnote %}
+
+Для простого переиспользования без профилирования все переменные указываются в пресете `default`.
+
+В случае использования переменных для [профилирования текста](./profiling.md) в файле `presets.yaml` укажите пресеты для каждого варианта профилирования. При сборке значения переменных берутся из пресета `default` или пресета, который указан в [конфигурационном файле `.yfm`](https://diplodoc.com/docs/ru/settings#config) в параметре `varsPreset`.
+
+
+#### Узнайте больше
+
+- [Как работать с переменными](https://diplodoc.com/docs/ru/syntax/vars)
+