Один Hugo сайт, Две Hugo темы

| October 12, 2022

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

Эта гибкость включает в себя - лёгкую кастомизацию функций сайта (легко добавить интеграцию с сервисами аналитики или, к примеру, сервисами отправки сообщений), лёгкую настройку внешнего вида всего сайта или отдельных его элементов, и так далее. Но что ещё более интересно - зная эти самые “точки кастомизации”, очень легко делать реально крутые штуки.

Об одной такой “штуке” и пойдёт речь в этой статье.

Адресация

Стандартный способ создания сайтов Hugo - это:

  • сгенерировать проект Hugo
  • установить тему из каталога
  • набить сайт контентом и зарелизиться

При этом, по скольку речь идёт о сайте, основным способ навигации в нём, естественно, помимо визуального меню, являются адреса или URL. Если Вы обратили внимание, на данном сайте, основным адресом является https://fullstackguy.anverbogatov.ru/. Именно от основного адреса происходит отсчёт для всех материалов этого сайта.

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

Если Вы читаете статью в разделе Блог, то в адрес может быть

https://fullstackguy.anverbogatov.ru/posts/2022/09/my-best-article

А если статью из раздела новостей, то адрес может быть

https://fullstackguy.anverbogatov.ru/news/2022/09/september-update.

При таком размещении контента абсолютно нормально то, что внешний вид страниц повторяет или развивает идеи внешнего вида главной страницы.

Продвинутый подход

В особых случаях, сайт может включать в себя подразделы или даже целые подсайты.

Например, секция Блог могла бы быть вынесена в отдельное пространство:

https://blog.fullstackguy.anverbogatov.ru/

А секция База знаний могла бы быть доступна как отдельная секция, подраздел:

https://fullstackguy.anverbogatov.ru/knowledge-base/.

И вот конкретно в этих случаях, оправданно то, что визуальное оформление подраздела или подсайта выделяется внешне, относительно основного сайта.

И вот этого, как раз таки, легко достичь в Hugo.

Как поддержать 2 hugo темы?

Создадим новый проект

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

hugo new site demo

Установим темы

И заодно, установим две темы в каталог themes:

cd demo/themes
git clone https://github.com/athul/archie.git
git clone https://github.com/devcows/hugo-universal-theme

Конфигурация основного сайта

Отлично! Теперь у нас есть, с чем работать. Прежде чем мы продолжим, необходимо выбрать какая из тем будет основной, а какая второстепенной. Для моего примера, пусть archie будет основной, а hugo-universal-theme будет темой, которую мы используем для избранной секции.

Для того чтобы это настроить, добавляем настройку с темой в имеющийся config.toml файл:

baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My Primary Site'
theme = 'archie'

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

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

После этих действий основной сайт уже находится в запускаемом состоянии. Займёмся настройкой подраздела.

Конфигурация подраздела

Предположим, нам нужно сделать так, чтобы отдельная секция, находящаяся по адресу http://example.org/next имела внешний вид, согласно второстепенной теме. Для этого, создаём новый конфигурационный файл, например - config-secondary.toml, и добавляем туда следующие настройки:

baseURL = 'http://example.org/next'
languageCode = 'en-us'
title = 'My Secondary Site'
theme = 'hugo-universal-theme'

style = "default"

[params]
    disabled_logo = false
    logo_text = "Universal"

    logo = "img/logo.png"
    logo_small = "img/logo-small.png"

⚠️ Все дополнительные настройки для второй темы взяты из Installation Guide’а самой темы и влияют только на визуальное отображение подраздела.

Локальная разработка

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

hugo server # эта команда запускает основную версию сайта
hugo server --config config-secondary.toml # а эта, запускает подсайт

И да, Вы всё верно поняли - работа с двумя темами выглядит, как работа с двумя отдельными сайтами. Выполнив вторую команду hugo server --config ..., обратите внимание на тот факт, что подсайт развёрнут и запущен на другом порту. В моём случае, получилось следующим образом:

# для основного
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

# для подсайта
port 1313 already in use, attempting to use an available port
Web Server is available at http://localhost:59465/next/ (bind address 127.0.0.1)

Если перейти по указанным адресам, то и основной сайт, и подраздел, теперь доступны для работы. Рисунок 1. Главная страница основного сайта

Рисунок 2. Главная страница подсайта

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

  • либо выполнять переход на подсайт и обратно с подсайта на основной сайт вручную, введя адрес в браузер
  • либо в один момент времени работать с одной частью сайта (либо основной сайт, либо подсайт)

В большинстве случаев, советов выше бывает достаточно.

Разделение содержимого

С конфигурацией и запуском разобрались. Самое время поговорить о содержимом. Hugo, по умолчанию, не делает разделений на контент основного сайта и контент подразделов. Если создать новый *.md файл с каким нибудь текстом в директории content, то его подцепят и отобразят сразу обе части сайта. Почему так?

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

Настройка основного сайта

В конфигурации основного сайта config.toml, нужно указать шаблон имени папок, которые будут проигнорированы в процессе построения сайта:

ignorefiles = [ "next/.*" ]

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

⚠️ Почему название папки next? Потому что вход в подсайт начинается по адресу http://example.org/next.

Настройка подсайта

Теперь наоборот, для работы с подсайтом Hugo должен учитывать только материалы подсайта, игнорируя материалы основного сайта. Для этого добавим в config-secondary.toml следующие настройки:

contentDir = "content/next"
publishDir = "public/next"
staticDir = "static/next"
dataDir = "data/next"

Настройки выше означают, что:

  • все материалы, относящиеся к подсайту будут расположены в папке content/next
  • все статические ресурсы (стили, скрипты, картинки и т.д.) подсайта будут расположены в static/next
  • данные в data/next
  • и наконец, результат сборки подсайта будет доступен в public/next

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

Тут всё предельно просто:

  • контент основной части сайта добавляется в папку content
  • контент подсайта добавляется в папку content/next

Сборка

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

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

hugo --minify && hugo --config config-secondary.toml --minify

где hugo --minify собирает основную часть сайта, используя настройки по умолчанию, то есть файл config.toml, а hugo --config config-secondary.toml --minify собирает подсайт, благодаря тому, что мы явно указали файл конфигурации подсайта.

Результатом станет сборка обеих частей сайта. Пример:

hugo --minify && hugo --config config-secondary.toml --minify

Start building sites … 
hugo v0.104.3+extended darwin/arm64 BuildDate=unknown

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

Total in 18 ms

Start building sites … 
hugo v0.104.3+extended darwin/arm64 BuildDate=unknown


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

Total in 56 ms

После этих действий, результат сборки из папки public можно размещать на публичных хостингах, и Ваш сайт заиграет новыми красками.

Заключение

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

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

И если Вы примете решение использовать данный подход, сразу хочу предупредить - это усложняет работу над сайтом. Каким образом? Дело в том, что сам Hugo приучает разработчиков к ряду соглашений (как именовать папки и файлы, куда что размещать и так далее), которые стоит разобрать и запомнить. Так вот, сам подход добавляет поверх соглашений Hugo ещё один слой соглашений - где и как стоит размещать материалы для какой части сайта, какие стили и локализация подходят для основного сайта, а какие для подраздела и так далее.

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

Источником вдохновения данного материала послужил пост в официальном форуме Hugo.