Вступ

Чому генератор статичних сайтів і чому саме Hugo?

  • бо це просте рішення, яке працює. Для сайтів візитка або блогів не потрібен складний бекенд.
  • Всі налаштування в одному файлі hugo.toml або hugo.yaml у декларативному стилі, а тому все дуже лаконічно. Формати TOML та YAML настільки прості, що ви зможете налаштувати сайт навіть значно не заглиблюючись в вивчення цих форматів.
  • Для створення контенту не потрібно заглиблюватись в HTML, CSS та JS. Контент створюється в Markdown файлах .md. Формат Markdown значно простіший. В інтернеті вдосталь посібників по синтаксису Markdown. Ось, наприклад тут.
  • Програма Hugo це всього лише один бінарний файл написаний на Go і не має додаткових залежностей. Hugo дуже швидко генерує сайт.

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

На сайті Hugo є чудова інструкція з встановлення Hugo для різних операційних систем і різних пакетних менеджерів. Але є один нюанс.
Операційні системи на кшталт Debian або MX Linux, орієнтовані на стабільність, тому деякі пакунки в їх репозиторії можуть бути застарілими.
І перше що ви зробите після створення проєкту за допомогою Hugo буде встановлення теми сайту. А якщо Hugo буде застарілої версії, значна кількість тем не буде працювати коректно.
Тому для операційних систем на кшталт Debian або MX Linux я раджу завантажити останню стабільну версію Hugo у вигляді .deb файлу з GitHub репозиторію Hugo і встановити її.
Окрім того, вам знадобиться Git для вашої операційної системи.

Створення проєкту

Тут все дуже просто. Відкриваєте термінал і запускаєте команду

hugo new site <ProjectName>

Hugo створить теку з назвою вашого проєкту <ProjectName> зі всіма необхідними файлами й теками всередині, а також файлом налаштувань hugo.toml.
Щоб Hugo створив проєкт з файлом налаштувань у форматі YAML необхідно виконати таку команду.

hugo new site <ProjectName> --format yaml

Деякі шаблони для Hugo на своїх сайтах наводять зразки налаштування теми сайту у форматі YAML, тому у вас може виникнути бажання використовувати саме цей формат.

Встановлення теми

Обрати тему можна на сайті Hugo. Після цього переходите на сторінку теми та слідуєте інструкції з встановлення. Способів встановлення є декілька.
Варто обрати рекомендований в інструкції.
Наприклад для теми PeperMod:

  1. Відкриваємо термінал і переходимо в корінь теки проєкту
cd <ProjectName>
  1. Ініціюємо локальний Git репозиторій
git init
  1. Встановлюємо тему як підмодуль Git (рекомендований для даної теми спосіб)
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive
  1. Далі в файл налаштувань hugo.yaml додаєте рядок
theme: ["PaperMod"]

Налаштування

Налаштування для всього сайту знаходяться в файлі hugo.toml або hugo.yaml. (Також є налаштування для кожної сторінки сайту в Markdown файлі. Блок метаданих “front matter” у такому випадку розміщується на початку .md файлу.)
Параметром baseURL в файлі hugo.yaml задається адреса вашого опублікованого сайту.
Приміром для запуску сайту локально, налаштування будуть наступні:

baseURL: http://localhost:1313

Вже після цього можна згенерувати сайт.

hugo

І запустити локально сервер.

hugo server  # або 'hugo server --baseURL="http://localhost:1313/"'

Далі відкриваєте в браузері Ваш сайт за адресою вказаній в налаштуваннях
http://localhost:1313
Налаштування специфічні для кожної теми задаються параметром - params.
Параметрів налаштування дуже багато, тому я всі їх описувати не буду. Детальну інформацію можна знайти на сайті Hugo
Також на сторінці теми PeperMod є зразок сайту з налаштуваннями для даної теми.

Наповнення контентом

Весь контент зберігається в теці content. Створимо нову сторінку сайту командою

hugo new content/FirstPage.md

Hugo створить файл за шаблоном default.md, який зберігається в теці archetypes.
Далі редагуєте файл FirstPage.md, заново генеруєте сайт і запускаєте сервер.

hugo
hugo server -D

Параметр -D означає “Включіть вміст, позначений як чорновий”. Коли Ви завершите редагування файлу FirstPage.md, в блоці метаданих цього ж файлу “front matter” слід змінити параметр draft.

draft: false

Після цього сторінка буде відображатись на сайті.

Додавання зображення

Всі зображення зберігаються в теках static або assets.
Зображення для обкладинки окремої сторінки задається в блоці метаданих .md файлу

cover:
  image: cover.png
  caption: "Обкладинка сторінки"

Зображення для всього сайту налаштовуються в hugo.yaml

params:
  env: production
  images: ["og-default.png"]
  cover:
    hidden: false
  label:
    icon: "logo.svg"
    iconHeight: 45
  assets:
    favicon: "favicon.ico"
    favicon16x16: "favicon.ico"
    favicon32x32: "favicon.ico"

Параметр images задає яке зображення буде використовуватись для обкладинки під час публікації посилання в соціальних мережах. Для того, щоб це налаштування спрацювало потрібно встановити env: production.
Параметр label задає логотип сайту.
Параметри favicon, favicon16x16 та favicon32x32 задають іконку сайту на вкладці браузера.
Зверніть увагу, favicon, favicon16x16 та favicon32x32 треба задати всі обов’язково, навіть якщо зображення одне!
Значення параметра hidden: false в налаштуванні -

params:
  cover:
    hidden: false

означає за замовченням показувати зображення обкладинки сторінок. Для окремої сторінки можна вимкнути цю поведінку в .md файлі сторінки.

Публікація сайту

Безплатно опублікувати сайт можна, наприклад на GitHub Pages.
Для цього на GitHub потрібно створити акаунт з вашим UserName і репозиторій з назвою UserName.github.io.
Це потрібно для того, щоб ваш сайт отримав URL - UserName.github.io.
Після цього завантажуєте ваш сайт з теки public у Вашому проєкті в цей репозиторій. Це можна зробити декількома способами. Розглянемо варіант з двома репозиторіями.
Створюємо один в корені проєкту для вихідного коду.

cd mywebsite
git init # якщо репозиторій ще не ініціалізовано
echo "public/" >> .gitignore
git add .
git commit -m "Initial commit."

Другий в теці public.

cd public
git init
git remote add origin git@github.com:username/username.github.io.git
cd ..
hugo
cd public
git add .
git commit -m "Deploy $(date)"
git push origin main --force

Важливо --force необхідний, тому що вміст public/ генерується заново при кожному запуску hugo.

Інший варіант це використовувати один репозиторій для вихідного коду та для публікації сайту.
У такому випадку створюють окрему гілку репозиторію для згенерованого коду git checkout -b gh-pages.
Також у цьому випадку необхідно в налаштуваннях репозиторію на GitHub Settings -> Pages вказати в розділі Source -> Deploy from a branch гілку gh-pages і теку де знаходиться сайт в цій гілці (/ - це корінь проєкту).