Как разместить сайт на Hugo на GitHub user pages

Чтобы разместить сайт на GitHub user pages, нужно, чтобы его содержимое было в ветке master репозитория username.github.io. В идеале, хотелось бы, организовать репозиторий так, чтобы исходный код хранился где-то рядом. Я нагуглила два решения. Отправная точка для обоих — локально работающий сайт, созданный при помощи blogdown в RStudio с темой Academic.

1. Решение на основе поддеревьев

Решение на основе поддеревьев (subtrees) мне показалось более простым, поскольку я не так хорошо понимаю git. Но потом пришлось все переделать, чтобы было аккуратно.

Получится один репозиторий с двумя ветками:

• username.github.io:
  • source — исходный код + содержимое папки public;
  • master — веб-версия (только содержимое папки public).

Веб-версия пушится в удаленный репозиторий командой git subtree push.

Основной недостаток этого решения — ветка source содержит содержимое publiс.

В блоге Анатолия (@tolikcode) очень просто описано, как нужно все настраивать. А чтобы немного автоматизировать процесс выгрузки можно использовать скрипт, как предлагает Jente Hidskes. Здесь я кратко законспектирую, что я делала, на случай, если придется повторить.

Настройка

1. В директории сайта инициализируем пустой репозиторий git и в его ветку master коммитим что-то неважное. Например, файл README.md.

git init
git add README.md
git commit -m "initial commit on master"

2. Создаем ветку source для исходного кода (орфан, т.е. без “родителя”). В эту ветку закоммичено все, кроме предварительно удаленной директории public, куда рендерится сайт по-умолчанию.

git checkout --orphan source
rm -rf public ## Удаляет директорию public!!!
git add .
git commit -m "initial commit on source branch"

3. Пушим все

git remote add origin git@github.com:username/username.github.io.git
git push origin master
git push origin source

4. Подключаем ветку master в директорию public.

git subtree add --prefix=public git@github.com:username/username.github.io.git master --squash

Работа

1. Работаем над сайтом в RStudio. Внесенные изменения можно просмотреть в реальном времени.

blogdown:::serve_site()

Сайт будет сгенерирован в public, но не спешите его в таком виде отправлять на гитхаб: предпросмотр рендерит в т.ч. черновики. В процессе можно все коммитить как обычно в ветку source, если это долгая работа.

2. Генерируем веб-версию.

Предварительно нужно остановить живое превью, перезагрузив R сессию или servr::daemon_stop("номер, выданный blogdown:::serve_site()").

blogdown::hugo_build()

В консоли коммитим окончательные изменения.

git add -A
git commit -m "update"
git push origin source

3. Публикуем измененный сайт в master при помощи subtree push.

git subtree push --prefix=public https://github.com/tolikcode/tolikcode.github.io.git master

После этого сайт будет доступен на GitHub user pages http://username.github.io/.

2. Решение на основе подмодулей (submodules)

Решение на основе подмодулей (submodules) описано в документации Hugo. Сначала я не поняла как его развернуть. Но после этого видео про подмодули все поняла и сделала именно так.

Получится два репозитория:

• username-src:

  • master — исходный код.

• username.github.io:

  • master — веб-версия (только содержимое папки public). Этот репозиторий подключен в виде submodule в папку public репозитория username-src.

Достоинство этого решения — отдельная чистая история для исходного кода и сайта.

Для автоматизации веб-версия пушится в удаленный репозиторий скриптом deploy.sh.

Настройка

1. В директории проекта генерируем сайт.

hugo -t hugo-academic # Если используете тему, замените на `hugo -t <YOURTHEME>`

2. В под-директории public создаем репозиторий для веб-версии. Пушим все изменения.

cd public
git init
git remote add origin git@github.com:username/username.github.io.git
git add .
git commit -m "initial commit of website"
git push -u origin master

3. Возвращаемся в директорию проекта и удаляем под-директорию public.

cd ..
rm -rf public

4. В директории проекта инициализируем репозиторий git. Добавляем public в .gitignore.

git init
git remote add origin git@github.com:username/username-src.git
echo "public" >> .gitignore
git add .
git commit -m "initial commit of source code"
git push -u origin master

5. Подключаем репозиторий с веб-версией в директорию public в качестве подмодуля.

git submodule add -b master git@github.com varmara/varmara.github.io.git
git add .
git commit -m 'added public as a submodule'
git push origin master

Работа

1. Работаем над сайтом в RStudio. Внесенные изменения можно просмотреть в реальном времени.

blogdown:::serve_site()

Сайт будет сгенерирован в public, но не спешите его в таком виде отправлять на гитхаб: предпросмотр рендерит в т.ч. черновики.

Изменения спокойно коммитим в репозиторий с исходным кодом username-src.

2. Когда приходит время, генерируем веб-версию.

Останавливаем живое превью, перезагрузив R сессию или servr::daemon_stop("номер, выданный blogdown:::serve_site()"). Затем, запускаем скрипт deploy.sh, который сам удаляет устаревшее содержимое public, генерирует сайт и коммитит его в username.github.io.

#!/bin/bash

# a script for easy site deploymend from submodule
# make it executable with chmod +x deploy.sh

# Set the English locale for the `date` command.
export LC_TIME=en_US.UTF-8

# The commit message.
MESSAGE="Site rebuild $(date)"

echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# Remove old files in public
pushd public
git rm -rf *
popd

# Build the project.
hugo -t hugo-academic # if using a theme, replace with `hugo -t <YOURTHEME>`

# Go To Public folder
cd public

# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
  then MESSAGE="$1"
fi
git commit -m "$MESSAGE"

# Push source and build repos.
git push origin master

# Come Back up to the Project Root
cd ..

Теперь обновленный сайт доступен на GitHub user pages http://username.github.io/.