mirror of https://github.com/jpanther/congo.git
📝 Add documentation for partials
James Panther
parent
ad0fe1db15
commit
5aa764976c
277
README.md
277
README.md
|
|
@ -2,21 +2,65 @@
|
||||||
|
|
||||||
Congo is designed to be a fast, lightweight theme for Hugo. It's based upon Tailwind CSS with a clean and minimalist design.
|
Congo is designed to be a fast, lightweight theme for Hugo. It's based upon Tailwind CSS with a clean and minimalist design.
|
||||||
|
|
||||||
|
[View Demo site](https://jpanther.github.io/Congo/)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- Built with [Tailwind CSS JIT](https://tailwindcss.com/docs/just-in-time-mode) for minified stylesheets without any excess code
|
- Built with Tailwind CSS JIT for minified stylesheets without any excess code
|
||||||
- Theme can be easily edited using simple [Tailwind colour definitions and styles](https://tailwindcss.com/docs)
|
- Dark mode (auto-switching based upon browser)
|
||||||
- Dark mode support (auto-switching based upon browser)
|
- Highly customisable configuration
|
||||||
- Highly customisable [configuration](#configuration)
|
|
||||||
- Flexible with any content types, taxonomies and menus
|
- Flexible with any content types, taxonomies and menus
|
||||||
- Diagrams and visualisations using [MermaidJS](https://mermaid-js.github.io/)
|
- Diagrams and visualisations using Mermaid JS
|
||||||
- SVG social icons from [FontAwesome 5](https://fontawesome.com/)
|
- SVG icons from FontAwesome 5
|
||||||
|
- HTML and Emoji support in articles
|
||||||
- SEO friendly
|
- SEO friendly
|
||||||
- [Fathom Analytics](https://usefathom.com/ref/RLAJSV) and Google Analytics
|
- Fathom Analytics and Google Analytics support
|
||||||
- Favicons support - Generate using [favicon.io](https://favicon.io)
|
- Favicons support
|
||||||
- [Comments support](https://gohugo.io/content-management/comments/)
|
- Comments support
|
||||||
|
- Advanced customisation using simple Tailwind colour definitions and styles
|
||||||
|
- Well documented (see below)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
### Table of Contents
|
||||||
|
|
||||||
|
- [Congo](#congo)
|
||||||
|
- [Features](#features)
|
||||||
|
- [Documentation](#documentation)
|
||||||
|
- [Table of Contents](#table-of-contents)
|
||||||
|
- [Installation](#installation)
|
||||||
|
- [1. Install Hugo](#1-install-hugo)
|
||||||
|
- [2. Create a new site](#2-create-a-new-site)
|
||||||
|
- [3. Download the Congo theme](#3-download-the-congo-theme)
|
||||||
|
- [Install using git](#install-using-git)
|
||||||
|
- [Install manually](#install-manually)
|
||||||
|
- [4. Set up your configuration files](#4-set-up-your-configuration-files)
|
||||||
|
- [Configuration](#configuration)
|
||||||
|
- [Getting started](#getting-started)
|
||||||
|
- [Organising content](#organising-content)
|
||||||
|
- [Shortcodes](#shortcodes)
|
||||||
|
- [Alert](#alert)
|
||||||
|
- [Icon](#icon)
|
||||||
|
- [Lead](#lead)
|
||||||
|
- [Mermaid](#mermaid)
|
||||||
|
- [Partials](#partials)
|
||||||
|
- [Analytics.html](#analyticshtml)
|
||||||
|
- [Fathom Analytics](#fathom-analytics)
|
||||||
|
- [Google Analytics](#google-analytics)
|
||||||
|
- [Custom analytics providers](#custom-analytics-providers)
|
||||||
|
- [Comments.html](#commentshtml)
|
||||||
|
- [Favicons.html](#faviconshtml)
|
||||||
|
- [Icon.html](#iconhtml)
|
||||||
|
- [Extend-head.html and Extend-footer.html](#extend-headhtml-and-extend-footerhtml)
|
||||||
|
- [Advanced customisation](#advanced-customisation)
|
||||||
|
- [Contributing](#contributing)
|
||||||
|
- [Bugs & Suggestions](#bugs--suggestions)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
|
|
@ -124,18 +168,155 @@ When you create a new taxonomy, you will need to adjust the navigation links on
|
||||||
```toml
|
```toml
|
||||||
# config/_default/menus.toml
|
# config/_default/menus.toml
|
||||||
|
|
||||||
[[menu.main]]
|
[[main]]
|
||||||
name = "Blog"
|
name = "Blog"
|
||||||
pageRef = "/posts/"
|
pageRef = "posts"
|
||||||
weight = 10
|
weight = 10
|
||||||
|
|
||||||
[[menu.main]]
|
[[main]]
|
||||||
name = "Topics"
|
name = "Topics"
|
||||||
pageRef = "/topics/"
|
pageRef = "topics"
|
||||||
weight = 20
|
weight = 20
|
||||||
```
|
```
|
||||||
|
|
||||||
## Customising the theme
|
## Shortcodes
|
||||||
|
|
||||||
|
In addition to all the [default Hugo shortcodes](https://gohugo.io/content-management/shortcodes/), Congo adds a few extras for additional functionality.
|
||||||
|
|
||||||
|
### Alert
|
||||||
|
|
||||||
|
`alert` outputs its contents as a stylised message box within your article. It's useful for drawing attention to important information that you don't want the reader to miss.
|
||||||
|
|
||||||
|
The input is written in Markdown so you can format it however you please.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
|
||||||
|
```md
|
||||||
|
{{< alert >}}
|
||||||
|
**Warning!** This action is destructive!
|
||||||
|
{{< /alert >}}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Icon
|
||||||
|
|
||||||
|
`icon` outputs an SVG icon and takes the icon name as its only parameter. The icon is scaled to match the current text size.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
|
||||||
|
```md
|
||||||
|
{{< icon "github" >}}
|
||||||
|
```
|
||||||
|
|
||||||
|
Icons are populated using Hugo pipelines which makes them very flexible. Congo ships with a default set of icons for social, email, and generic links. If you want to add your own icons, you can simply place them in `/assets/icons/` and reference them using the `icon` shortcode passing in the icon's filename (without the `.svg.` extension).
|
||||||
|
|
||||||
|
Icons can also be used in partials by calling the [`icon.html` partial](#iconhtml).
|
||||||
|
|
||||||
|
### Lead
|
||||||
|
|
||||||
|
`lead` is used to bring emphasis to the start of an article. It can be used to style an introduction, or to call out an important piece of information. Simply wrap any Markdown content in the `lead` shortcode.
|
||||||
|
|
||||||
|
```md
|
||||||
|
{{< lead >}}
|
||||||
|
When life gives you lemons, make lemonade.
|
||||||
|
{{< /lead >}}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Mermaid
|
||||||
|
|
||||||
|
`mermaid` allows you to draw detailed diagrams and visualisations using text. It uses MermaidJS under the hood and supports a wide variety of diagrams, charts and other output formats.
|
||||||
|
|
||||||
|
Simply write your Mermaid syntax within the `mermaid` shortcode and let the plugin do the rest.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
|
||||||
|
```md
|
||||||
|
{{< mermaid >}}
|
||||||
|
graph LR;
|
||||||
|
A[Lemons]-->B[Lemonade];
|
||||||
|
B-->C[Profit]
|
||||||
|
{{< /mermaid >}}
|
||||||
|
```
|
||||||
|
|
||||||
|
Refer to the [official Mermaid docs](https://mermaid-js.github.io/) for details on syntax and supported diagram types.
|
||||||
|
|
||||||
|
## Partials
|
||||||
|
|
||||||
|
### Analytics.html
|
||||||
|
|
||||||
|
Congo provides built-in support for Fathom Analytics and Google Analytics. Fathom is a paid alternative to Google Analytics that respects user privacy. If you're interested you can [receive $10 credit](https://usefathom.com/ref/RLAJSV) and try the service.
|
||||||
|
|
||||||
|
> **Note:** This is an affiliate link but helps to support the development of Congo.
|
||||||
|
|
||||||
|
#### Fathom Analytics
|
||||||
|
|
||||||
|
To enable Fathom Analytics support, simply provide your Fathom site code in the `config/_default/params.toml` file. If you also use the custom domain feature of Fathom and would like to serve their script from your domain, you can also additionally provide the `domain` configuration value. If you don't provide a `domain` value, the script will load directly from Fathom DNS.
|
||||||
|
|
||||||
|
```toml
|
||||||
|
# config/_default/params.toml
|
||||||
|
|
||||||
|
[fathomAnalytics]
|
||||||
|
site = "ABC12345"
|
||||||
|
domain = "llama.yoursite.com"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Google Analytics
|
||||||
|
|
||||||
|
Google Analytics support is provided through the internal Hugo partial. Simply provide the `googleAnalytics` key in the `config/_default/config.toml` file and the script will be added automatically.
|
||||||
|
|
||||||
|
```toml
|
||||||
|
# config/_default/config.toml
|
||||||
|
|
||||||
|
googleAnalytics = "UA-PROPERTY_ID"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Custom analytics providers
|
||||||
|
|
||||||
|
If you wish to use a different analytics provider on your website you can also override the analytics partial and provide your own script. Simply create the file `layouts/partials/analytics.html` in your project and it will automatically include it in the `<head>` of the website.
|
||||||
|
|
||||||
|
### Comments.html
|
||||||
|
|
||||||
|
To add comments to your articles, Congo includes support for a comments partial that is included at the base of each article page. Simply provide a `layouts/partials/comments.html` which contains the code required to display your chosen comments.
|
||||||
|
|
||||||
|
You can use either the built-in Hugo Disqus template, or provide your own custom code. Refer to the [Hugo docs](https://gohugo.io/content-management/comments/) for further information.
|
||||||
|
|
||||||
|
### Favicons.html
|
||||||
|
|
||||||
|
Congo provides a default set of blank favicons to get started but you can provide your own assets to override them. The easiest way to obtain new favicon assets is to generate them using a third-party provider like [favicon.io](https://favicon.io).
|
||||||
|
|
||||||
|
Icon assets should be placed directly in the `static/` folder of your website and named as per the listing below. If you use [favicon.io](https://favicon.io), these will be the filenames that are automatically generated for you, but you can provide your own assets if you wish.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
static/
|
||||||
|
├─ android-chrome-192x192.png
|
||||||
|
├─ android-chrome-512x512.png
|
||||||
|
├─ apple-touch-icon.png
|
||||||
|
├─ favicon-16x16.png
|
||||||
|
├─ favicon-32x32.png
|
||||||
|
├─ favicon.ico
|
||||||
|
└─ site.webmanifest
|
||||||
|
```
|
||||||
|
|
||||||
|
Alternatively, you can also completely override the default favicon behaviour and provide your own favicon HTML tags and assets. Simply provide a `layouts/partials/favicons.html` file in your project and this will be injected into the site `<head>` in place of the default assets.
|
||||||
|
|
||||||
|
### Icon.html
|
||||||
|
|
||||||
|
Similar to the [icon shortcode](#icon), you can include icons in your own templates and partials by using Congo's `icon.html` partial. The partial takes one parameter which is the name of the icon to be included.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
|
||||||
|
```go
|
||||||
|
{{ partial "icon.html" "github" }}
|
||||||
|
```
|
||||||
|
|
||||||
|
Congo includes a number of built-in icons for social, links and other purposes. You can also provide your own icon assets by including the SVG in `assets/icons/`.
|
||||||
|
|
||||||
|
### Extend-head.html and Extend-footer.html
|
||||||
|
|
||||||
|
The theme allows for inserting additional code directly into the `<head>` and `<footer>` sections of the template. These can be useful for providing scripts or other logic that isn't part of the theme.
|
||||||
|
|
||||||
|
Simply create either `layouts/partials/extend-head.html` or `layouts/partials/extend-footer.html` in your site folder and these will automatically be included in your website build. Both partials are injected as the last items in `<head>` and `<footer>` so they can be used to override theme defaults.
|
||||||
|
|
||||||
|
## Advanced customisation
|
||||||
|
|
||||||
There are a couple of ways you can make style changes to Congo.
|
There are a couple of ways you can make style changes to Congo.
|
||||||
|
|
||||||
|
|
@ -190,72 +371,6 @@ 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.
|
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.
|
||||||
|
|
||||||
## Shortcodes
|
|
||||||
|
|
||||||
In addition to all the [default Hugo shortcodes](https://gohugo.io/content-management/shortcodes/), Congo adds a few extras for additional functionality.
|
|
||||||
|
|
||||||
### Alert
|
|
||||||
|
|
||||||
`alert` outputs its contents as a stylised message box within your article. It's useful for drawing attention to important information that you don't want the reader to miss.
|
|
||||||
|
|
||||||
The input is written in Markdown so you can format it however you please.
|
|
||||||
|
|
||||||
**Usage:**
|
|
||||||
|
|
||||||
```md
|
|
||||||
{{< alert >}}
|
|
||||||
**Warning!** This action is destructive!
|
|
||||||
{{< /alert >}}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Icon
|
|
||||||
|
|
||||||
`icon` outputs an SVG icon and takes the icon name as its only parameter. The icon is scaled to match the current text size.
|
|
||||||
|
|
||||||
**Usage:**
|
|
||||||
|
|
||||||
```md
|
|
||||||
{{< icon "github" >}}
|
|
||||||
```
|
|
||||||
|
|
||||||
Icons are populated using Hugo pipelines which makes them very flexible. Congo ships with a default set of icons for social, email, and generic links. If you want to add your own icons, you can simply place them in `/assets/icons/` and reference them using the `icon` shortcode passing in the icon's filename (without the `.svg.` extension).
|
|
||||||
|
|
||||||
Icons can also be used in partials by calling the icon partial.
|
|
||||||
|
|
||||||
**Usage:**
|
|
||||||
|
|
||||||
```go
|
|
||||||
{{ partial "icon.html" "github" }}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Lead
|
|
||||||
|
|
||||||
`lead` is used to bring emphasis to the start of an article. It can be used to style an introduction, or to call out an important piece of information. Simply wrap any Markdown content in the `lead` shortcode.
|
|
||||||
|
|
||||||
```md
|
|
||||||
{{< lead >}}
|
|
||||||
When life gives you lemons, make lemonade.
|
|
||||||
{{< /lead >}}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Mermaid
|
|
||||||
|
|
||||||
`mermaid` allows you to draw detailed diagrams and visualisations using text. It uses MermaidJS under the hood and supports a wide variety of diagrams, charts and other output formats.
|
|
||||||
|
|
||||||
Simply write your Mermaid syntax within the `mermaid` shortcode and let the plugin do the rest.
|
|
||||||
|
|
||||||
**Usage:**
|
|
||||||
|
|
||||||
```md
|
|
||||||
{{<mermaid>}}
|
|
||||||
graph LR;
|
|
||||||
A[Lemons]-->B[Lemonade];
|
|
||||||
B-->C[Profit]
|
|
||||||
{{</mermaid>}}
|
|
||||||
```
|
|
||||||
|
|
||||||
Refer to the [official Mermaid docs](https://mermaid-js.github.io/) for details on syntax and supported diagram types.
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
Congo is still very much a work in progress. I intend to keep adding features and making changes as required.
|
Congo is still very much a work in progress. I intend to keep adding features and making changes as required.
|
||||||
|
|
@ -265,3 +380,5 @@ Congo is still very much a work in progress. I intend to keep adding features an
|
||||||
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.
|
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.
|
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.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue