Hugo. Развёртывание на базе страниц GitHub

Hugo. Развёртывание на базе страниц GitHub (github pages).

1 Хостинги

• Публикация типа github pages возможна на нескольких хостингах.
  • GitHub
  • GitLab
  • GitVerse

2 Типы страниц GitHub

• Существует два типа страниц GitHub:
  • Страницы пользователей/организаций: https://<username|organization>.github.io/
    • Необходимо создать отдельный репозиторий <username|organization>.github.io.
    • У пользователя может быть только одна страница подобного типа.
    • Используется для личной страницы пользователя.
  • Страницы проекта: https://<username|organization>.github.io/<project>
    • Создаётся как ветка gh-pages в рамках существующего репозитория.
    • Ваши файлы Hugo хранятся в одной ветке, а ваши сгенерированные файлы публикуются в отдельной ветке в рамках одного проекта.

3 Подходы к созданию репозитория

• На данный момент существует два метода создания репозитория сайта:
  • ручной метод (2 репозитория);
  • метод GitHub Actions (1 репозиторий).
• Не все шаблоны работают с ручным методом.

4 Создание репозитория для страницы пользователя на Github

• Чтобы опубликовать свой сайт со ссылкой https://username.github.io, необходимо создать репозиторий с именем username.github.io.
• Регистр важен, используйте строчные буквы.
• Видимость: public (бесплатный GitHub Pages работает с публичными репозиториями).
• При создании не нужно сразу добавлять файлы README, .gitignore или лицензию.
• Перейдите на свою веб-страницу Github и нажмите «Создать», чтобы создать новый репозиторий.
• Можно создать с помощью утилиты gh (см. github: утилиты командной строки):

  gh repo create username.github.io --public
  

5 Изменить baseURL в config.yaml для Hugo

• Не забудьте задать значение для baseURL в файле config.yaml:
  • baseURL: 'https://<username>.github.io' : для страницы пользователя;
  • baseURL: 'https://<username>.github.io/<repository_name>' : для репозитория проекта.
• Если это не сделать, то ваш сайт не будет работать.

6 Метод GitHub Actions

6.1 Подготовка сайта Hugo на вашем компьютере

• Создайте сайт и инициализируйте Git-репозиторий в его папке:

  # Создайте новый сайт Hugo
  hugo new site username.github.io
  cd username.github.io
  # Инициализируйте локальный Git-репозиторий
  git init
  

• Настройте базовый URL в конфигурационном файле: baseURL = 'https://username.github.io/'.

• Создайте контент, например, пост: hugo new posts/moy-pervyy-post.md.

• Проверьте сайт локально: запустите hugo server -D и откройте http://localhost:1313.

6.2 Настройка автоматической сборки и публикации через GitHub Actions

• Создайте файл рабочего процесса по пути .github/workflows/hugo.yaml в корне вашего проекта.
• Можно использовать официальный шаблон от Hugo (его предлагает использовать сам github, он сам же его и создаст).
• Свяжите локальный проект с GitHub-репозиторием, добавьте файлы и выполните первый коммит:

  # Добавьте удаленный репозиторий
  git remote add origin https://github.com/username/username.github.io.git
  # Добавьте все файлы
  git add .
  # Сделайте коммит
  git commit -m "Первая версия сайта на Hugo"
  git push -u origin master
  

6.3 Активация GitHub Pages в настройках репозитория

• После пуша файлов и файла рабочего процесса:
  • Перейдите в репозиторий на GitHub: Settings → Pages.
  • В разделе Build and deployment в качестве Source выберите GitHub Actions.
  • Через несколько минут сайт будет доступен по адресу https://username.github.io.
  • Статус сборки можно проверить на вкладке Actions вашего репозитория.

6.4 Примечания

• Убедитесь, что каталог public/ добавлен в .gitignore.
• Ваш репозиторий должен содержать только исходники:
  • конфиг hugo.toml;
  • папки content/, layouts/;
  • файл workflow .github/workflows/hugo.yaml;
  • файл .gitignore.
• При выполнении git push GitHub Actions считывает инструкции из hugo.yaml:
  • клонирует ваш репозиторий с исходниками;
  • устанавливает Hugo;
  • выполняет hugo --minify, создавая виртуальный каталог public на лету;
  • берет содержимое этого виртуального каталога и отправляет его на хостинг GitHub Pages.

6.5 Шаблон Academic CV

• В комплекте идут файлы:
  • .github/workflows/build.yml
  • .github/workflows/deploy.yml
• В них задано развёртывание сайта для ветки main.
• Если у вас ветка master, то замените название в этих файлах.
• Остальные файлы в этом каталоге можно удалить.

7 Ручной метод

• Считается устаревшим.
• Не всегда работает.

7.1 Подключение репозитория к вложенной папке

• Создайте отдельный репозиторий для исходных файлов блога.
• Создайте подмодуль public в папке блога:

  cd ~/work/blog/blog
  git submodule add git@github.com:username/username.github.io.git public
  

7.2 Генерация и развёртывание сайта

• Сгенерите проект

  cd ~/work/blog/blog
  hugo
  

• Зафиксируйте изменения и отправьте контент на GitHub:

  # Go To Public folder
  cd public
  
  # Add changes to git.
  git add .
  
  # Commit changes.
  git commit -am "rebuilding site $(date)"
  
  # Push source and build repos.
  git push origin master