congo/README.md

# Congo

Congo is designed to be a simple, lightweight theme for [Hugo](https://gohugo.io). It's built using Tailwind CSS with a clean and minimalist design that prioritises to your content.

🌏 [Demo site](https://jpanther.github.io/congo/)  
📑 [Theme documentation](https://jpanther.github.io/congo/docs/)  
🐛 [Bug reports & issues](https://github.com/jpanther/congo/issues)  
💡 [Questions & feature requests](https://github.com/jpanther/congo/discussions)

![Screenshot](https://raw.githubusercontent.com/jpanther/congo/stable/images/screenshot.png)

## Features

- Built with Tailwind CSS JIT for minified stylesheets without any excess code
- Fully responsive layout
- Multiple colour schemes (or fully customise your own)
- Dark mode (auto-switching based upon browser)
- Highly customisable configuration
- Multiple homepage layouts
- Flexible with any content types, taxonomies and menus
- Ability to link to posts on third-party websites
- Diagrams and visualisations using Mermaid JS
- SVG icons from FontAwesome 5
- Heading anchors, Buttons, Badges and more
- HTML and Emoji support in articles
- SEO friendly with links for sharing to social media
- RSS feeds
- Fathom Analytics and Google Analytics support
- Favicons support
- Comments support
- Advanced customisation using simple Tailwind colour definitions and styles
- [Fully documented](https://jpanther.github.io/congo/docs/)

---

## Installation

This is a simplified set of instructions and assumes a basic understanding of building Hugo sites and installing themes. For detailed instructions, refer to the full [theme documentation](https://jpanther.github.io/congo/docs/).

There are a few ways to install the Congo theme into your Hugo website.

### Install using Hugo

This method is the quickest and easiest for keeping the theme up-to-date. Hugo Modules uses Go to initialise and manage modules so you need to ensure you have Go installed before proceeding.

1. [Download](https://golang.org/dl/) and install Go. You can check if it's already installed by using the command `go version`.
2. From your Hugo project's directory, initiate the Hugo Modules system for your website:

   ```shell
   hugo mod init github.com/<username>/<repo-name>
   ```

3. Add the theme to your configuration by creating a new file `config/_default/module.toml` and adding the following:

   ```toml
   [[imports]]
   path = "github.com/jpanther/congo"
   ```

4. Start your server using `hugo server` and the theme will be downloaded automatically.
5. Continue to [set up the theme configuration files](#set-up-theme-configuration-files).

### Install using git

Change into the directory for your Hugo website, initialise a new repository and add Congo as a submodule.

```bash
cd mywebsite
git init
git submodule add -b stable https://github.com/jpanther/congo.git themes/congo
```

Then continue to [set up the theme configuration files](#set-up-theme-configuration-files).

### Install manually

Download the latest release of the theme from: [https://github.com/jpanther/congo/releases/latest](https://github.com/jpanther/congo/releases/latest)

Extract the archive, rename the folder to `congo` and move it to the `themes/` directory inside your Hugo project.

Then continue to [set up the theme configuration files](#set-up-theme-configuration-files).

### Set up theme configuration files

In the root folder of your website, delete the `config.toml` file that was generated by Hugo. Copy the `*.toml` config files from the theme into your `config/_default/` folder. If you installed using Hugo Modules, you should not copy the `module.toml` file! This will ensure you have all the correct theme settings and will enable you to easily customise the theme.

Depending on how you installed the theme you will find the theme config files in different places:

- **Hugo Modules:** In the Hugo cache directory, or [download a copy](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/jpanther/congo/tree/stable/config/_default) from GitHub
- **Git submodule or Manual install:** `themes/congo/config/_default`

> **Important:** If you didn't use Hugo Modules to install Congo, you must add the line `theme = "congo"` to the top of your `config.toml` file.

You're now all set up to use Congo. From here you can add some content and start the Hugo server.

## Configuration

For all the theme options and detailed configuration instructions, refer to the [Congo docs](https://jpanther.github.io/congo/docs/).

A few things you need to set for a new installation:

```toml
# config/_default/config.toml

baseURL = "https://your_domain.com"
languageCode = "en-AU"
title = "My awesome website"

[author]
name = "Your name"
links = [
  { twitter = "https://twitter.com/jpanther" }
]
```

## Advanced customisation

Refer to the [theme documentation](https://jpanther.github.io/congo/docs/advanced-customisation/) for details on customising Congo, including rebuilding the theme from scratch.

---

## Contributing

Congo is still very much a work in progress. I intend to keep adding features and making changes as required.

Feel free to get in touch with any issues or suggestions for new features you'd like to see.

- 🐛 **Bug reports & issues:** Use [GitHub Issues](https://github.com/jpanther/congo/issues)
- 💡 **Ideas for new features:** Open a discussion on [GitHub Discussions](https://github.com/jpanther/congo/discussions)
- 🙋‍♀️ **General questions:** Head to [GitHub Discussions](https://github.com/jpanther/congo/discussions)

If you're able to fix a bug or implement a new feature, I welcome PRs for this purpose. Learn more in the [contributing guidelines](https://github.com/jpanther/congo/CONTRIBUTING.md).