New toc

ru/about.md

@@ -1,21 +1,26 @@
-# Diplodoc
-
-Diplodoc - это платформа работы с документацией в парадигме Documentation as a Code. 
-
-Вы можете создавать свои документационные проекты в YFM, cо всей структурой, контентом и элементами, необходимыми для качественного предоставления информации пользователям. 
-
-## Достоинства платформы:
-
-### Простота использования
-Работа с документами как с кодом: в привычной среде и с минимальными усилиями по развёртыванию и поддержке.
-### Cкорость работы
-Быстрая сборка, валидация и выкладка документации любого размера. Полная интеграция в существующие CI/CD-системы для ускорения работы.
-### Общепринятый формат Markdown
-Простой, понятный и широко распространенный синтаксис с поддержкой базового Markdown. Концентрируйтесь на контенте, а не на том, как доставить его до пользователя.
-### Обширная функциональность
-Создание документов любой сложности, в том числе генерация из единого источника и работа с переменными. Широкие возможности по кастомизации и отображению гарантируют удовлетворённость конечных пользователей.
-### Интеграция с системами автоматической документации
-Поддержка широко распространённой OpenAPI-спецификации «из коробки». Обеспечение работы специализированных систем через интерфейс подключаемых внешних документов.
-### Поиск
-Самый частотный пользовательский сценарий по поиску документов на базе платформы без дополнительных затрат и усилий по поддержке.
-
+# О Diplodoc
+
+Добро пожаловать на платформу документирования Diplodoc — решение, созданное для тех, кто стремится эффективно управлять и публиковать документацию с использованием подхода «docs as code».
+
+Diplodoc предоставляет два варианта использования (оба из которых абсолютно бесплатны):
+
+{% list tabs %}
+
+- Серверная версия
+
+  Серверная версия Diplodoc обеспечивает простоту и удобство использования платформы без необходимости организации собственного хостинга. В этом варианте вся обработка и рендеринг контента осуществляется на наших ресурсах.
+
+  Вы просто работаете с Markdown-файлами на Github, и платформа автоматически генерирует из них документацию на на домене [diplodoc.com](https://diplodoc.com/).
+
+  Одним из преимуществ серверной версии является возможность проксирования с вашего собственного домена, что позволяет сохранить брендовый стиль и профессиональный вид документационного портала.
+
+- Cтатическая документация
+
+  Для пользователей, предпочитающих полный контроль над инфраструктурой, Diplodoc предлагает вариант использования через интерфейс командной строки (CLI).
+
+  В этом сценарии вы можете использовать наш CLI для генерации статических HTML-страниц из вашего контента, написанного в Markdown.
+
+  Этот подход позволяет размещать собранные файлы на любых собственных хостинговых платформах, обеспечивая максимальную гибкость и независимость. Это идеальный вариант для команд, желающих интегрировать процесс создания документации в свои CI/CD пайплайны.
+
+{% endlist %}
+

ru/deploy.md

@@ -0,0 +1,7 @@
+# Публикация документации
+
+Diplodoc поддерживает несколько вариантов размещения документации:
+
+- [Публикация на Diplodoc.com](how-it-work.md)
+- [Размещение на GitHub Pages](github-pages.md)
+- [Публикация на локальном сервере](installation.md)

ru/features.md

@@ -0,0 +1,33 @@
+# Функциональные возможности
+
+## Простота использования
+
+Управляйте документами так же, как исходным кодом: в привычной среде с минимальными усилиями на развертывание и обслуживание.
+
+## Расширенный Markdown
+
+Используйте [улучшенный Markdown](syntax/index.md) с необходимыми компонентами для документации, такими как кодовые блоки, изображения, диаграммы и многое другое.
+
+## Комбинирование ручной и генерируемой документации
+
+Поддерживается генерация из [OpenAPI-спецификаций](guides/openapi.md), а также автогенерация из Swift и Objective-C.
+
+## Локализация
+
+Платформа нативно поддерживает [извлечение текста](tools/docs/translate.md) для различных систем перевода, таких как SmartCAT, Weblate, YaCAT и Яндекс Переводчик.
+
+## Конструктор страниц
+
+Платформа нативно поддерживает [Page Constructor](https://github.com/gravity-ui/page-constructor) — тип страниц, позволяющих пользователям создавать страницы-лендинги с каруселями, фонами, плавно анимированными карточками и различными другими блоками.
+
+## Поддержка Right-to-Left
+
+Diplodoc предоставляет возможность поддержки режима Right-to-Left (RTL), обеспечивая беспрепятственный доступ и читаемость для таких языков, как арабский и иврит.
+
+## Встроенная функция поиска
+
+Наиболее типичный сценарий использования [поиска документов](project/search.md) на платформе, без дополнительных затрат или усилий по поддержке.
+
+## Визуальные возможности
+
+Платформа позволяет быстро создавать понятные формулы, красивые диаграммы и разводящие страницы, благодаря наличию [Mermaid](tools/mermaid.md), PlantUML, LaTeX.

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/guides/generic.md

@@ -0,0 +1,37 @@
+# Generic
+
+Вы можете сгенерировать документацию в markdown-формате любой утилитой и включить её в основную документацию.
+
+Инклюдер сгенерирует по ней оглавление и включит контент в документацию.
+
+#### Пример использования
+
+Проект документации лежит в `doc_root` папке.
+
+Положим сгенерированный контент в папку `doc_root/docs`.
+
+Включим этот контент с помощью generic-инклюдера в `doc_root/toc.yaml`.
+
+Подключим разводящую в `doc_root/index.yaml`.
+
+```yaml
+# doc_root/toc.yaml
+title: documentation
+href: index.yaml
+items:
+  - name: docs
+    include:
+      path: docs
+      includers:
+        - name: generic
+          input: docs
+      mode: link
+```
+
+```yaml
+# doc_root/index.yaml
+title: documentation
+links:
+  - title: docs
+    href: docs/
+```

ru/guides/includers.md

@@ -0,0 +1,57 @@
+# Вставка произвольного контента (Includers)
+
+Вы можете включить в оглавление произвольный контент через `includers`, но только в случае если `includer` для этого типа контента имплементирован. Список имплементированных инклюдеров можно посмотреть [ниже](#implement-includers).
+
+Возможные способы указания инклюдеров:
+
+- массив `includer`-объектов в поле `includers`;
+
+- `includer`-объект в поле `includer` (_в процессе деприкации в пользу `includers` поля_).
+
+**Требования к `include`:**
+
+1. `include` должен иметь поле `path`, куда контент будет включен.
+
+2. поле `path` должно быть **путем, куда будет включен контент**.
+
+3. свойство `mode` должно иметь значение `link или пропущенно, `link является дефолтным поведением.
+
+**Требования к `includers`:**
+
+`includers` должен быть массивом includer-объектов, которые будут запущенны в указанном порядке.
+
+**Требования к `includer`:**
+
+Параметры между includer-объектами разные, но имя `includer` является обязательным параметром.
+
+`name` указывает имя инклюдера, который запустится.
+
+
+#### Пример использования
+
+Абстрактный пример использования инклюдеров
+
+_Уточненный пример смотрите в разделе соответствуещего инклюдера для конкретного примера использования._
+
+```
+# toc.yaml
+...
+items:
+  - name: <item-name>
+    include:
+      path: <path-where-to-include>
+      includers:
+        - name: <name-of-the-first-includer>
+          <includer-parameter>: <includer-parameter-value>
+        - name: <name-of-the-second-includer>
+        - name: <name-of-the-third-includer>
+      mode: link
+...
+```
+
+## Список имплементированных инклюдеров {#implement-includers}
+
+- [Generic](generic.md);
+- [Open API](openapi.md);
+- [Unarchive](unarchive.md);
+- [Source Docs](source-docs.md) (_в процессе деприкации в пользу generic инклюдера_).