<scripttype=application/ld+json>{"@context":"https://schema.org","@type":"BlogPosting","articleSection":"Documentation","name":"Installation","headline":"Installation","description":"How to install the Congo theme.","inLanguage":"en-AU","author":{"@type":"Person","name":"Congo"},"creator":{"@type":"Person","name":"Congo"},"copyrightHolder":"Congo","copyrightYear":"2020","dateCreated":"2020-08-16T00:00:00\u002b00:00","datePublished":"2020-08-16T00:00:00\u002b00:00","dateModified":"2020-08-16T00:00:00\u002b00:00","url":"https:\/\/jpanther.github.io\/congo\/docs\/installation\/","wordCount":"976","keywords":["installation","docs"]}</script>
<p>These instructions will get you up and running using Hugo and Congo from a completely blank state. Most of the dependencies mentioned in this guide can be installed using the package manager of choice for your platform.</p>
<h3id=install-hugo>Install Hugo <aclass=heading-anchorhref=#install-hugoaria-label=Anchor>#</a></h3>
<p>If you haven’t used Hugo before, you will need to <ahref=https://gohugo.io/getting-started/installing>install it onto your local machine</a>. You can check if it’s already installed by running the command <code>hugo version</code>.</p>
<spanclass="no-prose dark:text-neutral-300">Make sure you are using <strong>Hugo version 0.86.1</strong> or later as the theme takes advantage of some of the latest Hugo features.</span>
</div>
<p>You can find detailed installation instructions for your platform in the <ahref=https://gohugo.io/getting-started/installing>Hugo docs</a>.</p>
<h3id=create-a-new-site>Create a new site <aclass=heading-anchorhref=#create-a-new-sitearia-label=Anchor>#</a></h3>
<p>Run the command <code>hugo new site mywebsite</code> to create a new Hugo site in a directory named <code>mywebsite</code>.</p>
<p>Note that you can name the project directory whatever you choose, but the instructions below will assume it’s named <code>mywebsite</code>. If you use a different name, be sure to substitute it accordingly.</p>
<h3id=download-the-congo-theme>Download the Congo theme <aclass=heading-anchorhref=#download-the-congo-themearia-label=Anchor>#</a></h3>
<p>There several different ways to install the Congo theme into your Hugo website. From easiest to most difficult to install and maintain, they are:</p>
<p>If you’re unsure, choose the Hugo module method.</p>
<h4id=install-using-hugo>Install using Hugo <aclass=heading-anchorhref=#install-using-hugoaria-label=Anchor>#</a></h4>
<p>This method is the quickest and easiest for keeping the theme up-to-date. Hugo uses <strong>Go</strong> to initialise and manage modules so you need to ensure you have <code>go</code> installed before proceeding.</p>
<p><ahref=https://golang.org/dl/>Download</a> and install Go. You can check if it’s already installed by using the command <code>go version</code>.</p>
<spanclass="no-prose dark:text-neutral-300">Make sure you are using <strong>Go version 1.12</strong> or later as Hugo requires this for modules to work correctly.</span>
<divclass=highlight><pretabindex=0class=chroma><codeclass=language-shelldata-lang=shell><spanclass=c1># If you're managing your project on GitHub</span>
hugo mod init github.com/<username>/<repo-name>
<spanclass=c1># If you're managing your project locally</span>
hugo mod init my-project
</code></pre></div></li>
<li>
<p>Add the theme to your configuration by creating a new file <code>config/_default/module.toml</code> and adding the following:</p>
<h4id=install-using-git>Install using git <aclass=heading-anchorhref=#install-using-gitaria-label=Anchor>#</a></h4>
<p>For this method you’ll need to ensure you have <strong>Git</strong> installed on your local machine.</p>
<p>Change into the directory for your Hugo website (that you created above), initialise a new <code>git</code> repository and add Congo as a submodule.</p>
<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.</p>
</li>
<li>
<p>Continue to <ahref=#set-up-theme-configuration-files>set up the theme configuration files</a>.</p>
<h3id=set-up-theme-configuration-files>Set up theme configuration files <aclass=heading-anchorhref=#set-up-theme-configuration-filesaria-label=Anchor>#</a></h3>
<p>In the root folder of your website, delete the <code>config.toml</code> file that was generated by Hugo. Copy the <code>*.toml</code> config files from the theme into your <code>config/_default/</code> folder. This will ensure you have all the correct theme settings and will enable you to easily customise the theme to your needs.</p>
<spanclass="no-prose dark:text-neutral-300"><strong>Note:</strong> You should not overwrite the <code>module.toml</code> file if one already exists in your project!</span>
<p>Depending on how you installed the theme you will find the theme config files in different places:</p>
<ul>
<li><strong>Hugo Modules:</strong> In the Hugo cache directory, or <ahref="https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/jpanther/congo/tree/stable/config/_default">download a copy</a> from GitHub</li>
<li><strong>Git submodule or Manual install:</strong><code>themes/congo/config/_default</code></li>
</ul>
<p>Once you’ve copied the files, your config folder should look like this:</p>
<spanclass="no-prose dark:text-neutral-300"><strong>Important:</strong> If you didn’t use Hugo Modules to install Congo, you must add the line <code>theme = "congo"</code> to the top of your <code>config.toml</code> file.</span>
<p>The basic Congo installation is now complete. Continue to the <ahref=https://jpanther.github.io/congo/docs/getting-started/>Getting Started</a> section to learn more about configuring the theme.</p>
<p>From time to time there will be <ahref=https://github.com/jpanther/congo/releases>new releases</a> posted that apply fixes and add new functionality to the theme. In order to take advantage of these changes, you will need to update the theme files on your website.</p>
<p>How you go about this will depend on the installation method you chose when the theme was originally installed. Instructions for each method can be found below.</p>
<h3id=update-using-hugo>Update using Hugo <aclass=heading-anchorhref=#update-using-hugoaria-label=Anchor>#</a></h3>
<p>Hugo makes updating modules super easy. Simply change into your project directory and execute the following command:</p>
<divclass=highlight><pretabindex=0class=chroma><codeclass=language-shelldata-lang=shell>hugo mod get -u
</code></pre></div><p>Hugo will automatically update any modules that are required for your project. It does this by inspecting your <code>module.toml</code> and <code>go.mod</code> files. If you have any issues with the update, check to ensure these files are still configured correctly.</p>
<p>Then simply rebuild your site and check everything works as expected.</p>
<h3id=update-using-git>Update using git <aclass=heading-anchorhref=#update-using-gitaria-label=Anchor>#</a></h3>
<p>Git submodules can be updated 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>
<spanclass="no-prose 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>
<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>Rebuild your site and check everything works as expected.</p>
