Change docs

ru/about.md

@@ -7,15 +7,26 @@ Diplodoc - это платформа работы с документацией
 ## Достоинства платформы:
 
 ### Простота использования
+
 Работа с документами как с кодом: в привычной среде и с минимальными усилиями по развёртыванию и поддержке.
+
 ### Cкорость работы
+
 Быстрая сборка, валидация и выкладка документации любого размера. Полная интеграция в существующие CI/CD-системы для ускорения работы.
+
 ### Общепринятый формат Markdown
+
 Простой, понятный и широко распространенный синтаксис с поддержкой базового Markdown. Концентрируйтесь на контенте, а не на том, как доставить его до пользователя.
+
 ### Обширная функциональность
+
 Создание документов любой сложности, в том числе генерация из единого источника и работа с переменными. Широкие возможности по кастомизации и отображению гарантируют удовлетворённость конечных пользователей.
+
 ### Интеграция с системами автоматической документации
+
 Поддержка широко распространённой OpenAPI-спецификации «из коробки». Обеспечение работы специализированных систем через интерфейс подключаемых внешних документов.
+
 ### Поиск
+
 Самый частотный пользовательский сценарий по поиску документов на базе платформы без дополнительных затрат и усилий по поддержке.
 

ru/features.md

@@ -1 +1,23 @@
-# Функциональные возможности
+# Функциональные возможности
+
+## Работа в парадигме Docs as code
+
+Документация разрабатывается с помощью привычных инструментов разработчика. Используйте расширенный диалект Markdown и отслеживайте изменения с помощью системы контроля версий.
+
+## Предварительный просмотр изменений
+
+Проверяйте изменения на тестовых хостах в каждом пулл-реквесте.
+
+Поддерживается в репозиториях GitHub и GitLab.
+
+## Интеграция и автоматизация
+
+Diplodoc поддерживает интеграцию с СI/CD системами – требуется включение [Builder](tools/docs/index.md) для срабатывания по триггерам обновления документации в репозитории. 
+
+Как для С++ или Java проектов используются специальные компиляторы в пайплайнах, так для документации эта задача выполняется Builder'ом. Он создает готовые документы (артефакты), которые потом можно автоматически разместить на внутренних или внешних ресурсах для пользователей.
+
+### Публикация на собственном домене или на diplodoc.com
+
+Если ваш проект использует Github как систему контроля версий и место хранения исходного кода вашей документации, Diplodoc позволит создать полностью интегрированный пайплайн работы, покрывающий все шаги от внесения изменений в исходные тексты до построения проекта с помощью Github actions и интеграции с Elastic Search. 
+
+[Свяжитесь с нами](https://diplodoc.com/#contact), чтобы обсудить детали вашей конфигурации и возможные варианты решения.

ru/github-pages.md

@@ -0,0 +1,21 @@
+# Публикация на GitHub Pages
+
+1. В GitHub в репозитории вашего документа перейдите на вкладку **Settings**  и в меню слева выберите **Pages**.
+
+1. В разделе **Build and deployment** в выпадающем списке выберите **GitHub Actions** и в появившемся блоке **Static HTML** нажмите кнопку **Configure**.  Откроется окно редактирования экшна.
+
+1. В блоке `jobs` после строки `uses: actions/configure-pages@v5` добавьте код
+
+    ```yaml
+    - name: Build docs
+      uses: diplodoc-platform/docs-build-action@v3
+      with:
+        src-root: './docs'
+        build-root: './docs-html'
+    ```
+
+1. Вверху справа нажмите **Commit changes...**, укажите имя коммита в поле **Commit message** и нажмите кнопку **Commit changes**.
+
+1. Перейдите на вкладку **Actions**. Вверху списка будет ваш последний коммит. 
+
+1. Нажмите на название коммита. После завершения сборки, документ будет размещен на GitHub Pages. Посмотреть его можно по ссылке ниже под надписью **deploy**.

ru/how-it-work.md

@@ -71,16 +71,6 @@ yfm -i ./input-folder -o ./ouput-folder
 
 Готовые проекты в HTML можно использовать локально или разместить на подходящем для Вас хостинге, включая S3-like хранилище.
 
-## Интеграция в ваш процесс разработки
-
-### Создание и построение проекта 
-
-В общем случае структура проекта и процедуры построения не отличаются от описанного в предыдущем разделе. 
-В случае интеграции с вашими СI/CD пайплайнами требуется включение Builder для срабатывания по триггерам обновления документации в репозитории. 
-
-Как для С++ или Java проектов используются специальные компиляторы в пайплайнах, так для документации эта задача выполняется Builder'ом. Он создает готовые документы (артефакты), которые потом можно автоматически разместить на внутренних или внешних ресурсах для пользователей.
-
-
 ### Подключение плагинов и расширенная конфигурация
 
 Как правило, большие документационные проекты используют дополнительные возможности по работе с контентом и специфичные конфигурации для построения.  
@@ -91,31 +81,3 @@ yfm -i ./input-folder -o ./ouput-folder
 Особенностью конфигурации при построении может быть возможность отключения линтера или сборка проекта в виде одного большого HTML-файла.
 
 Дополнительно с такими возможностями можно ознакомиться на [странице](./tools/transform/settings.md).
-
-## Работа с Github и публикация документов на своем домене или домене https://diplodoc.com 
-
-Если ваш проект использует Github как систему контроля версий и место хранения исходного кода вашей документации, Diplodoc позволит создать полностью интегрированный пайплайн работы, покрывающий все шаги от внесения изменений в исходные тексты до построения проекта с помощью Github actions и интеграции с Elastic Search. 
-
-[Свяжитесь с нами](https://diplodoc.com/#contact), чтобы обсудить детали вашей конфигурации и возможные варианты решения.
-
-### Размещение документа на GitHub Pages
-
-1. В GitHub в репозитории вашего документа перейдите на вкладку **Settings**  и в меню слева выберите **Pages**.
-
-1. В разделе **Build and deployment** в выпадающем списке выберите **GitHub Actions** и в появившемся блоке **Static HTML** нажмите кнопку **Configure**.  Откроется окно редактирования экшна.
-
-1. В блоке `jobs` после строки `uses: actions/configure-pages@v5` добавьте код
-
-    ```yaml
-    - name: Build docs
-      uses: diplodoc-platform/docs-build-action@v3
-      with:
-        src-root: './docs'
-        build-root: './docs-html'
-    ```
-
-1. Вверху справа нажмите **Commit changes...**, укажите имя коммита в поле **Commit message** и нажмите кнопку **Commit changes**.
-
-1. Перейдите на вкладку **Actions**. Вверху списка будет ваш последний коммит. 
-
-1. Нажмите на название коммита. После завершения сборки, документ будет размещен на GitHub Pages. Посмотреть его можно по ссылке ниже под надписью **deploy**.

ru/index.yaml

@@ -4,15 +4,9 @@ meta:
   title: Метаданные
   noIndex: true
 links:
-- title: Обзор системы
-  description: Описание платформы, ее основные возможности, особенности и преимущества.
+- title: О платформе
+  description: Описание платформы, ее особенности и преимущества.
   href: about.md
-- title: Быстрый старт
-  description: С чего начать работу
-  href: how-it-work.md
-- title: Yandex Flavored Markdown
-  description: Описание языка Yandex Flavored Markdown.
-  href: index-yfm.md
-
-
-
+- title: Возможности платформы
+  description: Функциональные возможности Diplodoc
+  href: features.md  

ru/toc.yaml

@@ -117,11 +117,13 @@ items:
             href: project/pc-example2.yaml
           - name: Пример 3 (fullScreen mode)
             href: project/pc-example3.yaml 
-  - name: Конфигурация проекта
+  - name: Деплой и конфигурация проекта
     labeled: true
     items:
       - name: Настройки проекта
         href: settings.md
+      - name: Github Pages
+        href: github-pages.md
   - name: Внесение изменений
     href: contribution.md
   - name: Практические руководства