Upgrading from Congo 1.x

Table of Contents

Although Congo 2.0 contains a large number of changes, the theme has been designed to minimise the effort required to upgrade to the latest release.

That said, there are some changes that require adjustments to existing sites that are built with Congo version 1.x. This guide will step you through the process and highlight things you need to consider.

Step 1: Upgrade Hugo #

Congo 2.0 requires a minimum of Hugo v0.87.0 or later

Congo is built to take advantage of some of the latest Hugo features. You should regularly keep your Hugo installation up to date to avoid any issues.

You can check your current version using the command hugo version. Visit the Hugo docs for information on obtaining a newer release for your platform.

Step 2: Upgrade Congo #

The process for upgrading Congo will depend on how you include the theme in your project. Instructions for each method can be found below.

Upgrade using Hugo
Upgrade using git
Upgrade manually

Upgrade using Hugo #

Hugo makes updating modules super easy. Simply change into your project directory and execute the following command:

hugo mod get -u

Hugo will automatically upgrade any modules that are required for your project. It does this by inspecting your module.toml and go.mod files. If you have any issues with the upgrade, check to ensure these files are still configured correctly.

Once the theme has been upgraded, continue to the next section.

Upgrade using git #

Git submodules can be upgraded using the git command. Simply execute the following command and the latest version of the theme will be downloaded into your local repository:

git submodule upgrade --remote --merge

Once the submodule has been upgraded, continue to the next section.

Upgrade manually #

Updating Congo manually requires you to download the latest copy of the theme and replace the old version in your project.

Note that any local customisations you have made to the theme files will be lost during this process.

Download the latest release of the theme source code.
Download from Github
Extract the archive, rename the folder to congo and move it to the themes/ directory inside your Hugo project’s root folder. You will need to overwrite the existing directory to replace all the theme files.
Continue to the next section.

Step 3: Theme configuration #

Congo 2.0 introduces a number of new theme configuration parameters. Although the theme will adapt to existing version 1 configurations, in order to take advantage of some of the newer theme features, you will need to adjust your existing configuration.

The simplest way to do this is to take a copy of the theme’s default configuration and compare it to your existing files. The process is outlined in greater detail below.

Languages.toml #

In order to provide multilingual support, language-specific theme parameters have been moved to a new config file languages.[lang-code].toml. The theme comes with a template languages.en.toml file which can be used as a guide.

This step is optional if you do not need multilingual support, although completing it now will make future theme upgrades easier.

The languages config file follows this structure:

# config/_default/languagues.en.toml

languageCode = "en"
languageName = "English"
displayName = "EN"
htmlCode = "en"
weight = 1
rtl = false

# Language-specific parameters go here

Using your preferred language, simply create this new file in config/_default/ and then move the language-specific parameters from any existing config files over to this new file. The table below outlines the parameters that need to be moved.

Parameter	Old location
`title`	`config.toml`
`description`	`params.toml`
`copyright`	`config.toml`
`dateFormat`	`params.toml`
`[author]`	`config.toml`

Once the values have been moved to the new location, these parameters should be deleted from their original locations.

Config.toml #

The config.toml file now only contains base Hugo configuration values. Other than removing the language-specific strings above, there are only two changes to consider.

If you’re using a language other than English, provide a defaultContentLanguage value that matches the language code in the config file you created for your language. Secondly, to take advange of the new site search in Congo 2.0, an [outputs] block needs to be provided.

# config/_default/config.toml

defaultContentLanguage = "en"

enableRobotsTXT = true
paginate = 10
summaryLength = 0

[outputs]
  home = ["HTML", "RSS", "JSON"]

Markup.toml #

Congo 2.0 adds support for tables of contents on article pages. Although Hugo ships with default settings for generating contents listings, you can adjust this behaviour by adding a new [tableOfContents] block to your markup.toml file.

The recommended settings are as follows, which includes any headings in the Markdown content at levels 2, 3 and 4:

# config/_default/markup.toml

[tableOfContents]
  startLevel = 2
  endLevel = 4

Params.toml #

A number of new theme parameters have been introduced in Congo 2.0. Some minor changes are requried to existing configurations. Remember, the theme will always revert to a sensible default if a parameter is not provided.

The way that dark mode works in Congo has been changed to allow greater flexibility around configuration. The old darkMode and darkToggle parameters have been removed and replaced by three new parameters. These new options operate independently of each other, making it possible to force the appearance while still allowing the user to override.

New parameter	Type	Default	Description
`defaultAppearance`	String	`"light"`	Default theme appearance; either `light` or `dark`. ⚠️ Setting this to `light` replicates the old `darkMode = false` setting, while `dark` replicates `darkMode = true`.
`autoSwitchAppearance`	Boolean	`true`	Whether the theme appearance automatically switches based upon the operating system preference. Set to `false` to force the site to always use the `defaultAppearance`. ⚠️ Setting this to `true` replicates the old `darkMode = "auto"` setting.
`showAppearanceSwitcher`	Boolean	`false`	Whether the theme appearance switcher is dispalyed in the site footer. ⚠️ This parameter replaces `darkToggle`.

The following table outlines some other key new parameters that control new features in version 2:

New parameter	Type	Default
`enableSearch`	Boolean	`false`
`showScrollToTop`	Boolean	`true`
`article.showTaxonomies`	Boolean	`false`
`article.showTableOfContents`	Boolean	`false`
`list.showTableOfContents`	Boolean	`false`

For the full list of supported parameters, refer to the Configuration docs.

Step 4: Move assets #

All site assets now use Hugo Pipes to build an optimised version of your project. In order for the theme to locate your files, any previously static assets used in the theme need to be moved to the Hugo assets folder.

static/me.jpg → assets/me.jpg
static/logo.jpg → assets/logo.jpg

If you have provided an author image or site logo, simply move these assets from the static/ folder to the assets/ folder. If you use the same directory structure the theme will know where to find these files automatically. If you would like to provide a new path, update the logo and author.image config values accordingly.

Step 5: Check content #

The behavior of the figure shortcode is different in version 2. If you are using figure in your content and have advanced use cases, you may need to adjust the parameters you are providing.

Consult the shortcode docs to learn more about supported parameters.

Step 6: Rebuild #

Now that all the configuration changes are complete, it’s time to rebuild the site. Run hugo, or your build command, and check that everything works as expected.

If you come across any errors, check the configuration is correct and refer to the full documentation for further guidance. Remember, the example config files bundled with the theme contain all the default parameters and are a great starting point.

🙋‍♀️ If you still need help, feel free to ask your question on GitHub Discussions.