Где все это хранить?
Есть разные варианты: от корпоративного облака до хранения в самом репозитории проекта, но в моем случае оказалось все сложнее.
Во-первых, микро-сервисы: вариант хранения в репозитории не подходит, документация это не то, что можно сегрегировать по репозиториям. Во-вторых, JetBrains Space: мы используем его в компании, и невзирая на откровенную сырость — это хороший продукт. Однако, JetBrains его упраздняют до обычного репозитория кода к 2025 году, что убивает все его отличительные от того же GitLab фишки. Необходима отдельная платформа сугубо под документацию.
Требования:
— Self-Hosted: без привязки к чему-либо
— Markdown: универсальный и понятный многим формат
— Минимум усилий, максимум пользы
Самым очевидным решением в лоб является отдельный репозиторий с .md файлами. Удобно, понятно и мигрировать можно куда хочешь, но нет удобного поиска и структурности.
Docusaurus — открытый проект на React позволяющий создавать свою небольшую вики на основе .md файликов. При желании и навыках в React можно и странички свои создавать, плагины писать и т.п. Для подсветки синтаксиса использует Prism.js.
Этот проект меня полностью устраивает. Для разработчиков ничего не меняется, они все также пишут документацию в .md файлах, но при этом мы получаем адекватный визуал, а также возможность видеть всю структуру и иерархию как по документу, так и по всей документации.