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

Быстрое развертывание сайта на GitHub Pages с помощью генератора статического html Hugo.

1 Установка программного обеспечения для Hugo

1.1 Необходимое программное обеспечение

• Необходим сам hugo.
• Есть две сборки: Hugo и Hugo Extended.
• Hugo Extended отличается от Hugo поддержкой SASS/SCSS.
• Часть тем (например, Wowchemy — Hugo. Шаблон для научных работников) требует наличия Hugo Extended.
• Поскольку hugo использует модули golang, то следует установить и его.
• Также может понадобиться NodeJS.

1.2 Установка в различных операционных системах

1.2.1 Linux

• Ubuntu:

  sudo apt-get install go hugo
  

• Fedora:

  sudo dnf install go hugo
  

• Gentoo:

  emerge dev-lang/go net-libs/nodejs dev-vcs/git
  USE="sass" emerge www-apps/hugo
  

1.2.2 Windows

• Chocolatey:

  choco install hugo-extended git go nodejs
  

• Scoop:

  scoop install hugo-extended git go nodejs
  

1.2.3 Ручная установка

• Если устанавливаемая в системе версия hugo меньше необходимой, тогда следует установить программу вручную.
• Версию hugo можно посмотреть при помощи команды:

  hugo version
  

• Следует скачать архив с репозитория: https://github.com/gohugoio/hugo/releases

1.3 Видео: Программное обеспечение для Hugo

2 Структура сайта

• Будем считать, что сайт находится в локальном каталоге:

  ~/work/blog/blog
  

• Структура сайта

  ls ~/work/blog/blog
  
  archetypes  config.toml  content  data  docs  layouts  README.md  static  themes
  

• Каталоги:

  • archetypes Каталог, содержащий шаблоны новых md-файлов, которые создаёт Hugo с помощью команды hugo new.
  • config.toml Основной конфиг сайта
  • content Каталог данных, из которых Hugo будет генерировать сайт
  • data Каталог дополнительных данных, которые непосредственно не участвуют в генерации сайта
  • docs Корень генерируемого сайта. Этот каталог не создается Hugo, мы его получили при заведении репозитория на GitHub и ниже мы его пропишем в файле config.toml
  • layouts Содержит шаблоны сайта
  • static Каталог для статических данных (изображения, CSS, JavaScript и т.д.)
  • themes Каталог для тем оформления сайта

3 Установка темы (внешнего вида) сайта

3.1 Видео: Установка темы сайта Hugo

4 Настройка сайта

5 Публикация сайта

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

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

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

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

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

  gh repo create username.github.io --public
  

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

• Создайте подмодуль public в папке блога:

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

5.1.4 Изменить baseURL в config.yaml

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

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

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

  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
  

6 Добавление контента

• Org-roam. Экспорт в Hugo