🔖 Release v1.5.0

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: jpanther

.github/labeller.yml

@@ -2,4 +2,5 @@ i18n:
   - i18n/*
 
 documentation:
+  - "*.md"
   - exampleSite/content/*

.gitignore

@@ -137,6 +137,9 @@ hugo.exe
 hugo.darwin
 hugo.linux
 
+# Temporary lock file while building
+.hugo_build.lock
+
 # End of https://www.toptal.com/developers/gitignore/api/hugo
 
 exampleSite/public/

CHANGELOG.md

@@ -6,6 +6,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [1.5.0] - 2021-11-04
+
+### Added
+
+- Chart.js support using `chart` shortcode
+- KaTeX support using `katex` shortcode
+- Dark mode toggle with new theme parameters for managing light/dark appearance
+- French translation ([#18](https://github.com/jpanther/congo/pull/18))
+- Author bio in article footer
+- Grouping by year can now be specificed in front matter on list pages
+
+### Changed
+
+- Site name, author and menus will now render Markdown and Emoji
+- Bundled Mermaid for better vendor dependency management
+- Mermaid diagrams are now themed to match the configured colour scheme
+- Upgrade to Tailwind v2.2.19
+
+### Fixed
+
+- Site logo image dimensions are unconstrained ([#19](https://github.com/jpanther/congo/issues/19))
+- Article summary styled incorrectly in dark mode
+- Links containing `code` blocks styled incorrectly
+
 ## [1.4.0] - 2021-10-20
 
 ### Added
@@ -127,7 +151,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Advanced customisation using simple Tailwind colour definitions and styles
 - Fully documented
 
-[unreleased]: https://github.com/jpanther/Congo/compare/v1.4.0...HEAD
+[unreleased]: https://github.com/jpanther/Congo/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/jpanther/Congo/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/jpanther/Congo/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/jpanther/Congo/compare/v1.2.1...v1.3.0
 [1.2.1]: https://github.com/jpanther/Congo/compare/v1.2.0...v1.2.1

CONTRIBUTING.md

@@ -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").

README.md

@@ -14,114 +14,78 @@ Congo is designed to be a simple, lightweight theme for [Hugo](https://gohugo.io
 - 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)
+- Dark mode (forced on/off or auto-switching with user toggle)
 - 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
+- Diagrams and visualisations using Mermaid
+- Charts using Chart.js
+- Mathematical notation using KaTeX
 - 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`.
+1. From your project directory, initialise Hugo Modules:
-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:
+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.
+3. 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
+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
+   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.
-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).
+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.
+Detailed [update instructions](https://jpanther.github.io/congo/docs/installation/#installing-updates) are available in the docs.
-
-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.
 
 ---
 
 ## 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 +93,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).

archetypes/default.md

@@ -3,6 +3,4 @@ title: "{{ replace .Name "-" " " | title }}"
 date: {{ .Date }}
 draft: true
 description: ""
-slug: "{{ .File.BaseFileName }}"
-topics: []
 ---

assets/css/main.css

@@ -1,4 +1,4 @@
-/*! Congo v1.4.0 | MIT License | https://github.com/jpanther/congo */
+/*! Congo v1.5.0 | MIT License | https://github.com/jpanther/congo */
 
 @tailwind base;
 @tailwind components;

assets/icons/moon.svg

@@ -0,0 +1 @@
+<svg aria-hidden="true" focusable="false" data-prefix="fas" data-icon="moon" class="svg-inline--fa fa-moon fa-w-16" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="currentColor" d="M283.211 512c78.962 0 151.079-35.925 198.857-94.792 7.068-8.708-.639-21.43-11.562-19.35-124.203 23.654-238.262-71.576-238.262-196.954 0-72.222 38.662-138.635 101.498-174.394 9.686-5.512 7.25-20.197-3.756-22.23A258.156 258.156 0 0 0 283.211 0c-141.309 0-256 114.511-256 256 0 141.309 114.511 256 256 256z"></path></svg>

assets/icons/sun.svg

@@ -0,0 +1 @@
+<svg aria-hidden="true" focusable="false" data-prefix="fas" data-icon="sun" class="svg-inline--fa fa-sun fa-w-16" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="currentColor" d="M256 160c-52.9 0-96 43.1-96 96s43.1 96 96 96 96-43.1 96-96-43.1-96-96-96zm246.4 80.5l-94.7-47.3 33.5-100.4c4.5-13.6-8.4-26.5-21.9-21.9l-100.4 33.5-47.4-94.8c-6.4-12.8-24.6-12.8-31 0l-47.3 94.7L92.7 70.8c-13.6-4.5-26.5 8.4-21.9 21.9l33.5 100.4-94.7 47.4c-12.8 6.4-12.8 24.6 0 31l94.7 47.3-33.5 100.5c-4.5 13.6 8.4 26.5 21.9 21.9l100.4-33.5 47.3 94.7c6.4 12.8 24.6 12.8 31 0l47.3-94.7 100.4 33.5c13.6 4.5 26.5-8.4 21.9-21.9l-33.5-100.4 94.7-47.3c13-6.5 13-24.7.2-31.1zm-155.9 106c-49.9 49.9-131.1 49.9-181 0-49.9-49.9-49.9-131.1 0-181 49.9-49.9 131.1-49.9 181 0 49.9 49.9 49.9 131.1 0 181z"></path></svg>

assets/vendor/katex/auto-render.min.js

@@ -0,0 +1 @@
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("katex")):"function"==typeof define&&define.amd?define(["katex"],t):"object"==typeof exports?exports.renderMathInElement=t(require("katex")):e.renderMathInElement=t(e.katex)}("undefined"!=typeof self?self:this,(function(e){return function(){"use strict";var t={771:function(t){t.exports=e}},r={};function n(e){var a=r[e];if(void 0!==a)return a.exports;var i=r[e]={exports:{}};return t[e](i,i.exports,n),i.exports}n.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return n.d(t,{a:t}),t},n.d=function(e,t){for(var r in t)n.o(t,r)&&!n.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},n.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)};var a={};return function(){n.d(a,{default:function(){return s}});var e=n(771),t=n.n(e),r=function(e,t,r){for(var n=r,a=0,i=e.length;n<t.length;){var o=t[n];if(a<=0&&t.slice(n,n+i)===e)return n;"\\"===o?n++:"{"===o?a++:"}"===o&&a--,n++}return-1},i=/^\\begin{/,o=function(e,t){for(var n,a=[],o=new RegExp("("+t.map((function(e){return e.left.replace(/[-/\\^$*+?.()|[\]{}]/g,"\\$&")})).join("|")+")");-1!==(n=e.search(o));){n>0&&(a.push({type:"text",data:e.slice(0,n)}),e=e.slice(n));var l=t.findIndex((function(t){return e.startsWith(t.left)}));if(-1===(n=r(t[l].right,e,t[l].left.length)))break;var d=e.slice(0,n+t[l].right.length),s=i.test(d)?d:e.slice(t[l].left.length,n);a.push({type:"math",data:s,rawData:d,display:t[l].display}),e=e.slice(n+t[l].right.length)}return""!==e&&a.push({type:"text",data:e}),a},l=function(e,r){var n=o(e,r.delimiters);if(1===n.length&&"text"===n[0].type)return null;for(var a=document.createDocumentFragment(),i=0;i<n.length;i++)if("text"===n[i].type)a.appendChild(document.createTextNode(n[i].data));else{var l=document.createElement("span"),d=n[i].data;r.displayMode=n[i].display;try{r.preProcess&&(d=r.preProcess(d)),t().render(d,l,r)}catch(e){if(!(e instanceof t().ParseError))throw e;r.errorCallback("KaTeX auto-render: Failed to parse `"+n[i].data+"` with ",e),a.appendChild(document.createTextNode(n[i].rawData));continue}a.appendChild(l)}return a},d=function e(t,r){for(var n=0;n<t.childNodes.length;n++){var a=t.childNodes[n];if(3===a.nodeType){var i=l(a.textContent,r);i&&(n+=i.childNodes.length-1,t.replaceChild(i,a))}else 1===a.nodeType&&function(){var t=" "+a.className+" ";-1===r.ignoredTags.indexOf(a.nodeName.toLowerCase())&&r.ignoredClasses.every((function(e){return-1===t.indexOf(" "+e+" ")}))&&e(a,r)}()}},s=function(e,t){if(!e)throw new Error("No element provided to render");var r={};for(var n in t)t.hasOwnProperty(n)&&(r[n]=t[n]);r.delimiters=r.delimiters||[{left:"$$",right:"$$",display:!0},{left:"\\(",right:"\\)",display:!1},{left:"\\begin{equation}",right:"\\end{equation}",display:!0},{left:"\\begin{align}",right:"\\end{align}",display:!0},{left:"\\begin{alignat}",right:"\\end{alignat}",display:!0},{left:"\\begin{gather}",right:"\\end{gather}",display:!0},{left:"\\begin{CD}",right:"\\end{CD}",display:!0},{left:"\\[",right:"\\]",display:!0}],r.ignoredTags=r.ignoredTags||["script","noscript","style","textarea","pre","code","option"],r.ignoredClasses=r.ignoredClasses||[],r.errorCallback=r.errorCallback||console.error,r.macros=r.macros||{},d(e,r)}}(),a=a.default}()}));

config/_default/config.toml

@@ -17,6 +17,7 @@ summaryLength = 0
 [author]
   # name = "Your name here"
   # image = "img/author.jpg"
+  # bio = "A little bit about you"
   # links = [
   #   { email = "mailto:hello@your_domain.com" },
   #   { link = "https://link-to-some-website.com/" },

config/_default/params.toml

@@ -6,6 +6,8 @@
 # https://jpanther.github.io/congo/docs/configuration/#theme-parameters
 
 colorScheme = "congo"
+# darkMode = "auto"
+# darkToggle = false
 # logo = "img/logo.jpg"
 # description = "My awesome website"
 # mainSections = ["section1", "section2"]

exampleSite/config.toml

@@ -17,6 +17,7 @@ summaryLength = 0
 [author]
   name = "Congo"
   image = "img/author.jpg"
