Hugo: Что такое Config Folder?

| August 23, 2022

Материал этой статьи предназначен для тех, кто уже обладает 
некоторыми знаниями по созданию сайтов с помощью Hugo. 

Если Вы НЕ один из таких, то я Вас научу. 
Следите за новостями на сайте! 🤝

Введение

Продолжаю делиться лучшими практиками Hugo. На этот раз мы поговорим о:

  • самом простом способе работать с конфигурацией Hugo веб-сайта
  • о том, почему самый простой способ - не значит - самый лучший
  • и о том, как действительно стоит управлять конфигурацией Hugo веб-сайтов (спойлер: через Config Folder)

Основная часть

Ну а прежде, чем мы начнём разговор о такой мощной фиче Hugo - как Config Folder, нужно разобраться с тем, а как вообще работа с конфигурацией выглядит в Hugo.

Стандартный подход

Для примера, возьмём следующий файл конфигурации:

baseURL = "http://example.com/"
languageCode = "en-us"
title = "Привет"
theme = "minimal"
disqusShortname = "username" # delete this to disable disqus comments
googleAnalytics = ""

[params]
    author = "Анвер Богатов"
    description = "Личный островок в океане Интернета"
    githubUsername = "#"
    accent = "red"
    showBorder = true
    backgroundColor = "white"
    font = "Raleway" # should match the name on Google Fonts!
    highlight = true
    highlightStyle = "default"
    highlightLanguages = ["go", "haskell", "kotlin", "scala", "swift"]

[[menu.main]]
    url = "/"
    name = "🏠"
    weight = 1

[[menu.main]]
    url = "/about/"
    name = "О проекте"
    weight = 2

[[menu.main]]
    url = "/post/"
    name = "Статьи"
    weight = 3

[[menu.main]]
    url = "/books/"
    name = "Книги"
    weight = 4

[[menu.main]]
    url = "/movies/"
    name = "Фильмы"
    weight = 5

# Social icons to be shown on the right-hand side of the navigation bar.
# The "name" field should match the name of the icon in Font Awesome.
# The list of available icons can be found at http://fontawesome.io/icons.

[[menu.icon]]
    url = "mailto:contact@flower2u.com"
    name = "fas fa-envelope"
    weight = 1

[[menu.icon]]
    url = "https://github.com/username/"
    name = "fab fa-github"
    weight = 2

[[menu.icon]]
    url = "https://twitter.com/username/"
    name = "fab fa-twitter"
    weight = 3

[[menu.icon]]
    url = "https://www.linkedin.com/in/username/"
    name = "fab fa-linkedin"
    weight = 4

[[menu.icon]]
    url = "https://www.stackoverflow.com/username/"
    name = "fab fa-stack-overflow"
    weight = 5

Перед Вами - абсолютно стандартный файл конфигурации Hugo проекта. Точно такой же, или похожий, Вы можете получить просто создав новый проект Hugo веб сайта и установив какую-либо тему.

config.toml (или config.yaml в зависимости от того, в каком именно формате Вы управляете конфигурацией) располагается в корневой директории Hugo проекта.

Каждый раз, когда Вам нужно внести какие-либо изменения в конфигурацию Вашего проекта, Вы открываете этот config.toml файл и вносите необходимые правки. Вот и всё. Это и есть стандартный способ управления конфигурацией Вашего Hugo веб сайта. Ничего сложного. Но у этого способа имеется ряд недостатков. Некоторые, могут быть довольно критическими для Вашего проекта.

Одной из самых первых проблем, с которой Вы можете столкнуться, работая над своим проектом, это - слишком длинная конфигурация. Действительно, по мере развития Вашего проекта конфигурация заполняется новыми и новыми параметрами. Интеграции с различными сервисами, работа с API ключами, многослойные навигационные меню и так далее - всё это может содержаться в файле конфигурации проекта. В какой-то момент, ловишь себя на мысли, что найти что-либо в файле конфигурации становится не просто из-за обилия информации.

Следующая проблема - поинтереснее. Предположим, Вы хотите сынтегрировать Ваш сайт с сервисом аналитики - например, Google Analytics. Многие Hugo темы сынтегрированы с этим сервисом изначально, и, всё, что Вам нужно сделать, чтобы начать работать с Google Analytics - это добавить свой google analytics идентификатор в файл конфигурации. Но - если Вы это сделаете, то тестовые запуски Вашего веб-сайта на Вашем рабочем компьютере будут генерировать статистику посещений. В Google Analytics нет способа отличить тестовую статистику, от статистики, полученной от реальных пользователей.

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

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

Config Folder

