Як я створив технічний блог за допомогою Hugo та GitHub Pages

💡 Усі статті, обговорення, новини про Front-end — в одному місці. Приєднуйтесь до Front-end спільноти!

Після кількох років розробки програмного забезпечення та написання технічної документації я замислився над ідеєю створення свого веб-сайту, де я буду публікувати статті про набутий мною досвід.

На сьогодні створити персональний блог стало простіше, ніж будь-коли, але для отримання легкого та надійного рішення, правильний вибір інструментів все ще має значення. У цій статті я хочу поділитися, як можна налаштувати веб-сайт і блог за допомогою Hugo з автоматичним деплоєм на GitHub Pages.

Цей гайд буде корисним для тих, кому цікаво як можна безкоштовно і швидко створити веб-сайт для блогінгу, портфоліо та іншого.

Вибір платформи

Я є фанатом мінімалізму і для мене було важливо знайти просте і оптимальне рішення для цієї задачі. Спочатку я мав ідею просто створити скрипт, що буде генерувати HTML із markdown файлів, проте для мене пріорітетом було першим чином зробити блог.

Сьогодні існує безліч варіантів для створення персонального сайту. Ось короткий огляд розглянутих мною рішень:

• CMS (WordPress, Content Hub, Joomla тощо): Попри безліч можливостей, CMS-платформи здалися мені занадто громіздкими для блогу зі статичним контентом. Дуже не хотілося підіймати віртуальну машину із базою даних (чи купувати виділений хостінг). Хотілося чогось легшого й гнучкішого, без необхідності підтримувати сервер.
• Jekyll: Дуже популярний серед розробників варіант та повністю задовільняє моїм потребам, але через брак досвіду з екосистемою Ruby я вирішив не використовувати його.
• Hugo: Написаний на Go, використовує знайомий синтаксис Go-шаблонів (що є зручним, якщо ви мали справу з Go, або такими інструментами як Helm), і рендерить сторінки з Markdown-файлів — аналогічно до Jekyll. З переваг можна виділити швидкість зборки веб-сторінок.
• 11ty, Astro, Hexo та інші Node.js-рішення. На JavaScript написано багато рішень, окремо можна виділити Next.js з його гнучкою підтримкою на Vercel і можливістю використовувати mdx формат markdown файлів, проте через свої вподобання я не хотів використовувати Node.js — в мене не раз траплялася проблема, коли код, який не змінювався 3-4 року переставав працювати через несумісність оновлених npm пакетів.

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

Проаналізувавши всі варіанти, я обрав Hugo як платформу для блогу. Оскільки мені вже доводилося створювати багато документації в Markdown, працювати через термінал на віддаленій віртуальній машині та користуватися текстовими редакторами типу neovim, для мене було комфортно працювати з cli-інструментом.

Процес побудови проєкту

Я вже мав заздалегідь створений репозиторій у GitHub, з налаштованим доменом та GitHub Pages, де автоматично відображався файл README.md, тому команда hugo для ініціалізації проєкту виглядає наступним чином:

hugo new site . --force
# параметр *--force* потрібен для створення у непорожній директорії

Далі потрібно налаштувати тему та інші параметри у файлі hugo.toml, після чого сайт можна запускати локально командою:

hugo server

Запуск сервера в режимі розробки

На цьому етапі сайт доступний за локальною адресою localhost:1313. Оскільки я працюю на віддаленій віртуальній машині, отримати доступ напряму через localhost було неможливо. Для цього я використав реверс-проксі — Caddy, оскільки він автоматично налаштовує SSL-сертифікати через Let’s Encrypt. Налаштування Caddy здійснюється конфігураційним файлом Caddyfile:

test-blog-domain.com {
    reverse_proxy localhost:1313
}

Після запуску Caddy (caddy run --config /path/to/Caddyfile) сайт стає доступним за адресою https://test-blog-domain.com, коректно встановивши A-запис на IP-адресу сервера для цього домену.

Додавання теми

Hugo має велику кількість безкоштовних тем на GitHub. Щоб додати тему, потрібно склонувати репозиторій з темою у директорію themes та прописати її у файлі hugo.toml. Я обрав тему cactus , за її мінімалістичний вигляд.

Проте після встановлення цієї теми виникла помилка через відсутність шаблону для Google Analytics:

Error: error building site: render: failed to render pages: render of "/" failed: "/home/user/projects/nexo-tech.github.io/themes/cactus/layouts/_default/baseof.html:3:3": execute of template failed: template: index.html:3:3: executing "index.html" at <partial "head.html"="" .="">: error calling partial: execute of template failed: html/template:partials/head.html:47:16: no such template "_internal/google_analytics_async.html"
make: *** [Makefile:2: up] Error

Вирішення цієї проблеми знайшлося у пул-реквесті. Спільнота Hugo доволі активна, і на більшість поширених проблем можна знайти відповідь у GitHub Issues відповідніх репозиторіїв.

Після виправлення застарілих налаштувань сайт успішно розгорнувся:

Деплой статичного сайту через GitHub Pages

Перевагою статичного сайту є те, що сторінки можна кешувати на мережі доставки контенту (CDN). Це дає можливість віддавати сторінки з географічно найближчого дата-центру до користувача. З безкоштовних сервісів для публікації статичного контенту та односторінкових додатків можна виділити: Netlify, Vercel, Firebase Hosting. Для свого рішення я обрав GitHub Pages, тому що він доступний для кожного репозиторію на GitHub.

Є два способи публікації статичного контенту на GitHub Pages: автоматично через GitHub Actions або використовуючи окрему гілку у репозиторії. Оскільки особисті акаунти GitHub мають обмеження на обсяг артефактів, я обрав простішу стратегію: оновлювати готові файли сайту безпосередньо у визначеній гілці (gh-pages).

Для Hugo існують готові GitHub Actions для цього способу оновлення сайту:

• actions-hugo від Shohei Ueda — налаштування Hugo у середовищі CI/CD.
• actions-gh-pages також від Shohei Ueda — публікація статичних файлів на GitHub Pages.

Ось приклад workflow для деплою:

name: Build and Deploy Hugo
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v3
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true
      - name: Build site
        run: hugo --minify
      - name: Add CNAME file
        run: cp CNAME public/CNAME
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: gh-pages

Після успішного виконання workflow сайт буде доступний через CDN GitHub. Не забудьте у налаштуваннях GitHub Pages обрати правильну гілку (gh-pages).

Тепер, коли Hugo налаштовано й розгорнуто, я можу зосередитись на головному — публікації технічного контенту на основі власного досвіду. Сподіваюся, цей гайд буде корисним для тих, хто шукає простий спосіб запустити свій технічний блог або портфоліо веб-сайт.

Додатково, окремою статтею я планую ще розповісти про кастомізацію веб-сайту, побудову власної теми та налаштування Tailwind CSS із оптимальним пакуванням JavaScript коду.

Корисні ресурси

• Репозиторій цього сайту
• Швидкий старт Hugo
• Налаштування DNS для GitHub Pages
• Тема Cactus для Hugo
• Налаштування Google Analytics у Hugo
• Швидкий старт Caddy reverse proxy