mirror of https://github.com/jpanther/congo.git
133 lines
5.5 KiB
Markdown
133 lines
5.5 KiB
Markdown
# 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)
|
|
|
|
|
|
|
|
## 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. 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).
|