Что такое Docara
Docara — генератор статических сайтов документации. Вы пишете страницы в Markdown и складываете настройки в несколько небольших JSON-файлов, а Docara собирает из них готовый сайт: меню, поиск, содержание страницы, переходы к соседним материалам, живые примеры и единый интерфейс из компонентов SIMAI Framework. Результат — обычные HTML, CSS и JavaScript, которые можно выложить на любой хостинг.
Docara распространяется как пакет Composer simai/docara с открытым кодом под
лицензией Apache 2.0. Из тех же исходников собирается и лендинг: у страницы
есть два готовых вида — документация (docs) и лендинг (landing).
Когда выбирать Docara
- Команда работает с PHP и Composer и не хочет поддерживать отдельную frontend-сборку или собственную тему.
- Нужен сайт, который целиком собирается из файлов в репозитории и публикуется как статический каталог — без базы данных и серверного кода.
- Важна строгая проверка: неизвестное поле настроек или неверный параметр
компонента останавливают сборку, а команда
verify-staticнаходит в готовом каталоге битые ссылки, отсутствующие якоря и файлы до публикации. - Сайт на нескольких языках, в том числе с письмом справа налево: каждый язык получает своё дерево страниц, свои подписи интерфейса и свой адрес.
- Интерфейс должен совпадать с другими продуктами на SIMAI Framework.
Ограничения
- Только статический сайт. На сервере нет PHP-кода проекта: формы, авторизация и другие серверные функции в Docara не входят.
- Нет произвольного HTML и скриптов в страницах. Raw HTML в Markdown удаляется, а расширения подключаются как проверенные компоненты с описанием параметров, а не как произвольный код.
- Одна версия документации в сборке. Для другой версии продукта собирают отдельный вариант сайта в свой каталог; встроенного переключателя версий нет.
- Простой поиск. Поиск работает в браузере по началу слов, без исправления опечаток и морфологии. Синонимы задаются метками страницы.
- Набор компонентов ограничен. Доступны компоненты из каталога; новый компонент добавляет разработчик по проверяемому пути.
- Документация Docara пока только на русском. Заготовка
minimalсоздаёт сайт на русском или английском,showcase— только на русском.
Что нужно для работы
На компьютере или сервере, где собирается сайт:
- PHP 8.2 или новее с расширениями
ctype,dom,intl,json,libxmlиmbstring; - Composer;
- Node.js 20 или новее, доступный командой
node. Команды, которые не собирают сайт, обходятся без Node.js.
Закреплённая версия SIMAI Framework входит в пакет Docara, отдельно её ставить не нужно. Готовому сайту нужен только веб-сервер для статических файлов: PHP, Composer и Node.js на хостинге не нужны.
Сравнение с другими генераторами
Все четыре инструмента собирают статический сайт документации из Markdown. Различаются они прежде всего средой сборки и способом расширения.
| Docara | VitePress | Docusaurus | MkDocs | |
|---|---|---|---|---|
| Среда сборки | PHP, Composer и Node.js | Node.js | Node.js | Python |
| Формат страниц | Markdown и JSON-настройки | Markdown с компонентами Vue | Markdown и MDX с компонентами React | Markdown и YAML-настройки |
| Интерфейс | SIMAI Framework | тема по умолчанию на Vue | тема по умолчанию на React | темы, например Material for MkDocs |
| Расширение | проверенные компоненты по описанию параметров | компоненты Vue и плагины Vite | плагины и компоненты React | плагины на Python |
| Версии документации | отдельная сборка на каждую версию | вручную | встроенные | сторонние плагины |
| Поиск | встроенный, в браузере | встроенный или внешний сервис | внешний сервис или плагины | встроенный, в браузере |
Docara стоит выбрать, если проект уже живёт в мире PHP и SIMAI Framework или если важнее строгая проверка сборки, чем свобода писать страницы с собственным JavaScript. Если команда пишет на Vue или React и хочет вставлять в страницы свои интерактивные компоненты, ближе будут VitePress или Docusaurus; если основной язык команды — Python, удобнее MkDocs.
См. также
- Быстрый старт — первый сайт за четыре шага
- Файлы проекта — из чего состоит проект
- Как устроены компоненты — Markdown и компоненты