Попалась мне на глаза классная статья Делаем документацию здорового человека в Git на примере Docs Ozon, где ребята из OZON вместо какого-нибудь топорного “веб-сервиса” типа Jekyll (Ruby) решили использовать нормальный тул написанный на Golang.

Утилиты на Golang всегда подкупают тем, что они надёжны как оглобля. Практически все их зависимости влинкованы в единый исполняемый файл на этапе сборки и не требуют на рабочей/сборочной машине поддержания “единственно правильной” версии языка, с набором единственно правильных для данной версии приложения библиотек. Если приложение собралось, то уже не получится “мы поставили обновление и половину зависимостей сломали, половину потеряли”.

Разворачивание

Ставим Hugo из репозитория или скачиваем готовый релиз

$ hugo new site my-site
$ cd my-site
$ git clone https://github.com/vaga/hugo-theme-m10c.git themes/m10c
$ hugo new index.md

Идём в content/index.md и прописываем черновик нашей первой страницы, затем удаляем из заголовка draft: true.

Прописываем тему в config.toml:

theme = "m10c"

Запускаем Hugo в режиме сервера и открываем адрес который он показывает на время отладки (по умолчанию http://localhost:1313/)

$ hugo server

Нюансы

Тема оформления обязательна. Тема служит шаблоном для генерации страниц. Если её нет, контент не будет генериться в принципе.

В заголовке файла дата и время должны быть правильно прописаны, с учётом сдвига UTC. По умолчанию формат выглядит как date: 2022-10-28T20:21:00+03:00, но можно и чуть очеловечить date: 2022-10-28 20:21:00 +03:00

---
title: Замена Jekyll на Hugo
date: 2022-10-28 20:21:00 +03:00
---

Если дата не парсится, за дефолт берётся Jan 1, 0001 и тогда документ оказывается самым старым в хронологии, в конце списка.

Если дата и время прописаны криво, например “смотрят в будущее”, документ не будет отображаться (не настал его час).

Все статьи хранятся в директории content или её поддиректории. Для тупого перечисления всех статей в директории (чтобы не прописывать их руками самому в index.md) создаётся _index.md следующего содержимого

---
title: ""
---

Автопубликация

Через GitHub Actions можно прикрутить сборочный конвейер, который будет пересобирать бложик при каждом коммите.

Подробнее https://gohugo.io/hosting-and-deployment/hosting-on-github/