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

В предыдущем посте я писал чем может быть интересен статический сайт и как его можно создать на базе репозитория в GitHub. Продолжу тему и расскажу, как создать сайт с помощью генератора статического html Hugo и разместить на GitHub Pages.

Для эксперимента с созданием сайта, я ранее зарегистрировал отдельный домен andrdi.ru и дальнейшее описание будет с использованием этого домена.

Подразумевается, что у нас уже установлен Git и мы понимаем как он работает, а также знаем, что такое markdown и с чем его едят. Все команды я проверял на себе, но здравый смысл и чтение документации никто не отменял.

Для начала определимся с задачей: Создать сайт про котиков, имеющий следующую структуру:

.
├── HOME
└── cats
    ├── black
    └── white

С воображением у меня туго, поэтому пусть это будут котики.

Порядок действий следующий:

1. Установка Hugo
2. Создание структуры сайта
3. Установка темы (внешнего вида) сайта
4. Настройка сайта
5. Публикация сайта
6. Добавление контента

1. Установка Hugo

На официальном сайте целая куча вариантов установки Hugo на различные системы.

Проверяем, как работает:

$ hugo version

Hugo Static Site Generator v0.40.1 linux/amd64 BuildDate: 2018-04-25T17:16:11Z

Не самая последняя версия, но нам хватит.

2. Создание структуры сайта

Ранее я уже создал репозиторий /home/user/git/andrdi.ru/, содержащий каталог docs/, который является корневым каталогом сайта.

$ tree /home/user/git/andrdi.ru/

andrdi.ru/                             
└── docs                    
    ├── CNAME
    └── index.html

Создадим там новый сайт:

$ hugo new site /home/user/git/andrdi.ru --force

Congratulations! Your new Hugo site is created in /home/user/git/andrdi.ru

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/, or
   create your own with the "hugo new theme " command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new /.".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

Параметр --force в нашем случае необходим чтобы не получить эту ошибку:

Error: /home/user/git/andrdi.ru already exists and is not empty

В результате получаем следующий набор файлов и каталогов:

$ ls /home/user/git/andrdi.ru

archetypes  config.toml  content  data  docs  layouts  README.md  static  themes

Рассмотрим подробнее:

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

На сайте Hugo есть множество различных готовых тем оформления для сайта и подробно расписано, как создать свою собственную. Я выбрал тему hugo-theme-techdoc.

Скачиваем и готовим тему оформления:

$ cd /home/user/git/andrdi.ru/themes/ && git clone https://github.com/thingsym/hugo-theme-techdoc.git && mv hugo-theme-techdoc/ techdoc/ && rm -rf techdoc/.git techdoc/.gitignore techdoc/yarn.lock

Эта команда клонирует репозиторий темы в каталог themes; переименовывает каталог темы в techdoc; удаляет из него каталог .git и файл .gitignore, чтобы GitHub не ругался на вложенный репозиторий; удаляет файл yarn.lock, на который GitHub присылает сразу целую пачку писем с предупреждениями.

Опционально можно удалить скриншоты темы и каталог с примерами:

