Однажды приходит понимание того, что нашим замечательным страницам с объемным контентом и множеством заголовков и подзаголовков чего-то не хватает, а именно - оглавления.

Конечно, hugo умеет автоматически создавать оглавление страницы, собирая заголовки из области контента {{.Content}}. Для этого достаточно добавить в шаблон страницы со статьей блок {{.TableOfContents}}.

Можно даже добавить щепотку логики в такое решение: например, выводить оглавления только в случаях, когда объем контентного содержимого превышает определенное количество слов (в нашем примере - 400).

Для этого нужно создать файл шаблона оглавления:

layouts/partials/toc.html

со следующим кодом:

{{ if and (gt .WordCount 400 ) (.Params.toc) }}

{{ end }}

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

Что же, создадим файл с шорткодом для вывода оглавления:

layouts/shortcodes/toc.html

со следующим кодом:

Содержание
{{.Page.TableOfContents}} 

в данном случае использование конструкции:

{{.TableOfContents}} 

будет неверным и неминуемо приведет к ошибке при сборке сайта.

Теперь для вызова оглавления достаточно создать шорткод:

{{< toc >}}

Казалось бы все замечательно. Но есть и ложка дегтя. Предложенное решение не позволяет назначать тег заголовка h1...h6 для первого уровня вложенности оглавления. В оглавлении отсчет всегда ведется от h1. Так как для контента стартовыми заголовками обычно являются теги h2 или h3, мы получаем непрезентабельный внешний вид страницы и лишние уровни вложенность списков

• • в HTML-коде.

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

    В случае, если стартовым заголовком для статьи является тег уровня h3, достаточно заменить:

    {{.Content}}
    
    

    на код:

    {{ .Content | replaceRE `` `

  ` | safeHTML}}

  и мы получим великолепное оглавление для страницы.

  ---

  Спасибо за внимание.