mirror of https://github.com/jpanther/congo.git
📝 Clean up readme and installation instructions
James Panther
parent
e75f375558
commit
9265fed50b
|
|
@ -45,7 +45,7 @@ The project includes a Prettier config that helps to format code in line with th
|
|||
|
||||
#### Commit message guidelines
|
||||
|
||||
- Use [Gitmoji](https://gitmoji.dev) in commit messages to provide context and.
|
||||
- Use [Gitmoji](https://gitmoji.dev) in commit messages to provide context.
|
||||
- Clearly describe the change with a short summary in the first 72 characters.
|
||||
- Place more detailed explanations in paragraphs below the summary, separated by a blank line.
|
||||
- Use imperative language (ie. "Fix bug", not "Fixed bug" or "Fixes bug").
|
||||
|
|
|
|||
90
README.md
90
README.md
|
|
@ -19,109 +19,71 @@ Congo is designed to be a simple, lightweight theme for [Hugo](https://gohugo.io
|
|||
- 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
|
||||
- Diagrams and visualisations using Mermaid
|
||||
- SVG icons from FontAwesome 5
|
||||
- Heading anchors, Buttons, Badges and more
|
||||
- HTML and Emoji support in articles
|
||||
- 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/)
|
||||
- Fully documented
|
||||
- Regular updates with fixes and new features
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
Congo has [extensive documentation](https://jpanther.github.io/congo/docs/) that covers all aspects of the theme. Be sure to [read the docs](https://jpanther.github.io/congo/docs/) to learn more about how to use the theme and its features.
|
||||
|
||||
---
|
||||
|
||||
## 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/).
|
||||
Congo supports several installation methods - as a Hugo Module (easiest), a git submodule, or as a completely manual install.
|
||||
|
||||
There are a few ways to install the Congo theme into your Hugo website.
|
||||
Detailed instructions for each method can be found in the [Installation](https://jpanther.github.io/congo/docs/installation) docs. You should consult the documentation for the simplest setup experience. Below is a quick start guide using Hugo modules if you're already confident installing Hugo themes.
|
||||
|
||||
### Install using Hugo
|
||||
### Quick start 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.
|
||||
> **Note:** Ensure you have **Go** and **Hugo** installed, and that you have created a new Hugo project 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:
|
||||
1. From your project directory, initialise Hugo Modules:
|
||||
|
||||
```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:
|
||||
2. Create `config/_default/module.toml` and add 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).
|
||||
3. Start your server using `hugo server` and the theme will be downloaded automatically.
|
||||
|
||||
### Install using git
|
||||
4. 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.
|
||||
|
||||
Change into the directory for your Hugo website, initialise a new repository and add Congo as a submodule.
|
||||
> **Note:** Do not overwrite the `module.toml` file you created above!
|
||||
|
||||
```bash
|
||||
cd mywebsite
|
||||
git init
|
||||
git submodule add -b stable https://github.com/jpanther/congo.git themes/congo
|
||||
```
|
||||
You will find these theme config files 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.
|
||||
|
||||
Then continue to [set up the theme configuration files](#set-up-theme-configuration-files).
|
||||
5. Follow the [Getting Started](https://jpanther.github.io/congo/docs/getting-started/) instructions to configure your website.
|
||||
|
||||
### Install manually
|
||||
### Installing theme updates
|
||||
|
||||
Download the latest release of the theme from: [https://github.com/jpanther/congo/releases/latest](https://github.com/jpanther/congo/releases/latest)
|
||||
As new releases are posted, you can update the theme using Hugo. Simply run `hugo mod get -u` from your project directory and the theme will automatically update to the latest release.
|
||||
|
||||
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.
|
||||
Detailed [update instructions](https://jpanther.github.io/congo/docs/installation/#installing-updates) are avaiable in the docs.
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Congo is still very much a work in progress. I intend to keep adding features and making changes as required.
|
||||
Congo is expected to evolve over time. 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.
|
||||
|
||||
|
|
@ -129,4 +91,4 @@ Feel free to get in touch with any issues or suggestions for new features you'd
|
|||
- 💡 **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).
|
||||
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/blob/dev/CONTRIBUTING.md).
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ This section assumes you have already [installed the Congo theme]({{< ref "docs/
|
|||
|
||||
The config files that ship with Congo contain all of the possible settings that the theme recognises. By default, many of these are commented out but you can simply uncomment them to activate or change a specific feature.
|
||||
|
||||
A few things you need to set for a new installation:
|
||||
There are a few things you should set in `config.toml` for a new installation:
|
||||
|
||||
```toml
|
||||
# config/_default/config.toml
|
||||
|
|
|
|||
|
|
@ -9,28 +9,49 @@ tags: ["installation", "docs"]
|
|||
|
||||
Simply follow the standard Hugo [Quick Start](https://gohugo.io/getting-started/quick-start/) procedure to get up and running quickly.
|
||||
|
||||
Detailed instructions can be found below.
|
||||
Detailed installation instructions can be found below. Instructions for [updating the theme](#installing-updates) are also available.
|
||||
|
||||
## Install Hugo
|
||||
## Installation
|
||||
|
||||
You can find specific instructions for your platform in the official [Hugo docs](https://gohugo.io/getting-started/installing.).
|
||||
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.
|
||||
|
||||
### Install Hugo
|
||||
|
||||
If you haven't used Hugo before, you will need to [install it onto your local machine](https://gohugo.io/getting-started/installing). You can check if it's already installed by running the command `hugo version`.
|
||||
|
||||
{{< alert >}}
|
||||
Make sure you are using **Hugo version 0.86.1** or later as the theme takes advantage of some of the latest Hugo features.
|
||||
{{< /alert >}}
|
||||
|
||||
## Create a new site
|
||||
You can find detailed installation instructions for your platform in the [Hugo docs](https://gohugo.io/getting-started/installing).
|
||||
|
||||
Run the command `hugo new site mywebsite` to create a new Hugo site in a folder named `mywebsite`.
|
||||
### Create a new site
|
||||
|
||||
## Download the Congo theme
|
||||
Run the command `hugo new site mywebsite` to create a new Hugo site in a directory named `mywebsite`.
|
||||
|
||||
There are a couple of ways to install the Congo theme into your Hugo website. The Hugo Modules method is the easiest, then the git method if you're familiar with submodules, but you can also download and install manually if you don't have `go` or `git` available.
|
||||
Note that you can name the project directory whatever you choose, but the instructions below will assume it's named `mywebsite`. If you use a different name, be sure to substitute it accordingly.
|
||||
|
||||
### Install using Hugo
|
||||
### Download the Congo theme
|
||||
|
||||
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.
|
||||
There several different ways to install the Congo theme into your Hugo website. From easiest to most difficult to install and maintain, they are:
|
||||
|
||||
- [Hugo module](#install-using-hugo) (recommended)
|
||||
- [Git submodule](#install-using-git)
|
||||
- [Manual file copy](#install-manually)
|
||||
|
||||
If you're unsure, choose the Hugo module method.
|
||||
|
||||
#### Install using Hugo
|
||||
|
||||
This method is the quickest and easiest for keeping the theme up-to-date. Hugo 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:
|
||||
|
||||
{{< alert >}}
|
||||
Make sure you are using **Go version 1.12** or later as Hugo requires this for modules to work correctly.
|
||||
{{< /alert >}}
|
||||
|
||||
2. From your Hugo project directory (that you created above), initialise modules for your website:
|
||||
|
||||
```shell
|
||||
# If you're managing your project on GitHub
|
||||
|
|
@ -50,9 +71,11 @@ This method is the quickest and easiest for keeping the theme up-to-date. Hugo M
|
|||
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
|
||||
#### Install using git
|
||||
|
||||
Change into the directory for your Hugo website, initialise a new repository and add Congo as a submodule.
|
||||
For this method you'll need to ensure you have **Git** installed on your local machine.
|
||||
|
||||
Change into the directory for your Hugo website (that you created above), initialise a new `git` repository and add Congo as a submodule.
|
||||
|
||||
```bash
|
||||
cd mywebsite
|
||||
|
|
@ -60,13 +83,9 @@ git init
|
|||
git submodule add -b stable https://github.com/jpanther/congo.git themes/congo
|
||||
```
|
||||
|
||||
{{< alert >}}
|
||||
**Note:** You need to substitute `mywebsite` for the correct folder name you used when creating your Hugo site.
|
||||
{{< /alert >}}
|
||||
|
||||
Then continue to [set up the theme configuration files](#set-up-theme-configuration-files).
|
||||
|
||||
### Install manually
|
||||
#### Install manually
|
||||
|
||||
1. Download the latest release of the theme source code.
|
||||
|
||||
|
|
@ -75,9 +94,13 @@ Then continue to [set up the theme configuration files](#set-up-theme-configurat
|
|||
2. Extract the archive, rename the folder to `congo` and move it to the `themes/` directory inside your Hugo project's root folder.
|
||||
3. Continue to [set up the theme configuration files](#set-up-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.
|
||||
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 to your needs.
|
||||
|
||||
{{< alert >}}
|
||||
**Note:** You should not overwrite the `module.toml` file if one already exists in your project!
|
||||
{{< /alert >}}
|
||||
|
||||
Depending on how you installed the theme you will find the theme config files in different places:
|
||||
|
||||
|
|
@ -99,6 +122,56 @@ 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.
|
||||
{{< /alert >}}
|
||||
|
||||
You're now all set up to use Congo. From here you can add some content and start the Hugo server.
|
||||
### Next steps
|
||||
|
||||
Refer to the [Hugo docs](https://gohugo.io/getting-started/) for more information or continue to the [Getting Started]({{< ref "getting-started" >}}) section to learn more about configuring the theme.
|
||||
The basic Congo installation is now complete. Continue to the [Getting Started]({{< ref "getting-started" >}}) section to learn more about configuring the theme.
|
||||
|
||||
---
|
||||
|
||||
## Installing updates
|
||||
|
||||
From time to time there will be [new releases](https://github.com/jpanther/congo/releases) 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.
|
||||
|
||||
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.
|
||||
|
||||
- [Hugo module](#update-using-hugo)
|
||||
- [Git submodule](#update-using-git)
|
||||
- [Manual file copy](#update-manually)
|
||||
|
||||
### Update using Hugo
|
||||
|
||||
Hugo makes updating modules super easy. Simply change into your project directory and execute the following command:
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
Hugo will automatically update any modules that are required for your project. It does this by inspecting your `module.toml` and `go.mod` files. If you have any issues with the update, check to ensure these files are still configured correctly.
|
||||
|
||||
Then simply rebuild your site and check everything works as expected.
|
||||
|
||||
### Update using git
|
||||
|
||||
Git submodules can be updated using the `git` command. Simply execute the following command and the latest version of the theme will be downloaded into your local repository:
|
||||
|
||||
```shell
|
||||
git submodule update --remote --merge
|
||||
```
|
||||
|
||||
Once the submodule has been updated, rebuild your site and check everything works as expected.
|
||||
|
||||
### Update manually
|
||||
|
||||
Updating Congo manually requires you to download the latest copy of the theme and replace the old version in your project.
|
||||
|
||||
{{< alert >}}
|
||||
Note that any local customisations you have made to the theme files will be lost during this process.
|
||||
{{< /alert >}}
|
||||
|
||||
1. Download the latest release of the theme source code.
|
||||
|
||||
{{< button href="https://github.com/jpanther/congo/releases/latest" target="_blank" >}}Download from Github{{< /button >}}
|
||||
|
||||
2. Extract the archive, rename the folder to `congo` and move it to the `themes/` directory inside your Hugo project's root folder. You will need to overwrite the existing directory to replace all the theme files.
|
||||
|
||||
3. Rebuild your site and check everything works as expected.
|
||||
|
|
|
|||
Loading…
Reference in New Issue