Поставить и запустить

#Что это за тема

Тема для учебных гайдов, которые читают подряд, а не вразброс. Контент раскладывается в три уровня: рубрики → серии → гайды. Серия — это папка внутри рубрики: членство определяется тем, где лежит гайд; всё остальное — «часть N из M» в кикере, панель-оглавление слева, мост с «осталось ~N мин» внизу — считается на сборке. Гайд — это папка: рядом с текстом лежат его интерактивные виджеты, стили и обложка, и переносится он целиком, одной папкой. Всё, что видно на этом демо, — лента, поиск, палитры, генерация обложек — штатные механизмы темы: само демо собрано на ней же.

Из инструментов нужны два бинаря. Первый — обычный hugo, не extended: Sass в теме нет, а esbuild для JS встроен в стандартный бинарь. Второй — pagefind, полнотекстовый поиск по собранному сайту. Node, npm и node_modules не участвуют ни в сборке, ни в разработке. Минимальная версия Hugo объявлена в конфиге темы: слишком старый бинарь остановит сборку с внятной ошибкой, а не со странным поведением.

#Три способа установить

Пути ниже — плейсхолдеры: подставь адрес репозитория темы.

Hugo Module — основной способ. В конфиг сайта:

[module]
  [[module.imports]]
    path = "github.com/user/theme"

Затем hugo mod get -u (если сайт ещё не модуль — один раз hugo mod init github.com/user/site). Версии резолвятся по semver-тегам темы; для локальной правки темы — replace в go.mod сайта.

Git submodule — если модули не хочется:

git submodule add https://github.com/user/theme themes/theme

и theme = "theme" в конфиге. В CI не забудь checkout с submodules: recursive.

Копия в themes/ — клон или распакованный архив в themes/theme плюс тот же theme = "theme". Обновления руками; зато способ годится, чтобы просто посмотреть тему без обязательств.

#Минимальный конфиг

baseURL = "https://example.org/"
title = "Мой учебник"
theme = "theme"                # не нужен при установке модулем
defaultContentLanguage = "ru"

[languages.ru]
  languageCode = "ru"
  languageName = "Русский"
  weight = 1

[taxonomies]
  tag = "tags"

[[menus.main]]
  name = "Гайды"
  url = "/guides/"
  weight = 10

Блок [languages.ru] выглядит лишним, пока язык один, но он делает добавление второго языка аддитивным шагом, а не миграцией конфига. Остальное поведение настраивается через [params] — hero-строка главной, число видимых постов ленты, «гайд недели», палитра по умолчанию, — и у всего есть дефолты: сайт собирается и без единого параметра. Полный реестр — в docs/params.md темы.

#Структура контента

content/
├── _index.md              # главная: hero-строка и данные
└── guides/
    ├── _index.md          # рубрика: label, lead
    ├── my-first/
    │   └── index.md       # одиночный гайд = папка (leaf bundle)
    └── track/             # серия = подпапка рубрики
        ├── _index.md      # метаданные серии: title, description
        └── part-one/
            └── index.md   # часть — та же папка гайда, уровнем глубже

Имена секций — свои: тема оперирует «секциями», «сериями» и «гайдами» и не хардкодит ни названий рубрик, ни предметных слов. Учебник про базы данных и учебник про акварель раскладываются одинаково.

#Собрать

hugo server                        # разработка
hugo && pagefind --site public     # прод: сайт + поисковый индекс

Команд две, потому что pagefind строит индекс по уже собранному сайту. В dev без индекса поиск не ломается: модалка тихо подсказывает, какой командой он собирается.

Теперь ты можешь развернуть сайт на теме с нуля и собрать его в один прогон — осталось его наполнить.

#Что дальше

Пустой сайт собирается, но показывать пока нечего. Следующая часть — про первый гайд: каркас одной командой, канон front matter и живой виджет за два касания.