Ruslan Nasonov
about me

Как выложить свой сайт на Hugo в GitHub

  • 438 words
  • #receipt
  • comments

Когда я захотел завести свою страницу в интернете, то сразу возник вопрос — а где ее разместить и как сделать? Вариантов несколько: платформа типа Blogger/LiveJournal, свой сервер и Wordpress/верстать самому/взять генератор сайтов. Готовые платформы не очень гибкие, а поддерживать решение на своем сервере не хочется. Да и свистелки мне были особо не нужны — только текст и картинки. В итоге я пришел к связке Hugo + Github Pages + Github Actions.

image

В двух словах что есть что.

  • Hugo — генератор статических сайтов, создает html на основе markdown. Работает очень шустро, и мне показался наиболее понятным из существующих генераторов.
  • Github Pages — хостинг статических сайтов. Можно добавить index.html в свой GitHub репозиторий, и он автоматичеки будет доступен на https://username.github.io/repo. Можно привязать свой домен.
  • Github Actions — сервис для CI/CD. Может много чего, нам пригодится для автоматической сборки сайта.

Я не буду останавливаться на том, как установить и использовать Hugo, на сайте есть прекрасная документация.

Настройка Hugo

У GitHub Pages есть два режима работы — хостить сайт из корня master ветки, из директории /docs в master ветке, или корня ветки gh-pages. Нам нужен второй режим, так как в корне будут лежать настройки и контент, а собранный сайт в отдельно директории. Для этого в config.toml нужно добавить настройку publishDir = "docs". Если запустить команду hugo, то можно увидеть директорию docs с собранным html.

Настройка GitHub Pages

Тут все просто, особенно если не нужен свой домен. Нужно натыкать пару галочек в настройках проекта. В случае если хочется использовать свое доменно имя, нужно будет у провайдера доменных имен прописать DNS сервер, все это хорошо описано в документации.

Настройка GitHub Actions

На данный момент уже есть настроенный Hugo и GitHub pages. В принципе на этом можно и остановиться — написал статью, собрал сайт, закоммитил, запушил, и готово. Но хочется же все автоматизировать ;) Довольно часто, во время написания, Hugo запускается с параметрами для сборки черновиков, каких-то других тем, или вообще не запускается. Получается что после отправки версии в GitHub, мы можем получить не то, что хотим. Можно исключить человеческий фактор, и переложить сборку проекта на плечи GitHub Actions. Для этого нужно.

  1. Добавить директорию docs в .gitignore. То, что мы собираем локально, пусть и остается локально.
  2. Создать в корне проекта директорию .github/worflows, и положить туда файлик publish.yml со следующим содержимым:

    name: publish
    
    on:
    push:
        branches:
        - master
        
    jobs:
    build:
        runs-on: ubuntu-latest
        steps:
        - name: checkout
        uses: actions/checkout@master
        with:
            ref: master
        - name: build
        uses: github-actions-x/hugo@master
        - name: push
        uses: github-actions-x/commit@master
        with:
            github-token: ${{ secrets.GH_TOKEN }}
            push-branch: 'master'
            commit-message: 'settings'
            force-add: 'true'
        
  3. Получить GitHub токен. Нужен чтобы коммит из Github Actions происходил от лица пользователя, и триггерился запуск сборки Github Pages. Права нужно выдать на repo.

  4. Зайти в настройки проекта GitHub (таб с шестеренкой) -> Secrets. Нужно создать секрет с именем GH_TOKEN, и вставить токен с предыдущего шага.

  5. Теперь можно запушить проект в GitHub, он автоматически соберется, появится коммит publish, и в GitHub Pages появятся изменения.