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