---
id: documentation-pass-on-a-flat-wiki
type: task
title: Превратить вики репозитория в читаемый набор документации
status: validated
confidence: medium
applicability: Репозиторий, чья вики имеет страницы, но не имеет навигации, а ссылки не разрешаются
tags: [documentation, github, wiki, links]
created_at: 2026-10-10
updated_at: 2026-10-24
last_verified_at: 2026-10-24
source: user task
related: [add-nullable-column-to-list-endpoint]
---

# Пример: запись задачи

## Request

«Наша вики нечитаема; сделай из неё настоящую документацию.» Ни списка страниц, ни адресата, ни рамок.

## What was done

1. Перечислили все страницы через API, а не глазами: вики — отдельный репозиторий.
2. Пересчитали якоря всех заголовков и сравнили с оглавлением. Шесть страниц из двенадцати были
   недостижимы; оглавление перечисляло страницы, которых уже нет.
3. Сочли ссылки по целям: внутренние, межрепозиторные, изображения. Мёртвыми оказались изображения —
   вики это отдельный репозиторий, поэтому относительный путь к картинке ведёт на несуществующую
   страницу.
4. Написали файл навигации и футер только с абсолютными ссылками.
5. Проверили скриптом, разрешающим каждый якорь, затем опубликовали в режиме сухого прогона.

## Outcome

Восемь страниц плюс восемь переводов, навигация покрывает все, битых якорей ноль. Сборка и проверка
лежат в репозитории; шаг публикации — одна команда.

## Verification

```text
wiki build    # 0 ошибок
wiki verify   # 0 ошибок, 0 примечаний
внешняя проверка по опубликованным байтам: якоря пересчитаны, 0 находок
```

## Reusable parts

- Правило пересчёта якорей: строчные, пунктуация отбрасывается, пробелы в дефисы, дубликаты через
  `-1`. Длинное тире даёт два дефиса, что ломает оглавления, написанные руками.
- Правило изображений: абсолютный raw-URL, никогда относительный путь.
- Правило навигации: порядок живёт в манифесте, поэтому сайдбар генерируется, а не набирается.

## What not to repeat

- Искать якорь страницы в отрисованном HTML: документация платформы показывает пример, который
  противоречит её собственному выводу. Пересчитывать по тексту заголовка.
- Доверять «проверке ссылок», которая проверяет лишь то, что строка похожа на ссылку: она ни разу не
  разрешила якорь и двенадцать раз сообщила успех.