Ставимо Hugo

Thu, 27 Aug 2026 22:24:40 +0300

Колись, у старі добрі часи, писав трохи технічних статей на платформі Blogger - було прикольно, й часом корисно повернутися в часі й повторити якийсь сетап.

І ось @Schistos почав свої сетапи описувати подібним чином, накрило ностальгією й пішов досліджувати тему, що зараз актуальне. Ну й знайшов кілька проєктів з генерації статичних сайтів, проте найбільше до душі припав Hugo, ось ви на нього зараз й дивитеся 😉

Як це працює?

📝 Примітка

Hugo - це статичний генератор сайтів. Ви пишете контент у Markdown-файлах, а Hugo перетворює їх на готові HTML/CSS/JS сторінки під час збірки. Це забезпечує максимальну швидкість завантаження та безпеку, оскільки на сервері немає бази даних чи активного бекенду.

Це зручно тримати в git-репозиторії й налаштувати CI/CD для збірки й публікації в GitHub/GitLab Pages, чим ми й займемося.

Вибір теми

Для початку йдемо на themes.gohugo.io й обираємо те, що подобається. Я, після кількох годин перегляду усіх можливих і неможливих тем, зупинив свій вибір на темі Stack. Йдемо на GitHub теми й у README.md бачимо, що автор створив шаблон репозиторію, який можна просто використати для швидкого розгортання, проте ми не шукаємо простих шляхів, тому будемо робити все вручну. Хостити я збираюся не на GitHub, а на GitLab, тому дещо доведеться адаптувати під себе у будь-якому разі.

Встановлення Hugo

Ставимо Hugo і Git:

1

sudo pacman -Sy hugo git

І перевіряємо чи все ок:

1
2


hugo version
hugo v0.165.0+extended+withdeploy linux/amd64 BuildDate=unknown

Створюємо проєкт

1

hugo new project blog.hardfault.win

Нам дає трішки підказок щодо того що робити далі. Глянемо що вже є:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


cd blog.hardfault.win && hugo server -D

Watching for changes in archetypes, assets, content, data, i18n, layouts, static
Watching for config changes in hugo.toml
Start building sites …
hugo v0.165.0+extended+withdeploy linux/amd64 BuildDate=unknown

WARN found no layout file for "html" for kind "home": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN found no layout file for "html" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

 │ EN
──────────────────┼────
 Pages │ 4
 Paginator pages │ 0
 Non-page files │ 0
 Static files │ 0
 Processed images │ 0
 Aliases │ 0
 Cleaned │ 0

Built in 2 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Отже, бачимо список директорій, за якими Hugo відстежує зміни, і одразу ж попередження про те, що він не має шаблонів для необхідних сторінок - це треба виправити.

Встановлюємо тему

Hugo використовує Go modules для керування залежностями, тому перетворимо наш проєкт на Go модуль:

1
2
3
4


hugo mod init blog.hardfault.win
go: creating new go.mod: module blog.hardfault.win
hugo: to add module requirements and sums:
 hugo mod tidy

Переглянемо його:

1
2
3


module blog.hardfault.win

go 1.26.6

Далі - додаємо залежність від нашої теми:

1
2
3
4
5


# ...

[module]
 [[module.imports]]
 path = "github.com/CaiJimmy/hugo-theme-stack/v4"

Перезапускаємо наш сервер:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


hugo server -D
Watching for changes in archetypes, assets, content, data, i18n, layouts, static
Watching for config changes in hugo.toml, go.mod
Start building sites …
hugo v0.165.0+extended+withdeploy linux/amd64 BuildDate=unknown


 │ EN
──────────────────┼────
 Pages │ 8
 Paginator pages │ 0
 Non-page files │ 0
 Static files │ 0
 Processed images │ 0
 Aliases │ 3
 Cleaned │ 0

Built in 33 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Warning-ів немає - можна переглянути у браузері:

Поки не густо, але вже працює. Проглянемо поточний граф залежностей:

1
2


hugo mod graph
blog.hardfault.win github.com/CaiJimmy/hugo-theme-stack/v4@v4.0.3

Підлаштування теми під себе

💡 Порада

Щоб зручніше переглядати вихідний код теми та вносити в нього правки (якщо це потрібно), використовуйте команду hugo mod vendor. Вона завантажить копію модуля в локальну директорію _vendor, що дозволить шукати по коду теми за допомогою IDE.

1

hugo mod vendor

Це створить директорію _vendor у нашому проєкті:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


tree -d _vendor -L 5
_vendor
└── github.com
 └── CaiJimmy
 └── hugo-theme-stack
 └── v4
 ├── archetypes
 ├── assets
 ├── config
 ├── data
 ├── i18n
 └── layouts

