Ссылки

В документацию можно вставлять как внешние, так и внутренние ссылки.

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

При сборке документации Собирака проверяет все внутренние ссылки, в том числе ссылки на подзаголовки. Если внутренняя ссылка указывает на несуществующее место или не может быть интерпретирована однозначно, Собирака сообщит об этом как об ошибке.

Примеры в статье приведены для синтаксиса Markdown.

Внешние ссылки #

- [Ссылка на сайт](https://documentat.io/)
- [Ссылка на электронную почту](mailto:info@documentat.io)
- [Ссылка на телеграм-канал](tg://resolve?domain=documentatio_official)

Когда ссылка начинается с названия протокола и двоеточия, она считается внешней ссылкой. Такие ссылки Собирака не проверяет и оставляет в документации как есть.

Относительные ссылки #

- [Ссылка на соседнюю страницу](upgrade.md)
- [Ссылка на родительскую страницу](..)
- [Ссылка на страницу, соседнюю с родительской](../upgrade.md)

В качестве адреса ссылки можно указать путь относительно текущего файла. Путь может указывать как на файл нужной страницы, так и на директорию. В последнем случае ссылка будет вести на главную страницу из этой директории — например, index.md (см. Директории и индексные файлы).

Обратите внимание, что следует использовать те имена файлов и директорий, под которыми они хранятся в исходниках проекта, например: не upgrade.html, а upgrade.md. Некоторые программы для редактирования Markdown предоставляют автоматическое дополнение таких путей при вводе.

К относительной ссылке можно добавить идентификатор подзаголовка.

Абсолютные ссылки #

- [Ссылка на главную страницу](/)
- [Ссылка на произвольную страницу](/setup/upgrade.md)

Ссылки, начинающиеся со слеша, интерпретируются как точные пути к нужной странице относительно корня текущего документа (настройка paths.root). В частности, путь из одного слеша / интерпретируется как ссылка на главную страницу документации.

К абсолютной ссылке можно добавить идентификатор подзаголовка.

Междокументные ссылки #

- [Ссылка на главную страницу другого документа]($admin-manual)
- [Ссылка на произвольную страницу другого документа]($admin-manual/setup/upgrade.md)

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

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

Междокументные ссылки можно считать «самыми абсолютными» из всех внутренних ссылок в Собираке: они работают одинаково на любой странице любого документа в вашем проекте. Вы можете использовать этот формат даже для ссылок внутри одного документа, но, к сожалению, программы для редактирования Markdown не смогут дополнять и проверять такие ссылки автоматически.

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

К междокументной ссылке можно добавить идентификатор подзаголовка.

Ссылки на подзаголовки #

- [Ссылка на подзаголовок текущей страницы](#requirements)
- [Ссылка на подзаголовок другой страницы](upgrade.md#requirements)

К любой внутренней ссылке (относительной, абсолютной или междокументной) можно добавить идентификатор подзаголовка, который также называют фрагментом или якорем (anchor). Он должен отделяться от остального текста ссылки знаком #.

Идентификатор должен совпадать с идентификатором одного из подзаголовков статьи, на которую вы ссылаетесь. Об идентификаторах подзаголовков для Markdown читайте в разделе Подзаголовки. Если по указанному идентификатору найдутся два или более подзаголовка, Собирака сообщит об ошибке и остановит сборку.

Автоименование ссылок #

- [](upgrade.md)

Текст любой внутренней ссылки (относительной, абсолютной или междокументной) можно оставить пустым. В этом случае Собирака автоматически подставит в ссылку текст из заголовка или подзаголовка, на который эта ссылка ведёт. Если в метаданных страницы задано свойство title, в качестве текста будет использовано его значение.

В автоматический заголовок не включаются форматирование заголовка и автонумерация.