$ rm /home/user/git/andrdi.ru/themes/techdoc/images/* && rm -rf /home/user/git/andrdi.ru/themes/techdoc/exampleSite/

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

Меняем дефолтный archetypes/default.md на тот, что из темы:

$ cp /home/user/git/andrdi.ru/themes/techdoc/archetypes/default.md /home/user/git/andrdi.ru/archetypes/

Переносим файл CNAME в static чтобы не заботиться о его сохранности – теперь он всегда будет восстанавливаться в корне сайта:

$ mv /home/user/git/andrdi.ru/docs/CNAME /home/user/git/andrdi.ru/static/

Правим config.toml и приводим его к следующему виду:

baseURL = "https://andrdi.ru/"
languageCode = "ru-ru"
title = "Сайт на HUGO"
theme = "techdoc"
newContentEditor = "vim"
publishDir = "docs"
pygmentsStyle = "native"

По параметрам, вроде, ясно что к чему. Обращу внимание на пару деталей:

newContentEditor = "vim" – тем, кто не дружит с vim изменить, например, на nano.

publishDir = "docs" – по умолчанию сайт генерируется в каталоге public. Здесь мы его меняем на docs, который задали при создании репозитория.

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

Сайт готов к первой генерации и публикации. Генерируем сайт:

$ hugo -D

                   | EN  
+------------------+----+
  Pages            |  7  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     |  9  
  Processed images |  0  
  Aliases          |  0  
  Sitemaps         |  1  
  Cleaned          |  0  

Total in 50 ms

В archetypes у нас задан параметр draft: true. Это означает, что создаваемые командой hugo new новые ресурсы, по умолчанию являются черновиками и не попадают в сборку. Ключ -D включает черновики в сборку.

Смотрим что же у нас сгенерировалось:

$ ls docs

404.html  categories  CNAME  css  index.html  index.xml  js  sitemap.xml  tags

Проверяем изменения перед коммитом:

$ git status

Добавляем новые данные в коммит:

$ git add archetypes/ config.toml docs/ static/ themes/

Снова проверяем статус, коммитим и отправляем в GitHub:

$ git status
$ git commit -a -m "First Hugo commit"
$ git push

Открываем сайт в браузере:

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

Сделаю небольшое отступление про типы страниц в Hugo, они делятся на два типа:

Индексные файлы категорий – это файлы _index.md, находящиеся внутри каждого каталога (включая корневой), являющегося категорией для вложенных страниц. Создавать эти файлы необязательно. В этом случае вместо них будет показан список ссылок на вложенные страницы или то, что задано по умолчанию в теме оформления сайта.

Обычные markdown-файлы, сгенерированные командой hugo new и содержащие данные сайта.

Все исходные данные сайта находятся в каталоге content в виде дерева каталогов и файлов, повторяющего логическую структуру сайта. Файлы и каталоги, кстати, можно создавать вручную или путем копирования и правки соседних. Время публикации при этом не будет корректным, но кого это волнует?

Ну вот, пришло время добавить текста и котиков:

$ hugo new _index.md
$ hugo new cats/_index.md
$ hugo new cats/black.md
$ hugo new cats/white.md

Заполняем title, description и другие поля; добавляем текста и картинок.

Снова генерируем сайт (Содержимое каталога docs/ можно смело чистить перед генерацией – все будет создано заново. Заодно мусор удалится):

$ hugo -D

и коммитим по описанному выше алгоритму.

Выводы:

Я давно уже присматриваюсь к генераторам статического контента в связке с бесплатными хостингами статических сайтов. Это отличная замена CMS для небольших и несложных проектов: сайтов-визиток, блогов и т.п..

В связке с markdown, они являются отличной заменой для Wiki и, при правильной шаблонизации, могут вообще работать локально, вообще без веб-сервера – закинул на флешку и хоть на Северный Полюс.

Не нужно следить за ОС, ПО и безопасностью, заморачиваться над конфигами и быстродействием. Статика безопасна и максимально быстро раздается.

Стоимость владения таким сайтом, даже в случае публикации на Amazon S3 или mail.ru, все равно, болтается около нуля и, максимум, равна стоимости владения доменом плюс пара копеек за место и траффик.

Hugo меня не разочаровал. Скорее даже вдохновил. Это, по возможностям, практически полноценная замена CMS, и кроме того, не тянет за собой дополнительного ПО при установке. Очень быстрый. Единственный минус (если это вообще минус, а не плюс), характерный для многих генераторов статики – контент-менеджер должен быть знакомым с markdown и иметь базовые навыки верстки.

В общем, я очень доволен.

Результат, пока не закончится регистрация домена andrdi.ru, доступен здесь: https://andrdi.ru/.

Ссылка на сам репозиторий https://github.com/andrdi/andrdi.ru.

Знатная вышла простыня. Разбавлю, пожалуй, котиков собаками.