Привет, хабр! Сегодня я расскажу вам, как создать свой блог на 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‑сервером, который можно использовать во время разработки для немедленного предоставления информации о любых изменениях, вносимых в веб‑страницы. Хьюго можно использовать двумя способами:
Режим разработки. В этом режиме Hugo использует свой HTML‑сервер для рендеринга страниц по мере их изменения во время разработки. Запуск сервера во время разработки обеспечивает немедленную обратную связь при внесении изменений в контент.
Режим сборки. Hugo также создаст полный статический веб‑сайт на основе макета темы, CSS и файлов уценки, определяющих содержимое. Результаты этого режима будут опубликованы.
Темы Hugo, а также определения страниц веб‑сайта хранятся в том, что я выше назвал репозиторием «разработки». Это основное пространство для разработки. Веб‑сервер Hugo работает с этим репозиторием. Благодаря магии подмодулей Git окончательный набор зафиксированных изменений в основной ветке репозитория разработки немедленно становится доступным в репозитории GitHub Pages.
Краткий переход к подмодулям Git :
Подмодули Git — это способ включения одного размещенного репозитория GitHub в другой хостинговый репозиторий. Все содержимое размещенного репозитория доступно в хост‑репозитории, как если бы это был обычный подкаталог в хост‑репозитории. Изменения в размещенном репозитории можно вносить в контексте хост‑репозитория. Любые такие изменения сразу же доступны в размещенном репозитории.
В контексте подмодулей репозиторий GitHub Pages является размещенным репозиторием. Он содержит опубликованный контент веб‑сайта. Напротив, репозиторий, содержащий темы Hugo и разрабатываемые версии контента, является хостинговым репозиторием . Когда контент веб‑сайта готов к публикации, Hugo используется для создания статического веб‑сайта. Хьюго генерирует контент в подмодуле, связанном с размещенным репозиторием GitHub Pages. Когда все будет готово, изменения фиксируются в репозитории хостинга и сразу же становятся доступными и, таким образом, публикуются в репозитории GitHub Pages.
Создаем GitHub репозиторий
Необходимо создать два репозитория: репозиторий GitHub Pages и репозиторий разработки хостинга. Есть 2 варианта репозитория GitHub Pages:
Личное или организационное
Проект
Дополнительные сведения о различиях см. в справочной документации 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 репозиторий разработки сайта
Спасибо за прочтение статьи, с вами был доктор Аргентум!
