Как всё устроено?

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

Присоединяйтесь к сообществу

GitHub

Telegram

Stack Overflow