Hugo
Hugo — самый быстрый генератор статических сайтов.
- Очень быстрый (видео генерации 5000 страниц за 6 секунд).
- Содержимое сайта хранится в виде простых текстовых файлов с расширением
.mdи редактируется в форматах Markdown и HTML. - Простая и логичная структура папок и файлов контента:
content
├── _index.md
├── categories
│ ├── _index.md
│ └── photo
│ └── _index.md
├── post
│ ├── _index.md
│ ├── firstpost.md
│ └── secondpost.md
└── tags
├── _index.md
└── hugo
└── _index.md
Сначала нужно скачать и установить Go:
Проверить версию Go:
go version
snap install hugo --channel=extended
Установить brew командой с официального сайта: https://brew.sh/
Установить Hugo (будет установлена extended версия):
brew install hugo
Сначала установить последнюю версию Go:
sudo add-apt-repository ppa:longsleep/golang-backports sudo apt install golang
Затем следовать официальной инструкции:
mkdir $HOME/src cd $HOME/src git clone https://github.com/gohugoio/hugo.git cd hugo go install --tags extended
Запустить Power Shell:
Win-R — powershell — Enter
Проверить версию — должна быть не ниже 5:
$PSVersionTable
Установить Scoop:
iwr -useb get.scoop.sh | iex
Установить Hugo и Git:
scoop install hugo git
Проверить версию Hugo:
hugo version
Обновить:
brew upgrade hugo
Перейдите в папку с проектами (типа ~/Sites) и выполните команду:
hugo new site site-name
Будет создана папка site-name и внутри структура из папок и файлов (Directory Structure):
site-name ├── archetypes # шаблоны типов материалов │ └── default.md # шаблон по умолчанию ├── content # страницы сайта (файлы .md и .html) и разделы (папки) ├── data # хранилище дополнительных данных ├── layouts # шаблоны (если нет темы) ├── resources # кеш ресурсов ├── static # статичные файлы типа .css, .js, изображений и т.п. ├── themes # темы └── config.toml # основной конфигурационный файл сайта
Добавьте в конфиг config.toml параметр, отключающий создание файлов .xml для RSS:
disableKinds = ["RSS","sitemap"]
Создайте первую черновую страницу контента:
hugo new posts/my-first-post.md
Текстовый файл этой страницы в формате Markdown появится в папке контента:
site-name
└── content
└── posts
└── my-first-post.md
Запустите сервер с параметром -D, включающим отображение черновых страниц (потому что в созданном файле my-first-post.md по умолчанию добавлен параметр черновика draft: true):
hugo server -D
Откройте в браузере http://localhost:1313/posts/my-first-post
В режиме сервера Hugo следит за изменениями в файлах контента и темы и автоматически обновляет сайт и окно браузера.
Страницы пока что сгенерированы в памяти, без записи файлов на диск. Чтобы сохранить их, запустите Hugo без сервера:
hugo -D
Файлы сайта будут записаны в папку public.
Находясь в корневой папке сайта, создайте новую тему:
hugo new theme theme-name
В папке themes будет создана структура:
site-name
└── themes
└── theme-name
├── archetypes
│ └── default.md
├── layouts
│ ├── _default
│ │ ├── baseof.html
│ │ ├── list.html
│ │ └── single.html
│ ├── partials
│ │ ├── footer.html
│ │ ├── header.html
│ │ └── head.html
│ ├── 404.html
│ └── index.html
├── static
│ ├── css
│ └── js
├── LICENSE
└── theme.toml
Добавьте новую тему в основной конфиг config.toml:
theme = "theme-name"
Можно это сделать одной командой:
echo 'theme = "theme-name"' >> config.toml
При настройке темы можно ограничиться минимальным набором файлов:
site-name
└── themes
└── theme-name
└── layouts
├── _default
│ ├── baseof.html
│ ├── list.html
│ └── single.html
└── index.html
Настройки сайта на Hugo хранятся в корне проекта в файле config.toml (или config.yaml).
baseurl: "http://www.example.com/"
title: "Название сайта"
languageCode: "ru-ru"
Все параметры: https://gohugo.io/overview/configuration/
Проверить все действующие параметры сайта:
hugo config
Отфильтровать — например, найти все параметры директорий:
hugo config | grep -i dir
Помимо стандартных параметров можно создавать собственные.
Например, добавим в конфиг два параметра:
devMode— чтобы включать и выключать отображение на сайте служебной информации;description— чтобы использовать как стандартный description, если не заполнен description страницы.
Добавьте в файл config.toml строки:
[params]
description = "Описание сайта"
devMode = true
Добавьте в шаблон layouts/_default/single.html код:
{{ if eq .Site.Params.devmode "yes" }}
{{ if .Params.note }}
<div>{{ .Params.note }}</div>
{{ end }}
{{ end }}
Теперь можно добавлять во front matter страниц (см. подробнее ниже) заметки типа note: Не забыть поправить… и во время разработки сайта с включенным параметром showTechInfo эти заметки будут отображаться, а с выключенным или отсутствующим — нет.
Другой пример - подстановка номера счетчика Google Analytics из параметра в config.toml в шаблон:
[params]
googleAnalytics = "UA-123456789-1"
Код счетчика в шаблоне:
{{ if not .Site.IsServer }}
{{ with .Site.Params.googleAnalytics }}
<script>
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', '{{ . }}', 'auto');
ga('send', 'pageview');
</script>
<script async src='https://www.google-analytics.com/analytics.js'></script>
{{ end }}
{{ end }}
Здесь используется функция with — если параметр не задан, то весь блок не будет показан.
И заодно здесь показан пример с переменной .Site.IsServer — если сайт тестируется на встроенном сервере Hugo, то блок тоже не будет показан.
Hugo позволяет на лету создавать новые параметры страницы (поля), просто добавляя во front matter (верхняя часть файла страницы .md) название параметра и его значение.
Например, добавим в страницу параметр showOnHomepage, в котором будем писать yes, если нужно показать эту страницу в блоке на главной странице.
Сначала определите параметр во front matter страницы:
---
showOnHomepage: "yes"
---
Чтобы вывести параметр showOnHomepage прямо на странице, в которую он добавлен, добавьте следующую строку в соответствующий шаблон (для большинства страниц подойдет шаблон layouts/_default/single.html):
{{ .Params.showonhomepage }}
Обратите внимание: имя параметра пишется в нижнем регистре, независимо от того, как он был написан во front matter.
Если мы хотим видеть параметр на странице только в том случае, если он определен (заполнен), то используем такой код:
{{ if .Params.showonhomepage }}
<div>{{ .Params.showonhomepage }}</div>
{{ end }}
А функция isset проверяет, существует ли вообще параметр showOnHomepage:
{{ if isset .Params "showonhomepage" }}
<div>{{ .Params.showonhomepage }}</div>
{{ end }}
По умолчанию контент страницы можно вывести такой переменной:
{{ .Content }}
Чтобы выделить верхнюю часть текста страницы в отдельный параметр .Summary, достаточно вставить в текст разделитель (всё, что выше него, пойдет в .Summary):
<!--more-->
Важно писать <!--more--> именно в таком виде — без пробелов и в нижнем регистре.
Если вывести текст страницы с расширением .md переменной .Content, то в ней будет и .Summary, и остальной текст. (В файлах страниц с расширением .html почему-то не так — .Content выводится без .Summary.) Если нужно вывести контент отдельно от .Summary:
<div class="page-summary">
{{ .Summary }}
</div>
<div class="page-content">
{{ $body := replace .Content .Summary "" }}
{{ $body | safeHTML }}
</div>
Чтобы убрать лишние тэги <p> вокруг .Summary (см. также):
{{ .Summary | replaceRE "^<p>|<p></p>$" "" | safeHTML }}
Типы страниц Hugo хранятся в папке archetypes в виде шаблонов в формате .md.
Для примера создадим тип страниц work.md.
Скопируйте default.md:
cp archetypes/default.md archetypes/work.md
Добавьте в заголовке шаблона work.md нужные параметры (поля), например:
---
draft: true
description: ""
slug: ""
categories:
- Site
- Shop
- Corporate ID
tags:
- Drupal
- Bootstap
years: 2016
---
В шаблон можно не добавлять поля title и date, они в любом случае будут добавлены автоматически при создании страницы.
Поля, содержащие несколько значений, можно записывать или как показан пример с categories — в строку в квадратных скобках, или как пример с tags — списком. По умолчанию Hugo использует второй вариант.
Два способа создать страницу нужного типа:
1) написать путь, который совпадает с именем типа страниц:
hugo new work/new_page.md
2) использовать параметр --kind или -k — тогда можно создать страницу с любым путем:
hugo new -k work any_path/new_page.md
Шаблон для создания страниц для терминов таксономии типа <taxonomy>/<term>/_index.md
Создайте новый файл с именем термина таксономии: archetypes/<taxonomy>.md (например, archetypes/brands.md)
---
title: {{ $term := index ( split .File.Dir "/") 1 }}"{{ replace $term "-" " " | title }}"
description: "This is the description for {{ $term | title }}"
website: "http://{{ $term }}.com"
logo: "/images/{{ $term }}.jpg"
date: {{ .Date }}
draft: false
---
Протестируйте:
hugo new brands/test/_index.md
Результат:
---
title: "Test"
description: "This is the description for Test"
website: "http://test.com"
logo: "/images/test.jpg"
date: 2017-08-07T12:04:03-06:00
draft: false
---
- Taxonomy (таксономия, словари терминов) — категоризация
- Term (термин) — ключ внутри словаря таксономии
- Value — часть контента, назначенного термину
Таксономия для сайта определяется в файле config.toml.
Формат имени каждого словаря: singular key: "plural value", т.е. имени словаря в единственном числе назначается значение в виде множественного числа этого же имени.
По умолчанию есть два словаря — tags и categories. Если других словарей не будет, то можно эти не упоминать в конфиге. Если будут дополнительные словари, то нужно упомянуть в конфиге все словари.
Например, добавим словарь years:
taxonomies:
tag: "tags"
category: "categories"
year: "years"
Название словаря, помещенное в кавычки, будет использовано в его URL. Например, можно сделать так, чтобы страница словаря находилась во вложенной директории:
taxonomies:
category: "portfolio/categories"
Поскольку словари таксономии определяются на уровне всего сайта, то любая часть контента может быть отнесена к таксономии, невзирая на тип контента или раздел сайта.
Назначение контента таксономии делается во front matter страницы. Просто добавьте переменную с именем словаря таксономии во множественном числе:
---
categories:
- Corporate ID
tags:
- Drupal
- Адаптивная верстка
years:
- 2016
---
Список терминов словаря таксономии можно посмотреть по адресу типа /PLURAL/ (/categories/), а список материалов, относящихся к термину, по адресу /PLURAL/TERM/ (/categories/corporate-id/).
- Списки страниц Hugo
- Списки таксономии Hugo
- ShortCodes — шаблоны Hugo внутри текста страниц
- Параметры страниц в шаблонах Hugo
Устарело, обновить:
Команды шаблонизатора пишутся внутри фигурных скобок.
Комментарии — как в CSS, но тоже внутри фигурных скобок:
{{/*
{{ . }}
*/}}
Шаблонизатор Go убирает все HTML комментарии, оставляя пустые строки.
Чтобы комментарии остались в итоговом HTML, нужно их писать так:
{{ "<!-- foo bar -->" | safeHTML }}
И Hugo, и Vue используют синтаксис с двойными фигурными скобками {{ counter }}, из-за чего Hugo возвращает ошибку.
Можно использовать так (обсуждение):
{{ safeHTML `
Счётчик: {{ counter }}
` }}
Либо изменить синтаксис Vue - вместо фигурных скобок использовать квадратные (статья):
new Vue({
delimiters: ["[[", "]]"],
Счётчик: [[ counter ]]
Примеры простых условий:
{{ if .IsHome }}
Это главная страница
{{ end }}
{{ if not .IsHome }}
Это внутренняя страница.
{{ end }}
{{ if ne .IsHome true }}
Это внутренняя страница.
{{ end }}
{{ if and (eq .Section "dictionary") (eq .Kind "page") }}
Это страница раздела dictionary, но не главная его страница.
{{ end }}
Больше примеров: Hugo's cond template function explained
defaultContentLanguage: "ru"
defaultContentLanguageInSubdir = true
languageCode: "ru-ru"
Все languageCode: http://www.lingoes.net/en/translator/langcode.htm.
Чаще всего используемые:
en-us ru-ru uk-ua
В config.toml добавить:
[languages]
[languages.ru]
title = "Название сайта"
weight = 1
languageName = "Рус"
languageCode = "ru-ru"
[languages.ru.params]
Locale = "ru_RU" # В т.ч. нужно для Facebook
[languages.uk]
title = "Назва сайту"
weight = 2
languageName = "Укр"
languageCode = "uk-ua"
[languages.uk.params]
Locale = "uk_UA"
Файлы контента создавать с таким же префиксом, как у параметра languages:
_index.ru.md _index.uk.md page.ru.md page.uk.md
Шаблон тэга hreflang (который ссылается на версии этой же страницы на других языках):
{{ if .IsTranslated }}
{{ range .Translations }}
<link rel="alternate" hreflang="{{ .Lang }}" href="{{ .Permalink }}" />
{{ end }}
{{ end }}
{{ if eq .Lang "uk" }}
Створення сайту
{{ else if eq .Lang "ru" }}
Создание сайта
{{ end }}
{{ if eq $.Site.Language.Lang "uk" }}
Створення сайту
{{ else if eq $.Site.Language.Lang "ru" }}
Создание сайта
{{ end }}
Создать страницу:
hugo new numerals/test.ru.md
Создать шаблон:
layouts/numerals/single.html
<ul>
<li>0 {{i18n "year" 0}}</li>
<li>1 {{i18n "year" 1}}</li>
<li>2 {{i18n "year" 2}}</li>
<li>3 {{i18n "year" 3}}</li>
<li>4 {{i18n "year" 4}}</li>
<li>5 {{i18n "year" 5}}</li>
<li>6 {{i18n "year" 6}}</li>
<li>7 {{i18n "year" 7}}</li>
<li>8 {{i18n "year" 8}}</li>
<li>9 {{i18n "year" 9}}</li>
<li>10 {{i18n "year" 10}}</li>
<li>11 {{i18n "year" 11}}</li>
<li>12 {{i18n "year" 12}}</li>
<li>13 {{i18n "year" 13}}</li>
<li>14 {{i18n "year" 14}}</li>
<li>15 {{i18n "year" 15}}</li>
<li>16 {{i18n "year" 16}}</li>
<li>17 {{i18n "year" 17}}</li>
<li>18 {{i18n "year" 18}}</li>
<li>19 {{i18n "year" 19}}</li>
<li>20 {{i18n "year" 20}}</li>
<li>21 {{i18n "year" 21}}</li>
<li>22 {{i18n "year" 22}}</li>
<li>23 {{i18n "year" 23}}</li>
<li>24 {{i18n "year" 24}}</li>
<li>25 {{i18n "year" 25}}</li>
<li>26 {{i18n "year" 26}}</li>
<li>101171 {{i18n "year" 101171}} </li>
</ul>
Добавить переводы:
i18n/ru.yaml
- id: year
translation:
zero: ни одного года
one: год
few: года
many: лет
other: года
i18n/uk.yaml
- id: year
translation:
zero: жодного року
one: рік
few: роки
many: років
other: роки
Открыть: http://localhost:1313/ru/numerals/test/ — будуть правильно просклоненные в множественном числе года:
- 0 лет
- 1 год
- 2 года
- ...
- 5 лет
- ...
- 20 лет
- 21 год
- 22 года
- ...
- 25 лет
- ...
- 101171 год
hugo --i18n-warnings | grep i18n
Начиная с версии v0.93.0:
hugo --printI18nWarnings | grep i18n
Показать отсутствующие переводы:
hugo --printI18nWarnings
Показать дублирующиеся пути и т.п.:
hugo --printPathWarnings
Показать неиспользуемые шаблоны:
hugo --printUnusedTemplates
Найти наиболее медленные шаблоны:
hugo --templateMetrics --templateMetricsHints
Те шаблоны, у которых в столбце "cache potential" стоит 100 или близкое к 100 значение, можно подключить не через partial, а через partialCached.
- https://circleci.com/pricing/ — CircleCI бесплатно
1. Установить плагин Go Template Support
2. Добавить в settings.json:
{
"files.associations": {
"*.html": "gohtml"
}
}
2020
- hugo related blogposts | Martijn van Vreeden
- Convert your plain old HTML site to Hugo
- Hugo static site tutorials
- Override a Hugo theme
- Syntax highlighting in Hugo with Chroma
Old
- Tips and tricks for building a theme in Hugo
- Статичные сайты
- Grunt and Hugo: A Fast Iteration Cookbook
- Hugo 101 series
- ktmud/huggle — Hugo theme boilerplate with Gulp and multiple-language support (глючит, потому что под Mac)
Пример сайта с кодом:
- https://robertbasic.com/ — https://github.com/robertbasic/robertbasic.com-hugo
- https://jamescampbell.us/ — https://github.com/jamesacampbell/causes-and-effects-hugo
⚡ AMP starter theme: