Как создать статичный сайт используя Hugo

Что такое Hugo

Hugo - это фрейморк для создания статичных сайтов. Он написан на языке Go.

Установка Hugo

Зависимости

Hugo имеет 3 необязательные зависимости

Варианты установки Hugo

Существует две версии Hugo стандартная и расширенная. Расширенная версия обладает дополнительным функционалом (например поддерживает формат изображений WebP). Нет смысла устанавливать стандартную версию, даже сами разработчики рекомендуют расширенную.

Существует несколько вариантов установки Hugo в Linux. Рассмотрим отдельные варианты установки уже скомпилированных файлов:

Из поддерживаемых репозиториев
Прямое скачивание бинарного исполняемого файла.

Установка из поддерживаемых репозиториев

Большинство дистрибутивов Linux имеют готовый пакет Hugo в своих репозиториях. Для установки нужно выполнить команду установки для соответствующего менеджера пакетов.

dnf - sudo dnf install hugo
apt - sudo apt install hugo
pacman - sudo pacman -S hugo
snap - sudo snap install hugo

В репозиториях могут быть не самые новые версии Hugo. Если нужна свежая версия то лучше скачать исполняемый файл с официального сайта.

Прямое скачивание бинарного исполняемого файла

Скачайте архив под нужную редакцию, операционную систему и архитектуру.
Распакуйте архив.
Переместите исполняемый файл в нужный каталог.
Добавьте этот каталог в переменную окружения PATH.
Добавьте разрешение на исполнение файла - chmod +x <имя_файла>.

Этот способ позволит иметь последнюю версию Hugo. Но для обновления программы придется повторить все шаги заново.

Создание сайта Hugo

Создание структуры директорий сайта

Откройте папку в которой хотите создать папку с новым сайтом и выполните команды:

hugo new site <имя_сайта>
cd <имя_сайта>
git init

Hugo создать требуемую структуру сайта. О самой структуре далее.

Подключение темы сайта

Для Hugo существует множество тем.

После того как вы выбрали подходящую вам, не спешите следовать инструкции по ее установке.

Так как в основном все темы размещены на Github, я рекомендую:

Сделайте форк интерсующей вас темы.
Выполните команду для по установке темы, только укажите в ней форк в вашем репозитории.

mkdir themes
git submodule add https://github.com/<имя_вашего_пользователя>/<название_репозитория_темы>.git themes/<название_репозитория_темы>

Если вы сделали форк, то вам будет проще управлять изменениями которые вы захотите внести в эту тему. Вы сможете коммитить их на Github и, при необходимости, мерджить с изменениями в родительском репозитории.

Кроме того, возможно, в какой-то момент, вы захотите сделать пулл-реквест ваших изменений в родительский репозиторий.

Для добавления темы в файл конфигурации выполните команду:

echo "theme = '<название_темы>'" >> hugo.toml

Эта команда добавит тему к файлу конфигурации сайта.

Конфигурация сайта

Различные темы сайта имеют свои собственные настройки для файла конфигурации. Обычно они находятся в файле /themes/<название_темы>/exampleSite/config.toml.

config.toml устаревшее название файла конфигурации. Начиная с версии 0.110.0 файл конфигурации должен называться hugo.toml

Скопируйте эти настройки и добавьте их в файл конфигурации hugo.toml. Далее отредактируйте их до нужной вам конфигурации.

Минимальная конфигурация:

baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'
theme = '<название_темы>'

Добавление favicon - иконки страницы

Поместите ваш файл favicon.ico в директорию /static или /static/img. Добавьте в файл конфигурации hugo.toml сроку favicon = true

Запуск тестового сервера

Для запуска тестового сервера Hugo введите команду hugo server -D. Сайт будет доступен на http://localhost:1313/.

Не забудьте отключить кэш браузера.

Создание контента для сайта Hugo

Структура директорий

Hugo сам формирует структуру каталогов проекта. Затем Hugo использует файлы из каталога content чтобы создать полноценные html страницы.

Структура проекта hugo:

example/
├── archetypes/
│   └── default.md
├── assets/
├── content/
├── data/
├── layouts/
├── public/
├── static/
├── themes/
└── hugo.toml

archetypes - здесь храняться шаблоны которые используются для создания .md файлов командой hugo new.
assets - здесь хранятся файлы которые могут обрабатываться при помощи hugo pipes.
content - здесь хранятся .md файлы для генерации контента для вебстраниц.
data - здесь храняться дополнительные файлы конфигурации. Эти файлы используются при генерации вебсайта.
layouts - здесь хранятся файлы шаблонов для создания .html страниц.
public - здесь хранятся файлы сгенерированого вебсайта. Именно их необходимо публиковать.
static - здесь храняться статичные файлы: изображения, CSS, Java Script.
themes - здесь храняться файлы подключенных тем сайта.

Архетипы

Архетипы - это шаблоны для .md файлов контента.

В файлы архетипов можно вносить любую информацю. Эта информации будет добавлена в новый файл при выполнении команды hugo new <название_файла>.

Архетип выбирается по названию директории в папке content, в которой создается новый файл. Если файл создан в директории content/post/, то будет применен архетип post.

Пример стандартного архетипа:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---

title - паттерн который создает заголовок контента на основании названия файла.
date - паттерн который создает дату публикации из текущей даты.
draft - значение ИСТИНА, этот файл является черновиком.

Таксономии

Таксономии в Hugo могут быть двух видов: categories, tags.

Таксономии определяются в метадате файлов контента:

tags:        ["tag1", "tag2"]
categories:  ["category1"]

Для отображения страниц таксономий, нужно создать шаблоны в директории layouts/, если их нет в директории установленной темы.

Создание контента

Для создания новой вебстраницы с контентом нужно создать .md файл в папке content/. Для этого выполните команду hugo new <путь/к/файлу>.
В зависимости от названия под-директории будет выбран архетип из которого будет сгенерирован файл.
Заполните поля метаданных в шапке файла.
Напишите текст.

Если необходимо хранить вместе со странцей изображения и другие файлы которые используются на ней то вместо файла нужно создать директорию и файл index.md внутри нее. В этой директории можно разместить необходимы файлы и обращаться к ним в .md файле по относительному пути.

content/
├── new-post/
│   ├── index.md
│   └── img.webp

Тестирование результата

Чтобы посмотреть, результат выполните команду hugo server --buildDrafts и перейдите в браузере по адресу 127.0.0.1:1313.

Если страница готова измените поле метаданных:

draft: false

Как развернуть сайт Hugo на хостинге

Для генерации сайта выполните команду hugo. Сайт будет сгенерирован в директории public/.

Для публикации сайта на хостинге перенесите содержимое директории public/ в корень директории сайта.

Для автоматизации процесса публикации можно воспользваться утилитой rclone и протоколом sftp:

Убедитесь, что у вас есть доступ к сайту по протоколу ssh.
Создайте новый remote для вашего сайта в rclone. Выполните команду rclone config. Следуйте инструкиям программы конфигурации.
Выполните скрипт для генерации и публикации сайта.

Простой скрипт для генерации и публикации сайта:

#!/bin/bash

# Выполните скрипт из корневой директории проекта.

hugo
rclone purge <ваш_remote>:<директория_сайта_на_хосте>/
rclone sync public/ <ваш_remote>:<директория_сайта_на_хосте>/

Что делает скрипт:

Генерирует сайт.
Удаляет предыдущую версию сайта с хоста.
Загружает новую версию сайта на хост.