Repository navigation
06 Traps.ru
Четырнадцать мест, где 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. Поэтому «напишем вики, и нас найдут» — неверная стратегия: вики служит тем, кто уже пришёл в репозиторий.
Публикация по умолчанию сохраняет страницы, которых нет в сборке, и печатает их список. Удаление — отдельный флаг. Причина проста: на сервере могли быть страницы, написанные руками, и потерять их молча нельзя.
Пустое дерево, сломанный путь, отсутствующий файл — всё это даёт не «зелёный результат»,
а ошибку или строку coverage.skipped. Иначе агент отчитывается об успехе, ничего не
проверив, и это хуже падения.
python tools/ghagent.py doc --root . --json
python tools/ghagent.py audit --repo owner/name
python tools/ghagent.py wiki verifydoc --json содержит поле rules_examined: по нему видно, сколько объектов осмотрело
каждое правило. Если для правила там ноль — правило не сработало, а не «прошло».
репозиторий · релизы · MIT