Hextra

Тема для движка Hugo

Поиск по сайту

Поиск включён сразу и ничего настраивать не нужно. Работает в браузере, на FlexSearch.

[params.search.flexsearch]
  index = "summary"

Плюсы

• Готовая раскладка документации: боковое меню по разделам, хлебные крошки, оглавление, переход к следующей странице.
• Не нужен Node.js: тема работает на одном Hugo, CSS уже собран.
• Поиск по сайту работает сразу: FlexSearch в браузере, без сервера и внешних сервисов (подробнее — в разделе «Поиск по сайту»).
• Интерфейс уже переведён на все языки проекта: en, uk, ru, pt.
• Inject Partials — главный плюс для доработок. В теме заранее есть пустые шаблоны-заготовки в местах, куда обычно нужно что-то добавить. Достаточно создать в своём проекте файл с тем же именем в layouts/_partials/custom/, и Hextra вставит его на все страницы. Саму тему трогать не нужно, поэтому её можно обновлять без потери своих правок. Так устроены и другие хорошие темы Hugo: в Hugo Book это inject/*.html, в PaperMod — extend_head.html и extend_footer.html.
• Точки встраивания в Hextra: head-end.html — в конец <head> (метатеги, hreflang, счётчики); banner.html — баннер над шапкой; navbar-title.html — логотип и название в шапке; page-begin.html и page-end.html — начало и конец страницы; content-begin.html и content-end.html — до и после текста статьи; footer.html — подвал. В этом просмотрщике через них сделаны hreflang и все таблицы базы.
• Боковое меню управляется со страницы: sidebar.exclude — скрыть статью или рубрику, sidebar.hide — убрать меню на странице, sidebar.open и separator.
• Пошаговые инструкции: шорткод steps, внутри — обычные заголовки и текст Markdown, удобно для перевода ИИ.
• Код подсвечивает сам Hugo при сборке (все языки Chroma), есть кнопка «копировать».
• Поиск грузит индекс отдельным файлом на язык только при первом поиске — страницы остаются лёгкими.
• Что попадает в индекс поиска, выбирается настройкой params.search.flexsearch.index: весь текст (content), краткое описание (summary), заголовки (heading) или только названия статей (title) — без правки шаблонов.
• Тёмная тема, карточки, вкладки, врезки, пошаговые блоки, дерево файлов, диаграммы Mermaid и формулы.
• Умеет отдавать llms.txt и Markdown-версии страниц для ИИ (включается настройкой).

Минусы

• Переключатель языков показывает все языки сайта, даже если у страницы нет перевода, и ведёт на главную другого языка.
• Нет hreflang вообще.
• Колонка текста ограничена 72rem, а справа всегда оставлено место под оглавление, даже если его выключить. Широкие таблицы не помещаются.
• toc: false прячет оглавление, но место под него справа остаётся пустым.
• Оглавление видно только на экране шире 1280 пикселей; на узком окне, планшете и телефоне его нет совсем.
• Португальский интерфейс — европейский, не бразильский; <html lang> берётся из ключа языка (pt), а не из locale (pt-BR).
• Свои Tailwind-классы в шаблонах не заработают без пересборки CSS темы через Node.js: в собранный CSS попали только классы самой темы. Проще писать обычный CSS.
• Первая сборка требует интернет: FlexSearch скачивается с CDN.
• Почти нет микроразметки Schema.org: у хлебных крошек нет BreadcrumbList, у страниц нет Article в JSON-LD — только несколько meta itemprop из встроенного шаблона Hugo. Добавлять придётся своим кодом через head-end.html.
• Поиск не понимает словоформы и не ищет по таблицам, которые строит шаблон.

Общее впечатление

Hextra — тема для документации и баз знаний в духе Nextra. На ней собран локальный просмотрщик этой базы, поэтому всё ниже проверено на деле, а не по описанию.

Для каталога или справочника тема подходит хорошо: боковое меню, поиск и переводы интерфейса работают из коробки. Для мультиязычного сайта у неё два серьёзных пробела: меню языков и отсутствие hreflang. Оба закрываются своими файлами поверх темы, примерно за полчаса работы. Без этих доработок публиковать мультиязычный сайт на Hextra не стоит.

Мнение автора: рекомендую тестировать — по сравнению с Lotus Docs на тех же данных Hextra явно выигрывает. Меню языков и hreflang всё равно придётся доработать самому.

Дизайн менять неудобно: CSS темы собран заранее, и для своих Tailwind-классов придётся ставить Node.js и пересобирать стили. Если внешний вид нужен свой, проще писать обычный CSS поверх.

Что пришлось доработать

Переключатель языков показывает только существующие переводы

{{- if or (eq $language.Lang $currentLanguageLang) (where $page.AllTranslations "Language.Lang" $language.Lang) -}}
  … пункт меню языка …
{{- end -}}

hreflang только на существующие переводы

{{- range .AllTranslations }}
<link rel="alternate" hreflang="{{ .Language.Locale }}" href="{{ .Permalink }}">
{{- end }}

Переводы интерфейса для en, uk, ru, pt-BR

Атрибут lang в нужном формате

<html lang="{{ partial "utils/hugo-compat/language-locale.html" .Site.Language | default .Site.Language.Lang }}" …>

Ширина страницы под широкие таблицы

:root { --hextra-max-content-width: 100%; }
.hextra-max-page-width:has(#stacks) > .hextra-toc { display: none !important; }

Результаты по требованиям с этой темой

Многие результаты задаёт сам Hugo, и они одинаковы для всех тем: языковые адреса, работа без базы данных, генерация страниц из данных. От темы зависят меню языков, hreflang, поиск и места для своего кода — их нужно проверять у каждой темы отдельно. Значок в пунктирной рамке — результат перенесён из проверки с другой темой этого движка. Наведите на значок, чтобы увидеть подробности.