Личный сайт на базе Hugo и GitHub Pages
Введение
В данной статье будет рассмотрен процесс создания личного сайта при помощи генератора статических сайтов Hugo1. Публикация сайта будет произведена при помощи GitHub Pages2. Для реализации данного проекта будут использованы инструменты:
- Ubuntu Server 22.04
- Hugo v0.92.2+extended
- Vim
- Аккаунт на GitHub
Установка и начальная настройка
Для начала необходимо установить Hugo.
sudo apt install hugo
Далее необходимо создать директорию, которая будет вмещать в себя сам сайт и перейти в неё.
hugo new site MyNewSite
cd MyNewSite
В данный момент мы находимся в директории нашего сайта. В ней необходимо инициализировать Git.
git init
После того как директория нашего сайта превратилась в наш репозиторий, необходимо прописать настройки самого генератора HUGO, которые значительно упростят жизнь в дальнейшем. Первым делом необходимо скорректировать файл default.md, который находится в директории archetypes:
vim archetypes/default.md
В данный файл необходимо добавить параметр публикации материала (в данном примере параметр прописан так, чтобы дата публикации, по умолчанию, совпадала с датой создания статьи), а также изменить параметр draft следующим образом: Было:
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
Стало:
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
- draft: true
+ publishDate: {{ .Date }}
+ draft: false
Далее необходимо подключить стороннюю тему к сайту. В данной статье будет применена простенькая тема Poison3. Подключить тему можно при помощи подмодулей git. Для этого необходимо перейти в директорию themes. В командной строке прописываем следующее:
cd themes
git submodule add https://github.com/lukeorth/poison.git
cd .. # Возвращаемся в корневую директорию сайта
Так как выбранная тема добавляет к стандартному Hugo дополнительные возможности, необходимо изменить и настроить конфигурационный файл соответствующим образом. Для этого необходимо добавить в него ряд параметров, которые можно скопировать из руководства на официальном сайте темы.
vim config.toml
Ниже приведен описание основных параметров.
| Параметр | Описание |
|---|---|
| baseURL | Адрес вашего сайта |
| theme | Название используемой темы сайта |
| brand | Имя вашего сайта |
| brand_image | Путь до логотипа сайта |
| Description | Описание вашего сайта |
| favicon | Путь до фавикона вашего сайта (отображается во вкладке в браузере) |
| menu | Параметр отвечает за список страниц сайта (будет подробнее описан далее) |
| название_url | Иконки со ссылками на соц. сети |
| название_color | Параметры цвета интерфейса (Например, цвет фона) |
Параметр menu отвечает за то, как выглядит список страниц на сайте. Имеет 2 типа:
| Тип | Описание |
|---|---|
| Одностраничник | Ссылается на конкретную страницу (Например, страницу “Обо мне”) |
| Список | Выводит список страниц из определённого раздела (Например 5 последних постов из директории “Posts”) |
Глобально, данные типы отличаются наличием параметров HasChildren и Limit. Где есть данные параметры- это список, а где нет- это одностраничник. После того как все параметры были корректно прописаны и скорректированы, необходимо отразить изменения в системе контроля версий:
git add .
git commit -m 'First commit'
Далее предлагается провести тестовое развёртывание.
Публикация в GitHub Pages
Для того, чтобы опубликовать получившийся сайт при помощи GitHub Pages, необходимо, разумеется, иметь активный аккаунт GitHub. Далее необходимо создать новый публичный репозиторий и связать его с локальным, в котором лежит наш сайт. Для этого можно воспользоваться инструкциями, которые представлены в самом GitHub:
git remote add origin git@github.com:Имя_пользователя/название_репозитория.git
git branch -M main
git push -u origin main
Далее необходимо на GitHub пройти во вкладку “Settings” –> “Pages”. Далее в разделе “Build and deployment” параметр “Source” выставить “GitHub Actions”. После этого система предложит выбрать готовый workflow “Hugo” –> нажимаем “Configure”. В системе уже существует готовый процесс, который будет публиковать материалы в GitHub Pages. Ничего менять не нужно, стоит лишь в разделе build добавить параметр extended со значнием true. Это необходимо для того, чтобы все элементы сайта работали корректно.
build:
runs-on: ubuntu-latest
env:
HUGO_VERSION: 0.120.4
+ extended: true
После внесения изменений, нажимаем кнопку “Commit changes” и подтверждаем коммит. Таким образом мы добавили в наш репозиторий файл, который содержит инструкцию для GitHub Actions по сборке и развёртыванию сайта. Для того, чтобы изменения отразились также и в локальном репозитории, прописываем в консоли:
git pull
Теперь по ссылке имя_пользователя.github.io доступна первая версия сайта. Осталось лишь заполнить сайт статьями и “навести марафет”.
Публикация материалов
Hugo поддерживает markdown разметку, что позволяет использовать в тексте блоки кода, диаграммы, таблицы и так далее. Будем пользоваться этим преимуществом. Для того, чтобы добавить материалы на сайт, необходимо использовать команду:
hugo new posts/first_post.md # Создать markdown файл в директории content/posts
vim content/posts/first_post.md # Открыть созданный файл в редакторе vim
В открывшемся файле необходимо сделать следующие шаги:
- Отредактировать шапку
- Написать что-нибудь
Для примера, напишем следующее:
### Привет, мир!
1. Создана первая страница
2. ¯\_(ツ)_/¯
echo "Hellow, mama, ya v televizore!"
Завершив написание поста, необходимо выйти из текстового редактора с сохранением данных. Также предлагаю Создать файл “Обо мне”, он же “About”. Чтобы не заморачиваться, пропишем простенькое предложение и не будем использовать отдельный текстовый редактор, а воспользуемся хередоком.
hugo new about/about.md
cat << EOF > content/about/about.md
My name is $LOGNAME
ha
ha
ha-ha
EOF
Чтобы наши страницы загрузились на сайт, необходимо отправить изменения в репозиторий:
git add . && git commit -m "Add About and first post"
git push
Как только изменения попадут в репозиторий и пройдут через GitHub Actions, они появятся в соответствующих разделах на сайте. Попробуйте!
Послесловие
В данной статье были затронуты лишь самые азы работы с Hugo, GitHub Actions и темой Poison. Hugo- очень удобный и довольно простой способ создания личного блога или простеньких сайтов. Страницы быстро загружаются, а администрирование сайта требует минимум усилий. В перспективе возможно рассмотреть переезд на собственный хостинг в лице GitLab и внедрение удобной среды создания статей (вместе с современным markdown редактором). Подробнее с этими инструментами Вы можете ознакомиться в соответствующей документации: