# Работа с вики

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

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

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

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

## Сборка

```bash
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`,
достижимость каждой страницы из навигации.

## Публикация

```bash
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` не посмотрев список | пропала страница | вернуть из истории вики-репозитория |

## Дальше

- [Выпуск версии](05-Release.ru).
- [Ловушки платформы](06-Traps.ru).