Merge pull request #40 from diplodoc-platform/DOCSUP-74043.Rewrite-Qu…

…ickstart-for-external

DOCSUP-74043: [Diplodoc] Переписать Quickstart для внешней доки

ru/index.yaml

@@ -7,9 +7,9 @@ links:
 - title: Обзор системы
   description: Описание платформы, ее основные возможности, особенности и преимущества.
   href: about.md
-- title: Как попробовать
+- title: Быстрый старт
   description: С чего начать работу
-  href: how-it-work.md
+  href: quickstart.md
 - title: Yandex Flavored Markdown
   description: Описание языка Yandex Flavored Markdown.
   href: index-yfm.md

ru/quickstart.md

@@ -0,0 +1,121 @@
+
+# Быстрый старт
+
+{% note warning %}
+
+Для работы с Diplodoc вам потребуются учетная запись на [GitHub](https://github.com/) и система контроля версий [Git](https://git-scm.com/downloads).
+
+{% endnote %}
+
+
+1. Перейдите на сайт [diplodoc.com](https://diplodoc.com/) и нажмите кнопку **Начать**.
+
+1. Следуйте инструкции, указанной на странице. 
+
+1. На вашей странице GitHub будет автоматически создан репозиторий `diplodoc-example` и создана ссылка на пример документации.
+
+{% note info %}
+
+Чтобы изменить стандартное имя репозитория `diplodoc-example`, [свяжитесь с нами](https://diplodoc.com/#contact).
+
+{% endnote %}
+
+## Создание простого документационного проекта в YFM 
+
+### Структура проекта
+
+Базовый проект состоит из нескольких конфигурационных файлов и страниц с контентом, связанных между собой в следующую структуру: 
+
+
+```
+input-folder
+|-- .yfm (Файл конфигурации)
+|-- toc.yaml (Оглавление)
+|-- presets.yaml (Пресеты переменных)
+|-- index.yaml (Разводящая страница)
+|-- pages (Файлы с контентом)
+    |-- faq.md
+    |-- how-to.md
+|-- _assets (Каталог с изображениями)
+    |-- image1.png
+    |-- image2.png
+|-- _includes (Каталог с файлами для переиспользования)
+    |-- faq_shared_block.md
+```
+
+Больше информации про параметры и конфигурацию можно найти в разделе [**Документационный проект**](./project/index.md). 
+
+### Сборка проекта 
+
+Сборка выполняется с помощью инструмента [**Builder**](tools/docs/index.md) в командной строке.
+
+Чтобы запустить сборку, выполните команду, указав обязательные ключи запуска:
+
+
+-  input, -i — путь до директории проекта.
+
+
+- output, -o — путь до директории, предназначенной для выходных данных (статических HTML).
+
+#### Пример
+
+```
+yfm -i ./input-folder -o ./ouput-folder
+```
+### Результат 
+
+После успешного выполнения работы сборщика появляется или готовый проект HTML или проект в YFM.
+Часто вывод в YFM применяется для создания подразделов и включения в крупные проекты. 
+
+### Использование
+
+Готовые проекты в HTML можно использовать локально или разместить на подходящем для Вас хостинге, включая S3-like хранилище.
+
+## Интеграция в ваш процесс разработки
+
+### Создание и построение проекта 
+
+В общем случае структура проекта и процедуры построения не отличаются от описанного в предыдущем разделе. 
+В случае интеграции с вашими СI/CD пайплайнами требуется включение Builder для срабатывания по триггерам обновления документации в репозитории. 
+
+Как для С++ или Java проектов используются специальные компиляторы в пайплайнах, так для документации эта задача выполняется Builder'ом. Он создает готовые документы (артефакты), которые потом можно автоматически разместить на внутренних или внешних ресурсах для пользователей.
+
+
+### Подключение плагинов и расширенная конфигурация
+
+Как правило, большие документационные проекты используют дополнительные возможности по работе с контентом и специфичные конфигурации для построения.  
+Примером таких расширений является возможность работы с видео или многострочными таблицами.
+
+Подробнее о способах корректного отображения и трансформации контента можно почитать на [странице](./plugins/index.md).
+
+Особенностью конфигурации при построении может быть возможность отключения линтера или сборка проекта в виде одного большого 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/toc.yaml

@@ -31,8 +31,8 @@ navigation:
 items:
   - name: Обзор системы
     href: about.md
-  - name: Начало работы
-    href: how-it-work.md
+  - name: Быстрый старт
+    href: quickstart.md
   - name: Yandex Flavored Markdown
     expanded: true
     href: index-yfm.md