Проекты с открытым исходным кодом живут или умирают благодаря документации. Библиотека с хорошей документацией находит пользователей. Библиотека с голым README и подходом «смотрите код» форкается тем, кто напишет лучшую документацию — или просто игнорируется.
Но большинство инструментов документации создано для компаний, а не для мейнтейнеров OSS. Они берут плату за пользователя, за страницу или за workspace. Для проекта, поддерживаемого волонтёрами с нулевым бюджетом, это неприемлемо.
Мы создали Community Edition DocPlatform бесплатным навсегда, без ограничений. Неограниченное число пользователей, страниц, workspace. Никакого «бесплатного тарифа», подталкивающего к обновлению — Community Edition — это полный продукт без облачного хостинга. Вот как настроить его для вашего проекта с открытым исходным кодом.
Типичная настройка документации OSS
Большинство проектов с открытым исходным кодом приходят к одному из этих подходов:
GitHub Pages + генератор статических сайтов. Вы пишете markdown-файлы, настраиваете пайплайн сборки и развёртываете на GitHub Pages. Самый распространённый стек — Docusaurus (на React) или MkDocs (на Python).
Плюсы: Бесплатный хостинг, контент под контролем версий, привычный git-процесс.
Минусы: Нет веб-редактора (контрибьюторы должны знать git, markdown и систему сборки), нет предпросмотра в реальном времени, нет поиска без сторонних сервисов (у Algolia DocSearch есть очередь и процесс одобрения), нет функций совместной работы.
Хостинговая платформа с бесплатным тарифом. GitBook, ReadMe или Notion с публичной страницей. Вы получаете веб-редактор и хостинговый поиск.
Плюсы: Легко начать, веб-редактор снижает порог для нетехнических контрибьюторов.
Минусы: Бесплатные тарифы ограничены (GitBook: 1 пространство, ограниченные интеграции; ReadMe: ограниченные справочники API). Ваш контент живёт на чужом сервере. Если они изменят цены или закроются, вам придётся мигрировать в спешке.
Сырой markdown в репозитории. Папка docs/ с markdown-файлами. Без этапа сборки, без хостинга, без поиска.
Плюсы: Нулевая настройка. Контент под контролем версий.
Минусы: Пользователи не могут просматривать документацию, не заходя на GitHub. Нет поиска. Нет навигационной структуры кроме имён файлов.
Лучший подход
DocPlatform даёт вам лучшее из всех трёх: контент хранится как markdown в git-репозитории, веб-редактор для нетехнических контрибьюторов, полнотекстовый поиск и опубликованный сайт документации — всё из одного бинарного файла, который можно хостить где угодно.
Вот настройка.
Шаг 1: Установите DocPlatform
На любой машине с Linux, macOS или Windows:
curl -fsSL https://get.valoryx.org | sh
Или скачайте бинарный файл прямо со страницы установки. Больше ничего устанавливать не нужно — ни базы данных, ни Docker, ни среды выполнения.
Шаг 2: Запустите сервер
docplatform serve
Откройте http://localhost:3000. Создайте учётную запись администратора. Ваш сервер работает.
Для постоянной настройки используйте systemd-сервис:
[Unit]
Description=DocPlatform
After=network.target
[Service]
ExecStart=/opt/docplatform/bin/docplatform serve
WorkingDirectory=/opt/docplatform
Restart=always
[Install]
WantedBy=multi-user.target
Шаг 3: Создайте workspace
Workspace в DocPlatform — это проект документации. Для проекта с открытым исходным кодом у вас обычно будет один workspace для публичной документации.
- Перейдите в Settings → Workspaces → Create
- Назовите его по имени проекта (например, «MyProject Docs»)
- Выберите тему — есть 7 встроенных тем, все разработаны для технической документации
Шаг 4: Подключите GitHub-репозиторий
Здесь становится интересно. DocPlatform поддерживает двунаправленную git-синхронизацию — правки в веб-интерфейсе коммитятся в репозиторий, а изменения, запушенные в репозиторий, отображаются в интерфейсе.
- Перейдите в Workspace Settings → Git Sync
- Добавьте URL репозитория:
https://github.com/yourorg/yourproject.git - Настройте путь к документации (например,
docs/, если markdown в подпапке) - Добавьте deploy key или personal access token для доступа на запись
После подключения DocPlatform забирает существующие markdown-файлы и индексирует их для поиска. Каждый .md файл по настроенному пути становится страницей.
Шаг 5: Опубликуйте документацию
Включите «Publish» в настройках workspace. DocPlatform генерирует просматриваемый сайт документации с:
- Навигационным деревом на основе структуры папок
- Полнотекстовым поиском с терпимостью к опечаткам
- Адаптивным дизайном для мобильных устройств
- Подсветкой синтаксиса для блоков кода
- Переключателем тёмной темы
Опубликованная документация доступна по адресу http://yourserver:3000/docs/workspace-slug/.
Git-процесс
Вот как выглядит рабочий процесс на практике для проекта с открытым исходным кодом с несколькими контрибьюторами:
Мейнтейнеры используют веб-редактор для быстрых исправлений — исправление опечаток, реструктуризация страниц, обновление скриншотов. Каждое сохранение автоматически создаёт git-коммит.
Внешние контрибьюторы отправляют PR в директорию документации вашего GitHub-репозитория — точно так же, как для кода. Когда вы мёржите PR, DocPlatform подхватывает изменения через git-синхронизацию и обновляет опубликованный сайт.
Нетехнические контрибьюторы (комьюнити-менеджеры, технические писатели) используют WYSIWYG-редактор в браузере. Им не нужно знать git или синтаксис markdown. Их правки всё равно коммитятся в репозиторий.
Это значит, что ваша документация проходит тот же процесс ревью, что и код. Хотите, чтобы кто-то проверил изменение документации перед публикацией? Пусть отправляет PR. Хотите разрешить доверенным контрибьюторам редактировать напрямую? Дайте им доступ редактора в DocPlatform.
Сравнение: DocPlatform vs. Docusaurus
Поскольку Docusaurus — самый популярный инструмент документации для OSS, вот прямое сравнение:
| Функция | Docusaurus | DocPlatform CE |
|---|---|---|
| Веб-редактор | Нет — редактируйте markdown, коммитьте, ждите сборку | Да — WYSIWYG, изменения мгновенно |
| Поиск | Требует Algolia DocSearch (очередь) или Lunr.js (клиентский, ограниченный) | Встроенный полнотекстовый поиск (Bleve) |
| Этап сборки | Да — React-сборка, может занимать 30+ секунд | Нет — страницы рендерятся при сохранении |
| Git-интеграция | Нативная (это генератор статических сайтов) | Двунаправленная синхронизация (веб ↔ git) |
| Множественные версии | Да (версионированная документация) | На основе workspace (один workspace на версию) |
| Время настройки | 10-30 минут (Node.js, npm, конфигурация) | 2 минуты (скачать бинарный файл, запустить) |
| Хостинг | GitHub Pages, Netlify, Vercel (бесплатно) | На своём сервере (нужен сервер) |
| RBAC | Нет (это инструмент сборки) | 5 ролей (admin, manager, editor, reviewer, viewer) |
| i18n | На основе плагинов | На основе workspace |
Docusaurus выигрывает, если вам нужен бесплатный хостинг на GitHub Pages и все контрибьюторы работают с git и React. DocPlatform выигрывает, если вам нужен веб-редактор, встроенный поиск, контроль доступа, или если не все контрибьюторы — разработчики.
Хостинг с минимальным бюджетом
Частое возражение: «Docusaurus бесплатен, потому что GitHub Pages хостит его. На своём сервере — значит мне нужен сервер.»
Верно. Но серверы дёшевы:
- Hetzner CX22: 2 vCPU, 4 ГБ RAM, 40 ГБ диск — EUR 3,99/мес
- Oracle Cloud Free Tier: ARM-инстанс, 24 ГБ RAM — бесплатно навсегда
- Старый ноутбук в шкафу: Бесплатно, если он у вас уже есть
DocPlatform использует примерно 50 МБ RAM в простое и 100-200 МБ под нагрузкой. Любой сервер, способный запустить бинарный файл Go, может его запустить.
Если вы уже запускаете CI-сервер, Discord-бот или другой сервис для проекта, DocPlatform может работать на той же машине.
Реальная настройка: от нуля до опубликованной документации
Давайте разберём конкретный пример. Вы поддерживаете CLI-инструмент fastgrep и хотите перейти от README к полноценной документации.
# Установите DocPlatform
curl -fsSL https://get.valoryx.org | sh
# Запустите сервер
docplatform serve &
# Откройте браузер, создайте учётную запись админа, создайте workspace
# Подключите к github.com/yourname/fastgrep, путь документации: docs/
# Создайте первые страницы в веб-редакторе:
# - Начало работы
# - Установка
# - Конфигурация
# - Справочник CLI
# - Вклад в проект
Каждая страница, созданная в веб-редакторе, коммитится в docs/ вашего репозитория. Существующие markdown-файлы в docs/ (если есть) импортируются автоматически.
Опубликуйте workspace, направьте домен на сервер, и у вашего проекта есть документация с поиском и веб-редактором — настроенная менее чем за 5 минут.
Полная настройка публикации — в руководстве по публикации.
Бесплатно значит бесплатно
Community Edition — это не пробная версия. Это не ограниченный бесплатный тариф. Это полный продукт:
- Неограниченное число пользователей и редакторов
- Неограниченное число workspace и страниц
- Полнотекстовый поиск
- Git-синхронизация
- RBAC с 5 ролями
- Все 7 тем
- Аутентификация WebAuthn/passkey
- MCP-сервер с 26 ИИ-инструментами
Единственное, что не включает Community Edition — облачный хостинг. Вы запускаете его на своей инфраструктуре. Для проектов с открытым исходным кодом, которые уже управляют собственной инфраструктурой, это не ограничение — это преимущество.
Скачайте DocPlatform и дайте вашему проекту документацию, которую он заслуживает.