+  bio = "This is an example author bio, and although there's a stock photo of a dog here, this article was actually created by a human. :dog:"
   links = [
     { twitter = "https://twitter.com/" },
     { facebook = "https://facebook.com/" },
@@ -27,6 +28,9 @@ summaryLength = 0
 [taxonomies]
   tag = "tags"
 
+[params]
+  # logo = "logo.jpg"
+
 [params.homepage]
   layout = "custom"
   showRecent = true

exampleSite/content/docs/configuration.md

@@ -41,6 +41,7 @@ Note that the variable names provided in this table use dot notation to simplify
 |`summaryLength`|integer|`0`|The number of words that are used to generate the article summary when one is not provided in the [front matter]({{< ref "front-matter" >}}). A value of `0` will use the first sentence. This value has no effect when summaries are hidden.|
 |`author.name`|string|_Not set_|The author's name. This will be displayed in article footers, and on the homepage when the profile layout is used.|
 |`author.image`|string|_Not set_|Path to the image file of the author. The image should be a 1:1 aspect ratio and placed in the site's `static/` folder.|
+|`author.bio`|string|_Not set_|A Markdown string containing the author's bio. It will be displayed in article footers.|
 |`author.links`|array of objects|_Not set_|The links to display alongside the author's details. The config file contains example links which can simply be uncommented to enable. The order that the links are displayed is determined by the order they appear in the array. Custom links can be added by providing corresponding SVG icon assets in `assets/icons/`.|
 |`permalinks`||_Not set_|Refer to the [Hugo docs](https://gohugo.io/content-management/urls/#permalinks) for permalink configuration.|
 |`taxonomies`||_Not set_|Refer to the [Organising content]({{< ref "getting-started#organising-content" >}}) section for taxonomy configuration.|
@@ -56,6 +57,8 @@ Many of the article defaults here can be overridden on a per article basis by sp
 |Name|Type|Default|Description|
 | --- | --- | --- | --- |
 |`colorScheme`|string|`"congo"`|The theme colour scheme to use. Valid values are `congo` (default), `avocado`, `ocean`, `fire` and `slate`. Refer to the [Colour Schemes]({{< ref "getting-started#colour-schemes" >}}) section for more details.|
+|`darkMode`|boolean or string|`"auto"`|The preferred theme appearance for dark mode. Set to `true` to force dark appearance or `false` to force light appearance. Using `"auto"` will defer to the user's operating system preference.|
+|`darkToggle`|boolean|`false`|When `darkMode` is set to `"auto"`, this parameter determines whether or not to show the appearance toggle in the site footer. The browser's local storage is used to persist the user's preference.|
 |`logo`|string|_Not set_|The relative path to the site logo file within the `assets/` folder. The logo file should be provided at 2x resolution and supports any image dimensions.|
 |`description`|string|_Not set_|The description of the website for metadata purposes.|
 |`mainSections`|array of strings|_Not set_|The sections that should be displayed in the recent articles list. If not provided the section with the greatest number of articles is used.|

exampleSite/content/docs/front-matter.md

@@ -18,6 +18,7 @@ Front matter parameter default values are inherited from the theme's [base confi
 |`externalUrl`|string|_Not set_|If this article is published on a third-party website, the URL to this article. Providing a URL will prevent a content page being generated and any references to this article will link directly to the third-party website.|
 |`editURL`|string|`article.editURL`|When `showEdit` is active, the URL for the edit link.|
 |`editAppendPath`|boolean|`article.editAppendPath`|When `showEdit` is active, whether or not the path to the current article should be appended to the URL set at `editURL`.|
+|`groupByYear`|boolean|`list.groupByYear`|Whether or not articles are grouped by year on list pages.|
 |`menu`|string or array|_Not set_|When a value is provided, a link to this article will appear in the named menus. Valid values are `main` or `footer`.|
 |`robots`|string|_Not set_|String that indicates how robots should handle this article. If set, it will be output in the page head. Refer to [Google's docs](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives) for valid values.|
 |`sharingLinks`|array of strings|`article.sharingLinks`|Which sharing links to display at the end of this article. When not provided, or set to `false` no links will be displayed.|

exampleSite/content/docs/getting-started.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
@@ -23,8 +23,9 @@ languageCode = "en-AU"
 title = "My awesome website"
 
 [author]
-name = "Your name"
+name = "My name"
 image = "img/author.jpg"
+bio = "A little bit about me"
 links = [
   { twitter = "https://twitter.com/username" }
 ]

exampleSite/content/docs/hosting-deployment/index.md

@@ -0,0 +1,123 @@
+---
+title: "Hosting & Deployment"
+date: 2020-08-08
+draft: false
+description: "Learn how to deploy a Congo site."
+slug: "hosting-deployment"
+tags: ["hosting", "deployment", "docs", "github", "netlify", "render"]
+---
+
+There are many ways to deploy your Hugo website built with Congo. The theme is designed to be flexible in almost any deployment scenario.
+
+Congo is built using relative URLs throughout the theme. This enables sites to easily be deployed to sub-folders and hosts like GitHub Pages. There's usually no special configuration required for this to work as long as the `baseURL` parameter has been configured in the `config.toml` file.
+
+The official Hugo [Hosting and Deployment](https://gohugo.io/hosting-and-deployment/) docs are the best place to learn how to deploy your site. The sections below contain some specific theme configuration details that can help you deploy smoothly with certain providers.
+
+**Choose your provider:**
+
+- [GitHub Pages](#github-pages)
+- [Netlify](#netlify)
+- [Render](#render)
+- [Shared hosting, VPS or private web server](#shared-hosting-vps-or-private-web-server)
+
+---
+
+## GitHub Pages
+
+GitHub allows hosting on [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages) using Actions. To enable this functionality, enable Pages on your repo and create a new Actions workflow to build and deploy your site.
+
+The file needs to be in YAML format, placed within the `.github/workflows/` directory of your GitHub repository and named with a `.yml` extension.
+
+```yaml
+# .github/workflows/gh-pages.yml
+
+name: GitHub Pages
+
+on:
+  push:
+    branches:
+      - main # change to the branch name for your project
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-20.04
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          submodules: true
+          fetch-depth: 0
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: "latest"
+
+      - name: Build
+        run: hugo --minify
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./public
+```
+
+Push the config file to GitHub and the action should automatically run. It may fail the first time and you'll need to visit the **Settings > Pages** section of your GitHub repo to check the source is correct. It should be set to use the `gh-pages` branch.
+
+{{< screenshot src="github-pages-source.jpg" alt="Screen capture of GitHub Pages source" >}}
+
+Once the settings are configured, re-run the action and the site should build and deploy correctly. You can consult the actions log to check everything deployed successfully.
+
+## Netlify
+
+To deploy to [Netlify](https://www.netlify.com), create a new continuous deployment site and link it to your source code. The build settings can be left blank in the Netlify UI. You will only need to configure the domain you'll be using.
+
+{{< screenshot src="netlify-build-settings.jpg" alt="Screen capture of Netlify build settings" >}}
+
+Then in the root of your site repository, create a `netlify.toml` file:
+
+```toml
+# netlify.toml
+
+[build]
+  command = "hugo mod get -u && hugo --gc --minify -b $URL"
+  publish = "public"
+
+[build.environment]
+  NODE_ENV = "production"
+  GO_VERSION = "1.16"
+  TZ = "UTC"  # Set to preferred timezone
+
+[context.production.environment]
+  HUGO_VERSION = "0.87.0"
+  HUGO_ENV = "production"
+```
+
+This configuration assumes you are deploying Congo as a Hugo module. If you have installed the theme using another method, change the build command to simply `hugo --gc --minify -b $URL`.
+
+When you push the config file to your repo, Netlify should automatically deploy your site. You can check the deploy logs in the Netlify UI to check for any errors.
+
+## Render
+
+Deploying to [Render](https://render.com) is very straightforward and all configuration is via the Render UI.
+
+Create a new **Static Site** and link it to your project's code repository. Then simply configure the build command to be `hugo --gc --minify` and publish directory to be `public`.
+
+{{< screenshot src="render-settings.jpg" alt="Screen capture of Render settings" >}}
+
+The site will automatically build and deploy whenever you push a change to your repo.
+
+## Shared hosting, VPS or private web server
+
+Using traditional web hosting, or deploying to your own web server, is as simple as building your Hugo site and transferring the files to your host.
+
+Make sure that the `baseURL` parameter in `config.toml` is set to the full URL to the root of your website (including any sub domains or sub-folders).
+
+Then build your site using `hugo` and copy the contents of the output directory to the root of your web server and you will be ready to go. By default, the output directory is named `public`.
+
+_If you need a hosting provider, check out [Vultr](https://www.vultr.com/?ref=8957394-8H) or [DigitalOcean](https://m.do.co/c/36841235e565). Signing up using these affiliate links will give you up to $100 in free credit so you can try the service._

exampleSite/content/docs/installation.md

@@ -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.

exampleSite/content/docs/shortcodes.md

@@ -59,6 +59,42 @@ Call to action
 Call to action
 {{< /button >}}
 
+## Chart
+
+`chart` uses the Chart.js library to embed charts into articles using simple structured data. It supports a number of [different chart styles](https://www.chartjs.org/docs/latest/samples/) and everything can be configured from within the shortcode. Simply provide the chart parameters between the shortcode tags and Chart.js will do the rest.
+
+Refer to the [official Chart.js docs](https://www.chartjs.org/docs/latest/general/) for details on syntax and supported chart types.
+
+**Example:**
+
+```js
+{{</* chart */>}}
+type: 'bar',
+data: {
+  labels: ['Tomato', 'Blueberry', 'Banana', 'Lime', 'Orange'],
+  datasets: [{
+    label: '# of votes',
+    data: [12, 19, 3, 5, 2, 3],
+  }]
+}
+{{</* /chart */>}}
+```
+
+<!-- prettier-ignore-start -->
+{{< chart >}}
+type: 'bar',
+data: {
+  labels: ['Tomato', 'Blueberry', 'Banana', 'Lime', 'Orange'],
+  datasets: [{
+    label: '# of votes',
+    data: [12, 19, 3, 5, 3],
+  }]
+}
+{{< /chart >}}
+<!-- prettier-ignore-end -->
+
+You can see some additional Chart.js examples on the [charts samples]({{< ref "charts" >}}) page.
+
 ## 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.
@@ -75,6 +111,26 @@ Icons are populated using Hugo pipelines which makes them very flexible. Congo s
 
 Icons can also be used in partials by calling the [icon partial]({{< ref "partials#icon" >}}).
 
+## Katex
+
+The `katex` shortcode can be used to add mathematical expressions to article content using the KaTeX package. Refer to the online reference of [supported TeX functions](https://katex.org/docs/supported.html) for the available syntax.
+
+To include mathematical expressions in an article, simply place the shortcode anywhere with the content. It only needs to be included once per article and KaTeX will automatically render any markup on that page. Both inline and block notation are supported.
+
+Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters. Alternatively, block notation can be generated using `$$` delimiters.
+
+**Example:**
+
+```md
+{{</* katex */>}}
+\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+```
+
+{{< katex >}}
+\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+
+Check out the [mathematical notation samples]({{< ref "mathematical-notation" >}}) page for more examples.
+
 ## 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.
@@ -93,7 +149,7 @@ When life gives you lemons, make lemonade.
 
 ## 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.
+`mermaid` allows you to draw detailed diagrams and visualisations using text. It uses Mermaid 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.
 
@@ -114,3 +170,5 @@ graph LR;
 A[Lemons]-->B[Lemonade];
 B-->C[Profit]
 {{< /mermaid >}}
+
+You can see some additional Mermaid examples on the [diagrams and flowcharts samples]({{< ref "diagrams-flowcharts" >}}) page.

exampleSite/content/samples/_index.md

@@ -11,9 +11,7 @@ cascade:
 Congo brings your content to life. :heart_eyes:
 {{< /lead >}}
 
-This section contains some demo pages that show how Congo renders different types of content. These pages come from Hugo's official [hugoBasicExample](https://github.com/gohugoio/hugoBasicExample) repository.
+This section contains some demo pages that show how Congo renders different types of content. You can also see an example [taxonomy listing]({{< ref "tags" >}}) page.
-
-You can also see an example [taxonomy listing]({{< ref "tags" >}}) page.
 
 _**Sidenote:** This page is just a standard Congo article listing and Hugo has been configured to generate a `samples` content type and display article summaries._
 

exampleSite/content/samples/charts.md

@@ -0,0 +1,85 @@
+---
+title: "Charts"
+date: 2019-03-06
+description: "Guide to Chart.js usage in Congo"
+summary: "Congo includes Chart.js for powerful charts and data visualisations."
+tags: ["chart", "sample", "graph", "shortcodes"]
+---
+
+Congo includes support for Chart.js using the `chart` shortcode. Simply wrap the chart markup within the shortcode. Congo automatically themes charts to match the configured `colorScheme` parameter, however the colours can be customised using normal Chart.js syntax.
+
+Refer to the [chart shortcode]({{< ref "docs/shortcodes#chart" >}}) docs for more details.
+
+The examples below are a small selection taken from the [official Chart.js docs](https://www.chartjs.org/docs/latest/samples). You can also [view the page source](https://raw.githubusercontent.com/jpanther/congo/dev/exampleSite/content/samples/charts.md) on GitHub to see the markup.
+
+## Bar chart
+
+<!-- prettier-ignore-start -->
+{{< chart >}}
+type: 'bar',
+data: {
+  labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
+  datasets: [{
+    label: 'My First Dataset',
+    data: [65, 59, 80, 81, 56, 55, 40],
+    backgroundColor: [
+      'rgba(255, 99, 132, 0.2)',
+      'rgba(255, 159, 64, 0.2)',
+      'rgba(255, 205, 86, 0.2)',
+      'rgba(75, 192, 192, 0.2)',
+      'rgba(54, 162, 235, 0.2)',
+      'rgba(153, 102, 255, 0.2)',
+      'rgba(201, 203, 207, 0.2)'
+    ],
+    borderColor: [
+      'rgb(255, 99, 132)',
+      'rgb(255, 159, 64)',
+      'rgb(255, 205, 86)',
+      'rgb(75, 192, 192)',
+      'rgb(54, 162, 235)',
+      'rgb(153, 102, 255)',
+      'rgb(201, 203, 207)'
+    ],
+    borderWidth: 1
+  }]
+}
+{{< /chart >}}
+<!-- prettier-ignore-end -->
+
+## Line chart
+
+<!-- prettier-ignore-start -->
+{{< chart >}}
+type: 'line',
+data: {
+  labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
+  datasets: [{
+    label: 'My First Dataset',
+    data: [65, 59, 80, 81, 56, 55, 40],
+    tension: 0.2
+  }]
+}
+{{< /chart >}}
+<!-- prettier-ignore-end -->
+
+## Doughnut chart
+
+<!-- prettier-ignore-start -->
+{{< chart >}}
+type: 'doughnut',
+data: {
+  labels: ['Red', 'Blue', 'Yellow'],
+  datasets: [{
+    label: 'My First Dataset',
+    data: [300, 50, 100],
+    backgroundColor: [
+      'rgba(255, 99, 132, 0.7)',
+      'rgba(54, 162, 235, 0.7)',
+      'rgba(255, 205, 86, 0.7)'
+    ],
+    borderWidth: 0,
+    hoverOffset: 4
+  }]
+}
+{{< /chart >}}
+<!-- prettier-ignore-end -->

exampleSite/content/samples/diagrams-flowcharts.md

@@ -0,0 +1,92 @@
+---
+title: "Diagrams and Flowcharts"
+date: 2019-03-06
+description: "Guide to Mermaid usage in Congo"
+summary: "It's easy to add diagrams and flowcharts to articles using Mermaid."
+tags: ["mermaid", "sample", "diagram", "shortcodes"]
+---
+
+Mermaid diagrams are supported in Congo using the `mermaid` shortcode. Simply wrap the diagram markup within the shortcode. Congo automatically themes Mermaid diagrams to match the configured `colorScheme` parameter.
+
+Refer to the [mermaid shortcode]({{< ref "docs/shortcodes#mermaid" >}}) docs for more details.
+
+The examples below are a small selection taken from the [official Mermaid docs](https://mermaid-js.github.io/mermaid/). You can also [view the page source](https://raw.githubusercontent.com/jpanther/congo/dev/exampleSite/content/samples/diagrams-flowcharts.md) on GitHub to see the markup.
+
+## Flowchart
+
+{{< mermaid >}}
+graph TD
+A[Christmas] -->|Get money| B(Go shopping)
+B --> C{Let me think}
+B --> G[/Another/]
+C ==>|One| D[Laptop]
+C -->|Two| E[iPhone]
+C -->|Three| F[Car]
+subgraph Section
+C
+D
+E
+F
+G
+end
+{{< /mermaid >}}
+
+## Sequence diagram
+
+{{< mermaid >}}
+sequenceDiagram
+autonumber
+par Action 1
+Alice->>John: Hello John, how are you?
+and Action 2
+Alice->>Bob: Hello Bob, how are you?
+end
+Alice->>+John: Hello John, how are you?
+Alice->>+John: John, can you hear me?
+John-->>-Alice: Hi Alice, I can hear you!
+Note right of John: John is perceptive
+John-->>-Alice: I feel great!
+loop Every minute
+John-->Alice: Great!
+end
+{{< /mermaid >}}
+
+## Class diagram
+
+{{< mermaid >}}
+classDiagram
+Animal "1" <|-- Duck
+Animal <|-- Fish
+Animal <--o Zebra
+Animal : +int age
+Animal : +String gender
+Animal: +isMammal()
+Animal: +mate()
+class Duck{
++String beakColor
++swim()
++quack()
+}
+class Fish{
+-int sizeInFeet
+-canEat()
+}
+class Zebra{
++bool is_wild
++run()
+}
+{{< /mermaid >}}
+
+## Entity relationship diagram
+
+{{< mermaid >}}
+erDiagram
+CUSTOMER }|..|{ DELIVERY-ADDRESS : has
+CUSTOMER ||--o{ ORDER : places
+CUSTOMER ||--o{ INVOICE : "liable for"
+DELIVERY-ADDRESS ||--o{ ORDER : receives
+INVOICE ||--|{ ORDER : covers
+ORDER ||--|{ ORDER-ITEM : includes
+PRODUCT-CATEGORY ||--|{ PRODUCT : contains
+PRODUCT ||--o{ ORDER-ITEM : "ordered in"
+{{< /mermaid >}}

exampleSite/content/samples/emoji-support.md

@@ -1,22 +0,0 @@
----
-title: "Emoji Support"
-date: 2019-03-05
-description: "Guide to emoji usage in Hugo"
-summary: "📖🏞️🧗🏽🪂🐉🧙🏽‍♂️🧚🏽👸"
-tags: ["emoji", "sample"]
----
-
-Emoji can be enabled in a Hugo project in a number of ways.
-
-The [`emojify`](https://gohugo.io/functions/emojify/) function can be called directly in templates or [Inline Shortcodes](https://gohugo.io/templates/shortcode-templates/#inline-shortcodes).
-
-To enable emoji globally, set `enableEmoji` to `true` in your site's [configuration](https://gohugo.io/getting-started/configuration/) and then you can type emoji shorthand codes directly in content files; e.g.
-
-<p><span class="nowrap"><span class="emojify">🙈</span> <code>:see_no_evil:</code></span>  <span class="nowrap"><span class="emojify">🙉</span> <code>:hear_no_evil:</code></span>  <span class="nowrap"><span class="emojify">🙊</span> <code>:speak_no_evil:</code></span></p>
-<br>
-
-The [Emoji cheat sheet](http://www.emoji-cheat-sheet.com/) is a useful reference for emoji shorthand codes.
-
----
-
-**N.B.** The above steps enable Unicode Standard emoji characters and sequences in Hugo, however the rendering of these glyphs depends on the browser and the platform. To style the emoji you can either use a third party emoji font or a font stack.

exampleSite/content/samples/emoji.md

@@ -0,0 +1,19 @@
+---
+title: "Emoji"
+date: 2019-03-05
+description: "Guide to Emoji usage in Congo"
+summary: "📖🏞️🧗🏽🪂🐉🧙🏽‍♂️🧚🏽👸"
+tags: ["emoji", "sample"]
+---
+
+Emoji is supported throughout Congo by default. Emoji can be used in titles, menu items and article content.
+
+{{< alert >}}
+**Note:** The rendering of these glyphs depends on the browser and the platform. To style the emoji you can either use a third party emoji font or a font stack.
+{{< /alert >}}
+
+Emoji replacements are controlled via the `enableEmoji` parameter in your [site configuration]({{< ref "configuration#site-configuration" >}}). Set it to `true` and then you can type Emoji shorthand codes directly in content files.
+
+**Example:** `see_no_evil` :see_no_evil:, `hear_no_evil` :hear_no_evil:, `speak_no_evil` :speak_no_evil:.
+
+The [Emoji cheat sheet](http://www.emoji-cheat-sheet.com/) is a useful reference for emoji shorthand codes.

exampleSite/content/samples/markdown.md

@@ -1,11 +1,11 @@
 ---
-title: "Markdown Syntax Guide"
+title: "Markdown"
 date: 2019-03-11
 description: "Sample article showcasing basic Markdown syntax and formatting for HTML elements."
 tags: ["markdown", "css", "html", "sample"]
 ---
 
-This article offers a sample of basic Markdown syntax that can be used in Hugo content files, also it shows whether basic HTML elements are decorated with CSS in a Hugo theme.
+This article offers a sample of basic Markdown formatting that can be used in Congo, also it shows how some basic HTML elements are decorated.
 
 <!--more-->
 

exampleSite/content/samples/math-typesetting.md

@@ -1,47 +0,0 @@
----
-author: Hugo Authors
-title: Math Typesetting
-date: 2019-03-08
-description: A brief guide to setup KaTeX
-math: true
-tags: ["sample"]
----
-
-Mathematical notation in a Hugo project can be enabled by using third party JavaScript libraries.
-
-<!--more-->
-
-In this example we will be using [KaTeX](https://katex.org/).
-
-- Create a partial under `/layouts/partials/math.html`
-- Within this partial reference the [Auto-render Extension](https://katex.org/docs/autorender.html) or host these scripts locally.
-- Include the partial in your templates like so:
-
-```bash
-{{ if or .Params.math .Site.Params.math }}
-{{ partial "math.html" . }}
-{{ end }}
-```
-
-- To enable KaTex globally set the parameter `math` to `true` in a project's configuration
-- To enable KaTex on a per page basis include the parameter `math: true` in content files
-
-**Note:** Use the online reference of [Supported TeX Functions](https://katex.org/docs/supported.html)
-
-<!-- KaTeX -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.13.13/dist/katex.min.css" integrity="sha384-RZU/ijkSsFbcmivfdRBQDtwuwVqK7GMOw6IMvKyeWL2K5UAlyp6WonmB8m7Jd0Hn" crossorigin="anonymous">
-<script defer src="https://cdn.jsdelivr.net/npm/katex@0.13.13/dist/katex.min.js" integrity="sha384-pK1WpvzWVBQiP0/GjnvRxV4mOb0oxFuyRxJlk6vVw146n3egcN5C925NCP7a7BY8" crossorigin="anonymous"></script>
-<script defer src="https://cdn.jsdelivr.net/npm/katex@0.13.13/dist/contrib/auto-render.min.js" integrity="sha384-vZTG03m+2yp6N6BNi5iM4rW4oIwk5DfcNdFfxkk9ZWpDriOkXX8voJBFrAO7MpVl" crossorigin="anonymous"
-    onload="renderMathInElement(document.body);"></script>
-
-### Examples
-
-<p>
-Inline math: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)
-</p>
-
-Block math:
-
-$$
- \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } }
-$$

exampleSite/content/samples/mathematical-notation.md

@@ -0,0 +1,46 @@
+---
+title: Mathematical notation
+date: 2019-03-08
+description: A brief sample of mathematical notation in Congo.
+tags: ["sample", "katex", "maths", "shortcodes"]
+---
+
+KaTeX can be used to render mathematical notation within articles.
+
+<!--more-->
+
+{{< katex >}}
+
+Congo will only bundle the KaTeX assets into your project if you make use of mathematical notation. In order for this to work, simply include the [`katex` shortcode]({{< ref "docs/shortcodes#katex" >}}) within the article. Any KaTeX syntax on that page will then be automatically rendered.
+
+Use the online reference of [supported TeX functions](https://katex.org/docs/supported.html) for the available syntax.
+
+## Inline notation
+
+Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters.
+
+**Example:**
+
+```tex
+% KaTeX inline notation
+Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+```
+
+Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+
+## Block notation
+
+Alternatively, block notation can be generated using `$$` delimiters. This will output the expression in its own HTML block.
+
+**Example:**
+
+```tex
+% KaTeX block notation
+$$
+ \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } }
+$$
+```
+
+$$
+ \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } }
+$$

exampleSite/content/samples/placeholder-text.md

@@ -3,7 +3,7 @@ title: "Placeholder Text"
 date: "2019-03-09"
 draft: true
 description: "Lorem Ipsum Dolor Si Amet"
-tags: ["markdown", "text", "sample"]
+tags: ["markdown", "text", "sample", "latin"]
 xml: false
 ---
 
@@ -22,24 +22,16 @@ Rursus nulli murmur; hastile inridet ut ab gravi sententia! Nomine potitus silen
 4. Arcanaque montibus omnes
 5. Quidem et
 
-# Vagus elidunt
+## Vagus elidunt
 
 <svg class="canon" xmlns="http://www.w3.org/2000/svg" overflow="visible" viewBox="0 0 496 373" height="373" width="496"><g fill="none"><path stroke="#000" stroke-width=".75" d="M.599 372.348L495.263 1.206M.312.633l494.95 370.853M.312 372.633L247.643.92M248.502.92l246.76 370.566M330.828 123.869V1.134M330.396 1.134L165.104 124.515"></path><path stroke="#ED1C24" stroke-width=".75" d="M275.73 41.616h166.224v249.05H275.73zM54.478 41.616h166.225v249.052H54.478z"></path><path stroke="#000" stroke-width=".75" d="M.479.375h495v372h-495zM247.979.875v372"></path><ellipse cx="498.729" cy="177.625" rx=".75" ry="1.25"></ellipse><ellipse cx="247.229" cy="377.375" rx=".75" ry="1.25"></ellipse></g></svg>
 
 [The Van de Graaf Canon](https://en.wikipedia.org/wiki/Canons_of_page_construction#Van_de_Graaf_canon)
 
-## Mane refeci capiebant unda mulcebat
+### Mane refeci capiebant unda mulcebat
 
 Victa caducifer, malo vulnere contra dicere aurato, ludit regale, voca! Retorsit colit est profanae esse virescere furit nec; iaculi matertera et visa est, viribus. Divesque creatis, tecta novat collumque vulnus est, parvas. **Faces illo pepulere** tempus adest. Tendit flamma, ab opes virum sustinet, sidus sequendo urbis.
 
 Iubar proles corpore raptos vero auctor imperium; sed et huic: manus caeli Lelegas tu lux. Verbis obstitit intus oblectamina fixis linguisque ausus sperare Echionides cornuaque tenent clausit possit. Omnia putatur. Praeteritae refert ausus; ferebant e primus lora nutat, vici quae mea ipse. Et iter nil spectatae vulnus haerentia iuste et exercebat, sui et.
 
 Eurytus Hector, materna ipsumque ut Politen, nec, nate, ignari, vernum cohaesit sequitur. Vel **mitis temploque** vocatus, inque alis, _oculos nomen_ non silvis corpore coniunx ne displicet illa. Crescunt non unus, vidit visa quantum inmiti flumina mortis facto sic: undique a alios vincula sunt iactata abdita! Suspenderat ego fuit tendit: luna, ante urbem Propoetides **parte**.
-
-{{< css.inline >}}
-
-<style>
-.canon { background: white; width: 100%; height: auto; }
-</style>
-
-{{< /css.inline >}}

exampleSite/content/samples/rich-content.md

@@ -3,27 +3,33 @@ title: "Rich Content"
 date: 2019-03-10
 description: "A brief description of Hugo Shortcodes"
 summary: "This is an _example_ of a **rich** content summary."
-tags: ["shortcodes", "privacy", "sample"]
+tags: ["shortcodes", "privacy", "sample", "gist", "twitter", "youtube", "vimeo"]
 ---
 
-Hugo ships with several [Built-in Shortcodes](https://gohugo.io/content-management/shortcodes/#use-hugos-built-in-shortcodes) for rich content, along with a [Privacy Config](https://gohugo.io/about/hugo-and-gdpr/) and a set of Simple Shortcodes that enable static and no-JS versions of various social media embeds.
+Hugo ships with several [built-in shortcodes](https://gohugo.io/content-management/shortcodes/#use-hugos-built-in-shortcodes) for rich content, along with a [privacy config](https://gohugo.io/about/hugo-and-gdpr/) and a set of _simple shortcodes_ that enable static and no-JS versions of various social media embeds.
 
-## YouTube Privacy Enhanced Shortcode
+## YouTube
+
+Below is an example using the built-in `youtube` shortcode.
 
 {{< youtube ZJthWmvUzzc >}}
 
-<br>
+## Twitter
 
----
+This example uses the `twitter_simple` shortcode to output a Tweet. It requires two named parameters `user` and `id`.
 
-## Twitter Simple Shortcode
+{{< twitter_simple user="DesignReviewed" id="1085870671291310081" >}}
 
-{{< twitter_simple 1085870671291310081 >}}
+Alternatively, the `tweet` shortcode can be used to embed a fully marked up Twitter card.
 
-<br>
+## Gist
 
----
+The `gist` shortcode can be used to embed a GitHub Gist. It requires two unnamed parameters: the username and ID of the Gist.
 
-## Vimeo Simple Shortcode
+{{< gist jpanther a873e1219ffeaa80a926bbe8255f348e >}}
+
+## Vimeo
+
+The `vimeo_simple` shortcode will embed a Vimeo video.
 
 {{< vimeo_simple 48912912 >}}

exampleSite/content/users.md

@@ -4,7 +4,7 @@ date: 2020-08-14
 draft: false
 description: "Some real-life Congo examples."
 slug: "users"
-tags: ["users"]
+tags: ["users", "sample"]
 showDate: false
 showAuthor: false
 showReadingTime: false
@@ -16,9 +16,10 @@ Real websites that are built with Congo.
 {{< /lead >}}
 
 | Website                                        | Details                      |
-| -------------------------------------------- | ---------------------------- |
+| ---------------------------------------------- | ---------------------------- |
 | [jamespanther.com](https://jamespanther.com)   | Personal site - Theme author |
 | [zekeriyaay.com](https://zekeriyaay.com)       | Personal cheat sheets site   |
 | [srisco.dev](https://srisco.dev)               | Personal site                |
+| [theophile-roos.fr](https://theophile-roos.fr) | Personal site                |
 
 **Congo user?** To add your site to this list, [submit a pull request](https://github.com/jpanther/congo/blob/dev/exampleSite/content/users.md).