Проєкти з відкритим кодом живуть або вмирають завдяки документації. Бібліотека з чудовою документацією отримує користувачів. Бібліотека з голим README та підходом «дивіться код» форкається кимось, хто пише кращу документацію — або просто ігнорується.
Але більшість інструментів документації створені для компаній, а не для мейнтейнерів відкритого коду. Вони беруть плату за користувача, за сторінку або за workspace. Для проєкту, який підтримують волонтери з нульовим бюджетом, це неприйнятно.
Ми створили Community Edition DocPlatform безкоштовним назавжди, без обмежень. Необмежені користувачі, необмежені сторінки, необмежені workspace. Жодного «безкоштовного рівня», що підштовхує до оновлення — Community Edition — це повний продукт без хмарного хостингу. Ось як налаштувати його для вашого проєкту з відкритим кодом.
Типове налаштування документації для відкритого коду
Більшість проєктів з відкритим кодом обирають один із таких підходів:
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 для доступу на push
Після підключення DocPlatform витягує ваші існуючі markdown-файли та індексує їх для пошуку. Кожен .md файл у налаштованому шляху стає сторінкою.
Крок 5: Опублікуйте документацію
Увімкніть «Publish» у налаштуваннях workspace. DocPlatform генерує сайт документації для перегляду з:
- Навігаційне дерево на основі структури папок
- Повнотекстовий пошук із толерантністю до помилок
- Адаптивний дизайн для мобільних пристроїв
- Підсвічування синтаксису для блоків коду
- Перемикач темної теми
Ваша опублікована документація доступна за адресою http://yourserver:3000/docs/workspace-slug/.
Git-процес
Ось як виглядає процес на практиці для проєкту з відкритим кодом із кількома учасниками:
Мейнтейнери використовують веб-редактор для швидких виправлень — виправлення помилок, реструктуризація сторінок, оновлення скріншотів. Кожне збереження автоматично створює git commit.
Зовнішні учасники подають PR до директорії документації у вашому GitHub-репозиторії, точно так само, як для коду. Коли ви зливаєте PR, DocPlatform підхоплює зміни через git sync і оновлює опублікований сайт.
Нетехнічні учасники (менеджери спільноти, технічні письменники) використовують WYSIWYG-редактор у браузері. Їм не потрібно знати git або синтаксис markdown. Їхні редагування все одно комітяться в репозиторій.
Це означає, що ваша документація має той самий процес рецензування, що й код. Хочете, щоб хтось переглянув зміну документації перед публікацією? Нехай подасть PR. Хочете дозволити довіреним учасникам редагувати напряму? Дайте їм доступ редактора в DocPlatform.
Порівняння: DocPlatform проти Docusaurus
Оскільки Docusaurus — найпопулярніший інструмент документації для відкритого коду, ось пряме порівняння:
| Функція | 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 ГБ диск — 3,99 EUR/місяць
- 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/
# Створіть перші сторінки у веб-редакторі:
# - Getting Started
# - Installation
# - Configuration
# - CLI Reference
# - Contributing
Кожна сторінка, створена у веб-редакторі, комітиться в docs/ вашого репозиторію. Ваші існуючі docs/ markdown-файли (якщо є) імпортуються автоматично.
Опублікуйте workspace, направте домен на сервер, і у вашого проєкту є документація з пошуком і веб-редактором — налаштована менш ніж за 5 хвилин.
Для повного налаштування публікації див. посібник з публікації.
Безкоштовно означає безкоштовно
Community Edition — це не пробна версія. Це не обмежений безкоштовний рівень. Це повний продукт:
- Необмежені користувачі та редактори
- Необмежені workspace та сторінки
- Повнотекстовий пошук
- Git sync
- RBAC з 5 ролями
- Усі 7 тем
- Автентифікація WebAuthn/passkey
- MCP-сервер із 26 ШІ-інструментами
Єдине, чого не включає Community Edition — хмарний хостинг. Ви запускаєте його на власній інфраструктурі. Для проєктів з відкритим кодом, що вже керують власною інфраструктурою, це не обмеження, а перевага.
Завантажте DocPlatform і дайте вашому проєкту документацію, яку він заслуговує.