11 directories

Скопіюємо й перглянемо конфіги з теми в проєкт:

1

cp -r _vendor/github.com/CaiJimmy/hugo-theme-stack/v4/config .

1
2
3
4
5
6
7


tree config
config
└── _default
 ├── module.toml
 └── params.toml

2 directories, 2 files

module.toml - тут тільки залежності від Hugo, а ось в params.toml знаходяться всі основні налаштування теми.

📌 Важливо

Щоб конфігурації не були розкидані по всьому проєкту, краще перемістити кореневий hugo.toml до інших конфігів у config/_default/ та розбити його на тематичні файли.

Переміщуємо файл:

1

mv hugo.toml config/_default/

І наводимо ладу: import із config.toml перемістимо в module.toml, змінимо імена і т.п. Отримуємо:

1
2
3


baseURL = 'https://hardfault.win/'
locale = 'en'
title = 'HardFault.win'

1
2
3
4
5
6


[hugoVersion]
 extended = true
 min = "0.157.0"

[imports]
 path = "github.com/CaiJimmy/hugo-theme-stack/v4"

Створимо конфіг для бокового меню:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61


[[social]]
 identifier = "github"
 name = "GitHub"
 url = "https://github.com/elektro-NIK"
 [social.params]
 icon = "brand-github"

[[social]]
 identifier = "gitlab"
 name = "GitLab"
 url = "https://gitlab.com/elektro.NIK"
 [social.params]
 icon = "brand-gitlab"

[[social]]
 identifier = "linkedin"
 name = "LinkedIn"
 url = "https://www.linkedin.com/in/elektro-nik"
 [social.params]
 icon = "brand-linkedin"


[[main]]
 identifier = "home"
 name = "Home"
 url = "/"
 weight = 10
 [main.params]
 icon = "home"

[[main]]
 identifier = "about"
 name = "About"
 url = "/about/"
 weight = 20
 [main.params]
 icon = "user"

[[main]]
 identifier = "archives"
 name = "Archives"
 url = "/archives/"
 weight = 30
 [main.params]
 icon = "archives"

[[main]]
 identifier = "search"
 name = "Search"
 url = "/search/"
 weight = 40
 [main.params]
 icon = "search"

[[main]]
 identifier = "links"
 name = "Links"
 url = "/links/"
 weight = 50
 [main.params]
 icon = "link"

І покладемо іконки, яких немає в темі:

1
2
3
4
5
6


tree assets/icons 
assets/icons
├── brand-gitlab.svg
└── brand-linkedin.svg

1 directory, 2 files

Всі посилання ведуть на 404, проте це вже щось :) Додамо сторінки, щоб бачити їхній функціонал:

1

hugo new content content/page/about/index.md

1

hugo new content content/page/archives/index.md

1

hugo new content content/page/links/index.md

1

hugo new content content/page/search/index.md

Редагуємо файли:

1
2
3
4
5


+++
date = '2026-01-01T00:00:00+00:00'
draft = false
title = 'About'
+++

1
2
3
4
5
6


+++
date = '2026-01-01T00:00:00+00:00'
draft = false
title = 'Archives'
layout = "archives"
+++

1
2
3
4
5


+++
date = '2026-01-01T00:00:00+00:00'
draft = false
title = 'Links'
+++

1
2
3
4
5
6
7
8


+++
date = '2026-01-01T00:00:00+00:00'
draft = false
title = 'Search'
type = "page"
layout = "search"
outputs = ["html", "json"]
+++

Додамо аватар й favicon:

1
2
3
4
5
6


tree assets/img 
assets/img
├── avatar.png
└── favicon.png

1 directory, 2 files

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# ...

favicon = "img/favicon.png"

# ...

[sidebar]
 compact = false
 avatar = "img/avatar.png"
 emoji = "🦀"
 subtitle = "Cortex-M panics, but we don't"

# ...

І створимо тестову публікацію:

1

hugo new content content/post/hello_world/index.md

1
2
3
4
5
6
7


## Hello

World

### Test

text

Цим вже можна користуватися, а в наступній частині ми займемося підключенням багатомовності.

Шпаргалка по конфігурації

Файл	Призначення
`hugo.toml`	Основні налаштування сайту (baseURL, title, locale)
`params.toml`	Налаштування теми Stack (Sidebar, Footer, Cookies тощо)
`module.toml`	Керування версією Hugo та імпорт теми як модуля
`menu.toml`	Структура навігації та соцмереж у боковій панелі
`languages.toml`	Налаштування багатомовності (якщо використовується)

Hugo on HardFault.win