Update 2023

In Summer 2023 this theme was updated to match version 5.18.0 of the base Hugo Relearn Theme

New Features

A full list of changes to the theme can be found on the What’s New page and in the Documentation.

Some notable feature updates:

• New Shortcode - Badge
• New Shortcode - Icon
• New Shortcode - Tab
• New Shortcode - Highlight
• The theme now includes warnings for deprecated and unsupported features
• Many shortcodes now color and icon configurable
• Supports task lists, definition lists, and footnotes using GHFM
• Search updates and a dedicated search page
• Automatically detect theme variant based on OS
• Swagger renamed to OpenAPI and now uses SwaggerUI instead of RapiDoc
• Absolute links now open in separate browser tab, configurable (this was previously handled by a custom HTML renderer that is no longer used)
• Supports Hugo up to version 0.114.0
• Supports the VSCode Front Matter extension (admittedly I have not tried this yet)
• JQuery completely removed from template

Upgrading

To upgrade to the new theme version, do the following:

1. Navigate to the themes/hugo-theme-relearn directory
2. Use git pull to pull the latest version of the theme
3. Navigate back to the root directory of your site.
4. Commit and push the site. It should see a new version of the themes/hugo-theme-relearn submodule.

Enable Search

To enable the new search features, update the [outputs] section of the config.toml (and other files like docker.toml and github.toml if present) to the following:

[outputs]
  home = ["HTML", "RSS", "PRINT", "SEARCH", "SEARCHPAGE"]
  section = ["HTML", "RSS", "PRINT", "TELE", "EMBED"]
  page = ["HTML", "RSS", "PRINT", "TELE", "EMBED"]

Enable Auto Theme Variants

To enable automatically detecting theme variants based on the user’s OS preferences, find the themeVariant item under [params] in the config.toml (and other files like docker.toml and github.toml if present) and replace that line with the following:

  themeVariant = ["auto", "light-theme", "dark-theme"]
  # The first element is the variant for light mode, the second for dark mode
  themeVariantAuto = ["light-theme", "dark-theme"]

Deprecated Chapter Features

Many of the previous textbooks use the old method for creating chapters by placing chapter = true in the frontmatter. This has been deprecated in favor of using the new archetype = "chapter" setting. See the documentation for details.

Unfortunately, the way that the new archetype system assigns chapter numbers is using the weight parameter. Many of our books use non-sequential weights to make it simpler to add pages later. This theme adds support for an ordinal value in the frontmatter to allow overriding this value.

To get rid of the deprecation warnings, find all pages that contain chapter = true and make the following updates:

1. Replace chapter = true with archetype = "chapter" in the page’s frontmatter
2. Remove the top-level headers. Typically these pages would include an h1 and h3 header. These are now generated by the archetype.
3. OPTIONAL: Add an ordinal = "X" line to the frontmatter, and replace the X with the chapter number.

For example, a chapter with the following content:

+++
title = "Basic Content"
weight = 5
chapter = true
pre = "<b>0. </b>"
+++

### Chapter 0

# Basic Content

The Basics of this Template

should be updated to match this format:

+++
title = "Basic Content"
weight = 5
ordinal = "0"
archetype = "chapter"
pre = "<b>0. </b>"
+++

The Basics of this Template