Быстрый старт

1. Перейдите на сайт diplodoc.com и нажмите кнопку Начать.

2. Следуйте инструкции, указанной на странице.

3. На вашей странице GitHub будет автоматически создан репозиторий diplodoc-example и создана ссылка на пример документации.

Создание простого документационного проекта в 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

Больше информации про параметры и конфигурацию можно найти в разделе Документационный проект.

Сборка проекта

Сборка выполняется с помощью инструмента Builder в командной строке.

Чтобы запустить сборку, выполните команду, указав обязательные ключи запуска:

• input, -i — путь до директории проекта.

• output, -o — путь до директории, предназначенной для выходных данных (статических HTML).

Пример

yfm -i ./input-folder -o ./ouput-folder

Результат

После успешного выполнения работы сборщика появляется или готовый проект HTML или проект в YFM.
Часто вывод в YFM применяется для создания подразделов и включения в крупные проекты.

Использование

Готовые проекты в HTML можно использовать локально или разместить на подходящем для Вас хостинге, включая S3-like хранилище.

Интеграция в ваш процесс разработки

Создание и построение проекта

В общем случае структура проекта и процедуры построения не отличаются от описанного в предыдущем разделе.
В случае интеграции с вашими СI/CD пайплайнами требуется включение Builder для срабатывания по триггерам обновления документации в репозитории.

Как для С++ или Java проектов используются специальные компиляторы в пайплайнах, так для документации эта задача выполняется Builder'ом. Он создает готовые документы (артефакты), которые потом можно автоматически разместить на внутренних или внешних ресурсах для пользователей.

Подключение плагинов и расширенная конфигурация

Как правило, большие документационные проекты используют дополнительные возможности по работе с контентом и специфичные конфигурации для построения.
Примером таких расширений является возможность работы с видео или многострочными таблицами.

Подробнее о способах корректного отображения и трансформации контента можно почитать на странице.

Особенностью конфигурации при построении может быть возможность отключения линтера или сборка проекта в виде одного большого HTML-файла.

Дополнительно с такими возможностями можно ознакомиться на странице.

Работа с Github и публикация документов на своем домене или домене https://diplodoc.com

Если ваш проект использует Github как систему контроля версий и место хранения исходного кода вашей документации, Diplodoc позволит создать полностью интегрированный пайплайн работы, покрывающий все шаги от внесения изменений в исходные тексты до построения проекта с помощью Github actions и интеграции с Elastic Search.

Свяжитесь с нами, чтобы обсудить детали вашей конфигурации и возможные варианты решения.

Размещение документа на GitHub Pages

1. В GitHub в репозитории вашего документа перейдите на вкладку Settings и в меню слева выберите Pages.

2. В разделе Build and deployment в выпадающем списке выберите GitHub Actions и в появившемся блоке Static HTML нажмите кнопку Configure. Откроется окно редактирования экшна.

3. В блоке jobs после строки uses: actions/configure-pages@v5 добавьте код

   - name: Build docs
     uses: diplodoc-platform/docs-build-action@v3
     with:
       src-root: './docs'
       build-root: './docs-html'
   

4. Вверху справа нажмите Commit changes..., укажите имя коммита в поле Commit message и нажмите кнопку Commit changes.

5. Перейдите на вкладку Actions. Вверху списка будет ваш последний коммит.

6. Нажмите на название коммита. После завершения сборки, документ будет размещен на GitHub Pages. Посмотреть его можно по ссылке ниже под надписью deploy.