📝 Add first pass at v2 documentation

README.md

@@ -1,6 +1,6 @@
 # Congo
 
-Congo is designed to be a simple, lightweight theme for [Hugo](https://gohugo.io). It's built using Tailwind CSS with a clean and minimalist design that prioritises to your content.
+Congo is designed to be a powerful, lightweight theme for [Hugo](https://gohugo.io). It's built using Tailwind CSS with a clean and minimalist design that prioritises to your content.
 
 🌏 [Demo site](https://jpanther.github.io/congo/)  
 📑 [Theme documentation](https://jpanther.github.io/congo/docs/)  
@@ -11,7 +11,7 @@ Congo is designed to be a simple, lightweight theme for [Hugo](https://gohugo.io
 
 ## Features
 
-- Fully responsive layout built with Tailwind CSS v3
+- Fully responsive layout built with Tailwind CSS 3.0
 - Multiple colour schemes (or fully customise your own)
 - Dark mode (forced on/off or auto-switching with user toggle)
 - Highly customisable configuration
@@ -19,20 +19,20 @@ Congo is designed to be a simple, lightweight theme for [Hugo](https://gohugo.io
 - Flexible with any content types, taxonomies and menus
 - Multilingual content support inlcuding support for RTL languages
 - Ability to link to posts on third-party websites
+- Client-side site search powered by Fuse.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
+- Automatic image resizing using Hugo Pipes
+- Heading anchors, Tables of Contents, Buttons, Badges and more
 - HTML and Emoji support in articles 🎉
 - SEO friendly with links for sharing to social media
-- RSS feeds
 - Fathom Analytics and Google Analytics support
-- Favicons support
-- Comments support
+- RSS feeds, Favicons and comments support
 - Advanced customisation using simple Tailwind colour definitions and styles
-- Fully documented
-- Regular updates with fixes and new features
+- Optimised for performance and accessibility with perfect Lighthouse scores
+- Fully documented with regular updates
 
 ---
 

exampleSite/content/_index.md

@@ -4,15 +4,17 @@ description: "This is a demo of the Congo theme for Hugo."
 ---
 
 {{< lead >}}
-A simple, lightweight theme for Hugo built with Tailwind CSS.
+A powerful, lightweight theme for Hugo built with Tailwind CSS.
 {{< /lead >}}
 
+This is a demo site built entirely using Congo. It also contains a complete set of [theme documentation]({{< ref "docs" >}}). Congo is flexible and is great for both static page-based content (like this demo) or a traditional blog with a feed of recent posts.
+
 <div class="flex px-4 py-2 mb-8 text-base rounded-md bg-primary-100 dark:bg-primary-900">
   <span class="flex items-center ltr:pr-3 rtl:pl-3 text-primary-400">
     {{< icon "exclamation-triangle" >}}
   </span>
   <span class="flex items-center justify-between grow dark:text-neutral-300">
-    <span class="markdown dark:markdown-invert">This is a demo of the <code id="layout">page</code> layout.</span>
+    <span class="prose dark:prose-invert">This is a demo of the <code id="layout">page</code> layout.</span>
     <button
       class="px-4 !text-neutral !no-underline rounded-md bg-primary-600 hover:!bg-primary-500 dark:bg-primary-800 dark:hover:!bg-primary-700"
       onclick="switchLayout()"
@@ -22,8 +24,6 @@ A simple, lightweight theme for Hugo built with Tailwind CSS.
   </span>
 </div>
 
-This is a demo site built entirely using Congo. It also contains a complete set of [theme documentation]({{< ref "docs" >}}). Congo is flexible and is great for both static page-based content (like this demo) or a traditional blog with a feed of recent posts.
-
 Explore the [sample pages]({{< ref "samples" >}}) to get a feel for what Congo can do. If you like what you see, check out the project on [Github](https://github.com/jpanther/congo) or read the [Installation guide]({{< ref "docs/installation" >}}) to get started.
 
 ![A stylised photograph of a purple squid on a pink backdrop.](squid.jpg "Photo by [Jippe Joosten](https://unsplash.com/@jippe_joosten?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/s/photos/vibrant-purple?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText).")

exampleSite/content/docs/version-2/_index.md

@@ -0,0 +1,92 @@
+---
+title: "What's New in 2.0 ✨"
+date: 2022-01-19
+draft: false
+description: "Discover what's new in Congo version 2.0."
+tags: ["new", "docs"]
+---
+
+{{< lead >}}
+Congo 2.0 is packed with tons of new features and optimisations.
+{{< /lead >}}
+
+The original aim of Congo was to develop a theme that was simple and lightweight. Version 2 takes this one step further and makes the theme even more powerful while still maintaining its lightweight footprint.
+
+Continue reading below to discover what's new. When you're ready to upgrade, check out the [guide to upgrading]({{< ref "upgrade" >}}).
+
+## Tailwind CSS 3.0
+
+Tailwind CSS is at the heart of Congo and this new release contains the very latest [Tailwind CSS version 3](https://tailwindcss.com/blog/tailwindcss-v3). It brings with it performance optimisations and support for some great new CSS features.
+
+{{< youtube "TmWIrBPE6Bc" >}}
+
+Implementing this new version has also removed some Tailwind plugin dependencies from the theme, allowing the overall footprint to remain lightweight.
+
+## Multilingual support
+
+A highly requested feature, Congo is now multilingual! If you publish your content in multiple languages, the site will be built with all the translations available.
+
+<div class="text-2xl text-center" style="font-size: 2.8rem">:flag-au: :de: :fr: :es: :brazil: :cn:</div>
+
+Thanks to submissions from the community, Congo has already been translated into [six languages](https://github.com/jpanther/tree/dev/i18n) with more to be added over time. By the way, pull requests for new languages are always welcome!
+
+## RTL language support
+
+One of the benefits of the new Tailwind and Multilingual features is the ability to add RTL language support. When enabled, the entire site will reflow content from right-to-left. Every element in the theme has been restyled to ensure it looks great in this mode which aids authors who wish to generate content in RTL languages.
+
+RTL is controlled on a per-language basis so you can mix and match both RTL and LTR content in your projects and the theme will respond accordingly.
+
+## Automatic image resizing
+
+A big change in Congo 2.0 is the addition of automatic image resizing. Using the power of Hugo Pipes, images in Markdown content are now automatically scaled to different output sizes. These are then presented using HTML `srcset` attributes enabling optimised file sizes to be served to your site visitors.
+
+![](image-resizing.png)
+
+```html
+<!-- Markdown: ![My image](image.jpg) -->
+<img
+  srcset="
+    /image_320x0_resize_q75_box.jpg 320w,
+    /image_635x0_resize_q75_box.jpg 635w,
+    /image_1024x0_resize_q75_box.jpg 1024w,
+    /image_1270x0_resize_q75_box.jpg 2x"
+  src="/image_635x0_resize_q75_box.jpg"
+  alt="My image"
+/>
+```
+
+Best of all there's nothing you need to change! Simply insert standard Markdown image syntax and let the theme do the rest. If you want a little more control, the `figure` shortcode has been completely rewritten to provide the same resizing benefits.
+
+## Performance improvements
+
+This update packs performance improvements throughout. A key objective for this release was to improve Lighthouse scores and Congo now scores a perfect 100 on all four metrics.
+
+{{< screenshot src="lighthouse.jpg" >}}
+
+There's too many individual changes to highlight them here but the results speak for themselves. If you want to dig deeper, you can [view the Lighthouse report](lighthouse.html). Real world performance will vary based upon server configuration.
+
+## Site search
+
+Powered by [Fuse.js](https://fusejs.io), site search allows visitors to quickly and easily find your content. All searches are performed client-side meaning there's nothing to configure on the server and queries are performed super fast. Simply enable the feature in your site configuration and you're all set. Oh, and it also supports full keyboard navigation!
+
+## Tables of contents
+
+A highly requested feature, Congo now supports tables of contents on article pages. You can see it in action on this page. The contents are fully responsive and will adjust to take advantage of the space available at different screen resolutions.
+
+Available on a global or per article basis, the table of contents can be fully customised using standard Hugo configuration values, allowing you to adjust the behaviour to suit your project.
+
+## Accessibility improvements
+
+From adding ARIA descriptions to more items or simply adjusting the contrast of certain text elements, this release is the most accessible yet.
+
+Version 2 also introduces "skip to content" and "scroll to top" links that enable quick navigation. There's also keyboard shortcuts for enabling items like search without reaching for the mouse.
+
+The new image resizing features also provide full control over `alt` and `title` elements enabling an accessible experience for all visitors.
+
+## A whole lot more
+
+There's countless other minor changes to explore. From being able to display taxonomies on articles and list pages, to using the new `headline` author parameter to customise your homepage. There's also improved JSON-LD strucured data which further optimises SEO performance. Plus the entire theme has had extra polish to ensure a consistent design language.
+
+If you're ready to upgrade, read the [upgrading from version 1 guide]({{< ref "upgrade" >}}) to get started. If you're new to Congo, check out the [Installation guide]({{< ref "docs/installation" >}}) to begin a new project.
+
+---

exampleSite/content/docs/version-2/upgrade/index.md

@@ -0,0 +1,177 @@
+---
+title: "Upgrading from Congo 1.x"
+date: 2022-01-20
+draft: false
+description: "Discover what's new in Congo version 2.0."
+tags: ["new", "docs"]
+---
+
+Although Congo 2.0 contains a large number of changes, the theme has been designed to minimise the effort required to upgrade to the latest release.
+
+That said, there are some changes that require adjustments to existing sites that are built with Congo version 1.x. This guide will step you through the process and highlight things you need to consider.
+
+## Step 1: Upgrade Hugo
+
+{{< alert >}}
+Congo 2.0 requires a minimum of **Hugo v0.87.0 or later**
+{{< /alert >}}
+
+Congo is built to take advantage of some of the latest Hugo features. You should regularly keep your Hugo installation up to date to avoid any issues.
+
+You can check your current version using the command `hugo version`. Visit the [Hugo docs](https://gohugo.io/getting-started/installing/) for information on obtaining a newer release for your platform.
+
+## Step 2: Upgrade Congo
+
+The process for upgrading Congo will depend on how you include the theme in your project. Instructions for each method can be found below.
+
+- [Upgrade using Hugo](#upgrade-using-hugo)
+- [Upgrade using git](#upgrade-using-git)
+- [Upgrade manually](#upgrade-manually)
+
+### Upgrade 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 upgrade 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 upgrade, check to ensure these files are still configured correctly.
+
+Once the theme has been upgraded, continue to the [next section](#step-3-theme-configuration).
+
+### Upgrade using git
+
+Git submodules can be upgraded 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 upgrade --remote --merge
+```
+
+Once the submodule has been upgraded, continue to the [next section](#step-3-theme-configuration).
+
+### Upgrade 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. Continue to the [next section](#step-3-theme-configuration).
+
+## Step 3: Theme configuration
+
+Congo 2.0 introduces a number of new theme configuration parameters. Although the theme will adapt to existing version 1 configurations, in order to take advantage of some of the newer theme features, you will need to adjust your existing configuration.
+
+The simplest way to do this is to take a copy of the theme's default configuration and compare it to your existing files. The process is outlined in greater detail below.
+
+### Languages.toml
+
+In order to provide multilingual support, language-specific theme parameters have been moved to a new config file `languages.[lang-code].toml`. The theme comes with a template `languages.en.toml` file which can be used as a guide.
+
+{{< alert >}}
+This step is optional if you do not need multilingual support, although completing it now will make future theme upgrades easier.
+{{< /alert >}}
+
+The languages config file follows this structure:
+
+```toml
+# config/_default/languagues.en.toml
+
+languageCode = "en"
+languageName = "English"
+displayName = "EN"
+htmlCode = "en"
+weight = 1
+rtl = false
+
+# Language-specific parameters go here
+```
+
+Using your preferred language, simply create this new file in `config/_default/` and then move the language-specific parameters from any existing config files over to this new file. The table below outlines the parameters that need to be moved.
+
+| Parameter     | Old location  |
+| ------------- | ------------- |
+| `title`       | `config.toml` |
+| `description` | `params.toml` |
+| `copyright`   | `config.toml` |
+| `dateFormat`  | `params.toml` |
+| `[author]`    | `config.toml` |
+
+Once the values have been moved to the new location, these parameters should be deleted from their original locations.
+
+### Config.toml
+
+The `config.toml` file now only contains base Hugo configuration values. Other than removing the language-specific strings above, there are only two changes to consider.
+
+If you're using a language other than English, provide a `defaultContentLanguage` value that matches the language code in the config file you created for your language. Secondly, to take advange of the new site search in Congo 2.0, an `[outputs]` block needs to be provided.
+
+```toml
+# config/_default/config.toml
+
+defaultContentLanguage = "en"
+[outputs]
+  home = ["HTML", "RSS", "JSON"]
+```
+
+### Markup.toml
+
+Congo 2.0 adds support for tables of contents on article pages. Although Hugo ships with default settings for generating contents listings, you can adjust this behaviour by adding a new `[tableOfContents]` block to your `markup.toml` file.
+
+The recommended settings are as follows, which includes any headings in the Markdown content at levels 2, 3 and 4:
+
+```toml
+# config/_default/markup.toml
+
+[tableOfContents]
+  startLevel = 2
+  endLevel = 4
+```
+
+### Params.toml
+
+A number of new theme parameters have been introduced in Congo 2.0. Some minor changes are requried to existing configurations. Remember, the theme will always revert to a sensible default if a parameter is not provided.
+
+The follow parameters have been **renamed**:
+
+`darkToggle` **&rarr;** `showDarkToggle`
+
+The following table outlines some key **new parameters** that control new features in version 2:
+
+| New parameter                 | Type    | Default |
+| ----------------------------- | ------- | ------- |
+| `enableSearch`                | Boolean | `false` |
+| `showScrollToTop`             | Boolean | `true`  |
+| `article.showTaxonomies`      | Boolean | `false` |
+| `article.showTableOfContents` | Boolean | `false` |
+| `list.showTableOfContents`    | Boolean | `false` |
+
+For the full list of supported parameters, refer to the [Configuration]({{< ref "docs/configuration" >}}) docs.
+
+## Step 4: Move assets
+
+All site assets now use Hugo Pipes to build an optimised version of your project. In order for the theme to locate your files, any previously static assets used in the theme need to be moved to the Hugo assets folder.
+
+`static/me.jpg` **&rarr;** `assets/me.jpg`  
+`static/logo.jpg` **&rarr;** `assets/logo.jpg`
+
+If you have provided an author image or site logo, simply move these assets from the `static/` folder to the `assets/` folder. If you use the same directory structure the theme will know where to find these files automatically. If you would like to provide a new path, update the `logo` and `author.image` config values accordingly.
+
+## Step 5: Check content
+
+The behavior of the `figure` shortcode is different in version 2. If you are using `figure` in your content, you may need to adjust the parameters you are providing. Consult the shortcode docs to learn more about supported parameters.
+
+## Step 6: Rebuild
+
+Now that all the configuration changes are complete, it's time to rebuild the site. Run `hugo`, or your build command, and check that everything works as expected.
+
+If you come across any errors, check the configuration is correct and refer to the [full documentation]({{< ref "docs" >}}) for further guidance. Remember, the example config files bundled with the theme contain all the default parameters and are a great starting point.
+
+🙋‍♀️ If you still need help, feel free to ask your question on [GitHub Discussions](https://github.com/jpanther/congo/discussions).