Сайт/блог на базе Hugo


Инструкция по разработке личного сайта/блога на базе генератора статических сайтов Hugo. Полезные сниппеты, разработка шаблонов, структура контента.

Процесс разработки

Если очень сильно упрощать, то весь процесс сводится к нескольким шагам:

  • Сгенерировать каркас сайта командой hugo new название_сайта
  • Утащить с сайта Hugo одну из тем (обязательный шаг)
  • Подогнать тему под свои нужды и дизайн
  • Разместить в папке content структуру и содержимое (разделы и статьи)
  • По мере готовности залить на хостинг все файлы в папке public, в которую Hugo складывает сгенерированный сайт в готовом к размещению виде

При этом для размещения сайта подойдет даже самый “дохлый хостинг”, но лично я рекомендую использовать популярные в последнее время облачные хранилища. Вкратце (на примере Selectel):

  • покупаем аккаунт, пополняем баланс
  • создаем публичный контейнер для размещения статических файлов
  • привязываем к контейнеру свой домен
  • заливаем в него сгенерированный сайт (все из папки public)
  • после успешной привязки домена сайт открывается и работает

Заливать на тот же Selectel (или к примеру AWS) можно очень удобной утилитой RClone, которая работает в консольном режиме, и после настройки позволяет синхронизировать файлы между папкой public и нужным контейнером. Так как утилита консольная и довольно быстрая, можно сделать скрипт (команды) для crontab на сервере и заливать файлы без участия программистов и авторов, просто по факту наличия папки public в нужном месте.

Пример простой синхронизации папки public и контейнера на Selectel через команду RClone:

#!/usr/bin/env bash
rclone sync ~/htdocs/mysqite.ru/public selectel_login:mysite.ru -v --exclude .file-segments/

Организация контента

По умолчанию Hugo предлагает раздел content/posts, на наличие которого рассчитано абсолютное большинство тем в репозитории генератора. Также по умолчанию предполагается, что структура папок (каталогов) внутри папки content будет один к одному отражать итоговую структуру URL на сгенерированном сайте. Папка content - это корень (/) вашего сайта в плане URL.

Бандлы (типы структуры)

dev-сервер для локальной разработки

Запуск dev-сервера с нужными ключами:

hugo serve -D --disableFastRender --noHTTPCache 

disableFastRender - учет всех изменений, полезно если часто меняется конфиг и статические файлы

noHTTPCache - не дает браузеру кешировать CSS и другие файлы, полезно при разработке дизайна

Hugo сам по себе очень быстрый, поэтому на достаточно мощном компьютере ключ disableFastRender не будет тормозить процесс разработки и нагружать процессор.

Внимание! Несмотря на эти ключи, Hugo все равно частенько “тупит” и не подхватывает некоторые изменения, поэтому если возникают подозрения на то, что dev-сайт не обновился, проще остановить сервер через Ctrl+C, сгенерировать полный сайт через команду hugo и запустить dev-сервер заново.

Документация по команде hugo server

Шаблоны

Переменные в шаблонах

Из-за некоторых ограничений go-шаблонов в плане присваивания значений новым переменным (особенно в контекстах и циклах) в Hugo добавлена “контекстная” функция Scratch, которая предоставляет интерфейс для записи и чтения значений в формате ключ-значение. Простой пример:

Инициализируем переменную и задаем значение нужной паре “ключ-значение”:

$scratch := newScratch
$scratch.Set "greeting" "Привет!"

Читаем значение из переменной по нужному ключу:

$scratch.Get "greeting"

получим значение “Привет!”

Документация по функции Scratch

Служебные страницы

Ошибка 404

Файл шаблона этой страницы с именем 404.html нужно разместить в корне папки layouts.

Внимание! DEV-сервер Hugo не умеет отображать эту страницу в ответ на запрос неверного URL, но проверить ее генерацию можно прямым обращением к URL - /404.html.

На рабочем сайте вывод страницы 404.html как реакцию на соответствующую ошибку настраивается на уровне сервера (Apache, Nginx и т.п.).

Документация по шаблону/странице 404.html

robots.txt

Этот файл можно сделать как статическим, так и сгенерированным с помощью шаблонизатора Hugo. Это может быть удобно, если в файле будут сгенерированные по определенным правилам шаблоны для разрешения или запрета определенных URL, к примеру. Для генерации (прогона) файла через шаблонизатор нужно разместить его в корне папки layouts.

Документация по шаблону robots.txt