Как видно из название - Config Folder - это папка конфигурации; это буквально папка с конфигурацией проекта. Папка с конфигурацией содержит в себе всю конфигурацию Hugo проекта, разделённую на смысловые части, и, одна такая папка конфигурации полностью заменяет собой файл конфигурации config.toml.

Config Folder должен быть расположен в корневой директории Hugo проекта и называться - config.

Конфигурация по-умолчанию

Config Folder поддерживает конфигурацию по умолчанию и даёт возможность переопределять элементы конфигурации. Конфигурация по умолчанию хранится в директории config/_default. Если перенести файл конфигурации config.toml приведённый выше в папку _default, то Ваш Hugo веб сайт продолжит свою работу. Дело в том, что Hugo знает, что любая конфигурация в папке _default является базовой конфигурацией, используемой по умолчанию.

Теперь давайте разделим элементы нашей конфигурации на отдельные единицы. Делается это следующим образом:

  1. Выбираем одну смысловую группу параметров конфигурации, которую можно вынести в отдельный файл. В случае примера выше, такой группой может быть раздел params:
[params]
    author = "Анвер Богатов"
    description = "Личный островок в океане Интернета"
    githubUsername = "#"
    accent = "red"
    showBorder = true
    backgroundColor = "white"
    font = "Raleway" # should match the name on Google Fonts!
    highlight = true
    highlightStyle = "default"
    highlightLanguages = ["go", "haskell", "kotlin", "scala", "swift"]
  1. Создаём новый файл в config/_default под названием раздела - в нашем случае это будет params, расширение файла при этом выбирается согласно формату содержимого этого файла. Мы используем язык разметки toml для нашей конфигурации, поэтому полное название нового файла будет выглядет следующим образом - params.toml.
  2. Переносим содержимое блока params из config.toml в params.toml. Перенести нужно само содержимое блока, без указание его названия, то есть - [params] копировать не нужно. Его нужно удалить из config.toml.

Вот такая структура должна получиться в результате этих действий:

config
└── _default
    ├── config.toml
    └── params.toml

Если после этих действий перезапустить веб-сайт локально, он будет работать, как и прежде, потому что, мы не меняли конфигурацию, мы её реструктурировали.

Тоже самое, можно сделать и с другими секциями конфигурации. Например, с меню:

[[main]]
    url = "/"
    name = "🏠"
    weight = 1

[[main]]
    url = "/about/"
    name = "О проекте"
    weight = 2

[[main]]
    url = "/post/"
    name = "Статьи"
    weight = 3

[[main]]
    url = "/books/"
    name = "Книги"
    weight = 4

[[main]]
    url = "/movies/"
    name = "Фильмы"
    weight = 5

Обратите внимание, в случае с меню изначально элементы меню назывались [[menu.main]] в config.toml, в новом файле menu.toml каждый элемент носит название уже [[main]]. Hugo автоматически загружает конфигурацию, учитывая именование самих файлов и их содержимого.

Переопределение конфигурации

Config Folder поддерживает переопределение конфигурации. Это означает, что мы можем задать значение какого-либо параметра в конфигурации по умолчанию, а для определённого окружения использовать другое его значение.

Что такое окружение в Hugo? Ваш сайт может быть запущен не только на Вашей локальной машине во время разработки, но и на публичных серверах в интернете. Точнее даже, именно размещение сайта на публичных серверах в интернете делает Ваш сайт доступным Вашим пользователям. Локальный компьютер и публичный сервер - это и есть окружения. Окружения могут быть разделены по типам. По умолчанию, Hugo поддерживает два типа окружения:

  • development
  • production

development - это окружение, в котором Hugo запускает веб сайт на локальном компьютере, каждый раз, когда Вы выполняете команду hugo server. Как можно догадаться из названия - это окружение предназначено для разработки Hugo проекта и не должно использоваться на при запуске сайта на публичных серверах.

production - это окружение, в котором Hugo работает на публичных серверах и сайт доступен для реальных пользователей.

Для создания конфигурации, специфичной для окружения, достаточно в папке config создать новую папку с названием окружения. Например - development. Внутри новой папки мы можем переопределять любые параметры конфигурации по умолчанию. Например, чтобы переопределить значение параметра description для development окружения, достаточно добавить следующее содержимое:

description = "Привет от разработчика"

в файл - config/development/params.toml. Полное содержимое Config Folder‘а в этом случае, будет выглядеть следующим образом:

config
├── _default
│   ├── config.toml
│   ├── menu.toml
│   └── params.toml
└── development
    └── params.toml

Заключительная часть

Config Folder - отличный способ не только навести порядок в конфигурации собственного Hugo веб сайта, но и сделать её проще и гибче в плане поддержки.

Список материалов

Больше о конфигурации Hugo проекта можно узнать отсюда:

Поиск

Категории

Теги