Быстрый старт
Этот путь начинается в пустом каталоге и заканчивается страницей, открытой по
HTTP. Для сборки нужны PHP 8.2+ с расширениями ctype, dom, intl, json,
libxml и mbstring, Composer и Node.js 20+. Готовый сайт остаётся статическим;
эти инструменты нужны только на компьютере или сервере сборки.
1. Создайте проект
Установите стабильный пакет Docara прямо в каталог будущего проекта. Composer берёт его с Packagist.
mkdir /path/to/my-docara
cd /path/to/my-docara
composer require simai/docara:^3.0
php vendor/bin/docara init .
Composer фиксирует точную установленную версию в composer.lock, а
vendor/bin/docara всегда относится именно к этому проекту. init допускает
пустой каталог или каталог, где уже находятся только проверенные
composer.json, composer.lock и vendor/ с simai/docara. Служебные
.git/, .gitignore, .gitattributes, .DS_Store и ваш AGENTS.md не
мешают: init их не трогает.
Путь может быть абсолютным или относительным к текущему каталогу. Если путь не
указан, init работает с текущим каталогом. Другие заготовки описаны на странице
«Заготовки и окружение».
2. Соберите production-каталог
php vendor/bin/docara build production
Результат появится в build_production.
3. Проверьте статический результат
php vendor/bin/docara verify-static build_production
Продолжайте только после успешного завершения команды. Verifier проверяет страницы, локальные ссылки и fragments, ассеты, поиск, resolved plans, component catalog и Framework projection.
4. Откройте сайт по HTTP
php vendor/bin/docara serve production --host=127.0.0.1 --port=8000 --no-build
После строки:
Server started on http://127.0.0.1:8000
откройте http://127.0.0.1:8000 в браузере. Успех виден, если загрузилась
стартовая страница Docara, работают переходы и стили. Сервер занимает текущий
терминал; после проверки нажмите Ctrl+C.
Не открывайте build_production/index.html через file://: такой просмотр не
проверяет pretty routes, base_url, поиск и загрузку ассетов.
Измените страницу
- Откройте
content/ru/index.md(илиcontent/en/index.md). - Измените заголовок или текст.
- После уже выполненной полной сборки запустите
php vendor/bin/docara build production --page=/. - Повторите
verify-static. - Перезапустите HTTP preview или запустите
serve productionбез--no-build, чтобы сначала пересобрать сайт.
Обычной Markdown-странице JSON-файл не нужен. Настройки всего сайта находятся
в docara.json; section.json добавляют только для наследуемых настроек
каталога, а соседний <page>.page.json — только для настройки одной страницы.
Заготовка содержит такие файлы как рабочие примеры, а не как обязательную пару
для каждого Markdown-файла.
--page предназначен только для изменения существующего Markdown-owner. После
добавления, переименования или удаления .md, изменения маршрутизации, меню,
глобальной конфигурации или Framework lock выполните полную
php vendor/bin/docara build production.
Заготовка задаёт default_locale, явный реестр locales, locale_routing без
языкового префикса и декларативный redirects_file. Как добавить второй язык,
описано в разделе Мультиязычный сайт. Для
другой версии документации создайте отдельный site variant и output, а не
смешивайте страницы в одной сборке.
Что хранить в Git
Храните в репозитории всё, что создал init, включая .docara/engine/:
по этим файлам docara update и docara upgrade проверяют проект. Не храните
зависимости и результаты сборки. Подойдёт такой .gitignore:
/vendor/
/build_*/
/.docara-preview/
/.docara-qa/
build_production.docara/ рядом с готовым сайтом содержит отчёты сборки для
verify-static; правило /build_*/ исключает и его.
Что читать дальше
- Заготовки и окружение: какие файлы создал
initи как проверить установку - Файлы проекта
- Как устроены компоненты
- Написание страниц
- Настройка сайта
- Проверка сборки
- Публикация и откат
- Размещение на хостинге