diff --git a/ru/_images/audio-track.png b/ru/_images/audio-track.png new file mode 100644 index 00000000..24c1f9bb Binary files /dev/null and b/ru/_images/audio-track.png differ diff --git a/ru/guides/single-source/index.md b/ru/guides/single-source/index.md new file mode 100644 index 00000000..a300ebe7 --- /dev/null +++ b/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) diff --git a/ru/guides/single-source/profiling.md b/ru/guides/single-source/profiling.md new file mode 100644 index 00000000..3c13e2d9 --- /dev/null +++ b/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). diff --git a/ru/project/presets.md b/ru/project/presets.md index 3fba99fe..e4d44ab9 100644 --- a/ru/project/presets.md +++ b/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` для выбранного пресета. Если запустить сборку с другими значениями в ту же директорию, файлы перезапишутся. + diff --git a/ru/toc.yaml b/ru/toc.yaml index be693873..5d193715 100644 --- a/ru/toc.yaml +++ b/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: