В предыдущем посте я писал чем может быть интересен статический сайт и как его можно создать на базе репозитория в GitHub. Продолжу тему и расскажу, как создать сайт с помощью генератора статического html Hugo и разместить на GitHub Pages.
Для эксперимента с созданием сайта, я ранее зарегистрировал отдельный домен andrdi.ru и дальнейшее описание будет с использованием этого домена.
Подразумевается, что у нас уже установлен Git и мы понимаем как он работает, а также знаем, что такое markdown и с чем его едят. Все команды я проверял на себе, но здравый смысл и чтение документации никто не отменял.
Для начала определимся с задачей: Создать сайт про котиков, имеющий следующую структуру:
.
├── HOME
└── cats
├── black
└── white
С воображением у меня туго, поэтому пусть это будут котики.
Порядок действий следующий:
- Установка Hugo
- Создание структуры сайта
- Установка темы (внешнего вида) сайта
- Настройка сайта
- Публикация сайта
- Добавление контента
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
Рассмотрим подробнее:
Имя файла (каталога) | Описание |
---|---|
archetypes | Каталог, содержащий шаблоны новых md-файлов, которые создает Hugo с помощью команды hugo new |
config.toml | Основной конфиг сайта |
content | Каталог данных, из которых Hugo будет генерировать сайт |
data | Каталог дополнительных данных, которые непосредственно не учавствуют в генерации сайта |
docs | Корень генерируемого сайта. Этот каталог не создается Hugo, мы его получили при заведении репозитория на GitHub и ниже мы его пропишем в файле config.toml |
layouts | Содержит шаблоны сайта |
static | Каталог для статических данных (изображения, CSS, JavaScript и т.д.) |
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.
Знатная вышла простыня. Разбавлю, пожалуй, котиков собаками.