Создаем свой блог на Github и Hugo
Привет, хабр! Сегодня я расскажу вам, как создать свой блог на 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 довольно просто, но есть одно очень важное ограничение на его имя. Имя репозитория должно иметь вид 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 = ""' >> 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
Спасибо за прочтение статьи, с вами был доктор Аргентум!
