Привет, хабр! Сегодня я расскажу вам, как создать свой блог на Github Pages, используя hugo!

Хотите создать свой собственный блог, но не хотите привязываться к каким‑либо крупным хостинговым решениям или издательским сайтам по подписке?

Эта статья представляет собой довольно подробное руководство о том, как создать полнофункциональный веб‑сайт/блог с использованием Hugo и GitHub Pages. Если вам просто нужен краткий обзор того, как использовать Hugo, я рекомендую перейти на страницу быстрого запуска Hugo . Если вам нужен быстрый старт по настройке сайта Hugo/GitHub Pages, я рекомендую перейти на страницу быстрого запуска Hugo GitHub Pages.

По своей сути GitHub Pages представляет собой комбинацию репозитория GitHub и опубликованного веб‑сайта. Одним из последствий этого является то, что любая фиксация в основной ветке репозитория немедленно публикуется. Одним из способов создания веб‑сайта GitHub Pages является создание связанного с ним репозитория GitHub для «разработки». Вот что описано здесь.

Hugo — генератор статических веб‑сайтов с открытым исходным кодом. Он довольно мощный, и веб‑сайты, которые можно создать с помощью Hugo, могут быть весьма сложными. Hugo — это базовый движок, используемый для интерпретации создания веб‑сайта на основе предопределенного шаблона. Хьюго называет эти шаблоны темами. «Кожа» — другое слово для обозначения темы. Тема представляет собой комбинацию HTML и CSS. HTML используется для макета сайта. CSS используется для определения цветов, шрифтов, размера шрифта и других атрибутов, не связанных с макетом, которые определяют, как выглядит веб‑сайт. Эта комбинация является довольно мощной. Сами определения страниц веб‑сайта, то есть содержимое веб‑сайта, определяются с использованием стандартного синтаксиса Markdown.

Hugo также поставляется с HTML‑сервером, который можно использовать во время разработки для немедленного предоставления информации о любых изменениях, вносимых в веб‑страницы. Хьюго можно использовать двумя способами:

1. Режим разработки. В этом режиме Hugo использует свой HTML‑сервер для рендеринга страниц по мере их изменения во время разработки. Запуск сервера во время разработки обеспечивает немедленную обратную связь при внесении изменений в контент.

2. Режим сборки. Hugo также создаст полный статический веб‑сайт на основе макета темы, CSS и файлов уценки, определяющих содержимое. Результаты этого режима будут опубликованы.

Темы Hugo, а также определения страниц веб‑сайта хранятся в том, что я выше назвал репозиторием «разработки». Это основное пространство для разработки. Веб‑сервер Hugo работает с этим репозиторием. Благодаря магии подмодулей Git окончательный набор зафиксированных изменений в основной ветке репозитория разработки немедленно становится доступным в репозитории GitHub Pages.

Краткий переход к подмодулям Git :

Подмодули Git — это способ включения одного размещенного репозитория GitHub в другой хостинговый репозиторий. Все содержимое размещенного репозитория доступно в хост‑репозитории, как если бы это был обычный подкаталог в хост‑репозитории. Изменения в размещенном репозитории можно вносить в контексте хост‑репозитория. Любые такие изменения сразу же доступны в размещенном репозитории.

В контексте подмодулей репозиторий GitHub Pages является размещенным репозиторием. Он содержит опубликованный контент веб‑сайта. Напротив, репозиторий, содержащий темы Hugo и разрабатываемые версии контента, является хостинговым репозиторием . Когда контент веб‑сайта готов к публикации, Hugo используется для создания статического веб‑сайта. Хьюго генерирует контент в подмодуле, связанном с размещенным репозиторием GitHub Pages. Когда все будет готово, изменения фиксируются в репозитории хостинга и сразу же становятся доступными и, таким образом, публикуются в репозитории GitHub Pages.

Создаем GitHub репозиторий

Необходимо создать два репозитория: репозиторий GitHub Pages и репозиторий разработки хостинга. Есть 2 варианта репозитория GitHub Pages:

1. Личное или организационное

2. Проект

Дополнительные сведения о различиях см. в справочной документации GitHub Pages. В этой статье описывается, как создать личный репозиторий GitHub.

Создать репозиторий GitHub Pages довольно просто, но есть одно очень важное ограничение на его имя. Имя репозитория должно иметь вид <github_username>.github.io. Например, habruser.github.ioгде habruserнаходится имя учетной записи связанного пользователя. Это будет URL‑адрес веб‑сайта. Таким образом, репозиторий страниц GitHub — это обычный репозиторий GitHub, только с очень специфическим именем. Мы будем использовать это имя репозитория habruser.github.ioв оставшейся части статьи при упоминании репозитория GitHub Pages. Если вам нужна дополнительная информация о том, как создать репозиторий, обратитесь к краткому руководству по GitHub Pages.

Второй шаг — создать репозиторий, в котором будет происходить разработка/авторство веб‑сайта. Это обычный репозиторий GitHub. Для целей этой статьи мы будем использовать blog.dev.repo (имя репозитория разработки). Если вам нужна дополнительная информация о том, как создать репозиторий, обратитесь к документации GitHub.

Я думаю, что вы знаете как создать репозиторий и у вас уже есть аккаунт.

Клонирование репозитория и установка

git clone git@github.com:<пользователь>/<репозиторий> # не <пользователь>.github.io, а репозиторий для разработки
cd <репозиторий>

