Настройка и кастомизация темы Hugo

Настройка и кастомизация темы Hugo

Установить тему Hugo несложно. Правильно её кастомизировать — уже задача с нюансами. Главное правило: никогда не редактировать файлы внутри themes/. Любые изменения в директории темы перезаписываются при обновлении. Hugo предусматривает механизм override через корневые папки проекта.

Подключение темы

Способ 1: Git submodule (рекомендуется)

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke

В hugo.toml:

theme = "ananke"

При клонировании репозитория:

git clone --recurse-submodules https://github.com/yourorg/yoursite

Способ 2: Hugo Modules (современный подход)

# hugo.toml
[module]
  [[module.imports]]
    path = "github.com/theNewDynamic/gohugo-theme-ananke"

hugo mod init github.com/yourorg/yoursite
hugo mod get github.com/theNewDynamic/gohugo-theme-ananke

Hugo Modules работают через Go modules proxy, версионируются через go.sum.

Механизм override

Hugo ищет файлы по приоритету: корневые папки проекта → папки темы. Это значит, что файл layouts/partials/header.html в корне проекта полностью заменяет themes/themename/layouts/partials/header.html.

myproject/
├── layouts/
│   └── partials/
│       └── header.html    ← этот файл используется
└── themes/
    └── mytheme/
        └── layouts/
            └── partials/
                └── header.html    ← этот игнорируется

Для кастомизации части шаблона: скопировать файл из темы в корневой layouts/, затем редактировать копию.

Параметры темы через hugo.toml

Большинство тем читают настройки из секции [params]. Документация темы перечисляет доступные параметры:

[params]
  logo = "/images/logo.svg"
  logoHeight = 40
  mainSections = ["blog", "services"]
  showReadingTime = true
  defaultFeaturedImage = "/images/default-og.jpg"
  googleFonts = "Montserrat:300,400,600"
  footerText = "© 2024 Компания. Все права защищены."

[params.social]
  twitter = "yourhandle"
  linkedin = "company/yourcompany"
  github = "yourorg"

[params.contact]
  email = "[email protected]"
  phone = "+7 (xxx) xxx-xx-xx"

Переопределение стилей

Темы обычно предоставляют точку входа для кастомных стилей. Два паттерна:

Паттерн 1: Custom CSS файл Тема читает переменную params.customCSS:

[params]
  customCSS = ["/css/custom.css"]

Файл static/css/custom.css добавляется к стилям темы.

Паттерн 2: Override переменных SCSS Если тема использует SCSS с переменными, создаём assets/sass/_variables_override.scss:

// Override темы
$primary-color: #2563eb;
$font-family-base: 'Inter', sans-serif;
$border-radius-base: 4px;
$container-max-width: 1280px;

В override-файле assets/sass/main.scss:

@import "variables_override";
@import "../../../themes/mytheme/assets/sass/main"; // путь к теме
@import "custom";

Кастомизация навигации

Меню в Hugo настраивается через конфиг, не через тему:

[[menus.main]]
  name = "Главная"
  url = "/"
  weight = 1

[[menus.main]]
  name = "Услуги"
  url = "/services/"
  weight = 2
  [menus.main.params]
    icon = "briefcase"

[[menus.main]]
  name = "Блог"
  url = "/blog/"
  weight = 3

[[menus.footer]]
  name = "Политика конфиденциальности"
  url = "/privacy/"
  weight = 1

Темы рендерят {{ range .Site.Menus.main }} — переопределять партиал навигации не нужно, если только не нужна нестандартная разметка.

Частичное переопределение шаблонов

Пример: в теме есть layouts/partials/footer.html, но нужно добавить блок с контактами.

1. Скопировать themes/mytheme/layouts/partials/footer.html в layouts/partials/footer.html
2. Внести изменения

Если тема хорошо структурирована, footer разбит на подпартиалы:

layouts/partials/footer/
  ├── contacts.html
  ├── nav.html
  └── copyright.html

Тогда достаточно переопределить только layouts/partials/footer/contacts.html.

Добавление нового типа страниц

Если тема не предусматривает, например, страницы «Команда»:

content/team/
  _index.md          # Список команды
  ivan-petrov.md     # Страница сотрудника

layouts/team/
  list.html          # Шаблон списка
  single.html        # Шаблон страницы сотрудника

# content/team/ivan-petrov.md
---
title: "Иван Петров"
role: "Технический директор"
photo: "ivan.jpg"
order: 1
---
Биография и описание...

Обновление темы

# Git submodule
git submodule update --remote themes/mytheme

# Hugo Modules
hugo mod get -u github.com/theNewDynamic/gohugo-theme-ananke

После обновления проверять: не сломались ли overridden шаблоны из-за изменений в теме. CI-пайплайн должен включать hugo --buildFuture --buildDrafts для проверки.

Сроки

Настройка готовой темы под контент клиента (цвета, шрифты, меню, параметры) — 1–3 дня. Глубокая кастомизация с override шаблонов, добавлением новых типов контента, кастомными стилями — 3–7 дней.