04 Wiki Workflow.ru

Работа с вики

Вики ведётся из репозитория: страницы лежат в wiki/, порядок задаёт wiki/wiki.json. Публикация — отдельный шаг, который выполняет пакет.

Почему нельзя просто отредактировать вики на GitHub

Подход	Проблема
Правка в веб-интерфейсе вики	расходится с репозиторием, ревью нет
Копия страниц в двух местах	через месяц они разные
Публикация вручную через git clone .wiki.git	забывается шаг проверки, чужие страницы теряются

Пакет держит источник в репозитории, где работает ревью и CI, а вики получает собранное дерево.

Сборка

python tools/ghagent.py wiki build
python tools/ghagent.py wiki verify

Что делает build:

1. Читает wiki/wiki.json; каждый пункт манифеста обязан существовать.
2. Каждый файл в wiki/ обязан быть в манифесте — иначе ошибка «страница невидима».
3. Переписывает ссылки: внутренние теряют .md, ссылки в дерево репозитория становятся абсолютными https://github.com/<owner>/<repo>/blob/<branch>/….
4. Относительная картинка — ошибка: вики-репозиторий дерева проекта не видит.
5. Генерирует _Sidebar.md по группам манифеста и _Footer.md со ссылками на репозиторий.

verify проверяет собранное дерево: обязательные файлы, ссылки на существующие страницы, отсутствие .md во внутренних ссылках, отсутствие относительных картинок, наличие H1, достижимость каждой страницы из навигации.

Публикация

python tools/ghagent.py wiki publish --repo owner/name            # сухой прогон
python tools/ghagent.py wiki publish --repo owner/name --push     # публикация

Флаг	Что делает	Когда нужен
без флагов	коммит в локальную копию, без отправки	всегда сначала
--push	отправляет в <repo>.wiki.git	после просмотра сухого прогона
--prune	удаляет страницы, которых нет в сборке	только осознанно
--force	публикует даже при провале проверки	почти никогда
--author-name, --author-email	подпись коммита	подпись владельца, не агента

Что печатается: добавленные, изменённые, сохранённые (kept) страницы и хеш коммита. Страницы на сервере, которых нет в сборке, по умолчанию сохраняются — потеря чужих страниц не происходит молча.

Что писать на странице

1. H1 — название, совпадает с именем файла без .md.
2. Абзац: зачем эта страница.
3. Таблица или список: конкретика, не рассуждения.
4. Блок кода с языком для каждой команды.
5. В конце — ссылка на соседнюю страницу или репозиторий.

Ловушки

Ловушка	Признак	Что делать
Вики-репозитория ещё нет	remote: Repository not found при публикации	сохранить первую страницу в интерфейсе (Wiki → New page): пушем репозиторий не создаётся
Ссылка с .md	открывается сырой файл	убрать расширение
Картинка внутри wiki/	не отображается	положить в дерево репозитория, ссылаться абсолютно
Страница не в манифесте	нет в навигации	добавить в wiki.json
Кириллический якорь	#Установка не находится	сравнение без учёта регистра, писать как в заголовке
--prune не посмотрев список	пропала страница	вернуть из истории вики-репозитория

Дальше

• Выпуск версии.
• Ловушки платформы.