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

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

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

Hugo по умолчанию имеет возможность ссылаться на заголовки.

Если вы напишете такой markdown:

# First
## Second
### Third

По умолчанию он преобразуется в такой html-код:

<h1 id="first">First</h1>
<h2 id="second">Second</h2>
<h3 id="third">Third</h3>

Обратите внимание на атрибут id в тегах заголовков. Если добавить #id в конец URL поста, браузер перенаправит вас непосредственно к этому заголовку. Для моего примера добавление #first к URL приведет к переходу к тегу <h1 id="first">First</h1>.

Эта возможность описана в документации Hugo.

Так что все, что нам нужно сделать — изменить разметку, чтобы эта ссылка была видна.

Разметка

Hugo имеет полезную функцию под названием Markdown Render Hooks.

По сути, вы можете переопределить то, как некоторые элементы рендерятся из markdown-текста. Нам нужно переопределить Heading.

Для этого нужно добавить layouts/_default/_markup/render-heading.html в блог или в директорию вашей пользовательской темы. Мой шаблон ниже:

<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }}
{{- if and (ge .Level 1) (le .Level 6) }}{{" " -}}
<a class="anchor" href="#{{ .Anchor | safeURL }}">
    <i class="fas fa-hashtag"></i>
</a>
{{- end -}}
</h{{ .Level }}>

Давайте опишем это подробнее. Это шаблон, который будет использоваться для тегов <hN>, где N — от 1 до 6, что видно в условии if. Я создал тег <a>, ссылающийся на переменную anchor, и использовал иконку fas fa-hashtag из Font Awesome. Вместо иконки можно использовать текстовую ссылку или что угодно другое.

Результат

Вот и все, что мне нужно было сделать для реализации якорных ссылок на заголовки для блога на Hugo. Вы можете увидеть "демо" на этом сайте. Обратите внимание на иконку решетки рядом с каждым заголовком внутри любого поста.

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