congo/README.md

# Congo

Congo is designed to be a fast, lightweight theme for Hugo. It's based upon Tailwind CSS with a clean and minimalist design.

🌏 [Demo site](https://jpanther.github.io/Congo/)  
📑 [Theme documentation](https://jpanther.github.io/Congo/docs/)

![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
- 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 couple of ways to install the Congo theme into your Hugo website. The git method is the easiest to keep the theme up-to-date, but you can also download and install manually if you don't have git available.

### 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
```

### Install manually

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

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

### Set up your configuration files

In the root folder of your website, delete the `config.toml` file that was generated by Hugo. Copy the entire `config` folder from `themes/congo/config/` into the root of your website. This will ensure you have all the correct theme settings and will enable you to easily customise the theme.

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"
```

It's also useful to set the author configuration in the `config/_default/author.toml` file. You can also add links to your profiles here to enable them in the theme.

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

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

## Advanced customisation

There are a couple of ways you can make style changes to Congo.

If you just need to add or override some simple styles, you can do so by creating a `custom.css` file in your project's `static/css/` folder. This file will be loaded automatically after the theme's default styles.

Alternatively, if you'd like to make a major change, you can take advantage of Tailwind CSS's JIT compiler and rebuild the entire theme CSS from scratch.

> **Note:** Building the theme manually is intended for advanced users.

Change into the `themes/congo/` folder and install the project dependencies.

```bash
npm install
```

Once installed, you can edit the `themes/congo/tailwind.config.js` to change the styles that are applied throughout the theme. You can also adjust specific styles in `themes/congo/assets/css/main.css`.

To allow for easy theme colour changes, Congo defines a `primary` and `secondary` colour palette that is used throughout the theme. In order to change the colour across the entire theme, simply edit the `tailwind.config.js` file accordingly.

For example, to change to a green colour scheme, you could apply these changes:

```js
  // themes/congo/tailwind.config.js

  theme: {
    colors: {
      transparent: "transparent",
      white: colors.white,
      gray: colors.gray,
      primary: colors.lime,
      secondary: colors.teal,
    },
    ...
  }
```

For a full list of colours available, and their corresponding configuration values, see the official [Tailwind docs](https://tailwindcss.com/docs/customizing-colors#color-palette-reference).

After editing the configuration, you need to rebuild the theme's stylesheets.

```bash
npm run build
```

This will automatically output a minified CSS file to `/themes/congo/static/css/main.css`.

To aid with testing style changes, you can also run the Tailwind JIT comiler in watch mode.

```bash
npm run dev
```

Now whenever you make a change, the (non-minified) CSS files will be rebuilt automatically. This mode is useful to run when using `hugo server` to preview your site during development. Remember to perform a full build before publishing your website.

---

## Contributing

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

### Bugs & Suggestions

Feel free to get in touch with any issues or suggestions for new features you'd like to see. Please use GitHub issues for all bug reports and suggestions to help keep everything in one spot.

If you're able to fix a bug or implement a new feature, I welcome PRs for this purpose.

All development occurs on the `dev` branch and new PRs should be forked from here.