mirror of https://github.com/jpanther/congo.git
41 lines
39 KiB
HTML
41 lines
39 KiB
HTML
<!doctype html><html lang=en-AU dir=ltr class=scroll-smooth data-default-appearance=light data-auto-appearance=true><head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=theme-color content="rgb(255,255,255)"><title>Upgrading from Congo 1.x · Congo</title>
|
|
<meta name=title content="Upgrading from Congo 1.x · Congo"><script type=text/javascript src=/congo/js/appearance.min.022d0ebc3b46a335eb1c7ef79b7f2de143d7cd5156d433638592ef1ce5f8554e.js integrity="sha256-Ai0OvDtGozXrHH73m38t4UPXzVFW1DNjhZLvHOX4VU4="></script><link type=text/css rel=stylesheet href=/congo/css/main.bundle.min.694b3186494b75c5b42f8cefd6fc32ab5524f28be728b0aa63c1e89c1b10850e.css integrity="sha256-aUsxhklLdcW0L4zv1vwyq1Uk8ovnKLCqY8HonBsQhQ4="><script defer type=text/javascript id=script-bundle src=/congo/js/main.bundle.min.f29ffdffd9ab4cc95250c3c7196b2d5dae8ee6ef0a4139451073f90183ae7e31.js integrity="sha256-8p/9/9mrTMlSUMPHGWstXa6O5u8KQTlFEHP5AYOufjE=" data-copy=Copy data-copied=Copied></script><meta name=description content="
|
|
Discover what's new in Congo version 2.0.
|
|
"><link rel=canonical href=https://jpanther.github.io/congo/docs/version-2/upgrade/><link rel=apple-touch-icon sizes=180x180 href=/congo/apple-touch-icon.png><link rel=icon type=image/png sizes=32x32 href=/congo/favicon-32x32.png><link rel=icon type=image/png sizes=16x16 href=/congo/favicon-16x16.png><link rel=manifest href=/congo/site.webmanifest><meta property="og:title" content="Upgrading from Congo 1.x"><meta property="og:description" content="Discover what's new in Congo version 2.0."><meta property="og:type" content="article"><meta property="og:url" content="https://jpanther.github.io/congo/docs/version-2/upgrade/"><meta property="article:section" content="docs"><meta property="article:published_time" content="2022-01-20T00:00:00+00:00"><meta property="article:modified_time" content="2022-01-20T00:00:00+00:00"><meta name=twitter:card content="summary"><meta name=twitter:title content="Upgrading from Congo 1.x"><meta name=twitter:description content="Discover what's new in Congo version 2.0."><script type=application/ld+json>{"@context":"https://schema.org","@type":"Article","articleSection":"Documentation","name":"Upgrading from Congo 1.x","headline":"Upgrading from Congo 1.x","description":"Discover what\u0027s new in Congo version 2.0.","abstract":"Although Congo 2.","inLanguage":"en-AU","url":"https:\/\/jpanther.github.io\/congo\/docs\/version-2\/upgrade\/","author":{"@type":"Person","name":"Congo"},"copyrightYear":"2022","dateCreated":"2022-01-20T00:00:00\u002b00:00","datePublished":"2022-01-20T00:00:00\u002b00:00","dateModified":"2022-01-20T00:00:00\u002b00:00","keywords":["new","docs"],"mainEntityOfPage":"true","wordCount":"1369"}</script><meta name=author content="Congo"><link href=https://twitter.com/ rel=me><link href=https://facebook.com/ rel=me><link href=https://linkedin.com/ rel=me><link href=https://youtube.com/ rel=me></head><body class="flex flex-col h-screen px-6 m-auto text-lg leading-7 max-w-7xl bg-neutral text-neutral-900 dark:bg-neutral-800 dark:text-neutral sm:px-14 md:px-24 lg:px-32"><div id=the-top class="absolute flex self-center"><a class="px-3 py-1 text-sm -translate-y-8 rounded-b-lg bg-primary-200 focus:translate-y-0 dark:bg-neutral-600" href=#main-content><span class="font-bold pe-2 text-primary-600 dark:text-primary-400">↓</span>Skip to main content</a></div><header class="py-6 font-semibold text-neutral-900 dark:text-neutral print:hidden sm:py-10"><nav class="flex items-start justify-between sm:items-center"><div class="flex flex-row items-center"><a class="decoration-primary-500 hover:underline hover:decoration-2 hover:underline-offset-2" rel=me href=/congo/>Congo</a></div><ul class="flex flex-col list-none text-end sm:flex-row"><li class="group mb-1 sm:mb-0 sm:me-7 sm:last:me-0.5"><a href=/congo/docs/ title=Documentation><span class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2">Docs</span></a></li><li class="group mb-1 sm:mb-0 sm:me-7 sm:last:me-0.5"><a href=/congo/samples/ title="Content Samples"><span class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2">Samples</span></a></li><li class="group mb-1 sm:mb-0 sm:me-7 sm:last:me-0.5"><a href=/congo/users/ title=Users><span class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2">Users</span></a></li><li class="group mb-1 sm:mb-0 sm:me-7 sm:last:me-0.5"><a href=https://github.com/jpanther/congo title target=_blank><span class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"><span class="relative inline-block align-text-bottom px-1 icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><path fill="currentcolor" d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6.0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6.0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3.0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1.0-6.2-.3-40.4-.3-61.4.0.0-70 15-84.7-29.8.0.0-11.4-29.1-27.8-36.6.0.0-22.9-15.7 1.6-15.4.0.0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5.0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9.0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4.0 33.7-.3 75.4-.3 83.6.0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6.0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9.0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg></span></span></a></li><li class="group mb-1 sm:mb-0 sm:me-7 sm:last:me-0.5"><button id=search-button-1 title="Search (/)">
|
|
<span class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"><span class="relative inline-block align-text-bottom px-1 icon"><svg aria-hidden="true" focusable="false" data-prefix="fas" data-icon="search" class="svg-inline--fa fa-search fa-w-16" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="currentcolor" d="M505 442.7 405.3 343c-4.5-4.5-10.6-7-17-7H372c27.6-35.3 44-79.7 44-128C416 93.1 322.9.0 208 0S0 93.1.0 208s93.1 208 208 208c48.3.0 92.7-16.4 128-44v16.3c0 6.4 2.5 12.5 7 17l99.7 99.7c9.4 9.4 24.6 9.4 33.9.0l28.3-28.3c9.4-9.4 9.4-24.6.1-34zM208 336c-70.7.0-128-57.2-128-128 0-70.7 57.2-128 128-128 70.7.0 128 57.2 128 128 0 70.7-57.2 128-128 128z"/></svg></span></span><span class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2"></span></button></li><li class="group mb-1 sm:mb-0 sm:me-7 sm:last:me-0.5"><div class="relative group"><button class="flex items-center justify-end w-full transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600">
|
|
<span class="relative inline-block align-text-bottom px-1 icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill="currentcolor" d="M4.545 6.714 4.11 8H3l1.862-5h1.284L8 8H6.833l-.435-1.286H4.545zm1.634-.736L5.5 3.956h-.049l-.679 2.022H6.18z"/><path fill="currentcolor" d="M0 2a2 2 0 012-2h7a2 2 0 012 2v3h3a2 2 0 012 2v7a2 2 0 01-2 2H7a2 2 0 01-2-2v-3H2A2 2 0 010 9V2zm2-1A1 1 0 001 2v7a1 1 0 001 1h7a1 1 0 001-1V2A1 1 0 009 1H2zm7.138 9.995c.193.301.402.583.63.846-.748.575-1.673 1.001-2.768 1.292.178.217.451.635.555.867 1.125-.359 2.08-.844 2.886-1.494.777.665 1.739 1.165 2.93 1.472.133-.254.414-.673.629-.89-1.125-.253-2.057-.694-2.82-1.284.681-.747 1.222-1.651 1.621-2.757H14V8h-3v1.047h.765c-.318.844-.74 1.546-1.272 2.13a6.066 6.066.0 01-.415-.492 1.988 1.988.0 01-.94.31z"/></svg></span><span class=text-sm>EN</span><span class=text-[0.6rem]><span class="relative inline-block align-text-bottom px-1 icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="currentcolor" d="M233.4 406.6c12.5 12.5 32.8 12.5 45.3.0l192-192c12.5-12.5 12.5-32.8.0-45.3s-32.8-12.5-45.3.0L256 338.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3.0s-12.5 32.8.0 45.3l192 192z"/></svg></span></span></button><div class="invisible w-full h-2 bg-transparent group-hover:visible"></div><div class="top-8 invisible absolute ltr:right-0 rtl:left-0 z-50 flex flex-col whitespace-nowrap rounded border border-neutral-300 bg-neutral text-start text-base shadow group-hover:visible dark:border-neutral-600 dark:bg-neutral-800"><div class="flex flex-grow"><a href=/congo/docs/version-2/upgrade/ class="flex items-center justify-between w-full px-2 py-1 bg-primary-100 dark:bg-primary-900">English (Australia)<span class="w-6 ms-2 text-primary-600 dark:text-primary-400"><span class="relative inline-block align-text-bottom px-1 icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path fill="currentcolor" d="M438.6 105.4c12.5 12.5 12.5 32.7.0 45.2l-256 256c-12.5 12.5-32.7 12.5-45.2.0L9.372 278.6c-12.496-12.5-12.496-32.7.0-45.2 12.498-12.5 32.758-12.5 45.258.0L159.1 338.7 393.4 105.4c12.5-12.52 32.7-12.52 45.2.0h0z"/></svg></span></span></a></div><div class="flex flex-grow"><a href=/congo/ja/docs/version-2/upgrade/ class="w-full py-1 pe-10 ps-2 decoration-primary-500 hover:underline hover:decoration-2 hover:underline-offset-2">日本語</a></div></div></div></li></ul></nav></header><div class="relative flex flex-col grow"><main id=main-content class=grow><article><header class=max-w-prose><ol class="text-sm text-neutral-500 dark:text-neutral-400 print:hidden"><li class="inline hidden"><a class="hover:underline decoration-neutral-300 dark:underline-neutral-600" href=/congo/>Welcome to Congo! :tada:</a><span class="px-1 text-primary-500">/</span></li><li class=inline><a class="hover:underline decoration-neutral-300 dark:underline-neutral-600" href=/congo/docs/>Documentation</a><span class="px-1 text-primary-500">/</span></li><li class=inline><a class="hover:underline decoration-neutral-300 dark:underline-neutral-600" href=/congo/docs/version-2/>What's New in 2.0 ✨</a><span class="px-1 text-primary-500">/</span></li><li class="inline hidden"><a class="hover:underline decoration-neutral-300 dark:underline-neutral-600" href=/congo/docs/version-2/upgrade/>Upgrading from Congo 1.x</a><span class="px-1 text-primary-500">/</span></li></ol><h1 class="mt-0 text-4xl font-extrabold text-neutral-900 dark:text-neutral">Upgrading from Congo 1.x</h1><div class="mt-8 mb-12 text-base text-neutral-500 dark:text-neutral-400 print:hidden"><div class="flex flex-row flex-wrap items-center"><span title="Reading time">7 mins</span><span class="px-2 text-primary-500">·</span>
|
|
<span class=mb-[2px]><a href=https://github.com/jpanther/congo/tree/dev/exampleSite/content/docs/version-2/upgrade/index.md class="text-lg hover:text-primary-500" rel="noopener noreferrer" target=_blank title="Edit content"><span class="relative inline-block align-text-bottom px-1 icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="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><section class="flex flex-col max-w-full mt-0 prose dark:prose-invert lg:flex-row"><div class="order-first px-0 lg:order-last lg:max-w-xs lg:ps-8"><div class="toc pe-5 print:hidden lg:sticky lg:top-10"><details open class="-ms-5 mt-0 overflow-hidden rounded-lg ps-5"><summary class="-ms-5 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><div class="-ms-5 border-s border-dotted border-neutral-300 py-2 ps-5 dark:border-neutral-600"><nav id=TableOfContents><ul><li><a href=#step-1-upgrade-hugo>Step 1: Upgrade Hugo</a></li><li><a href=#step-2-upgrade-congo>Step 2: Upgrade Congo</a><ul><li><a href=#upgrade-using-hugo>Upgrade using Hugo</a></li><li><a href=#upgrade-using-git>Upgrade using git</a></li><li><a href=#upgrade-manually>Upgrade manually</a></li></ul></li><li><a href=#step-3-theme-configuration>Step 3: Theme configuration</a><ul><li><a href=#languagestoml>Languages.toml</a></li><li><a href=#menustoml>Menus.toml</a></li><li><a href=#configtoml>Config.toml</a></li><li><a href=#markuptoml>Markup.toml</a></li><li><a href=#paramstoml>Params.toml</a></li></ul></li><li><a href=#step-4-move-assets>Step 4: Move assets</a></li><li><a href=#step-5-check-content>Step 5: Check content</a></li><li><a href=#step-6-rebuild>Step 6: Rebuild</a></li></ul></nav></div></details></div></div><div class="min-w-0 min-h-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><h2 id=step-1-upgrade-hugo class="relative group">Step 1: Upgrade Hugo <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#step-1-upgrade-hugo aria-label=Anchor>#</a></span></h2><div class="flex px-4 py-3 rounded-md bg-primary-100 dark:bg-primary-900"><span class="pe-3 text-primary-400"><span class="relative inline-block align-text-bottom px-1 icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="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><span class=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 <a href=https://gohugo.io/getting-started/installing/ target=_blank rel=noreferrer>Hugo docs</a> for information on obtaining a newer release for your platform.</p><h2 id=step-2-upgrade-congo class="relative group">Step 2: Upgrade Congo <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#step-2-upgrade-congo aria-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><a href=#upgrade-using-hugo>Upgrade using Hugo</a></li><li><a href=#upgrade-using-git>Upgrade using git</a></li><li><a href=#upgrade-manually>Upgrade manually</a></li></ul><h3 id=upgrade-using-hugo class="relative group">Upgrade using Hugo <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#upgrade-using-hugo aria-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><div class=highlight><pre tabindex=0 class=chroma><code class=language-shell data-lang=shell><span class=line><span class=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
|
|
<a href=#step-3-theme-configuration>next section</a>.</p><h3 id=upgrade-using-git class="relative group">Upgrade using git <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#upgrade-using-git aria-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><div class=highlight><pre tabindex=0 class=chroma><code class=language-shell data-lang=shell><span class=line><span class=cl>git submodule update --remote --merge
|
|
</span></span></code></pre></div><p>Once the submodule has been upgraded, continue to the
|
|
<a href=#step-3-theme-configuration>next section</a>.</p><h3 id=upgrade-manually class="relative group">Upgrade manually <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#upgrade-manually aria-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><div class="flex px-4 py-3 rounded-md bg-primary-100 dark:bg-primary-900"><span class="pe-3 text-primary-400"><span class="relative inline-block align-text-bottom px-1 icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="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><span class=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><a class="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/latest target=_blank role=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
|
|
<a href=#step-3-theme-configuration>next section</a>.</p></li></ol><h2 id=step-3-theme-configuration class="relative group">Step 3: Theme configuration <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#step-3-theme-configuration aria-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><h3 id=languagestoml class="relative group">Languages.toml <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#languagestoml aria-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><div class="flex px-4 py-3 rounded-md bg-primary-100 dark:bg-primary-900"><span class="pe-3 text-primary-400"><span class="relative inline-block align-text-bottom px-1 icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="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><span class=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><div class=highlight><pre tabindex=0 class=chroma><code class=language-toml data-lang=toml><span class=line><span class=cl><span class=c># config/_default/languagues.en.toml</span>
|
|
</span></span><span class=line><span class=cl>
|
|
</span></span><span class=line><span class=cl><span class=nx>languageCode</span> <span class=p>=</span> <span class=s2>"en"</span>
|
|
</span></span><span class=line><span class=cl><span class=nx>languageName</span> <span class=p>=</span> <span class=s2>"English"</span>
|
|
</span></span><span class=line><span class=cl><span class=nx>displayName</span> <span class=p>=</span> <span class=s2>"EN"</span>
|
|
</span></span><span class=line><span class=cl><span class=nx>htmlCode</span> <span class=p>=</span> <span class=s2>"en"</span>
|
|
</span></span><span class=line><span class=cl><span class=nx>weight</span> <span class=p>=</span> <span class=mi>1</span>
|
|
</span></span><span class=line><span class=cl><span class=nx>rtl</span> <span class=p>=</span> <span class=kc>false</span>
|
|
</span></span><span class=line><span class=cl>
|
|
</span></span><span class=line><span class=cl><span class=c># Language-specific parameters go here</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><h3 id=menustoml class="relative group">Menus.toml <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#menustoml aria-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><h3 id=configtoml class="relative group">Config.toml <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#configtoml aria-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><div class=highlight><pre tabindex=0 class=chroma><code class=language-toml data-lang=toml><span class=line><span class=cl><span class=c># config/_default/config.toml</span>
|
|
</span></span><span class=line><span class=cl>
|
|
</span></span><span class=line><span class=cl><span class=nx>defaultContentLanguage</span> <span class=p>=</span> <span class=s2>"en"</span>
|
|
</span></span><span class=line><span class=cl>
|
|
</span></span><span class=line><span class=cl><span class=nx>enableRobotsTXT</span> <span class=p>=</span> <span class=kc>true</span>
|
|
</span></span><span class=line><span class=cl><span class=nx>paginate</span> <span class=p>=</span> <span class=mi>10</span>
|
|
</span></span><span class=line><span class=cl><span class=nx>summaryLength</span> <span class=p>=</span> <span class=mi>0</span>
|
|
</span></span><span class=line><span class=cl>
|
|
</span></span><span class=line><span class=cl><span class=p>[</span><span class=nx>outputs</span><span class=p>]</span>
|
|
</span></span><span class=line><span class=cl> <span class=nx>home</span> <span class=p>=</span> <span class=p>[</span><span class=s2>"HTML"</span><span class=p>,</span> <span class=s2>"RSS"</span><span class=p>,</span> <span class=s2>"JSON"</span><span class=p>]</span>
|
|
</span></span></code></pre></div><h3 id=markuptoml class="relative group">Markup.toml <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#markuptoml aria-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><div class=highlight><pre tabindex=0 class=chroma><code class=language-toml data-lang=toml><span class=line><span class=cl><span class=c># config/_default/markup.toml</span>
|
|
</span></span><span class=line><span class=cl>
|
|
</span></span><span class=line><span class=cl><span class=p>[</span><span class=nx>tableOfContents</span><span class=p>]</span>
|
|
</span></span><span class=line><span class=cl> <span class=nx>startLevel</span> <span class=p>=</span> <span class=mi>2</span>
|
|
</span></span><span class=line><span class=cl> <span class=nx>endLevel</span> <span class=p>=</span> <span class=mi>4</span>
|
|
</span></span></code></pre></div><h3 id=paramstoml class="relative group">Params.toml <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#paramstoml aria-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
|
|
<a href=https://jpanther.github.io/congo/docs/configuration/>Configuration</a> docs.</p><h2 id=step-4-move-assets class="relative group">Step 4: Move assets <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#step-4-move-assets aria-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 values accordingly.</p><p>Note that this step does not apply to any assets in your project that are actually static. For example, a PDF file that you link directly to from within an article is a static asset. These files should remain in the <code>static/</code> directory to ensure they are copied to the output folder when Hugo builds the site.</p><h2 id=step-5-check-content class="relative group">Step 5: Check content <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#step-5-check-content aria-label=Anchor>#</a></span></h2><p>The behavior of the <code>figure</code> shortcode is different in version 2. If you are using <code>figure</code> in your content and have advanced use cases, you may need to adjust the parameters you are providing.</p><p>Consult the
|
|
<a href=https://jpanther.github.io/congo/docs/shortcodes/#figure>shortcode docs</a> to learn more about supported parameters.</p><h2 id=step-6-rebuild class="relative group">Step 6: Rebuild <span class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><a class="group-hover:text-primary-300 dark:group-hover:text-neutral-700" style=text-decoration-line:none!important href=#step-6-rebuild aria-label=Anchor>#</a></span></h2><p>Now that all the configuration changes are complete, it’s time to rebuild the site. Run <code>hugo</code>, or your build command, and check that everything works as expected.</p><p>If you come across any errors, check the configuration is correct and refer to the
|
|
<a href=https://jpanther.github.io/congo/docs/>full documentation</a> for further guidance. Remember, the example config files bundled with the theme contain all the default parameters and are a great starting point.</p><p>🙋♀️ If you still need help, feel free to ask your question on <a href=https://github.com/jpanther/congo/discussions target=_blank rel=noreferrer>GitHub Discussions</a>.</p></div></section><footer class="pt-8 max-w-prose print:hidden"></footer></article><div class="pointer-events-none absolute bottom-0 end-0 top-[100vh] w-12"><a href=#the-top class="pointer-events-auto sticky top-[calc(100vh-5.5rem)] flex h-12 w-12 items-center justify-center rounded-full bg-neutral/50 text-xl text-neutral-700 backdrop-blur hover:text-primary-600 dark:bg-neutral-800/50 dark:text-neutral dark:hover:text-primary-400" aria-label="Scroll to top" title="Scroll to top">↑</a></div></main><footer class="py-10 print:hidden"><div class="flex items-center justify-between"><div><p class="text-sm text-neutral-500 dark:text-neutral-400">© 2023 Congo contributors</p><p class="text-xs text-neutral-500 dark:text-neutral-400">Powered by <a class="hover:underline hover:decoration-primary-400 hover:text-primary-500" href=https://gohugo.io/ target=_blank rel="noopener noreferrer">Hugo</a> & <a class="hover:underline hover:decoration-primary-400 hover:text-primary-500" href=https://github.com/jpanther/congo target=_blank rel="noopener noreferrer">Congo</a></p></div><div class="flex flex-row items-center"><div class="me-14 cursor-pointer text-sm text-neutral-700 hover:text-primary-600 dark:text-neutral dark:hover:text-primary-400"><button id=appearance-switcher-0 type=button aria-label="appearance switcher"><div class="flex items-center justify-center w-12 h-12 dark:hidden" title="Switch to dark appearance"><span class="relative inline-block align-text-bottom px-1 icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="currentcolor" d="M32 256C32 132.2 132.3 32 255.8 32c11.36.0 29.7 1.668 40.9 3.746 9.616 1.777 11.75 14.63 3.279 19.44C245 86.5 211.2 144.6 211.2 207.8c0 109.7 99.71 193 208.3 172.3 9.561-1.805 16.28 9.324 10.11 16.95C387.9 448.6 324.8 480 255.8 480 132.1 480 32 379.6 32 256z"/></svg></span></div><div class="items-center justify-center hidden w-12 h-12 dark:flex" title="Switch to light appearance"><span class="relative inline-block align-text-bottom px-1 icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="currentcolor" d="M256 159.1c-53.02.0-95.1 42.98-95.1 95.1s41.2 96.9 95.1 96.9 95.1-42.98 95.1-95.1S309 159.1 256 159.1zM509.3 347l-63.2-91.9 63.15-91.01c6.332-9.125 1.104-21.74-9.826-23.72l-109-19.7-19.7-109c-1.975-10.93-14.59-16.16-23.72-9.824L256 65.89 164.1 2.736c-9.125-6.332-21.74-1.107-23.72 9.824L121.6 121.6 12.56 141.3C1.633 143.2-3.596 155.9 2.736 164.1L65.89 256 2.74 347.01c-6.332 9.125-1.105 21.74 9.824 23.72l109 19.7 19.7 109c1.975 10.93 14.59 16.16 23.72 9.824L256 446.1l91.01 63.15c9.127 6.334 21.75 1.107 23.72-9.822l19.7-109 109-19.7C510.4 368.8 515.6 356.1 509.3 347zM256 383.1c-70.69.0-127.1-57.31-127.1-127.1.0-70.69 57.31-127.1 127.1-127.1S383.1 186.2 383.1 256c0 70.7-56.4 127.1-127.1 127.1z"/></svg></span></div></button></div></div></div></footer><div id=search-wrapper class="invisible fixed inset-0 z-50 flex h-screen w-screen cursor-default flex-col bg-neutral-500/50 p-4 backdrop-blur-sm dark:bg-neutral-900/50 sm:p-6 md:p-[10vh] lg:p-[12vh]" data-url=https://jpanther.github.io/congo/><div id=search-modal class="flex flex-col w-full max-w-3xl min-h-0 mx-auto border rounded-md shadow-lg top-20 border-neutral-200 bg-neutral dark:border-neutral-700 dark:bg-neutral-800"><header class="relative z-10 flex items-center justify-between flex-none px-2"><form class="flex items-center flex-auto min-w-0"><div class="flex items-center justify-center w-8 h-8 text-neutral-400"><span class="relative inline-block align-text-bottom px-1 icon"><svg aria-hidden="true" focusable="false" data-prefix="fas" data-icon="search" class="svg-inline--fa fa-search fa-w-16" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="currentcolor" d="M505 442.7 405.3 343c-4.5-4.5-10.6-7-17-7H372c27.6-35.3 44-79.7 44-128C416 93.1 322.9.0 208 0S0 93.1.0 208s93.1 208 208 208c48.3.0 92.7-16.4 128-44v16.3c0 6.4 2.5 12.5 7 17l99.7 99.7c9.4 9.4 24.6 9.4 33.9.0l28.3-28.3c9.4-9.4 9.4-24.6.1-34zM208 336c-70.7.0-128-57.2-128-128 0-70.7 57.2-128 128-128 70.7.0 128 57.2 128 128 0 70.7-57.2 128-128 128z"/></svg></span></div><input type=search id=search-query class="flex flex-auto h-12 mx-1 bg-transparent appearance-none focus:outline-dotted focus:outline-2 focus:outline-transparent" placeholder=Search tabindex=0></form><button id=close-search-button class="flex items-center justify-center w-8 h-8 text-neutral-700 hover:text-primary-600 dark:text-neutral dark:hover:text-primary-400" title="Close (Esc)">
|
|
<span class="relative inline-block align-text-bottom px-1 icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"><path fill="currentcolor" d="M310.6 361.4c12.5 12.5 12.5 32.75.0 45.25C304.4 412.9 296.2 416 288 416s-16.38-3.125-22.62-9.375L160 301.3 54.63 406.6C48.38 412.9 40.19 416 32 416S15.63 412.9 9.375 406.6c-12.5-12.5-12.5-32.75.0-45.25l105.4-105.4L9.375 150.6c-12.5-12.5-12.5-32.75.0-45.25s32.75-12.5 45.25.0L160 210.8l105.4-105.4c12.5-12.5 32.75-12.5 45.25.0s12.5 32.75.0 45.25l-105.4 105.4L310.6 361.4z"/></svg></span></button></header><section class="flex-auto px-2 overflow-auto"><ul id=search-results></ul></section></div></div></div></body></html> |