Настройка Хьюго
Конфигурационный файл
Хьюго использует файлы config.toml
, config.yaml
или config.json
(если он находится в корне сайта) в качестве файла конфигурации сайта по умолчанию.
Пользователь может выбрать переопределение этого значения по умолчанию с помощью одного или нескольких файлов конфигурации сайта, используя переключатель командной строки --config
.
Примеры:
hugo --config debugconfig.toml
hugo --config a.toml,b.toml,c.toml
Каталог конфигурации
В дополнение к использованию одного файла конфигурации сайта, можно использовать каталог configDir
(по умолчанию config/
), чтобы упростить организацию и настройки, специфичные для среды.
-
Каждый файл представляет собой корневой объект конфигурации, такой как
params.toml
для[Params]
,menu(s).toml
для[Menu]
,languages.toml
для[Languages]
и т.д… -
Содержимое каждого файла должно быть верхнего уровня, например:
В
config.toml
находится:[Params] foo = "bar"
В
params.toml
находится:foo = "bar"
-
Каждый каталог содержит группу файлов, содержащих настройки, уникальные для конкретной среды.
-
Файлы могут быть локализованы для соответствия языку.
├── config
│ ├── _default
│ │ ├── config.toml
│ │ ├── languages.toml
│ │ ├── menus.en.toml
│ │ ├── menus.zh.toml
│ │ └── params.toml
│ ├── production
│ │ ├── config.toml
│ │ └── params.toml
│ └── staging
│ ├── config.toml
│ └── params.toml
Учитывая приведенную выше структуру, при запуске hugo --environment staging
, Hugo будет использовать все настройки из config/_default
и объединить staging
поверх них.
Все настройки конфигурации
Ниже приводится полный список переменных, определенных Hugo, со значениями по умолчанию в скобках. Пользователи могут выбрать переопределение этих значений в файлах конфигурации своего сайта.
- archetypeDir (“archetypes”)
- Каталог, в котором Хьюго находит файлы архетипов (шаблоны содержимого). Also see Module Mounts Config for an alternative way to configure this directory (from Hugo 0.56).
- assetDir (“assets”)
- Каталог, в котором Хьюго находит файлы ресурсов, используемые в Hugo Pipes. Also see Module Mounts Config for an alternative way to configure this directory (from Hugo 0.56).
- baseURL
- Имя хоста (и путь) к корню, например, https://bep.is/
- blackfriday
- Смотрите Настройка Blackfriday
- build
- Смотрите Настройка сборки
- buildDrafts (false)
- Учитывать черновики при сборке.
- buildExpired (false)
- Включить контент, срок действия которого уже истек.
- buildFuture (false)
- Включите контент с датой публикации в будущем.
- caches
- Смотрите Настройка кеша файлов
- canonifyURLs (false)
- Включите, чтобы превратить относительные URL-адреса в абсолютные.
- contentDir (“content”)
- Каталог, из которого Хьюго читает файлы контента. Also see Module Mounts Config for an alternative way to configure this directory (from Hugo 0.56).
- dataDir (“data”)
- Каталог, из которого Хьюго читает файлы данных. Also see Module Mounts Config for an alternative way to configure this directory (from Hugo 0.56).
- defaultContentLanguage (“en”)
- Контент без индикатора языка по умолчанию будет использовать этот язык.
- defaultContentLanguageInSubdir (false)
- Отобразите язык содержимого по умолчанию в подкаталоге, например,
content/en/
. Затем корень сайта/
будет перенаправлен на/en/
. - disableAliases (false)
- Отключит генерацию переадресации псевдонимов. Обратите внимание, что даже если установлен
disableAliases
, сами псевдонимы сохраняются на странице. Мотивация при этом состоит в том, чтобы иметь возможность генерировать 301 редирект в файле.htaccess
, Netlify_redirects
или подобном с использованием настраиваемого формата вывода. - disableHugoGeneratorInject (false)
- По умолчанию Hugo вставляет метатег генератора в заголовок HTML на только домашнюю страницу. Вы можете отключить его, но мы будем очень признательны, если Вы этого не сделаете, так как это хороший способ наблюдать за ростом популярности Хьюго.
- disableKinds ([])
- Разрешить отключение всех страниц указанного Вида. Допустимые значения в этом списке:
"page"
,"home"
,"section"
,"taxonomy"
,"term"
,"RSS"
,"sitemap"
,"robotsTXT"
,"404"
. - disableLiveReload (false)
- Отключить автоматическую перезагрузку окна браузера в реальном времени.
- disablePathToLower (false)
- Не переводить URL/path в нижний регистр.
- enableEmoji (false)
- Включить поддержку смайлов Emoji для содержимого страницы; смотрите Памятку по эмодзи.
- enableGitInfo (false)
- Включите объект
.GitInfo
для каждой страницы (если версия сайта Hugo поддерживается Git). Затем это обновит параметрLastmod
для каждой страницы, используя дату последней фиксации git для этого файла содержимого. - enableInlineShortcodes (false)
- Включите встроенную поддержку шорткода. Смотрите Встроенные шорткоды.
- enableMissingTranslationPlaceholders (false)
- Показать заполнитель вместо значения по умолчанию или пустой строки, если перевод отсутствует.
- enableRobotsTXT (false)
- Включите создание файла
robots.txt
. - frontmatter
- Смотрите Конфигурация основного материала.
- footnoteAnchorPrefix ("")
- Префикс для якорей сноски.
- footnoteReturnLinkContents ("")
- Текст, отображаемый для обратных ссылок сноски.
- googleAnalytics ("")
- Идентификатор отслеживания Google Analytics.
- hasCJKLanguage (false)
- Если true, автоматически определять китайский/японский/корейский языки в содержимом. Это заставит
.Summary
и.WordCount
вести себя правильно для CJK языков. - imaging
- Смотрите Конфигурация обработки изображений.
- languages
- Смотрите Конфигурация языков.
- languageCode ("")
- Код языка сайта. Он используется в шаблоне RSS по умолчанию и может быть полезен для многоязычных сайтов.
- languageName ("")
- Название языка сайта.
- disableLanguages
- Смотрите Отключение языка
- layoutDir (“layouts”)
- Каталог, из которого Хьюго читает макеты (шаблоны).
- log (false)
- Включить ведение журнала.
- logFile ("")
- Путь к файлу журнала (если задан, ведение журнала включается автоматически).
- markup
- Смотрите Настройку разметки.
- menu
- Смотрите Добавление записей, не относящихся к содержанию, в меню.
- minify
- Смотрите Настройку Minify
- module
- Смотрите настройку модуля Конфигурация модуля.
- newContentEditor ("")
- Редактор для использования при создании нового контента.
- noChmod (false)
- Не синхронизировать режим разрешений файлов.
- noTimes (false)
- Не синхронизировать время модификации файлов.
- paginate (10)
- Количество элементов на странице по умолчанию в пагинации.
- paginatePath (“page”)
- Элемент пути, используемый при разбивке на страницы (https://example.com/page/2).
- permalinks
- Смотрите Управление содержанием.
- pluralizeListTitles (true)
- Множественное число заголовков в списках.
- publishDir (“public”)
- Каталог, в который Хьюго запишет окончательный статический сайт (файлы HTML и т.д.).
- related
- Смотрите Связанный контент.
- relativeURLs (false)
- Включите это, чтобы сделать все относительные URL-адреса относительно корня содержимого. Обратите внимание, что это не влияет на абсолютные URL-адреса.
- refLinksErrorLevel (“ERROR”)
- При использовании
ref
илиrelref
для разрешения ссылок на страницы и ссылка не может быть разрешена, она будет регистрироваться с этим уровнем журнала. Допустимые значенияERROR
(по умолчанию) илиWARNING
. ЛюбаяERROR
приведет к сбою сборки (exit -1
). - refLinksNotFoundURL
- URL-адрес, который будет использоваться в качестве заполнителя, когда ссылка на страницу не может быть найдена в
ref
илиrelref
. Используется как есть. - rssLimit (unlimited)
- Максимальное количество элементов в RSS-ленте.
- sectionPagesMenu ("")
- Смотрите “Меню раздела для отложенных блогеров”.
- sitemap
- По умолчанию конфигурация карты сайта.
- staticDir (“static”)
- Каталог или список каталогов, из которых Хьюго читает статические файлы. Also see Module Mounts Config for an alternative way to configure this directory (from Hugo 0.56).
- summaryLength (70)
- Длина текста в словах, отображаемого в
.Summary
. - taxonomies
- Смотрите конфигурацию таксономии.
- theme ("")
- Тема для использования (по умолчанию находится в
/themes/THEMENAME/
). - themesDir (“themes”)
- Каталог, из которого Хьюго читает темы.
- timeout (10000)
- Тайм-аут для создания содержимого страницы в миллисекундах (по умолчанию 10 секунд). Примечание: это используется для отказа от создания рекурсивного контента, если Ваши страницы генерируются медленно (например, потому что они требуют обработки больших изображений или зависят от удаленного содержимого), Вам может потребоваться увеличить этот предел.
- title ("")
- Название сайта.
- titleCaseStyle (“AP”)
- Смотрите настройку регистра заголовка
- uglyURLs (false)
- Когда этот параметр включен, создает URL-адрес в виде
/filename.html
вместо/filename/
. - verbose (false)
- Включить подробный вывод.
- verboseLog (false)
- Включить подробное ведение журнала.
- watch (false)
- Следите за изменениями файловой системы и воссоздайте ее по мере необходимости.
Настройка сборки
Раздел конфигурации build
содержит глобальные параметры конфигурации, связанные со сборкой.
build:
noJSConfigInAssets: false
useResourceCacheWhen: fallback
writeStats: false
[build]
noJSConfigInAssets = false
useResourceCacheWhen = "fallback"
writeStats = false
{
"build": {
"noJSConfigInAssets": false,
"useResourceCacheWhen": "fallback",
"writeStats": false
}
}
- useResourceCacheWhen
- Когда использовать кэшированные ресурсы в
/resources/_gen
для PostCSS и ToCSS. Допустимые значенияnever
,always
иfallback
. Последнее значение означает, что кеш будет проверяться, если PostCSS/расширенная версия недоступна. - writeStats
- Если этот параметр включен, в корень Вашего проекта будет записан файл с именем
hugo_stats.json
с некоторыми агрегированными данными о сборке, например список объектов HTML, опубликованных для использования для сокращения CSS. Если Вы используете его только для производственной сборки, Вам следует подумать о том, чтобы разместить его ниже config/production. Также стоит упомянуть, что из-за характера частичных сборок сервера новые HTML-объекты будут добавляться, когда Вы добавляете или изменяете их во время работы сервера, но старые значения не будут удалены, пока Вы не перезапустите сервер или не запустите обычную сборкуhugo
. - noJSConfigInAssets
- Отключите запись
jsconfig.js
в папку/assets
с отображением импорта из запущенного js.Build. Этот файл предназначен для помощи с intellisense / навигацией внутри редакторов кода, таких как VS Code. Обратите внимание, что если Вы не используетеjs.Build
, файл не будет записан.
Настройка сервера
Это актуально только при запуске hugo server
и позволяет устанавливать заголовки HTTP во время разработки, что позволяет Вам протестировать свою Политику безопасности контента и тому подобное. Формат конфигурации соответствует Netlify’s с чуть более мощным Glob matching:
server:
headers:
- for: /**.html
values:
Content-Security-Policy: script-src localhost:1313
Referrer-Policy: strict-origin-when-cross-origin
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
[server]
[[server.headers]]
for = "/**.html"
[server.headers.values]
Content-Security-Policy = "script-src localhost:1313"
Referrer-Policy = "strict-origin-when-cross-origin"
X-Content-Type-Options = "nosniff"
X-Frame-Options = "DENY"
X-XSS-Protection = "1; mode=block"
{
"server": {
"headers": [
{
"for": "/**.html",
"values": {
"Content-Security-Policy": "script-src localhost:1313",
"Referrer-Policy": "strict-origin-when-cross-origin",
"X-Content-Type-Options": "nosniff",
"X-Frame-Options": "DENY",
"X-XSS-Protection": "1; mode=block"
}
}
]
}
}
Поскольку это “только разработка”, возможно, имеет смысл поместить его под средой development
:
headers:
- for: /**.html
values:
Content-Security-Policy: script-src localhost:1313
Referrer-Policy: strict-origin-when-cross-origin
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
[[headers]]
for = "/**.html"
[headers.values]
Content-Security-Policy = "script-src localhost:1313"
Referrer-Policy = "strict-origin-when-cross-origin"
X-Content-Type-Options = "nosniff"
X-Frame-Options = "DENY"
X-XSS-Protection = "1; mode=block"
{
"headers": [
{
"for": "/**.html",
"values": {
"Content-Security-Policy": "script-src localhost:1313",
"Referrer-Policy": "strict-origin-when-cross-origin",
"X-Content-Type-Options": "nosniff",
"X-Frame-Options": "DENY",
"X-XSS-Protection": "1; mode=block"
}
}
]
}
Вы также можете указать простые правила перенаправления для сервера. Синтаксис снова аналогичен синтаксису Netlify.
Обратите внимание, что код статуса status
200 вызовет перезапись URL, что Вы и хотите в ситуациях SPA, например:
redirects:
- force: false
from: /myspa/**
status: 200
to: /myspa/
[[redirects]]
force = false
from = "/myspa/**"
status = 200
to = "/myspa/"
{
"redirects": [
{
"force": false,
"from": "/myspa/**",
"status": 200,
"to": "/myspa/"
}
]
}
Установка force=true
приведет к перенаправлению, даже если в пути уже есть контент. Обратите внимание, что до Hugo 0.76 force
был поведением по умолчанию, но это соответствует тому, как это делает Netlify.
Настройка регистра заголовка
Установите titleCaseStyle
, чтобы указать стиль заголовка, используемый функцией шаблона заголовка, и автоматические заголовки разделов в Hugo. По умолчанию для заголовка используется AP Stylebook, но Вы также можете установить его на Chicago
или Go
(каждое слово начинается с заглавной буквы).
Настройка переменных среды разработки
- HUGO_NUMWORKERMULTIPLIER
- Можно настроить на увеличение или уменьшение количества рабочих процессов, используемых при параллельной обработке в Hugo. Если не установлен, будет использовано количество логических ЦП.
Настройка порядка поиска
Подобно шаблону порядка поиска, Hugo имеет стандартный набор правил для поиска файла конфигурации в корне исходного каталога Вашего веб-сайта в качестве поведения по умолчанию:
./config.toml
./config.yaml
./config.json
В Вашем файле config
Вы можете указать Хьюго, как Вы хотите отображать свой веб-сайт, управлять меню своего веб-сайта и произвольно определять параметры сайта, специфичные для Вашего проекта.
Пример конфигурации
Ниже приведен типичный пример файла конфигурации. Значения, вложенные в params:
, будут заполнять переменную .Site.Params
для использования в шаблонах:
baseURL: https://yoursite.example.com/
footnoteReturnLinkContents: ↩
params:
AuthorName: Jon Doe
GitHubUser: spf13
ListOfFoo:
- foo1
- foo2
SidebarRecentLimit: 5
Subtitle: Hugo is Absurdly Fast!
permalinks:
posts: /:year/:month/:title/
title: My Hugo Site
baseURL = "https://yoursite.example.com/"
footnoteReturnLinkContents = "↩"
title = "My Hugo Site"
[params]
AuthorName = "Jon Doe"
GitHubUser = "spf13"
ListOfFoo = ["foo1", "foo2"]
SidebarRecentLimit = 5
Subtitle = "Hugo is Absurdly Fast!"
[permalinks]
posts = "/:year/:month/:title/"
{
"baseURL": "https://yoursite.example.com/",
"footnoteReturnLinkContents": "↩",
"params": {
"AuthorName": "Jon Doe",
"GitHubUser": "spf13",
"ListOfFoo": [
"foo1",
"foo2"
],
"SidebarRecentLimit": 5,
"Subtitle": "Hugo is Absurdly Fast!"
},
"permalinks": {
"posts": "/:year/:month/:title/"
},
"title": "My Hugo Site"
}
Настройка с помощью переменных среды разработки
В дополнение к 3 уже упомянутым параметрам конфигурации, пары “ключ-значение” конфигурации могут быть определены через переменные среды операционной системы.
Например, следующая команда эффективно устанавливает заголовок веб-сайта в Unix-подобных системах:
$ env HUGO_TITLE="Some Title" hugo
Это действительно полезно, если Вы используете такую службу, как Netlify, для развертывания своего сайта. Посмотрите в качестве примера документацию Hugo файл конфигурации Netlify.
Если Вы используете имена переменных snake_cased, приведенное выше не будет работать, поэтому, поскольку Hugo 0.79.0, Hugo определяет разделитель, который будет использоваться первым символом после HUGO
. Это позволяет Вам определять переменные среды в форме HUGOxPARAMSxAPI_KEY=abcdefgh
, используя любой разрешенный разделитель.
Игнорировать файлы содержимого при рендеринге
Следующий оператор внутри ./config.toml
заставит Hugo игнорировать файлы содержимого, заканчивающиеся на .foo
и .boo
при рендеринге:
ignoreFiles = [ "\\.foo$", "\\.boo$" ]
Выше приведен список регулярных выражений. Обратите внимание, что символ обратной косой черты (\
) в этом примере экранирован, чтобы сохранить TOML счастливым.
Настройка переднего плана
Настройка даты
Даты важны в Hugo, и Вы можете настроить, как Hugo назначает даты Вашим информационным страницам. Вы делаете это, добавляя раздел frontmatter
в Ваш config.toml
.
Конфигурация по умолчанию:
[frontmatter]
date = ["date", "publishDate", "lastmod"]
lastmod = [":git", "lastmod", "date", "publishDate"]
publishDate = ["publishDate", "date"]
expiryDate = ["expiryDate"]
Если у Вас, например, есть нестандартный параметр даты в каком-либо из Ваших материалов, Вы можете переопределить настройку для date
:
[frontmatter]
date = ["myDate", ":default"]
:default
- это ярлык для настроек по умолчанию. Вышеупомянутое установит .Date
в значение даты в myDate
, если оно присутствует, в противном случае мы посмотрим на date
,publishDate
, lastmod
и выберем первую действительную дату.
В списке справа значения, начинающиеся с “:”, являются обработчиками дат со специальным значением (см. ниже). Остальные - это просто имена параметров даты (без учета регистра) в Вашей конфигурации. Также обратите внимание, что у Hugo есть несколько встроенных псевдонимов для вышеуказанного: lastmod
=> modified
, publishDate
=> pubdate
, published
и expiryDate
=> unpublishdate
. При этом, в качестве примера, использование pubDate
в качестве даты перед публикацией по умолчанию будет присвоено .PublishDate
.
К специальным обработчикам дат относятся:
:fileModTime
- Получает дату из метки времени последнего изменения файла содержимого.
Пример:
[frontmatter]
lastmod = ["lastmod", ":fileModTime", ":default"]
Вышеупомянутое сначала попытается извлечь значение для .Lastmod
, начиная с переднего параметра lastmod
, а затем отметку времени модификации файла содержимого. Последний, :default
, здесь не нужен, но Хьюго наконец будет искать действительную дату в :git
, date
, а затем в publishDate
.
:filename
- Получает дату из имени файла файла содержимого. Например,
2018-02-22-mypage.md
извлечет дату2018-02-22
. Кроме того, еслиslug
не установлен,mypage
будет использоваться как значение для.Slug
.
Пример:
[frontmatter]
date = [":filename", ":default"]
Вышеупомянутое сначала попытается извлечь значение для .Date
из имени файла, затем оно будет смотреть в параметрах date
, publishDate
и, наконец, lastmod
.
:git
- Это дата создания Git последней редакции этого файла содержимого. Это будет установлено, только если установлен параметр
--enableGitInfo
илиenableGitInfo = true
в конфигурации сайта.
Настройка дополнительных форматов вывода
В Hugo v0.20 появилась возможность отображать Ваш контент в нескольких форматах вывода (например, в JSON, AMP html или CSV). Смотрите Форматы вывода для получения информации о том, как добавить эти значения в файл конфигурации Вашего проекта Hugo.
Настройка Minify
Конфигурация по умолчанию:
minify:
disableCSS: false
disableHTML: false
disableJS: false
disableJSON: false
disableSVG: false
disableXML: false
minifyOutput: false
tdewolff:
css:
decimals: -1
keepCSS2: true
html:
keepConditionalComments: true
keepDefaultAttrVals: true
keepDocumentTags: true
keepEndTags: true
keepQuotes: false
keepWhitespace: false
js: {}
json: {}
svg:
decimals: -1
xml:
keepWhitespace: false
[minify]
disableCSS = false
disableHTML = false
disableJS = false
disableJSON = false
disableSVG = false
disableXML = false
minifyOutput = false
[minify.tdewolff]
[minify.tdewolff.css]
decimals = -1
keepCSS2 = true
[minify.tdewolff.html]
keepConditionalComments = true
keepDefaultAttrVals = true
keepDocumentTags = true
keepEndTags = true
keepQuotes = false
keepWhitespace = false
[minify.tdewolff.js]
[minify.tdewolff.json]
[minify.tdewolff.svg]
decimals = -1
[minify.tdewolff.xml]
keepWhitespace = false
{
"minify": {
"disableCSS": false,
"disableHTML": false,
"disableJS": false,
"disableJSON": false,
"disableSVG": false,
"disableXML": false,
"minifyOutput": false,
"tdewolff": {
"css": {
"decimals": -1,
"keepCSS2": true
},
"html": {
"keepConditionalComments": true,
"keepDefaultAttrVals": true,
"keepDocumentTags": true,
"keepEndTags": true,
"keepQuotes": false,
"keepWhitespace": false
},
"js": {},
"json": {},
"svg": {
"decimals": -1
},
"xml": {
"keepWhitespace": false
}
}
}
}
Настройка кеши файлов
Начиная с Hugo 0.52 Вы можете настраивать не только cacheDir
. Это конфигурация по умолчанию:
caches:
assets:
dir: :resourceDir/_gen
maxAge: -1
getcsv:
dir: :cacheDir/:project
maxAge: -1
getjson:
dir: :cacheDir/:project
maxAge: -1
images:
dir: :resourceDir/_gen
maxAge: -1
modules:
dir: :cacheDir/modules
maxAge: -1
[caches]
[caches.assets]
dir = ":resourceDir/_gen"
maxAge = -1
[caches.getcsv]
dir = ":cacheDir/:project"
maxAge = -1
[caches.getjson]
dir = ":cacheDir/:project"
maxAge = -1
[caches.images]
dir = ":resourceDir/_gen"
maxAge = -1
[caches.modules]
dir = ":cacheDir/modules"
maxAge = -1
{
"caches": {
"assets": {
"dir": ":resourceDir/_gen",
"maxAge": -1
},
"getcsv": {
"dir": ":cacheDir/:project",
"maxAge": -1
},
"getjson": {
"dir": ":cacheDir/:project",
"maxAge": -1
},
"images": {
"dir": ":resourceDir/_gen",
"maxAge": -1
},
"modules": {
"dir": ":cacheDir/modules",
"maxAge": -1
}
}
}
Вы можете переопределить любую из этих настроек кеша в Вашем собственном файле config.toml
.
Объяснение ключевых слов
:cacheDir
- Это значение параметра конфигурации
cacheDir
, если оно установлено (также может быть установлено через переменную env ОСHUGO_CACHEDIR
). Он вернется к/opt/build/cache/hugo_cache/
на Netlify или к каталогуhugo_cache
ниже временного каталога ОС для остальных. Это означает, что если Вы запустите свои сборки на Netlify, все кеши, настроенные с помощью:cacheDir
, будут сохранены и восстановлены при следующей сборке. Для других поставщиков CI, пожалуйста, прочтите их документацию. Смотрите пример CircleCI этой конфигурации. :project
- Имя базового каталога текущего проекта Hugo. Это означает, что в настройках по умолчанию каждый проект будет иметь отдельные кеши файлов, а это значит, что когда Вы выполняете
hugo --gc
, Вы не будете касаться файлов, связанных с другими проектами Hugo, запущенными на том же ПК. :resourceDir
- Это значение параметра конфигурации
resourceDir
. - maxAge
- Это время до того, как запись в кэше будет удалена, -1 означает навсегда, а 0 эффективно отключает этот конкретный кеш. Использует Go
time.Duration
, поэтому допустимые значения:"10s"
(10 секунд),"10m"
(10 минут) и"10h"
(10 часов). - dir
- Абсолютный путь к месту хранения файлов этого кеша. Допустимые начальные заполнители:
:cacheDir
и:resourceDir
(смотрите выше).