# Установка hugo
# Debian
sudo apt install hugo
# Arch
sudo pacman -Sy hugo

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

# Инициализация
hugo new site . --force

Мы создали новый сайт с hugo.

У Hugo есть темы. Я буду использовать тему Monochrome в этой статье.

Для того, чтобы применить тему, следуйте следующим инструкциям:

git submodule add https://github.com/kaiiiz/hugo-theme-monochrome.git themes/monochrome
# Подключаем подмодуль в git

И добавляем ее в конфиг Hugo:

# пример: echo 'theme = "<theme-name>"' >> hugo.toml
echo 'theme = "monochrome"' >> hugo.toml

Тестируем сайт

Давайте создадим пост. Для этого запустим следующую команду:

# создаем пост greeting.md
hugo new post/greeting.md

После открываем файл content/post/greeting.md и видим следующее:

+++
title = 'Greeting'
date = 2023-12-06T22:43:16+07:00
draft = true
+++

Давайте его чуть-чуть изменим:

+++
title = 'Привет, хабр!'
date = 2023-12-06T22:43:16+07:00
draft = true
tags = ['хабр', 'блог']
categories = ['приветствие', 'блог']
+++

# Привет, хабр!

Как дела, хабр?

# Пока, хабр?

Разделителями +++ мы добавляем секцию информации о посте. title — название, заголовок, date — дата, draft — черновик, tags — теги, categories — категории. Дальше идет пост в формате Markdown.

Тестируем...

hugo server -D

Мы должны где-то увидеть строку Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

Мы открываем браузер, переходим по этой ссылке, и все отлично! Мы можем перейти на наш пост.

Конфигурация

Теперь нам надо изменить конфиг. Вот что получилось у меня:

baseURL = 'https://okulusdev.github.io'
languageCode = 'ru'
title = 'Okulus Dev'
languageName = 'ru'
defaultContentLanguage = "ru"
paginate = 100 #frontpage pagination
theme = 'monochrome'
enableGitInfo = true

[[navbar]]
  identifier = "categories"
  name = "Категории"
  url = "/categories/"
  weight = 1
[[navbar]]
  identifier = "tags"
  name = "Теги"
  url = "/tags/"
  weight = 2
[[navbar]]
  identifier = "posts"
  name = "Статьи"
  url = "/post/"
  weight = 3

[taxonomies]
	category = "categories"
	tag = "tags"
	series = "series"

[markup]
  [markup.highlight] # подсветка кода
    anchorLineNos = false
    codeFences = true
    guessSyntax = false
    hl_Lines = ''
    hl_inline = false
    lineAnchors = ''
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    noHl = false
    style = 'gruvbox' # темы можно посмотреть на https://xyproto.github.io/splash/docs/all.html
    tabWidth = 4

[params]
	navbar_title = "Okulus Dev" # default: site's `title`
	footer = "Copyright © 2023 by OkulusDev" # default: None
	enable_toc = true # default: true
	enable_collapsible_toc = true # default: false
	enable_collapsible_changelogs = false # default: false
	enable_math = true
	enable_site_search = true # default: false
	author = "Okulus Dev" # default: no author `meta` tag
	color_scheme = "dark" # "light" or "dark"

  	[params.list_layout]
		enable_group_by_year = false # default: true
		enable_show_date = true # default: true
		enable_pagination = true # default: false

[menu]
[[menu.main]]
    name = 'Статьи'
    pageRef = '/'
    weight = 10
[[menu.main]]
    name = 'Теги'
    pageRef = '/tags'
    weight = 20
[[menu.main]]
    name = 'Категории'
    pageRef = '/categories'
    weight = 30

[[menu.navbar]]
identifier = "tags"
name = "Теги"
title = "Теги"
url = "/tags/"
weight = 100

[[menu.navbar]]
identifier = "categories"
name = "Категории"
title = "Категории"
url = "/categories/"
weight = -100

[[menu.navbar]]
identifier = "posts"
name = "Статьи"
title = "Статьи"
url = "/post/"
weight = 80

Здесь нет ничего сложного, простая конфигурация. Учтите, что этот конфиг — мой, и под тему, которую я использую. Если вы используете другую тему, вам может надо будет изменить конфиг, и написать по другому.

Публикация и деплой

Время публикации и деплоя нашего сайта на Github Pages!

git submodule add git@<имя пользователя>.github.io.git public # добавляем наш сайт в директорию public

И создаем скрипт для деплоя:

#!/bin/sh

set -e

printf "\033[0;32mДеплой на Github!..\033[0m\n"

msg="rebuilding site $(date)"
if [ -n "$*" ]; then
	msg="$*"
fi

echo ""
echo ""
echo "Коммитим изменения в $(pwd)"
hugo -D

cd public

echo ""
echo ""
echo "Коммитим изменения в $(pwd)"
git add .
git commit -m "$msg"
git push origin

cd ..
echo ""
echo ""
echo "Коммитим изменения в pwd $(pwd)"
git add .
git commit -m "$msg"
git push origin

После:

chmod +x <название скрипта для деплоя>.sh
./<скрипт для деплоя>.sh

Все готово! После этого немного ожидаем, пока изменения придут на Github - и получаем такую красоту (что получилось у меня):

Заключение

Мой сайт

Github репозиторий разработки сайта

Мой GitHub

Спасибо за прочтение статьи, с вами был доктор Аргентум!