Как всё устроено?
Diplodoc — это платформа документации со следущими компонентами:
- клиентская часть отвечает за отображение документов в браузере на стороне пользователя;
- серверная часть отвечает за хостинг и выдачу документов клиенту;
- инструменты создания и преобразования документов из Markdown в статический сайт (Transform & Build).
Система выполняет основные операции на Node.js и React.
Подход Docs as Сode
Markdown
Документация пишется на языке разметки Markdown, а не в plain text или WYSIWYG-редакторе.
Хранение в репозитории
Документация хранится в репозитории с остальным кодом. Это может быть GitHub или ваше собственное решение.
Налаженный процесс
Документация собирается в финальный проект при помощи генератора статических сайтов и публикуется автоматически.
Синхронизация
Документация пишется и обновляется совместно — точно так же, как и остальной код.
Хранение данных
Добавление
Исходный код документации хранится в репозитории клиента в формате Markdown.
Преобразование
Преобразованный из Markdown-файлов документационный проект попадает в отдельную директорию S3-совместимого хранилища для каждого клиента.
Доступ
Доступ к S3 регулируется с помощью уникальных ключей.
Развёртывание
Хранение
Документационный проект из S3-совместимого хранилища выкладывается на Diplodoc.com.
Проксирование
Возможно проксирование с сайта клиента на сайт diplodoc.com для бесшовной интеграции.
Поиск
Поддержка поиска с помощью Elasticsearch.
Локализация
Поддержка локализации и кастомизации проекта документации.
Полная совместимость
YFM
Диалект Markdown, соответствующий спецификации CommonMark, с поддержкой плагинов и дополнительными возможностями разметки.
GitHub
Полная интеграция с системами контроля версий, в первую очередь, с GitHub — одним из основных инструментов разработки.
Elasticsearch
Быстрая индексация и поиск на основе Elasticsearch для обеспечения релевантности и точности результатов запросов.
