Установка Hugo + тема Blowfish с нуля — подробная инструкция#
Эта заметка — отдельный, самостоятельный гайд: как развернуть сайт на Hugo с темой Blowfish с чистого листа. Она не зависит от инструкции по автоматизации публикации (Obsidian → Forgejo → CI/CD) — если сайт уже работает, эта заметка не нужна. Пригодится, если разворачиваете новый сайт, тестовый стенд, или хотите понимать, что вообще происходит внутри той LXC-машины, где уже стоит ваш сайт.
Инструкция рассчитана на новичка — каждая команда с объяснением.
У меня сайт со всеми файлами крутится в LXC контейнере внутри Proxmox, поэтому в настоящей статье я буду исходит из этого. Но Hugo можно установить в любую систему, которая поддерживает git, даже WIndows.
0. Термины#
- Hugo — генератор статичных сайтов: берёт markdown-файлы с контентом и шаблоны оформления, на выходе даёт готовый HTML-сайт (без базы данных, без PHP — просто файлы).
- тема (theme) — набор шаблонов оформления и стилей. Blowfish — одна из популярных тем для Hugo, заточенная под блоги/документацию, ио точно одна из самых кастомизируемых.
- Hugo Extended — расширенная сборка Hugo с поддержкой SCSS/SASS (компиляция стилей). Большинству современных тем, включая Blowfish, нужна именно она — обычная (не Extended) сборка не подойдёт.
- submodule — репозиторий внутри репозитория. Тема обычно подключается как submodule: ваш сайт ссылается на конкретную версию репозитория темы, не копируя её файлы напрямую.
- frontmatter (фронтматтер) — блок метаданных в начале markdown-файла статьи, обычно между
---, где указываются заголовок, дата, теги и т.д. - page bundle — способ оформления статьи в Hugo, при котором у статьи есть своя папка (а не просто один
.md-файл), и рядом с текстом лежат её изображения (напримерfeatured.png). - config/_default/ — папка с настройками сайта, разбитая на несколько файлов по смыслу (
hugo.toml,params.toml,menus.tomlи т.д.) — так организована конфигурация в Blowfish. - TOML — формат файлов конфигурации (похож на INI, но со своими особенностями синтаксиса).
Фаза 1. Подготовка сервера#
Если разворачиваете на новой машине (например, ещё один LXC-контейнер в Proxmox) — сначала базовая подготовка.
Шаг 1.1. Создайте/подключитесь к серверу#
Если это новый LXC-контейнер в Proxmox — создайте его с шаблоном Debian или Ubuntu, выделите хотя бы 1 vCPU / 1 ГБ RAM / 8 ГБ диска — для статического сайта этого с запасом хватит.
Подключитесь по SSH:
ssh root@IP_КОНТЕЙНЕРАШаг 1.2. Обновите систему#
apt update && apt upgrade -yШаг 1.3. Установите git#
apt install -y git
git --versionФаза 2. Установка Hugo Extended#
Шаг 2.1. Почему не через apt install hugo#
В стандартных репозиториях Debian/Ubuntu версия Hugo обычно старая и не Extended — темы вроде Blowfish не будут собираться (ошибки про отсутствующий SCSS-транспайлер). Ставим актуальный релиз вручную, с GitHub.
Шаг 2.2. Скачайте актуальный релиз Hugo Extended#
Откройте в браузере страницу релизов:
https://github.com/gohugoio/hugo/releasesНайдите последний стабильный релиз (не пререлиз/beta), и в списке файлов — архив с именем вида hugo_extended_X.XXX.X_linux-amd64.tar.gz (обратите внимание на слово extended в имени — обычная сборка без него не подойдёт).
На сервере, подставив реальную версию:
cd /opt
curl -L -o hugo.tar.gz "https://github.com/gohugoio/hugo/releases/download/vX.XXX.X/hugo_extended_X.XXX.X_linux-amd64.tar.gz"
tar -xzf hugo.tar.gz hugo
mv hugo /usr/local/bin/
rm hugo.tar.gzШаг 2.3. Проверьте установку#
hugo versionВ выводе обязательно должно быть слово extended — например:
hugo v0.163.3-...+extended linux/amd64 ...Если слова extended нет — скачали не тот архив, повторите Шаг 2.2, внимательно выбрав файл с extended в названии.
Фаза 3. Создание нового сайта#
Шаг 3.1. Создайте структуру проекта#
mkdir -p /home/prohomelab
cd /home/prohomelab
hugo new site . --forceРазбор: hugo new site . --force создаёт стандартную структуру Hugo-сайта прямо в текущей папке (.), --force разрешает сделать это в уже существующей (но пустой) папке.
Появятся папки: archetypes/, assets/, content/, data/, i18n/, layouts/, static/, и файл hugo.toml.
Шаг 3.2. Инициализируйте git#
git init
git config user.name "Ваше имя"
git config user.email "you@example.com"Фаза 4. Подключение темы Blowfish#
Шаг 4.1. Добавьте тему как submodule#
git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfishНа сайте разработчика есть инструкция, как подключить тему с помощью встроенных инструментов. В ходе такой установки вам будет задано огромное количество вопросов, ответив на которые вы получите готовую к использованию тему, но мы пойдем по старинке.
Разбор значений: -b main — отслеживать ветку main репозитория темы. Команда создаст файл .gitmodules (в нём будет записано, откуда брать тему) и скачает саму тему в themes/blowfish.
Шаг 4.2. Подключите тему в конфиге#
Откройте hugo.toml:
nano hugo.tomlДобавьте (или замените, если уже есть строка theme):
theme = "blowfish"Шаг 4.3. Скопируйте образец конфигурации Blowfish#
У темы Blowfish есть готовый пример конфигурации (папка exampleSite), с которого удобно начать вместо конфигурации с нуля:
cp -r themes/blowfish/config/_default config/Это создаст папку config/_default/ с несколькими файлами вместо одного hugo.toml — так рекомендует сама тема Blowfish, конфигурация разложена по смыслу:
hugo.toml— базовые настройки сайта (заголовок, baseURL, языки по умолчанию)params.toml— параметры темы (цветовая схема, футер, соцсети и т.д.)menus.<язык>.toml— пункты меню (напримерmenus.ru.toml)languages.<язык>.toml— настройки конкретного языка (напримерlanguages.ru.toml)markup.toml— настройки обработки markdownmodule.toml— настройки Hugo Modules (если используете модули вместо submodule — в нашем случае не нужен, можно удалить или оставить пустым)
Шаг 4.4. Настройте базовые параметры#
nano config/_default/hugo.tomlКлючевое, что стоит проверить/поправить:
baseURL = "https://ваш-домен.com/"
languageCode = "ru-ru"
title = "Название вашего сайта"В config/_default/languages.ru.toml (если делаете русскоязычный сайт) — проверьте, что язык подключён правильно, ключевые поля:
languageName = "Русский"
weight = 1(В новых версиях Hugo поля languageCode/languageName в некоторых местах заменены на locale/label — если увидите предупреждение deprecated при сборке с указанием, какое поле использовать вместо старого, замените согласно тексту предупреждения; сайт при этом продолжит работать, это не критичная ошибка.)
Шаг 4.5. Первый локальный запуск (превью)#
hugo server -D --bind 0.0.0.0 --baseURL "http://IP_ВАШЕГО_СЕРВЕРА"Разбор: -D — показывать черновики тоже, --bind 0.0.0.0 — слушать на всех сетевых интерфейсах (по умолчанию Hugo слушает только 127.0.0.1, и с другого компьютера в сети не достучаться), --baseURL — на какой адрес ссылаться внутри сгенерированных страниц.
Откройте в браузере http://IP_ВАШЕГО_СЕРВЕРА:1313 (Hugo dev-сервер по умолчанию слушает порт 1313) — должна открыться стартовая страница темы Blowfish (пока пустая, без статей).
Остановить сервер — Ctrl+C в терминале.
Фаза 5. Структура контента (под ваш формат статей)#
Я все буду рассказывать на примере своего сайта, но у вас, конечно, может быть своя структура. У меня уже устоявшийся формат — статьи оформлены как page bundle (папка на статью со слагом внутри, плюс featured.png рядом), а фронтматтер включает конкретный набор полей. Задокументируем это здесь, чтобы формат был предсказуем при создании новых статей вручную (без Obsidian) или при разворачивании копии сайта.
Шаг 5.1. Создайте архетип (шаблон новой статьи)#
Архетип — это заготовка, которую Hugo подставляет при создании новой статьи командой hugo new. Отредактируйте archetypes/default.md:
nano archetypes/default.mdВпишите шаблон фронтматтера под ваш формат:
---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
published: {{ .Date }}
pinned: false
description: ""
tags: []
slug: "{{ .File.ContentBaseName }}"
category: ""
licenseName: "CC BY 4.0"
author: "ваше имя"
draft: true
series: ""
toc: true
showDate: true
showDateUpdated: true
showReadingTime: true
showAuthor: true
cover: ./featured.png
summary: ""
---Данный шаблон повторяет структуру фронтматтера, которую я использую (без отдельных полей date/pubDate — публикационная дата берётся из published).
Шаг 5.2. Создайте новую статью как page bundle#
hugo new content/posts/Selfhosting/Моя-новая-статья/index.mdЭто создаст папку content/posts/Selfhosting/Моя-новая-статья/ с файлом index.md внутри, оформленным по архетипу из Шага 5.1. Картинку обложки положите туда же, под именем featured.png (или поправьте cover: в фронтматтере на другое имя файла).
Шаг 5.3. Категории и теги#
В вашей текущей структуре у каждой крупной категории (content/posts/Traefik/, content/posts/Proxmox/ и т.д.) есть файл _index.md — он описывает саму категорию/раздел (не отдельную статью), например задаёт заголовок раздела и обложку featured.png/featured.webp для страницы-листинга этой категории. Создаётся так же, вручную:
mkdir -p content/posts/НоваяКатегория
cat > content/posts/НоваяКатегория/_index.md <<'EOF'
---
title: "Название категории"
---
EOFФаза 6. Сборка для продакшена#
Шаг 6.1. Соберите сайт#
cd /home/prohomelab
hugo -D --minifyРазбор: -D — включить черновики в сборку (уберите этот флаг, когда захотите публиковать только полностью готовые статьи), --minify — сжать итоговые HTML/CSS/JS.
Результат появится в папке public/ — это и есть готовый статичный сайт, который можно заливать на любой хостинг (в вашем случае — на smartape, см. отдельную инструкцию по автоматизации).
Шаг 6.2. Локальная проверка собранного сайта#
Если хотите посмотреть именно собранную (production) версию, а не через dev-сервер:
cd public
python3 -m http.server 8080Откройте http://IP_СЕРВЕРА:8080 в браузере. Остановить — Ctrl+C.
Что дальше#
На этом сайт развёрнут и умеет собираться. Дальше — либо заливаете public/ на хостинг вручную (как раньше делали через FileZilla), либо настраиваете автоматическую публикацию через Forgejo Actions — это отдельная, уже пройденная вами инструкция (Obsidian → Forgejo → Hugo → smartape).
Пара вещей, о которых стоит подумать отдельно, не описанных в этом гайде:
Резервное копирование: сам Hugo-репозиторий версионируется в git, но сгенерированный
public/— нет (мы его исключаем через.gitignore), это нормально, он пересоздаётся из исходников в любой момент.HTTPS/TLS для локального дев-сервера — не нужен,
hugo serverпредназначен только для локального превью, не для публичного доступа.Обновление темы: раз в какое-то время стоит обновлять submodule темы до новой версии:
cd themes/blowfish git pull origin main cd ../.. git add themes/blowfish git commit -m "Update Blowfish theme"Перед обновлением стоит свериться с changelog темы на GitHub — иногда меняются названия полей конфигурации (как в примере с
languageCode/localeвыше), и после обновления может понадобиться поправитьconfig/_default/*.toml.
