<spanclass=mb-[2px]><ahref=https://github.com/jpanther/congo/tree/dev/exampleSite/content/docs/version-2/upgrade/index.mdclass="text-lg hover:text-primary-500"rel="noopener noreferrer"target=_blanktitle="Edit content"><spanclass="icon relative inline-block px-1 align-text-bottom"><svgxmlns="http://www.w3.org/2000/svg"viewBox="0 0 512 512"><pathfill="currentcolor"d="M490.3 40.4c21.9 21.87 21.9 57.33.0 79.2l-30 30.1-98-97.98 30.1-30.06C414.3-.2135 449.7-.2135 471.6 21.66L490.3 40.4zM172.4 241.7 339.7 74.34l98 97.96L270.3 339.6C264.2 345.8 256.7 350.4 248.4 353.2l-88.8 29.6C150.1 385.6 141.5 383.4 135 376.1 128.6 370.5 126.4 361 129.2 352.4l29.6-88.8C161.6 255.3 166.2 247.8 172.4 241.7v0zM192 63.1c17.7.0 32 15.23 32 32 0 18.6-14.3 32-32 32H96c-17.67.0-32 15.2-32 32V416c0 17.7 14.33 32 32 32H352c17.7.0 32-14.3 32-32V319.1c0-16.8 14.3-32 32-32s32 15.2 32 32V416c0 53-43 96-96 96H96c-53.02.0-96-43-96-96V159.1c0-53 42.98-96 96-96h96z"/></svg></span></a></span></div></div></header><sectionclass="prose mt-0 flex max-w-full flex-col dark:prose-invert lg:flex-row"><divclass="order-first px-0 lg:order-last lg:max-w-xs lg:ps-8"><divclass="toc pe-5 print:hidden lg:sticky lg:top-10"><detailsopenclass="-ms-5 mt-0 overflow-hidden rounded-lg ps-5"><summaryclass="block cursor-pointer bg-neutral-100 py-1 ps-5 text-lg font-semibold text-neutral-800 dark:bg-neutral-700 dark:text-neutral-100 lg:hidden">Table of Contents</summary><divclass="border-s border-dotted border-neutral-300 py-2 ps-5 dark:border-neutral-600"><navid=TableOfContents><ul><li><ahref=#step-1-upgrade-hugo>Step 1: Upgrade Hugo</a></li><li><ahref=#step-2-upgrade-congo>Step 2: Upgrade Congo</a><ul><li><ahref=#upgrade-using-hugo>Upgrade using Hugo</a></li><li><ahref=#upgrade-using-git>Upgrade using git</a></li><li><ahref=#upgrade-manually>Upgrade manually</a></li></ul></li><li><ahref=#step-3-theme-configuration>Step 3: Theme configuration</a><ul><li><ahref=#languagestoml>Languages.toml</a></li><li><ahref=#menustoml>Menus.toml</a></li><li><ahref=#configtoml>Config.toml</a></li><li><ahref=#markuptoml>Markup.toml</a></li><li><ahref=#paramstoml>Params.toml</a></li></ul></li><li><ahref=#step-4-move-assets>Step 4: Move assets</a></li><li><ahref=#step-5-check-content>Step 5: Check content</a></li><li><ahref=#step-6-rebuild>Step 6: Rebuild</a></li></ul></nav></div></details></div></div><divclass="min-h-0 min-w-0 max-w-prose grow"><p>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.</p><p>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.</p><h2id=step-1-upgrade-hugoclass="relative group">Step 1: Upgrade Hugo <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#step-1-upgrade-hugoaria-label=Anchor>#</a></span></h2><divclass="flex rounded-md bg-primary-100 px-4 py-3 dark:bg-primary-900"><spanclass="pe-3 text-primary-400"><spanclass="icon relative inline-block px-1 align-text-bottom"><svgxmlns="http://www.w3.org/2000/svg"viewBox="0 0 512 512"><pathfill="currentcolor"d="M506.3 417 293 53c-16.33-28-57.54-28-73.98.0l-213.2 364C-10.59 444.9 9.849 480 42.74 480h426.6c32.76.0 53.26-35 36.96-63zM232 168c0-13.25 10.75-24 24-24s24 10.8 24 24v128c0 13.25-10.75 24-23.1 24S232 309.3 232 296V168zm24 248c-17.36.0-31.44-14.08-31.44-31.44s14.07-31.44 31.44-31.44 31.44 14.08 31.44 31.44C287.4 401.9 273.4 416 256 416z"/></svg>
</span></span><spanclass=dark:text-neutral-300>Congo 2.0 requires a minimum of <strong>Hugo v0.87.0 or later</strong></span></div><p>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.</p><p>You can check your current version using the command <code>hugo version</code>. Visit the <ahref=https://gohugo.io/getting-started/installing/target=_blankrel=noreferrer>Hugo docs</a> for information on obtaining a newer release for your platform.</p><h2id=step-2-upgrade-congoclass="relative group">Step 2: Upgrade Congo <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#step-2-upgrade-congoaria-label=Anchor>#</a></span></h2><p>The process for upgrading Congo will depend on how you include the theme in your project. Instructions for each method can be found below.</p><ul><li><ahref=#upgrade-using-hugo>Upgrade using Hugo</a></li><li><ahref=#upgrade-using-git>Upgrade using git</a></li><li><ahref=#upgrade-manually>Upgrade manually</a></li></ul><h3id=upgrade-using-hugoclass="relative group">Upgrade using Hugo <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#upgrade-using-hugoaria-label=Anchor>#</a></span></h3><p>To upgrade a go module to a new major release, the <code>modules.toml</code> and <code>go.mod</code> files need to be updated. In each file, update the path to the theme from <code>github.com/jpanther/congo</code> to <code>github.com/jpanther/congo/v2</code>.</p><p>Then change into your project directory and execute the following command:</p><divclass=highlight><pretabindex=0class=chroma><codeclass=language-shelldata-lang=shell><spanclass=line><spanclass=cl>hugo mod get -u
</span></span></code></pre></div><p>Note that in some circumstances there may be issues with this step due to the way that Hugo locally caches modules. If the command above doesn’t work, try using <code>hugo mod clean</code> to clear out the local cache and re-download any modules.</p><p>Once the theme has been upgraded, continue to the <ahref=#step-3-theme-configuration>next section</a>.</p><h3id=upgrade-using-gitclass="relative group">Upgrade using git <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#upgrade-using-gitaria-label=Anchor>#</a></span></h3><p>Git submodules can be upgraded using the <code>git</code> command. Simply execute the following command and the latest version of the theme will be downloaded into your local repository:</p><divclass=highlight><pretabindex=0class=chroma><codeclass=language-shelldata-lang=shell><spanclass=line><spanclass=cl>git submodule update --remote --merge
</span></span></code></pre></div><p>Once the submodule has been upgraded, continue to the <ahref=#step-3-theme-configuration>next section</a>.</p><h3id=upgrade-manuallyclass="relative group">Upgrade manually <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#upgrade-manuallyaria-label=Anchor>#</a></span></h3><p>Updating Congo manually requires you to download the latest copy of the theme and replace the old version in your project.</p><divclass="flex rounded-md bg-primary-100 px-4 py-3 dark:bg-primary-900"><spanclass="pe-3 text-primary-400"><spanclass="icon relative inline-block px-1 align-text-bottom"><svgxmlns="http://www.w3.org/2000/svg"viewBox="0 0 512 512"><pathfill="currentcolor"d="M506.3 417 293 53c-16.33-28-57.54-28-73.98.0l-213.2 364C-10.59 444.9 9.849 480 42.74 480h426.6c32.76.0 53.26-35 36.96-63zM232 168c0-13.25 10.75-24 24-24s24 10.8 24 24v128c0 13.25-10.75 24-23.1 24S232 309.3 232 296V168zm24 248c-17.36.0-31.44-14.08-31.44-31.44s14.07-31.44 31.44-31.44 31.44 14.08 31.44 31.44C287.4 401.9 273.4 416 256 416z"/></svg>
</span></span><spanclass=dark:text-neutral-300>Note that any local customisations you have made to the theme files will be lost during this process.</span></div><ol><li><p>Download the latest release of the theme source code.</p><aclass="inline-block !rounded-md bg-primary-600 px-4 py-1 !text-neutral !no-underline hover:!bg-primary-500 dark:bg-primary-800 dark:hover:!bg-primary-700"href=https://github.com/jpanther/congo/releases/latesttarget=_blankrole=button>Download from Github</a></li><li><p>Extract the archive, rename the folder to <code>congo</code> and move it to the <code>themes/</code> directory inside your Hugo project’s root folder. You will need to overwrite the existing directory to replace all the theme files.</p></li><li><p>Continue to the <ahref=#step-3-theme-configuration>next section</a>.</p></li></ol><h2id=step-3-theme-configurationclass="relative group">Step 3: Theme configuration <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#step-3-theme-configurationaria-label=Anchor>#</a></span></h2><p>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.</p><p>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.</p><h3id=languagestomlclass="relative group">Languages.toml <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#languagestomlaria-label=Anchor>#</a></span></h3><p>In order to provide multilingual support, language-specific theme parameters have been moved to a new config file <code>languages.[lang-code].toml</code>. The theme comes with a template <code>languages.en.toml</code> file which can be used as a guide.</p><divclass="flex rounded-md bg-primary-100 px-4 py-3 dark:bg-primary-900"><spanclass="pe-3 text-primary-400"><spanclass="icon relative inline-block px-1 align-text-bottom"><svgxmlns="http://www.w3.org/2000/svg"viewBox="0 0 512 512"><pathfill="currentcolor"d="M506.3 417 293 53c-16.33-28-57.54-28-73.98.0l-213.2 364C-10.59 444.9 9.849 480 42.74 480h426.6c32.76.0 53.26-35 36.96-63zM232 168c0-13.25 10.75-24 24-24s24 10.8 24 24v128c0 13.25-10.75 24-23.1 24S232 309.3 232 296V168zm24 248c-17.36.0-31.44-14.08-31.44-31.44s14.07-31.44 31.44-31.44 31.44 14.08 31.44 31.44C287.4 401.9 273.4 416 256 416z"/></svg>
</span></span><spanclass=dark:text-neutral-300>This step is optional if you do not need multilingual support, although completing it now will make future theme upgrades easier.</span></div><p>The languages config file follows this structure:</p><divclass=highlight><pretabindex=0class=chroma><codeclass=language-tomldata-lang=toml><spanclass=line><spanclass=cl><spanclass=c># config/_default/languagues.en.toml</span>
</span></span></code></pre></div><p>Using your preferred language, simply create this new file in <code>config/_default/</code> 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.</p><table><thead><tr><th>Parameter</th><th>Old location</th></tr></thead><tbody><tr><td><code>title</code></td><td><code>config.toml</code></td></tr><tr><td><code>description</code></td><td><code>params.toml</code></td></tr><tr><td><code>copyright</code></td><td><code>config.toml</code></td></tr><tr><td><code>dateFormat</code></td><td><code>params.toml</code></td></tr><tr><td><code>[author]</code></td><td><code>config.toml</code></td></tr></tbody></table><p>Once the values have been moved to the new location, these parameters should be deleted from their original locations.</p><h3id=menustomlclass="relative group">Menus.toml <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#menustomlaria-label=Anchor>#</a></span></h3><p>As the theme is now aware of languages, the <code>menus.toml</code> file should also be renamed to include a language code. Rename the existing <code>menus.toml</code> to <code>menus.[lang-code].toml</code>, where the language code matches the code used in the <code>languages.toml</code> file in the previous section.</p><h3id=configtomlclass="relative group">Config.toml <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#configtomlaria-label=Anchor>#</a></span></h3><p>The <code>config.toml</code> file now only contains base Hugo configuration values. Other than removing the language-specific strings above, there are only two changes to consider.</p><p>If you’re using a language other than English, provide a <code>defaultContentLanguage</code> 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 <code>[outputs]</code> block needs to be provided.</p><divclass=highlight><pretabindex=0class=chroma><codeclass=language-tomldata-lang=toml><spanclass=line><spanclass=cl><spanclass=c># config/_default/config.toml</span>
</span></span></code></pre></div><h3id=markuptomlclass="relative group">Markup.toml <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#markuptomlaria-label=Anchor>#</a></span></h3><p>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 <code>[tableOfContents]</code> block to your <code>markup.toml</code> file.</p><p>The recommended settings are as follows, which includes any headings in the Markdown content at levels 2, 3 and 4:</p><divclass=highlight><pretabindex=0class=chroma><codeclass=language-tomldata-lang=toml><spanclass=line><spanclass=cl><spanclass=c># config/_default/markup.toml</span>
</span></span></code></pre></div><h3id=paramstomlclass="relative group">Params.toml <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#paramstomlaria-label=Anchor>#</a></span></h3><p>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.</p><p>The way that dark mode works in Congo has been changed to allow greater flexibility around configuration. The old <code>darkMode</code> and <code>darkToggle</code> parameters have been <strong>removed and replaced</strong> 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.</p><table><thead><tr><th>New parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>defaultAppearance</code></td><td>String</td><td><code>"light"</code></td><td>Default theme appearance; either <code>light</code> or <code>dark</code>.<br>⚠️ <em>Setting this to <code>light</code> replicates the old <code>darkMode = false</code> setting, while <code>dark</code> replicates <code>darkMode = true</code>.</em></td></tr><tr><td><code>autoSwitchAppearance</code></td><td>Boolean</td><td><code>true</code></td><td>Whether the theme appearance automatically switches based upon the operating system preference. Set to <code>false</code> to force the site to always use the <code>defaultAppearance</code>.<br>⚠️ <em>Setting this to <code>true</code> replicates the old <code>darkMode = "auto"</code> setting.</em></td></tr><tr><td><code>showAppearanceSwitcher</code></td><td>Boolean</td><td><code>false</code></td><td>Whether the theme appearance switcher is dispalyed in the site footer.<br>⚠️ <em>This parameter replaces <code>darkToggle</code>.</em></td></tr></tbody></table><p>The following table outlines some other key <strong>new parameters</strong> that control new features in version 2:</p><table><thead><tr><th>New parameter</th><th>Type</th><th>Default</th></tr></thead><tbody><tr><td><code>enableSearch</code></td><td>Boolean</td><td><code>false</code></td></tr><tr><td><code>showScrollToTop</code></td><td>Boolean</td><td><code>true</code></td></tr><tr><td><code>article.showTaxonomies</code></td><td>Boolean</td><td><code>false</code></td></tr><tr><td><code>article.showTableOfContents</code></td><td>Boolean</td><td><code>false</code></td></tr><tr><td><code>list.showTableOfContents</code></td><td>Boolean</td><td><code>false</code></td></tr></tbody></table><p>For the full list of supported parameters, refer to the <ahref=https://jpanther.github.io/congo/docs/configuration/>Configuration</a> docs.</p><h2id=step-4-move-assetsclass="relative group">Step 4: Move assets <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#step-4-move-assetsaria-label=Anchor>#</a></span></h2><p>All site assets, with the exception of favicons, now use Hugo Pipes to build an optimised version of your project. In order for the theme to locate your files, any previously static theme assets need to be moved to the Hugo assets folder. Primarily this is the author image and site logo:</p><p><code>static/me.jpg</code><strong>→</strong><code>assets/me.jpg</code><br><code>static/logo.jpg</code><strong>→</strong><code>assets/logo.jpg</code></p><p>If you have provided an author image or site logo, simply move these assets from <code>static/</code> to <code>assets/</code>. 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 <code>logo</code> and <code>author.image</code> config val
