Налаштування та кастомізація теми 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 = "+1 (xxx) xxx-xxxx"

Переопределення стилів

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

Паттерн 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 днів.