Оглавления

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

Оглавления генерируются на одном из последних шагов сборки, когда уже известны и заголовки всех страниц, и даже подзаголовки внутри страниц. Это позволяет, если необходимо, создавать «сквозные оглавления» — оглавления, в которые включены пункты, ведущие на подзаголовки каждой страницы.

В качестве текста ссылки на каждую страницу используется свойство toc_title или title из её метаданных или заголовок первого уровня.

Оглавления по подразделам и страницам #

С помощью специальной директивы @toc технический писатель может поместить на любую страницу список ссылок на её подразделы или дочерние страницы.

При сортировке ссылок и формировании их текстов директива следует правилам, описанным в разделах Файлы и директории и Файлы навигации.

Составление оглавлений вручную #

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

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

Разработчикам тем оформления для Собираки доступны две функции для генерации оглавлений:

  • toc() — полное оглавление от корня текущего документа;
  • local_toc() (только для HTML) — оглавление по подразделам текущей страницы.

Результаты обеих функций представляют собой объектно-ориентированные аналоги вывода директивы @toc. Разработчик темы должен выполнить рекурсивную итерацию по элементам результата и поместить их в нужное место страницы. Примеры итерации можно посмотреть в специальном простом шаблоне simple/web.html.

Обеим функциям передаются параметры по умолчанию в соответствии с настройками web.combined_toc, web.toc_depth и pdf.toc_depth. Например, при настройке web.combined_toc: always результат вызова toc() будет аналогичен выводу директивы @toc --combined.