Основные сценарии использования Diplodoc
Создание простого документационного проекта в 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. C его помощью генерируются артефакты, которые могут быть автоматически выложены на
внутренние или внешние ресурсы для доступа конечных пользователей.
Подключение плагинов и расширенная конфигурация
Как правило, большие документационные проекты используют дополнительные возможности по работе с контентом и специфичные конфигурации для построения.
Примером таких расширений является возможность работы с видео или многострочных таблиц.
Подробнее о способах корректного отображения и трансформации контента можно почитать на странице.
Особенностью конфигурации при построении может быть возможность отключения линтера или сборка проекта в виде одного большого html файла.
Дополнительно о таких возможностях можно ознакомиться на странице.
Работа с Github и публикация документов на своем домене или домене https://diplodoc.com
Если Ваш проект использует Github как систему контроля версий и место хранения исходного кода Вашей документации, Diplodoc позволит создать полностью интегрированный пайплайн работы, покрывающий все шаги от внесения изменений в исходные тексты до построения проекта с помощью Github actions и интеграции с Elastic Search.
Свяжитесь с нами, чтобы обсудить детали Вашей конфигурации и возможные варианты решения.