Denis Tv

Сайт на Hugo

Статический сайт на Hugo без внешней темы: свои шаблоны, свой CSS. Собирается в GitHub Actions и публикуется на GitHub Pages по адресу https://denistv.com/.

Требования

Установка на macOS:

brew install hugo
hugo version   # ожидаемо: hugo v0.168.0+extended

Быстрый старт

hugo server -D            # http://localhost:1313, включая черновики
hugo server               # без черновиков, как на проде
hugo --minify --gc        # разовая сборка в public/

hugo server пересобирает страницу при сохранении файлов. Если правка не видна — проверьте, что сервер запущен из корня репозитория.

Структура

hugo.toml                      конфигурация: baseURL, язык, параметры сайта
content/_index.md              главная страница
content/*.md                   остальные страницы
layouts/baseof.html            каркас HTML: head, шапка, main, футер
layouts/index.html             шаблон главной
layouts/_default/single.html   шаблон обычной страницы
static/css/style.css           стили: тёмная тема, мобильная вёрстка, print
static/favicon.svg             иконка сайта
static/                        всё отсюда публикуется в корень сайта
.github/workflows/pages.yml    сборка и деплой на Pages
CNAME                          домен для Pages

Важно: static/css/style.css попадает на сайт как /css/style.css. Файлы из корня репозитория (кроме static/) на сайт не копируются.

Контент

Главная — content/_index.md. Front matter в формате YAML:

---
title: "Заголовок страницы"
description: "Описание для meta description"
draft: true          # черновик: не попадёт в сборку без -D
---

Тело — обычный Markdown: заголовки ##/###, списки, ссылки, таблицы. Заголовок title выводится шаблоном, поэтому # H1 в теле не нужен — иначе заголовок продублируется.

Новая страница — просто новый файл:

content/about.md   →  /about/

Черновики видны только в hugo server -D. Перед пушем черновик либо заполняется, либо получает draft: false.

Картинки кладите в static/ (например static/photo.jpg) и ссылайтесь как /photo.jpg. Указывайте alt и сжимайте файлы — репозиторий публичный.

Шаблоны

layouts/baseof.html — общий каркас, страницы подставляют содержимое в блок:


  <article class="page">
    
  </article>

Что используется:

Если нужен повторяющийся фрагмент — layouts/partials/name.html и вызов ``.

Стили

Один файл static/css/style.css, без препроцессоров и внешних шрифтов (системный стек шрифтов). Цвета — CSS-переменные в :root, тёмная тема включается через @media (prefers-color-scheme: dark).

При правках проверяйте три режима:

  1. узкий экран (≤ 30rem);
  2. тёмная тема;
  3. печать: Cmd+P в браузере — ссылки должны быть читаемы, разрывы страниц не должны рвать блоки.

Сборка

hugo --minify --gc

Результат — в public/. Каталог в .gitignore и не коммитится: артефакт создаёт CI.

Публикация

  1. Коммит и пуш в main:

    git add -A
git commit -m "Обновить страницу"
git push
  2. Запускается .github/workflows/pages.yml: checkout → установка Hugo → hugo --minify --gc → upload-pages-artifact → deploy-pages.
  3. Source в Settings → Pages должен быть GitHub Actions. Если стоит Deploy from a branch, GitHub дополнительно собирает ветку Jekyll-ем и перетирает результат Hugo.
  4. Custom domain — denistv.com (задан в настройках Pages). Файл CNAME в репозитории для Actions-деплоя не обязателен.

Ручной запуск без нового коммита: Actions → Deploy Hugo site to Pages → Run workflow (workflow_dispatch).

Домен и HTTPS

Проверка:

echo | openssl s_client -connect denistv.com:443 -servername denistv.com 2>/dev/null \
  | openssl x509 -noout -subject -dates -ext subjectAltName
curl -I https://denistv.com/

Диагностика

Симптом Причина и что делать
Сборка падает на Build смотреть лог шага; чаще всего синтаксис шаблона или front matter
На сайте 404 после пуша Pages не включён, или Source = Deploy from a branch, или деплой ещё идёт
Правка не видна кеш Pages max-age=600; открыть с ?v=1 или подождать 10 минут
Ссылки ведут на localhost в hugo.toml сломан baseURL; должен быть https://denistv.com/
Ошибка сертификата домен не привязан к сайту, или появились лишние A/AAAA
WARN deprecated обновить ключ конфига под текущую версию Hugo (например languageCode → locale)

hugo --minify --gc перед пушем ловит большинство проблем локально.

Правила