# Ловушки платформы

Четырнадцать мест, где GitHub ведёт себя не так, как ожидает человек, пишущий документацию.
Каждая ловушка либо подтверждена документацией GitHub, либо замерена на живом репозитории.

| Ловушка | Признак | Что делать |
|---|---|---|
| Вики почти не индексируется | страница есть, в поиске её нет | по документации индексируются только вики с 500+ звёзд и запретом публичного редактирования; для поиска — GitHub Pages |
| Приватная вики требует платного плана | вики нет в приватном репозитории | на бесплатном плане её не будет |
| Вики-репозиторий не создаётся пушем | `Repository not found` на `<repo>.wiki.git` | сохранить первую страницу в интерфейсе; после этого публикация работает |
| Вики — плоское пространство | ссылка на `docs/page` не работает | все страницы в корне вики-репозитория |
| Относительная картинка в вики | не отображается | абсолютный URL на файл в основном репозитории |
| `.md` в ссылке вики | открывается сырой файл | ссылки на страницы — без расширения |
| Кириллический якорь | `#Установка` не находится | знаки препинания удаляются, пробелы → дефисы, регистр нижний |
| Тире в заголовке | двойной дефис в якоре | тире удаляется, два соседних пробела дают два дефиса |
| `PUT /topics` заменяет список | пропали темы, которых не касались | слить с существующими и перечитать |
| Больше 20 тем | часть тем исчезла | API хранит не больше 20 |
| Pages в приватном репозитории | `422 Your current plan does not support GitHub Pages for this repository` | на бесплатном плане недоступно |
| Сборка Pages асинхронна | сразу после включения 404 | ждать сборку, потом проверять URL |
| `gh api --jq .content` для README | base64 с переводами строк | `-H 'Accept: application/vnd.github.raw'` |
| Пример якоря в документации GitHub | заглавная греческая буква в якоре | сравнивать якоря без учёта регистра |

## Три ловушки, которые дороже остальных

### Вики не заменяет сайт

Документация GitHub говорит прямо: индексируются только вики с 500+ звёзд и запретом
публичного редактирования, а если нужно индексирование — используйте GitHub Pages.
Поэтому «напишем вики, и нас найдут» — неверная стратегия: вики служит тем, кто уже
пришёл в репозиторий.

### `--prune` удаляет чужое

Публикация по умолчанию сохраняет страницы, которых нет в сборке, и печатает их список.
Удаление — отдельный флаг. Причина проста: на сервере могли быть страницы, написанные
руками, и потерять их молча нельзя.

### Проверка, осмотревшая ноль объектов

Пустое дерево, сломанный путь, отсутствующий файл — всё это даёт не «зелёный результат»,
а ошибку или строку `coverage.skipped`. Иначе агент отчитывается об успехе, ничего не
проверив, и это хуже падения.

## Как проверять ловушки самому

```bash
python tools/ghagent.py doc --root . --json
python tools/ghagent.py audit --repo owner/name
python tools/ghagent.py wiki verify
```

`doc --json` содержит поле `rules_examined`: по нему видно, сколько объектов осмотрело
каждое правило. Если для правила там ноль — правило не сработало, а не «прошло».

## Дальше

- [Импорт в другой агент](07-Import.ru).
- [Контракты файлов](03-Repository-Contract.ru).