все хорошо и красиво когда ссылки идут на подкаталоги и документы ниже по иерархии.

Если нужно сослаться на документ выше по иерархии или в боковой ветке, относительные ссылки относительно текущего документа не так уж и хороши

документ у нас может состоять из множества файлов, это скорее логическая сущность. Пусть для приамера это будет описание какого-нибудь из продуктов.

Разные документы тогда могут быть в разных репозиториях?

Например: документ "самолеты", документ "поезда", документ "аэродромы"
нужно провесить ссылки между самолеты и аэродромы

такое тоже может быть, но что это меняет?
Скажу сразу - масштаб порядка тысяч документов

Если один репозиторий, проще всего правила написать, как иерархию строить, чтобы переходы по каталогу выше единообразными были

А всё же, для чего именно отображение в гите онлайн? Почему автосборка не подходит?

сделать правила не проблема, но все же ссылки вида ../../../processes/xxx/index.adoc выглядят весьма уродливо, а так же будут ломаться при перемещении/переиеновании документов

пытаемся пользовать гит в режиме вики

сборка подходит для отдельных документов, сборка всего репозитория условно займет часы

По сути вы ищете функции, которые дают препроцессоры, но столкнулись с отдельными проблемами при их использовании

Не искали причину, почему так долго собирается?

не в этом дело, нам не нужно решать задачу времени сборки. Сборка документа происходит в браузере клиента при его открытии на просмотр в гите.

гит нам нужен ради бранчей и пулл-реквестов, чтобы управлять изменениями, делать приемку-ревью

у нас может существовать множество версий документа, так как у нас параллельно могут идти множество проектов несущих свои изменения в псевдослучайном порядке. Но в конце должно быть актуальное отражение состояния системы.

вопрос методический, а совершенно не технический)

как бы вы строили систему гиперссылок между разными независимыми документами на разных уровнях иерархии

Ваше описание проблемы с неудобными ссылками говорит об обратном, это не методически решается)

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

У вас GitHub, GitLab, BitBucket, Gitea или какой сервис?

у нас BitBucket

вот есть опасение что не хватает какой-то детали для построения такой системы ссылок

сразу скажу что превьюер может обработать любые ссылки какие потребуется, мы его допилим

Если сильно захотеть решить без технических решений, можно придумать index страницы в каждом репозитории, договориться в команде чтоб у оглавлений разделов ссылки были неизменными, и ссылаться на полную ссылку в репозитории

При перемещении оставлять заглушку с переходом на новое место. Как 301 код ответа в HTTP или "содержание устарело, см. ГК ст. НОМЕР СТАТЬИ" в наших законах

спасибо, это идея
сделать что-то типа карты коротких ссылок

например у confluence механизм ссылок основан на внутреннем идентфиикаторе докусмента, который не меняется при переименовании/перемещении документов