One Hugo site, Two Hugo themes

As practice has shown, Hugo is a very flexible tool for building your own websites.

This flexibility includes – easy customization of site functions (it’s easy to add integration with analytics services or, for example, messaging services), easy customization of the appearance of the entire site or its individual elements, and so on. But what is even more interesting – knowing these very “customization points”, it is very easy to do really cool things.

One such “thing” will be discussed in this article.

About creating your own site on Hugo, I already talked about hereand also created a whole educational course.

Addressing

The standard way to build Hugo sites is:

• generate project Hugo

• install theme from directory

• fill the site with content and get released

At the same time, since we are talking about a site, the main way to navigate in it, of course, in addition to the visual menu, are addresses or URLs. For example, on the website of my educational project, the main address is https://fullstackguy.anverbogatov.ru/. It is from the main address that the countdown for all materials on this site occurs.

Standard Approach

If you are reading an article in the section Блогthen the address can be

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

And if the article is from the news section, then the address can be

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

With this placement of content, it is absolutely normal that the appearance of the pages repeats or develops the ideas of the appearance of the main page.

Advanced Approach

In special cases, the site may include subsections or even entire subsites.

For example, section Блог could be moved to a separate space:

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

A section База знаний could be available as a separate section, subsection:

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

And specifically in these cases, it is justified that the visual design of a subsection or subsite stands out externally, relative to the main site.

And this, just the same, is easy to achieve in Hugo.

How to support 2 hugo themes?

Let’s create a new project

First, let’s create an empty Hugo project using the following command:

hugo new site demo

Install themes

And at the same time, install two themes in the directory themes:

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

Main site configuration

Great! Now we have something to work with. Before we continue, it is necessary to choose which of the topics will be the main and which is the secondary. For my example, let archie will be the main hugo-universal-theme will be the theme we use for the featured section.

In order to set it up, add a setting with a theme to the existing config.toml file:

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

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

Please note that for ease of navigation, we immediately add the main menu element – the button Secondarywith the help of which navigation will be carried out in the subsection of the site.

After these steps, the main site is already in the running state. Let’s set up the subsection.

Subsection configuration

Suppose we need to make sure that a separate section located at http://example.org/next had an appearance, according to a secondary theme. To do this, create a new configuration file, for example – config-secondary.tomland add the following settings there:

 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"

⚠️ All additional settings for the second theme are taken from the Installation Guide of the theme itself and affect only the visual display of the subsection.

Local development

With this in hand, we can start working on our site with two Hugo themes. Since two separate configuration files have been added, the launch of our main site and subsite will also be separated. In order to run the site on a local environment, you need to run two commands:

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

And yes, you got it right – working with two themes looks like working with two separate sites. Executing the second command hugo server --config ..., note the fact that the subsite is deployed and running on a different port. In my case, it turned out like this:

# для основного
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)

If you go to the specified addresses, then both the main site and the subsection are now available for work.

Particular attention should be paid to the fact that in the case of a local deployment of two parts of the site, the main menu element on the main site will not work. This is due, just the same, to the fact that the subsite is deployed on a different port. Therefore, when working on a site in a local environment, you need to:

• or navigate to the subsite and back from the subsite to the main site manually by entering the address into the browser

• either work with one part of the site at one time (either the main site or a subsite)

In most cases, the tips above are enough.

Separation of content

We figured out the configuration and launch. It’s time to talk about content. Hugo, by default, does not differentiate between main site content and sub-site content. If you create a new .md a file with some text in a directory content, then it will be picked up and both parts of the site will be displayed at once. Why is that?

The thing is that despite the fact that we created two configuration files, for Hugo it’s just two versions of the same site, with different configurations. In order for the main site and subsection to display their own content that is relevant only to them, we need to tell Hugo which materials belong to the main site and which to the subsection. This is done, again, in the configuration.

Setting up the main site

In the main site configuration config.tomlyou need to specify a folder name template that will be ignored during the site building process:

ignorefiles = [ "next/." ]

The setting above tells Hugo the following – all files in folders named next should be ignored. That is, now, pages, styles and other materials of the subsite will NOT be taken into account when working with the main site.

⚠️ Why folder name next? Because the entrance to the subsite starts at http://example.org/next.

Subsite setup

Now, on the contrary, to work with a subsite, Hugo should consider only the materials of the subsite, ignoring the materials of the main site. To do this, add to config-secondary.toml the following settings:

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

The settings above mean that:

• all materials related to the subsite will be located in the folder content/next

• all static resources (styles, scripts, pictures, etc.) of the subsite will be located in static/next

• data in data/next

• and finally, the subsite build result will be available in public/next

Adding content

Everything is extremely simple here:

Assembly

The point is small, prepare our site with two themes for release.

The main difference from building a regular Hugo site with a single theme is that now we need to build the main site and subsite separately. You can do this with one command:

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

Where hugo --minify collects the main part of the site using the default settings, i.e. the file config.tomlA hugo --config config-secondary.toml --minifyassembles the subsite, thanks to the fact that we explicitly specified the subsite configuration file.

The result will be the assembly of both parts of the site. Example:

 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

After these steps, the build result from the folder public can be placed on public hosting, and your site will sparkle with new colors.

Conclusion

I really hope that after reading this article, it became clear to you that adding new sections of the site with their own topics, different from the main one, is actually adding new Hugo sites to the project.

Who might need such an approach? If you want work on one site to take place in one place, If you want all site subsections to have a single deployment process with the main site, and in general, If you consider that site subsections are an inseparable part of your main site – then a similar approach may be useful to you.

And if you decide to use this approach, I want to warn you right away – it complicates the work on the site. How? The fact is that Hugo itself accustoms developers to a number of conventions (how to name folders and files, where to place what, and so on) that are worth parsing and remembering. So, the approach itself adds another layer of agreements on top of the Hugo agreements – where and how to place materials for which part of the site, which styles and localization are suitable for the main site, and which for a subsection, and so on.

List of materials

This article was inspired by a post on the official Hugo forum.