Как собрать аккуратную документацию без гигабайтов node_modules

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

Часто в таких ситуациях берут Docusaurus или VuePress. Они хороши, но тянут за собой целое море пакетов из npm. Если вы хотите обойтись без Node.js в сборке и цените молниеносную генерацию, стоит взглянуть на тему Hugo Book от Александра Шпака.

Что это за тема и для кого она

Hugo Book — это минималистичный шаблон для генератора статических сайтов Hugo, стилизованный под обычную книгу с боковым меню. Автор проекта, Александр Шпак, ставил перед собой понятную цель: сделать аккуратную тему оформления, которая быстро работает и не заставляет пользователя часами ковыряться в конфигурационных файлах.

У репозитория набралось больше 4000 звезд на GitHub, что вполне солидно для специализированной темы Hugo. Шаблон подхватывает стандартный Markdown и автоматически выстраивает древовидную структуру страниц на основе вложенности папок.

Screenshot

Главные особенности под капотом

В отличие от многих современных веб-инструментов, Hugo Book придерживается строгой диеты. Основная функциональность сайта работает вообще без JavaScript. Переключение мобильного меню, разворачивание вложенных разделов и древовидная навигация сделаны на чистом CSS.

Из практических вещей тут есть:

Готовая тёмная тема. Она автоматически подстраивается под системные настройки операционной системы, но переключатель можно вывести и вручную.
Мультиязычность из коробки. Hugo умеет вести параллельные структуры папок для разных языков, а тема корректно отрисовывает переключатель версий.
Удобные встроенные шорткоды. Для оформления заметок, предупреждений, красивых кнопок и вкладок с кодом не нужно изобретать свои костыли.
Встроенный поиск и комментарии. Поиск можно задействовать через встроенный легкий скрипт (FlexSearch) или сторонние сервисы.

Принцип минимального вмешательства

Автор отдельно отмечает в философии проекта: тема не должна мешать пользовательским макетам и перегружать конфигурацию. Для запуска сайта буквально не нужно задавать никаких специфических параметров в config.toml или hugo.toml. Шаблон подхватывает стандартную структуризацию контента Hugo.

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

Быстрый старт

Для работы требуется установленная расширенная версия генератора (Hugo extended) версии 0.158 или выше. Процесс разворачивания занимает две минуты.

Самый простой путь — использовать готовый стартовый репозиторий:

git clone https://github.com/alex-shpak/hugo-book-starter my-docs
cd my-docs
git submodule update --init --remote
hugo server --minify

После запуска локального сервера по адресу http://localhost:1313 откроется готовый сайт с документацией. При изменении Markdown-файлов Hugo обновляет страницу в браузере практически мгновенно. Время сборки сайтов на пару сотни страниц обычно не превышает доли секунды.

Шорткоды для верстки текста

Стандартный Markdown бывает слишком бедным, когда надо выделить важное примечание или сделать колонки. В Hugo Book есть набор встроенных шорткодов.

Например, для красивых информационных блоков используется шорткод hint:

{{< hint info >}}
Здесь можно написать полезную подсказку для читателя.
{{< /hint >}}

{{< hint warning >}}
А так оформляется предупреждение о возможных ошибках.
{{< /hint >}}

А если нужно показать варианты кода для разных операционных систем или языков программирования, пригодится шорткод tabs:

{{< tabs "unique-id" >}}
{{< tab "Linux" >}}
sudo apt install my-tool
{{< /tab >}}
{{< tab "macOS" >}}
brew install my-tool
{{< /tab >}}
{{< /tabs >}}

Подход к версионированию

Тема распространяется по лицензии MIT. Автор использует инкрементальное версионирование (например, v0.13.0, v0.14.0). Ломающие изменения между релизами иногда случаются, поэтому для продакшена лучше фиксировать конкретный тег, а не сидеть на ветке main.

Где это пригодится

Тема отлично подойдет для:

Технической документации к Open Source библиотекам
Внутренней базы знаний команды или корпоративной Wiki
Инструкций по развертыванию сервисов и API
Личного инженерного блога или сбора заметок

Если вам нужен тяжелый интерактив, трехмерная графика прямо в документации или глубокая интеграция с React-компонентами, Hugo Book вряд ли подойдет. Тут придется копать в сторону Docusaurus или Astro Starlight. Но для обычных задач по документации простоты Hugo Book хватает с головой.

Подводные камни

При всех плюсах надо понимать нюансы инфраструктуры Hugo. Шаблонизатор Go HTML Templates, который лежит в основе Hugo, имеет специфический синтаксис. Если вам захочется кардинально переписать структуру шапки или подвала, придется потратить время на изучение структуры шаблонов Go.

Кроме того, search-индекс для локального поиска генерируется при сборке. Для огромных сайтов на десятки тысяч страниц файл поиска может получиться увесистым, хотя для обычных руководств это вообще не проблема.

В сухом остатке

Hugo Book — это честный инструмент без лишнего глянца. Он делает ровно то, что обещает: превращает пачку папок с Markdown в быстрый, аккуратный и читаемый сайт. Без установки npm-пакетов, без долгой сборки и без сложной настройки.