
Как всё устроено?
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 для обеспечения релевантности и точности результатов запросов.