diff --git a/README.md b/README.md index 6fdbdce7..8a57bb4b 100644 --- a/README.md +++ b/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. +[View Demo site](https://jpanther.github.io/Congo/) + ![Screenshot](https://raw.githubusercontent.com/jpanther/Congo/stable/images/screenshot.png) ## Features -- Built with [Tailwind CSS JIT](https://tailwindcss.com/docs/just-in-time-mode) 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 support (auto-switching based upon browser) -- Highly customisable [configuration](#configuration) +- Built with Tailwind CSS JIT for minified stylesheets without any excess code +- Dark mode (auto-switching based upon browser) +- Highly customisable configuration - Flexible with any content types, taxonomies and menus -- Diagrams and visualisations using [MermaidJS](https://mermaid-js.github.io/) -- SVG social icons from [FontAwesome 5](https://fontawesome.com/) +- Diagrams and visualisations using Mermaid JS +- SVG icons from FontAwesome 5 +- HTML and Emoji support in articles - SEO friendly -- [Fathom Analytics](https://usefathom.com/ref/RLAJSV) and Google Analytics -- Favicons support - Generate using [favicon.io](https://favicon.io) -- [Comments support](https://gohugo.io/content-management/comments/) +- Fathom Analytics and Google Analytics support +- Favicons support +- 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 @@ -124,18 +168,155 @@ When you create a new taxonomy, you will need to adjust the navigation links on ```toml # config/_default/menus.toml -[[menu.main]] +[[main]] name = "Blog" - pageRef = "/posts/" + pageRef = "posts" weight = 10 -[[menu.main]] +[[main]] name = "Topics" - pageRef = "/topics/" + pageRef = "topics" 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 `` 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 `` 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 `` and `