---
name: github-wiki
description: Ведение GitHub Wiki как документации проекта — страницы в репозитории, манифест порядка, _Sidebar и _Footer, переписывание ссылок под плоское пространство вики, сборка, проверка и публикация. Загружать, когда документация переросла README, когда вики есть но в ней нет навигации, когда ссылки в вики ведут в никуда или картинки не отображаются.
---

# Вики, которая работает

## Что нужно знать до первой страницы

| Свойство платформы | Следствие |
|---|---|
| Вики — отдельный git-репозиторий `<repo>.wiki.git` | дерева основного репозитория она не видит |
| Пространство плоское | подкаталогов нет, страница = файл в корне |
| Ссылка на страницу — без `.md` | `` `[Установка](01-Install)` `` |
| `_Sidebar.md` и `_Footer.md` — единственная навигация | без них страницы не находятся |
| Относительная картинка не работает | картинка в основном репозитории + абсолютный URL |
| Заголовок страницы = имя файла | переименование файла меняет URL |
| Индексируются поисковиками только вики с 500+ звёзд и запретом публичного редактирования | для поиска нужен GitHub Pages |
| Приватная вики требует платного плана | не обещать её на бесплатном |

## Структура в репозитории

```text
wiki/
  wiki.json      манифест: порядок, группы, заголовок, ссылка на репозиторий
  Home.md        первая страница
  01-Install.md
  02-Setup.md
```

Каждый файл обязан быть в манифесте, каждый пункт манифеста обязан существовать. Иначе
`wiki build` падает: невидимая страница считается потерянной, а «пустая» ссылка —
дефектом.

## Сборка и проверка

```bash
python <pack>/tools/ghagent.py wiki build
python <pack>/tools/ghagent.py wiki verify
```

`build` переписывает страницы в `.ghagent/wiki/`: внутренние ссылки теряют `.md`, ссылки
в дерево репозитория становятся `https://github.com/<owner>/<repo>/blob/<branch>/…`,
относительная картинка становится ошибкой. `verify` проверяет собранное дерево:
`Home`/`_Sidebar`/`_Footer` на месте, ссылки ведут на существующие страницы, ни одна
страница не забыта в навигации, у страницы есть `H1`.

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

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

Правила, которые нельзя нарушать:

1. **Сухой прогон обязателен.** Он печатает, что добавится, что изменится и что
   **сохранится** (`kept`).
2. **Чужое не удаляется.** Страницы на сервере, которых нет в сборке, сохраняются.
   Удаление — только `--prune` и только после просмотра списка.
3. **Проверка перед публикацией.** `publish` отказывается отправлять дерево с ошибками;
   `--force` — осознанное решение, а не обход.
4. **`Home.md` обязателен.** Публикация без него не начинается.

## Якоря и перекрёстные ссылки

- Якорь = заголовок в нижнем регистре, знаки препинания удалены, пробелы → дефисы.
- Тире в заголовке даёт **двойной** дефис: `## Помочь — фактами` → `#помочь--фактами`.
- Повтор заголовка получает `-1`, `-2`.
- Сравнение якорей делается без учёта регистра: документация GitHub сама себе
  противоречит в примере с греческой буквой.

## Ловушки

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

## Критерий готовности

- `wiki build` и `wiki verify` — код `0`.
- Сухой прогон показывает только ожидаемые файлы, `kept` просмотрен.
- После `--push` страница открывается, навигация работает, ссылки не 404.