nishiki/hugo-theme-relearn
1
0
Fork 0
mirror of https://github.com/McShelby/hugo-theme-relearn.git synced 2024-11-22 15:27:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: chapter 3 content-complete #567

Browse source 
add other stuff
This commit is contained in:
Sören Weber 2024-10-12 18:37:59 +02:00
parent dcaeb13860
commit e4e750c1cc
No known key found for this signature in database
GPG key ID: BEC6D55545451B6D
97 changed files with 816 additions and 662 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
README.md
View file

@ -14,24 +14,24 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
- **Versatile Usage**
- [Responsive design for mobile devices](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/width)
- [Looks nice on paper - if it has to](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/outputformats)
- Usable offline with no external dependencies
- [Usable from your local file system without a web server via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/deployment)
- Integration with the [VSCode Front Matter CMS extension](https://github.com/estruyf/vscode-front-matter) for on-premise CMS capabilities
- [Looks nice on paper](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/outputformats) - if it has to
- [Usable offline with no external dependencies](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/deployment#offline-usage)
- [Usable from your local file system without a web server](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/deployment#file-system) via `file://` protocol
- [Integration with the VSCode Front Matter CMS extension](https://mcshelby.github.io/hugo-theme-relearn/introduction/tools#front-matter-cms) for on-premise CMS capabilities
- **Customizable Appearance**
- [Flexible brand image configuration](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding#change-the-logo)
- [Automatic light/dark mode switching based on OS settings](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding#adjust-to-os-settings)
- Pre-defined color variants
- [User-selectable variants](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding#multiple-variants)
- [Built-in stylesheet generator](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/generator)
- [Customizable syntax highlighting](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding/#change-syntax-highlighting)
- [Flexible brand image configuration](https://mcshelby.github.io/hugo-theme-relearn/configuration/branding/logo#change-the-logo)
- [Automatic light/dark mode switching based on OS settings](https://mcshelby.github.io/hugo-theme-relearn/configuration/branding/colors#adjust-to-os-settings)
- Many pre-defined color variants
- [User-selectable variants](https://mcshelby.github.io/hugo-theme-relearn/configuration/branding/colors#multiple-variants)
- [Built-in stylesheet generator](https://mcshelby.github.io/hugo-theme-relearn/configuration/branding/generator)
- [Customizable syntax highlighting](https://mcshelby.github.io/hugo-theme-relearn/configuration/branding/modules/#change-syntax-highlighting)
- **Advanced Functionality**
- [Chapter and site-wide printing capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/topbar#print-support)
- [Chapter and site-wide printing capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/outputformats#print-support)
- [Versatile search options: in-page, popup, and dedicated search page](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/search)
- [Customizable top bar buttons](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/topbar)
- [Nested navigation menu](https://mcshelby.github.io/hugo-theme-relearn/authoring/structure)
- [Nested navigation menu](https://mcshelby.github.io/hugo-theme-relearn/authoring/frontmatter/navigationmenu)
- [Configurable menu shortcuts](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/shortcutmenu)
- [Support for hidden pages](https://mcshelby.github.io/hugo-theme-relearn/configuration/content/hidden)
- [Comprehensive taxonomy support](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/taxonomy)
@ -43,7 +43,7 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
- [Multilingual content search capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/search#mixed-language-support)
- **Enhanced Markdown Features**
- [GitHub Flavored Markdown (GFM) support](https://mcshelby.github.io/hugo-theme-relearn/authoring/markdown)
- [CommonMark and other Markdown extensions](https://mcshelby.github.io/hugo-theme-relearn/authoring/markdown#standard-and-extensions)
- [Support for Obsidian callouts](https://mcshelby.github.io/hugo-theme-relearn/authoring/markdown#obsidian-callouts)
- [Advanced image manipulation like lightbox, sizing, shadows, borders, and alignment](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/imageeffects)

86
exampleSite/config/_default/hugo.toml
View file

@ -1,7 +1,7 @@
# this is a required setting for this theme to appear on https://themes.gohugo.io/
# change this to a value appropriate for you; if your site is served from a subdirectory
# set it like "https://example.com/mysite/"
baseURL = "https://example.com/"
# set it like 'https://example.com/mysite/'
baseURL = 'https://example.com/'
# required value to serve this page from a webserver AND the file system;
# if you don't want to serve your page from the file system, you can also set this value
@ -14,19 +14,19 @@ uglyURLs = false # true -> basic/index.html -> basic.html
# the directory where Hugo reads the themes from; this is specific to your
# installation and most certainly needs be deleted or changed
themesdir = "../.."
themesdir = '../..'
# yeah, well, obviously a mandatory setting for your site, if you want to
# use this theme ;-)
theme = "hugo-theme-relearn"
theme = 'hugo-theme-relearn'
# make sure your defaultContentLanguage is the first one in the [languages]
# array below, as the theme needs to make assumptions on it
defaultContentLanguage = "en"
defaultContentLanguage = 'en'
# if you want to get rrrid o' ourrr pirrrates nonsense uncomment th' next line
# disableLanguages = ['pir']
# the site's title of this showcase; you should change this ;-)
title = "Hugo Relearn Theme"
title = 'Hugo Relearn Theme'
# Don't use any auto-generated summaries
summaryLength = 10
@ -34,9 +34,9 @@ summaryLength = 10
[outputs]
# add `print` to home, section and page to activate the feature to print whole
# chapters
home = ["html", "rss", "print"]
section = ["html", "rss", "print"]
page = ["html", "rss", "print"]
home = ['html', 'rss', 'print']
section = ['html', 'rss', 'print']
page = ['html', 'rss', 'print']
[markup]
[markup.highlight]
@ -54,7 +54,7 @@ summaryLength = 10
# stylesheet will be ignored and the internal style is used for all variants and
# even print
noClasses = false
# style = "tango"
# style = 'tango'
[markup.goldmark]
# this is required for the themes exampleSite to make the piratify shortcode work
@ -95,40 +95,40 @@ summaryLength = 10
# your project
[languages]
[languages.en]
title = "Hugo Relearn Theme"
title = 'Hugo Relearn Theme'
weight = 1
languageCode = "en"
languageName = "English"
languageCode = 'en'
languageName = 'English'
# Language dependent settings:
# Use case https://gohugo.io/content-management/multilingual/#translation-by-content-directory
#contentDir = "content/en"
#contentDir = 'content/en'
[languages.en.params]
landingPageName = "<i class='fa-fw fas fa-home'></i> Home"
landingPageName = '<i class="fa-fw fas fa-home"></i> Home'
[[languages.en.menu.shortcuts]]
name = "<i class='fa-fw fab fa-github'></i> GitHub Repo"
identifier = "ds"
url = "https://github.com/McShelby/hugo-theme-relearn"
name = '<i class="fa-fw fab fa-github"></i> GitHub Repo'
identifier = 'ds'
url = 'https://github.com/McShelby/hugo-theme-relearn'
weight = 10
[[languages.en.menu.shortcuts]]
name = "<i class='fa-fw fas fa-camera'></i> Showcases"
pageRef = "/showcase"
name = '<i class="fa-fw fas fa-camera"></i> Showcases'
pageRef = '/showcase'
weight = 20
[[languages.en.menu.shortcuts]]
name = "<i class='fa-fw fas fa-bullhorn'></i> Credits"
pageRef = "/more/credits"
name = '<i class="fa-fw fas fa-bullhorn"></i> Credits'
pageRef = '/more/credits'
weight = 30
[[languages.en.menu.shortcuts]]
name = "<i class='fa-fw fas fa-tags'></i> Tags"
pageRef = "/tags"
name = '<i class="fa-fw fas fa-tags"></i> Tags'
pageRef = '/tags'
weight = 40
[[languages.en.menu.shortcuts]]
name = "<i class='fa-fw fas fa-layer-group'></i> Categories"
pageRef = "/categories"
name = '<i class="fa-fw fas fa-layer-group"></i> Categories'
pageRef = '/categories'
weight = 50
# this is ourrr way t' showcase th' multilang settings by
@ -142,39 +142,39 @@ summaryLength = 10
weight = 2
# It would be more standard compliant to have the language key also
# named art-x-pir but that would require to rename all files
languageCode = "art-x-pir"
languageDirection = "rtl"
languageName = "Arrr! ☠ Pirrratish ☠"
languageCode = 'art-x-pir'
languageDirection = 'rtl'
languageName = 'Arrr! ☠ Pirrratish ☠'
# Language dependent settings:
# Use case https://gohugo.io/content-management/multilingual/#translation-by-content-directory
#contentDir = "content/pir"
#contentDir = 'content/pir'
[languages.pir.params]
landingPageName = "<i class='fa-fw fas home'></i> Arrr! Home"
landingPageName = '<i class="fa-fw fas home"></i> Arrr! Home'
[[languages.pir.menu.shortcuts]]
name = "<i class='fa-fw fab fa-github'></i> GitHub Repo"
identifier = "ds"
url = "https://github.com/McShelby/hugo-theme-relearn"
name = '<i class="fa-fw fab fa-github"></i> GitHub Repo'
identifier = 'ds'
url = 'https://github.com/McShelby/hugo-theme-relearn'
weight = 10
[[languages.pir.menu.shortcuts]]
name = "<i class='fa-fw fas fa-camera'></i> Showcases"
pageRef = "/showcase"
name = '<i class="fa-fw fas fa-camera"></i> Showcases'
pageRef = '/showcase'
weight = 20
[[languages.pir.menu.shortcuts]]
name = "<i class='fa-fw fas fa-bullhorn'></i> Crrredits"
pageRef = "/more/credits"
name = '<i class="fa-fw fas fa-bullhorn"></i> Crrredits'
pageRef = '/more/credits'
weight = 30
[[languages.pir.menu.shortcuts]]
name = "<i class='fa-fw fas fa-tags'></i> Arrr! Tags"
pageRef = "/tags"
name = '<i class="fa-fw fas fa-tags"></i> Arrr! Tags'
pageRef = '/tags'
weight = 40
[[languages.pir.menu.shortcuts]]
name = "<i class='fa-fw fas fa-layer-group'></i> Categorrries"
pageRef = "/categories"
name = '<i class="fa-fw fas fa-layer-group"></i> Categorrries'
pageRef = '/categories'
weight = 50
# mounts are only needed in this showcase to access the publicly available screenshots and CHANGELOG;
@ -239,6 +239,6 @@ summaryLength = 10
[params]
# Demo setting for displaying the siteparam shortcode the docs.
siteparam.test.text = "A **nested** option <b>with</b> formatting"
siteparam.test.text = 'A **nested** option <b>with</b> formatting'
# Extension to the image effects only for the docs.
imageEffects.bg-white = true

129
exampleSite/config/_default/params.toml
View file

@ -9,28 +9,28 @@
# Default: not set
# This name will be used for the link to the main page in the upper section
# of the menu. If not set, `title` from the Hugo settings will be used.
linkTitle = "Relearn"
linkTitle = 'Relearn'
# The author of your site.
# Default: not set
# This will be used in HTML meta tags, the opengraph protocol and twitter
# cards.
# You can also set `author.email` if you want to publish this information.
author.name = "Sören Weber"
author.name = 'Sören Weber'
# The social media image of your site.
# Default: not set
# This is used for generating social media meta information for the opengraph
# protocol and twitter cards.
# This can be overridden in the page's frontmatter.
images = [ "images/hero.png" ]
images = [ 'images/hero.png' ]
# Admin options for social media.
# Default: not set
# Configuration for the Open Graph protocol and Twitter Cards adhere to Hugo's
# implementation. See the Hugo docs for possible values.
social.facebook_admin = ""
social.twitter = ""
social.facebook_admin = ''
social.twitter = ''
###############################################################################
# Relearn Theme
@ -41,38 +41,38 @@ social.twitter = ""
# These options set your overall visual appearance.
# Used color variants.
# Default: "auto"
# Default: 'auto'
# This sets one or more color variants, available to your readers to choose
# from. You can
# - set a single value eg. "zen-light"
# - an array like [ "neon", "learn" ]
# - an array with options like [ { identifier = "neon" },{ identifier = "learn" } ]
# - set a single value eg. 'zen-light'
# - an array like [ 'neon', 'learn' ]
# - an array with options like [ { identifier = 'neon' },{ identifier = 'learn' } ]
# The last form allows to set further options for each variant.
# The `identifier` is mandatory. You can also set `name` which overrides the
# value displayed in the variant selector.
# If the array has more than one entry, a variant selector
# is shown in the lower part of the menu. The first entry in the array is the
# default variant, used for first time visitors.
# The theme ships with the following variants: "relearn-bright",
# "relearn-light", "relearn-dark", "zen-light", "zen-dark", "neon", "learn",
# "blue", "green", "red". In addition you can use auto mode variants. See the
# The theme ships with the following variants: 'relearn-bright',
# 'relearn-light', 'relearn-dark', 'zen-light', 'zen-dark', 'neon', 'learn',
# 'blue', 'green', 'red'. In addition you can use auto mode variants. See the
# docs for a detailed explanation.
# You can also define your own variants. See the docs how this works. Also,
# the docs provide an interactive theme generator to help you with this task.
themeVariant = [
{ identifier = "relearn-auto", name = "Relearn Light/Dark", auto = [] },
{ identifier = "relearn-light" },
{ identifier = "relearn-dark" },
{ identifier = "relearn-bright" },
{ identifier = "zen-auto", name = "Zen Light/Dark", auto = [ "zen-light", "zen-dark" ] },
{ identifier = "zen-light" },
{ identifier = "zen-dark" },
{ identifier = "retro-auto", name = "Retro Learn/Neon", auto = [ "learn", "neon" ] },
{ identifier = "neon" },
{ identifier = "learn" },
{ identifier = "blue" },
{ identifier = "green" },
{ identifier = "red" }
{ identifier = 'relearn-auto', name = 'Relearn Light/Dark', auto = [] },
{ identifier = 'relearn-light' },
{ identifier = 'relearn-dark' },
{ identifier = 'relearn-bright' },
{ identifier = 'zen-auto', name = 'Zen Light/Dark', auto = [ 'zen-light', 'zen-dark' ] },
{ identifier = 'zen-light' },
{ identifier = 'zen-dark' },
{ identifier = 'retro-auto', name = 'Retro Learn/Neon', auto = [ 'learn', 'neon' ] },
{ identifier = 'neon' },
{ identifier = 'learn' },
{ identifier = 'blue' },
{ identifier = 'green' },
{ identifier = 'red' }
]
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@ -143,7 +143,7 @@ disableNextPrev = false
# `${FilePath}` was appended at the end of the value. This can be overridden
# in the pages frontmatter. This is useful if you want to give the opportunity
# for people to create merge request for your content.
editURL = "https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/${FilePath}"
editURL = 'https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/${FilePath}'
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Search
@ -164,10 +164,10 @@ disableSearch = false
disableSearchIndex = false
# URL of the search index file relative to the language home.
# Default: "searchindex.js"
# Default: 'searchindex.js'
# You have to set this option if your page already has a content file named
# `searchindex.js` in the language home.
searchIndexURL = "searchindex.js"
searchIndexURL = 'searchindex.js'
# Disable the dedicated search page.
# Default: false
@ -176,12 +176,12 @@ searchIndexURL = "searchindex.js"
disableSearchPage = false
# URL of the dedicated search page relative to the language home.
# Default: "search"
# Default: 'search'
# In its basic form the search page URL is named the same for all languages
# but you are free to override it in each language options to localised the
# URL. You also need to set this option if your page already has a content
# page named `search`.
searchPageURL = "search"
searchPageURL = 'search'
# Multilanguage content.
# Default: not set
@ -190,7 +190,7 @@ searchPageURL = "search"
# will create a search index with support for all used languages of your site.
# This is handy for example if you are writing in Spanish but have lots of
# source code on your page which typically uses English terminology.
additionalContentLanguage = [ "en" ]
additionalContentLanguage = [ 'en' ]
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Menu
@ -203,11 +203,11 @@ additionalContentLanguage = [ "en" ]
disableLandingPageButton = true
# The order of main menu submenus.
# Default: "weight"
# Submenus can be ordered by "weight", "title", "linktitle", "modifieddate",
# "expirydate", "publishdate", "date", "length" or "default" (adhering to
# Default: 'weight'
# Submenus can be ordered by 'weight', 'title', 'linktitle', 'modifieddate',
# 'expirydate', 'publishdate', 'date', 'length' or 'default' (adhering to
# Hugo's default sort order). This can be overridden in the pages frontmatter.
ordersectionsby = "weight"
ordersectionsby = 'weight'
# The initial expand state of submenus.
# Default: not set
@ -216,7 +216,7 @@ ordersectionsby = "weight"
# levels are set to true. This can be overridden in the page's frontmatter.
# If the displayed page has submenus, they will always been displayed expanded
# regardless of this option.
alwaysopen = ""
alwaysopen = ''
# Shows expander for submenus.
# Default: false
@ -277,16 +277,16 @@ disableTagHiddenPages = false
# These options modify how your content is displayed.
# Title separator.
# Default: "::"
# Default: '::'
# Changes the title separator used when concatenating the page title with the
# site title. This is consistently used throughout the theme.
titleSeparator = "::"
titleSeparator = '::'
# Breadcrumb separator.
# Default: ">"
# Default: '>'
# Changes the breadcrumb separator used in the topbars breadcrumb area and for
# search results and term pages.
breadcrumbSeparator = ">"
breadcrumbSeparator = '>'
# Hide the root breadcrumb.
# Default: false
@ -325,7 +325,7 @@ disableAnchorScrolling = false
# that key. The `title` may be empty in which case, the box does not contain a
# default title. `icon` and `color` are working similar.
boxStyle = [
{ identifier = "magic", i18n = "", title = "Magic", icon = "rainbow", color = "gold" }
{ identifier = 'magic', i18n = '', title = 'Magic', icon = 'rainbow', color = 'gold' }
]
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@ -359,21 +359,21 @@ highlightWrap = true
# These options configure how the include shortcode works.
# What to do when path is not resolved.
# Default: ""
# Default: ''
# You can control what should happen if a path can not be resolved to as
# a resource or via the file system. If not set, no output will be written
# for the unresolved path. If set to `warning` the same happens and an additional
# warning is printed. If set to `error` an error message is printed and the build
# is aborted.
# This can be overridden in the page's frontmatter.
include.errorlevel = "error"
include.errorlevel = 'error'
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Images
# These options configure how images are displayed.
# What to do when local image link is not resolved.
# Default: ""
# Default: ''
# You can control what should happen if a local image can not be resolved to as
# a resource. If not set, the unresolved link is written as given into the resulting
# output. If set to `warning` the same happens and an additional warning is
@ -381,7 +381,7 @@ include.errorlevel = "error"
# aborted.
# Please note that this can not resolve files inside of your `static` directory.
# This can be overridden in the page's frontmatter.
image.errorlevel = "error"
image.errorlevel = 'error'
# Image effects.
# See the documentation for how you can even add your own arbitrary effects to
@ -412,8 +412,15 @@ imageEffects.shadow = false
# See discussion in https://github.com/McShelby/hugo-theme-relearn/discussions/862
disableDefaultRelref = false
# Generate link URLs the Hugo way.
# Default: false
# If set to true, the theme behaves like a standard Hugo installation and
# appends no index.html to prettyURLs. As a trade off, your build project will
# not be servable from the file system.
disableExplicitIndexURLs = false
# What to do when local page link is not resolved.
# Default: ""
# Default: ''
# You can control what should happen if a local link can not be resolved to a
# page. If not set, the unresolved link is written as given into the resulting
# output. If set to `warning` the same happens and an additional warning is
@ -422,22 +429,16 @@ disableDefaultRelref = false
# Please note that with Hugo < 0.123.0 + `uglyURLs=true` this can lead to false
# negatives.
# This can be overridden in the page's frontmatter.
link.errorlevel = "error"
link.errorlevel = 'error'
# How to open external links.
# Default: "_blank"
# Default: '_blank'
# For external links you can define how they are opened in your browser. All
# values for the HTML `target` attribute of the `a` element are allowed. The
# default value opens external links in a separate browser tab. If you want
# to open those links in the same tab, use "_self".
externalLinkTarget = "_self"
# Generate link URLs the Hugo way.
# Default: false
# If set to true, the theme behaves like a standard Hugo installation and
# appends no index.html to prettyURLs. As a trade off, your build project will
# not be servable from the file system.
disableExplicitIndexURLs = false
# to open those links in the same tab, use '_self'.
# This can be overridden in the page's frontmatter.
externalLinkTarget = '_self'
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# MathJax
@ -447,7 +448,7 @@ disableExplicitIndexURLs = false
# Default: not set
# A JSON value. See the MathJaxdocumentation for possible parameter.
# This can be overridden in the page's frontmatter.
mathJaxInitialize = "{}"
mathJaxInitialize = '{}'
# Force load Math on every page.
# Default: false
@ -465,7 +466,7 @@ math = false
# Specifies the remote location of the MathJax library. By default the shipped
# version will be used.
# This can be overridden in the page's frontmatter.
customMathJaxURL = "" # "https://unpkg.com/mathjax/es5/tex-mml-chtml.js"
customMathJaxURL = '' # 'https://unpkg.com/mathjax/es5/tex-mml-chtml.js'
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Mermaid
@ -483,7 +484,7 @@ mermaidZoom = true
# Default: not set
# A JSON value. See the Mermaid documentation for possible parameter.
# This can be overridden in the page's frontmatter.
mermaidInitialize = "{ \"securityLevel\": \"loose\" }"
mermaidInitialize = '{ "securityLevel": "loose" }'
# Force load Mermaid on every page.
# Default: false
@ -500,7 +501,7 @@ mermaid.force = false
# Specifies the remote location of the Mermaid library. By default the shipped
# version will be used.
# This can be overridden in the page's frontmatter.
customMermaidURL = "" # "https://unpkg.com/mermaid/dist/mermaid.min.js"
customMermaidURL = '' # 'https://unpkg.com/mermaid/dist/mermaid.min.js'
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# OpenApi
@ -521,10 +522,10 @@ oppenapi.force = false
# Specifies the remote location of the OpenAPI library. By default the shipped
# version will be used.
# This can be overridden in the page's frontmatter.
customOpenapiURL = "" # "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
customOpenapiURL = '' # 'https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js'
# What to do when a local OpenAPI spec link is not resolved.
# Default: ""
# Default: ''
# You can control what should happen if a local OpenAPI spec link can not be resolved
# to a resource. If not set, the unresolved link is written as given into the resulting
# output. If set to `warning` the same happens and an additional warning is
@ -532,4 +533,4 @@ customOpenapiURL = "" # "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
# aborted.
# Please note that this can not resolve files inside of your `static` directory.
# This can be overridden in the page's frontmatter.
openapi.errorlevel = "error"
openapi.errorlevel = 'error'

2
exampleSite/config/github/hugo.toml
View file

@ -1,2 +1,2 @@
baseURL = "https://mcshelby.github.io/hugo-theme-relearn/"
baseURL = 'https://mcshelby.github.io/hugo-theme-relearn/'
relativeURLs = false

2
exampleSite/content/authoring/frontmatter/designs/_index.en.md
View file

@ -1,7 +1,7 @@
+++
description = "How to vary layouts by using page designs"
title = "Page Designs"
weight = 3
weight = 1
+++
A page is displayed by exactly one page design and represented by [Hugo's reserved `type` front matter](https://gohugo.io/content-management/front-matter/#type).

2
exampleSite/content/authoring/frontmatter/designs/_index.pir.md
View file

@ -1,6 +1,6 @@
+++
description = "How to vary layouts by using page designs"
title = "Page Designs"
weight = 3
weight = 1
+++
{{< piratify >}}

32
exampleSite/content/authoring/frontmatter/linking/index.en.md Normal file
View file

@ -0,0 +1,32 @@
+++
description = "What options are available for links and images"
frontmatter = ["externalLinkTarget", "image.errorlevel", "link.errorlevel"]
options = ["externalLinkTarget", "image.errorlevel", "link.errorlevel"]
title = "Linking"
weight = 3
+++
## Opening Links
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} By default, external links open in a new tab. To change this, use the `externalLinkTarget` setting with a proper [link target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).
For example, this will open links in the same tab
{{< multiconfig fm=true >}}
externalLinkTarget = '_self'
{{< /multiconfig >}}
## Enabling Link and Image Link Warnings
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can use `link.errorlevel` and `image.errorlevel` to control what should happen if a local link can not be resolved to a resource.
If not set or empty, any unresolved link is written as given into the resulting output. If set to `warning` the same happens and an additional warning is printed in the built console. If set to `error` an error message is printed and the build is aborted.
Please note that this can not resolve files inside of your `static` directory. The file must be a resource of the page or the site.
Link warnings are also available for the [include](shortcodes/include#enabling-link-warnings) and [openapi](shortcodes/openapi#enabling-link-warnings) shortcodes.
{{< multiconfig fm=true >}}
link.errorlevel = 'warning'
image.errorlevel = 'warning'
{{< /multiconfig >}}

8
exampleSite/content/authoring/frontmatter/linking/index.pir.md Normal file
View file

@ -0,0 +1,8 @@
+++
description = "What options are available for links and images"
frontmatter = ["externalLinkTarget", "image.errorlevel", "link.errorlevel"]
options = ["externalLinkTarget", "image.errorlevel", "link.errorlevel"]
title = "Linking"
weight = 3
+++
{{< piratify >}}

7
exampleSite/content/authoring/frontmatter/meta/_index.en.md
View file

@ -1,7 +0,0 @@
+++
description = "What page meta information can be set"
title = "Meta Information"
weight = 1
+++
The theme adds social media meta tags including feature images for the [Open Graph](https://gohugo.io/templates/internal/#open-graph) protocol and [Twitter Cards](https://gohugo.io/templates/internal/#twitter-cards) to your site. These are configured as mentioned in the linked Hugo docs.

6
exampleSite/content/authoring/frontmatter/meta/_index.pir.md
View file

@ -1,6 +0,0 @@
+++
description = "What page meta information can be set"
title = "Meta Information"
weight = 1
+++
{{< piratify >}}

119
exampleSite/content/authoring/frontmatter/navigationmenu/_index.en.md
View file

@ -1,61 +1,22 @@
+++
description = "Per page behavior of the navigation menu"
description = "Behavior of the navigation menu"
frontmatter = ["alwaysopen", "collapsibleMenu", "linkTitle", "menuPost", "menuPre", "ordersectionsby"]
options = ["alwaysopen", "collapsibleMenu", "ordersectionsby"]
title = "Navigation Menu"
weight = 2
+++
## Custom Title for Menu Entries
The navigation menu is automatically created from [your content files](authoring/structure).
By default, the Relearn theme will use a page's `title` front matter for the menu entry.
But a page's title has to be descriptive on its own while the menu is a hierarchy. Use `linkTitle` to shorten the text of the menu entry.
For example (for a page named `install/linux.md`):
{{< multiconfig fm=true >}}
title = "Install on Linux"
linkTitle = "Linux"
{{< /multiconfig >}}
## Add Icon to a Menu Entry
In the page front matter, add a `menuPre` to insert any HTML code before the menu label. You can also set `menuPost` to insert HTML code after the menu label.
The example below uses the GitHub icon.
{{< multiconfig fm=true >}}
title = "GitHub Repo"
menuPre = "<i class='fab fa-github'></i> "
{{< /multiconfig >}}
![Title with icon](frontmatter-icon.png?width=18.75rem)
## Ordering Sibling Menu Entries
### By Weight
Hugo provides a [simple way](https://gohugo.io/getting-started/glossary/#weight) to handle order for your pages by setting the `weight` front matter to a number.
{{< multiconfig fm=true >}}
title = "My page"
weight = 5
{{< /multiconfig >}}
### Other
Using the `weight` for sorting can get cumbersome if you, for example, just want to sort alphabetically. Each time you add a new page in the set of pages, you may have to renumber some or all of them to make space for the new page.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Use `ordersectionsby` to choose how navigation menus are sorted. The default is `weight`. You can sort by `weight`, `title`, `linktitle`, `modifieddate`, `expirydate`, `publishdate`, `date`, `length`, or `default` (Hugo's standard order).
{{< multiconfig fm=true >}}
ordersectionsby = 'linktitle'
{{< /multiconfig >}}
All configurations options apply to all pages but can be changed in each page's front matter.
## Expand State of Nested Sections
You can change how the theme submenus appear with `alwaysopen` on a per page basis. If `alwaysopen=false` for any given entry, its children will not be shown in the menu as long as it is not necessary for the sake of navigation.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can change how the theme submenus appear with `alwaysopen`.
The theme generates the menu based on the following rules:
If `alwaysopen=false` for any given entry, its children will not be shown in the menu as long as it is not necessary for the sake of navigation.
The theme generates the expand state based on the following rules:
- all parent entries of the active page including their visible siblings are shown regardless of any settings
- immediate child entries of the active page are shown regardless of any settings
@ -64,7 +25,65 @@ The theme generates the menu based on the following rules:
- all visible entries show their immediate child entries if `alwaysopen=true`; this proceeds recursively
- all remaining entries are not shown
You can see this feature in action on the example page for [children shortcode](shortcodes/children) and its child pages.
## Expander for Nested Sections
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Set `collapsibleMenu=true` to add an expander for submenus. This shows submenus as collapsible trees with a clickable expander.
{{< multiconfig fm=true >}}
collapsibleMenu = true
{{< /multiconfig >}}
> [!WARNING]
> Using this option may slow down your build process, especially with many pages.
>
> We've seen builds taking 2 minutes with 1000+ pages, and over 30 minutes with 5000+ pages.
>
> This happens because each new page affects all other pages, leading to exponentially longer build times.
## Ordering Sibling Menu Entries
### By Weight
Hugo provides a [simple way](https://gohugo.io/getting-started/glossary/#weight) to handle order for your pages by setting the `weight` front matter to a number.
{{< multiconfig fm=true >}}
title = 'My page'
weight = 5
{{< /multiconfig >}}
### Other
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Using the `weight` for sorting can get cumbersome if you, for example, just want to sort alphabetically. Each time you add a new page in the set of pages, you may have to renumber some or all of them to make space for the new page.
{{< multiconfig fm=true >}}
ordersectionsby = 'linktitle'
{{< /multiconfig >}}
## Custom Title for Menu Entries
By default, the Relearn theme will use a page's `title` front matter for the menu entry.
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} But a page's title has to be descriptive on its own while the menu is a hierarchy. Use `linkTitle` to shorten the text of the menu entry.
For example (for a page named `install/linux.md`):
{{< multiconfig fm=true >}}
title = 'Install on Linux'
linkTitle = 'Linux'
{{< /multiconfig >}}
## Add Icon to a Menu Entry
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} In the page front matter, add a `menuPre` to insert any HTML code before the menu label. You can also set `menuPost` to insert HTML code after the menu label.
The example below uses the GitHub icon.
{{< multiconfig fm=true >}}
title = 'GitHub Repo'
menuPre = '<i class="fab fa-github"></i> '
{{< /multiconfig >}}
![Title with icon](item-with-icon.png?width=18.75rem)
## Disable Section Pages
@ -77,5 +96,5 @@ For this, open `content/first-chapter/first-page/_index.md` and add the followin
{{< multiconfig fm=true >}}
collapsibleMenu = true
[_build]
render = "never"
render = 'never'
{{< /multiconfig >}}

4
exampleSite/content/authoring/frontmatter/navigationmenu/_index.pir.md
View file

@ -1,5 +1,7 @@
+++
tags = ["reference"]
description = "Behavior of the navigation menu"
frontmatter = ["alwaysopen", "collapsibleMenu", "linkTitle", "menuPost", "menuPre", "ordersectionsby"]
options = ["alwaysopen", "collapsibleMenu", "ordersectionsby"]
title = "Navigation Menu"
weight = 2
+++

0
exampleSite/content/authoring/frontmatter/navigationmenu/frontmatter-icon.png → exampleSite/content/authoring/frontmatter/navigationmenu/item-with-icon.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.1 KiB

After

Width:  |  Height:  |  Size: 3.1 KiB

2
exampleSite/content/authoring/frontmatter/reference/_index.en.md
View file

@ -3,7 +3,7 @@ description = "All front matter for the Relearn theme"
linkTitle = "Reference"
tags = ["reference"]
title = "Front Matter Reference"
weight = 4
weight = 5
+++
Every Hugo page must have front matter.

2
exampleSite/content/authoring/frontmatter/reference/_index.pir.md
View file

@ -3,6 +3,6 @@ description = "All front matter for the Relearn theme"
linkTitle = "Reference"
tags = ["reference"]
title = "Front Matter Reference"
weight = 4
weight = 5
+++
{{< piratify >}}

73
exampleSite/content/authoring/frontmatter/reference/frontmatter.toml
View file

@ -10,12 +10,12 @@
# This is used for generating social media meta information for the opengraph
# protocol and twitter cards.
# If not set, the set value of your site's hugo.toml is used.
images = [ "images/hero.png" ]
images = [ 'images/hero.png' ]
# The title of your page.
# Default: not set
# A page without a title is treated as a hidden page.
title = "Example Page"
title = 'Example Page'
# The description of your page.
# Default: not set
@ -24,13 +24,13 @@ title = "Example Page"
# If not set, the set value of your site's hugo.toml is used for the html
# meta tag, social media meta information for the opengraph protocol and
# twitter cards.
description = ""
description = ''
# The page design to be used
# Default: not set
# This decides the layout of your page. The theme ships 'home', 'chapter' and
# 'default'. If not set, 'default' is taken.
type = ""
type = ''
###############################################################################
# Relearn Theme
@ -69,29 +69,35 @@ disableNextPrev = false
# an disabled button, you can set the value to a string containing just spaces.
# This is useful if you want to give the opportunity for people to create merge
# request for your content.
editURL = ""
editURL = ''
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Menu
# These options modify the menu appearance.
# Menu specific title
# Default: not set
# The title displayed in the menu. If not set the `title` front matter will
# be used.
linkTitle = ''
# Prefix for the title in navigation menu.
# Default: not set
# The title of the page in the menu will be prefixed by this HTML content.
menuPre = ""
menuPre = ''
# Suffix for the title in navigation menu.
# Default: not set
# The title of the page in the menu will be suffixed by this HTML content.
menuPost = ""
menuPost = ''
# The order of navigation menu submenus.
# Default: "weight"
# Submenus can be ordered by "weight", "title", "linktitle", "modifieddate",
# "expirydate", "publishdate", "date", "length" or "default" (adhering to
# Default: 'weight'
# Submenus can be ordered by 'weight', 'title', 'linktitle', 'modifieddate',
# 'expirydate', 'publishdate', 'date', 'length' or 'default' (adhering to
# Hugo's default sort order).
# If not set, the value of the parent menu entry is used.
ordersectionsby = "weight"
ordersectionsby = 'weight'
# The initial expand state of submenus.
# Default: not set
@ -100,7 +106,7 @@ ordersectionsby = "weight"
# levels are set to true. If not set, the value of the parent menu entry is used.
# If the displayed page has submenus, they will always been displayed expanded
# regardless of this option.
alwaysopen = ""
alwaysopen = ''
# Shows expander for submenus.
# Default: false
@ -129,23 +135,23 @@ hidden = false
# Prefix for the title in the content area.
# Default: not set
# The title of the page heading will be prefixed by this HTML content.
headingPre = ""
headingPre = ''
# Suffix for the title in the content area.
# Default: not set
# The title of the page heading will be suffixed by this HTML content.
headingPost = ""
headingPost = ''
# Display name of the page's last editor.
# Default: not set
# If set, it will be displayed in the default footer.
LastModifierDisplayName = ""
LastModifierDisplayName = ''
# Email address of the page's last editor.
# Default: not set
# If set together with LastModifierDisplayName, it will be displayed in the
# default footer.
LastModifierEmail = ""
LastModifierEmail = ''
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Highlight
@ -166,21 +172,21 @@ highlightWrap = true
# These options configure how the include shortcode works.
# What to do when path is not resolved.
# Default: ""
# Default: ''
# You can control what should happen if a path can not be resolved to as
# a resource or via the file system. If not set, no output will be written
# for the unresolved path. If set to `warning` the same happens and an additional
# warning is printed. If set to `error` an error message is printed and the build
# is aborted.
# If not set, the set value of your site's hugo.toml is used.
include.errorlevel = ""
include.errorlevel = ''
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Images
# These options configure how images are displayed.
# What to do when local image link is not resolved.
# Default: ""
# Default: ''
# You can control what should happen if a local image can not be resolved to as
# a resource. If not set, the unresolved link is written as given into the resulting
# output. If set to `warning` the same happens and an additional warning is
@ -188,7 +194,7 @@ include.errorlevel = ""
# aborted.
# Please note that this can not resolve files inside of your `static` directory.
# If not set, the set value of your site's hugo.toml is used.
image.errorlevel = ""
image.errorlevel = ''
# Image effects.
# See the documentation for how you can even add your own arbitrary effects to
@ -211,7 +217,7 @@ imageEffects.shadow = false
# These options configure how links are displayed.
# What to do when local page link is not resolved.
# Default: ""
# Default: ''
# You can control what should happen if a local link can not be resolved to a
# page. If not set, the unresolved link is written as given into the resulting
# output. If set to `warning` the same happens and an additional warning is
@ -220,7 +226,16 @@ imageEffects.shadow = false
# Please note that with Hugo < 0.123.0 + `uglyURLs=true` this can lead to false
# negatives.
# If not set, the set value of your site's hugo.toml is used.
link.errorlevel = ""
link.errorlevel = ''
# How to open external links.
# Default: '_blank'
# For external links you can define how they are opened in your browser. All
# values for the HTML `target` attribute of the `a` element are allowed. The
# default value opens external links in a separate browser tab. If you want
# to open those links in the same tab, use '_self'.
# If not set, the set value of your site's hugo.toml is used.
externalLinkTarget = '_self'
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# MathJax
@ -230,7 +245,7 @@ link.errorlevel = ""
# Default: not set
# A JSON value. See the MathJaxdocumentation for possible parameter.
# If not set, the set value of your site's hugo.toml is used.
mathJaxInitialize = "{}"
mathJaxInitialize = '{}'
# Force load Math on every page.
# Default: false
@ -248,7 +263,7 @@ math = false
# Specifies the remote location of the MathJax library. By default the shipped
# version will be used.
# If not set, the set value of your site's hugo.toml is used.
customMathJaxURL = "" # "https://unpkg.com/mathjax/es5/tex-mml-chtml.js"
customMathJaxURL = '' # 'https://unpkg.com/mathjax/es5/tex-mml-chtml.js'
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Mermaid
@ -266,7 +281,7 @@ mermaidZoom = true
# Default: not set
# A JSON value. See the Mermaid documentation for possible parameter.
# If not set, the set value of your site's hugo.toml is used.
mermaidInitialize = "{ \"securityLevel\": \"loose\" }"
mermaidInitialize = '{ "securityLevel": "loose" }'
# Force load Mermaid on every page.
# Default: false
@ -283,7 +298,7 @@ mermaid.force = false
# Specifies the remote location of the Mermaid library. By default the shipped
# version will be used.
# If not set, the set value of your site's hugo.toml is used.
customMermaidURL = "" # "https://unpkg.com/mermaid/dist/mermaid.min.js"
customMermaidURL = '' # 'https://unpkg.com/mermaid/dist/mermaid.min.js'
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# OpenApi
@ -304,10 +319,10 @@ oppenapi.force = false
# Specifies the remote location of the OpenAPI library. By default the shipped
# version will be used.
# If not set, the set value of your site's hugo.toml is used.
customOpenapiURL = "" # "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
customOpenapiURL = '' # 'https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js'
# What to do when a local OpenAPI spec link is not resolved.
# Default: ""
# Default: ''
# You can control what should happen if a local OpenAPI spec link can not be resolved
# to a resource. If not set, the unresolved link is written as given into the resulting
# output. If set to `warning` the same happens and an additional warning is
@ -315,4 +330,4 @@ customOpenapiURL = "" # "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
# aborted.
# Please note that this can not resolve files inside of your `static` directory.
# If not set, the set value of your site's hugo.toml is used.
openapi.errorlevel = ""
openapi.errorlevel = ''

40
exampleSite/content/configuration/appearance/topbar/_index.en.md → exampleSite/content/authoring/frontmatter/topbar/_index.en.md
View file

@ -1,8 +1,9 @@
+++
description = "Configure the site's topbar"
description = "Configure the topbar"
frontmatter = ["disableBreadcrumb", "disableNextPrev", "disableToc", "editURL"]
options = ["disableBreadcrumb", "disableNextPrev", "disableToc", "editURL"]
title = "Topbar"
weight = 2
weight = 4
+++
This page is about how to configure the topbar using configuration options. If you want to add further buttons or functionality, [see this section](configuration/customization/topbar).
@ -13,52 +14,43 @@ Your topbar contains the following elements. Some of them are configuarable:
- {{% button style="transparent" icon="list-alt" %}}{{% /button %}} **toc**: [opens the table of contents in an overlay](#table-of-contents)
- {{% button style="transparent" icon="empty" %}}{{% /button %}} **breadcrumb**: shows the clickable [breadcrumbs](#breadcrumbs)
- {{% button style="transparent" icon="pen" %}}{{% /button %}} **edit**: browses to the editable page if the `editURL` [parameter is set](#edit-button)
- {{% button style="transparent" icon="print" %}}{{% /button %}} **print**: browses to the chapters printable page if [print support](#print-support) was activated
- {{% button style="transparent" icon="print" %}}{{% /button %}} **print**: browses to the chapters printable page if [print support](configuration/sitemanagement/outputformats#print-support) was activated
- {{% button style="transparent" icon="chevron-left" %}}{{% /button %}} **prev**: browses to the [previous page](#arrow-navigation) if there is one
- {{% button style="transparent" icon="chevron-right" %}}{{% /button %}} **next**: browses to the [next page](#arrow-navigation) if there is one
- {{% button style="transparent" icon="ellipsis-v" %}}{{% /button %}} **more**: opens the overlay if screen space is limited
## Table of Contents
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `disableToc=true` to hide the TOC button on all pages. If the button is hidden, also the keyboard shortcut is disabled. This can be overridden in a page's front matter.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Set `disableToc=true` to hide the TOC button on all pages. If the button is hidden, also the keyboard shortcut is disabled. This can be overridden in a page's front matter.
{{< multiconfig file=hugo >}}
[params]
disableToc = true
{{< multiconfig fm=true >}}
disableToc = true
{{< /multiconfig >}}
## Breadcrumbs
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `disableBreadcrumb=true` to hide the breadcrumb in the topbar.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Set `disableBreadcrumb=true` to hide the breadcrumb in the topbar.
Further breadcrumbs settings can be found in the [content configuration section](configuration/content/titles).
{{< multiconfig file=hugo >}}
[params]
disableBreadcrumb = true
{{< multiconfig fm=true >}}
disableBreadcrumb = true
{{< /multiconfig >}}
## Edit Button
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} If `editURL` is set to a URL, an edit button will be shown in the topbar. If the button is hidden, also the keyboard shortcut is disabled.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} If `editURL` is set to a URL, an edit button will be shown in the topbar. If the button is hidden, also the keyboard shortcut is disabled.
The value can contain the macro `${FilePath}` which will be replaced by the file path of your displayed page. If no `${FilePath}` is given in the value, the value is treated as if the `${FilePath}` was appended at the end of the value. This can be overridden in the pages front matter.
{{< multiconfig file=hugo >}}
[params]
editURL = 'https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/${FilePath}'
{{< multiconfig fm=true >}}
editURL = 'https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/${FilePath}'
{{< /multiconfig >}}
## Print Support
If you have [activated print support](configuration/sitemanagement/outputformats#print-support), a printer icon will be displayed to access the print preview.
## Arrow Navigation
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can hide the previous/next buttons by setting `disableNextPrev=true`. If the buttons are hidden, also the keyboard shortcuts are disabled.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can hide the previous/next buttons by setting `disableNextPrev=true`. If the buttons are hidden, also the keyboard shortcuts are disabled.
{{< multiconfig file=hugo >}}
[params]
disableNextPrev = true
{{< multiconfig fm=true >}}
disableNextPrev = true
{{< /multiconfig >}}

8
exampleSite/content/authoring/frontmatter/topbar/_index.pir.md Normal file
View file

@ -0,0 +1,8 @@
+++
description = "Configure the topbar"
frontmatter = ["disableBreadcrumb", "disableNextPrev", "disableToc", "editURL"]
options = ["disableBreadcrumb", "disableNextPrev", "disableToc", "editURL"]
title = "Topbarrr"
weight = 4
+++
{{< piratify >}}

8
exampleSite/content/authoring/imageeffects.en.md
View file

@ -2,12 +2,12 @@
description = "How to apply graphical effects to your images"
frontmatter = ["imageEffects"]
title = "Image Effects"
weight = 4
weight = 5
+++
The theme offers [graphical effects](authoring/markdown#image-effects) for your linked images.
You can [define additional custom image effects](configuration/customization/imageeffects) in your configuration.
You can [define additional custom image effects and set defaults](configuration/customization/imageeffects) in your configuration.
The default image effects shipped with the theme are
@ -18,9 +18,9 @@ The default image effects shipped with the theme are
| lightbox | The image will be clickable to show it enlarged |
| shadow | Draws a shadow around the image to make it appear hovered/glowing |
As [described](authoring/markdown#image-effects), one way to use them is to add them as URL query parameter.
One way to use them is to add them as URL query parameter to each individually linked image.
This can become cumbersome to be done consistently for the whole site. Instead, you can configure the defaults in your `hugo.toml` as well as overriding these defaults in a page's front matter.
This can become cumbersome to be done consistently for the whole site. Instead, you can [configure the defaults](configuration/customization/imageeffects) in your `hugo.toml` as well as overriding these defaults in a page's front matter.
Explicitly set URL query parameter will override the defaults set for a page or your site.

2
exampleSite/content/authoring/imageeffects.pir.md
View file

@ -2,6 +2,6 @@
description = "How to apply graphical effects to your images"
frontmatter = ["imageEffects"]
title = "Image Effects"
weight = 4
weight = 5
+++
{{< piratify >}}

16
exampleSite/content/authoring/markdown.en.md
View file

@ -1,8 +1,8 @@
+++
description = "Reference of Commonmark and Markdown extensions"
description = "Reference of CommonMark and Markdown extensions"
tags = ["reference"]
title = "Markdown Syntax"
weight = 3
weight = 4
+++
Let's face it: Writing content for the web is tiresome. WYSIWYG editors help alleviate this task, but they generally result in horrible code, or worse yet, ugly web pages.
@ -29,7 +29,7 @@ John Gruber, the author of Markdown, puts it like this:
## Standard and Extensions
If not otherwise noted, the shown examples adhere to the [Commonmark](https://commonmark.org/help/) standard. In addition the theme supports the following extensions that [can be activated](https://gohugo.io/getting-started/configuration-markup/#goldmark) in your `hugo.toml` or are built into the theme:
If not otherwise noted, the shown examples adhere to the [CommonMark](https://commonmark.org/help/) standard. In addition the theme supports the following extensions that [can be activated](https://gohugo.io/getting-started/configuration-markup/#goldmark) in your `hugo.toml` or are built into the theme:
- {{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} Extension on top of standard Markdown adhering to [GitHub Flavored Markdown](https://github.github.com/gfm/).
@ -142,11 +142,11 @@ Blockquotes can also be nested.
> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.
{{% /notice %}}
### GitHub Styled Alerts
### GitHub Alerts
{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} Since Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}0.132.0{{% /badge %}} [GitHub styled alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) are also supported. Please note, that coloring and icons of severities may defer between GitHub and this theme.
{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} Since Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}0.132.0{{% /badge %}} [GitHub alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) are also supported. Please note, that coloring and icons of severities may defer between GitHub and this theme.
If you are in need of more advanced options to style your alerts, use the [notice shortcode](shortcodes/notice).
If you are in need of more advanced options to style your alerts, like icons, use the [notice shortcode](shortcodes/notice).
````md
> [!CAUTION]
@ -192,6 +192,8 @@ If you are in need of more advanced options to style your alerts, use the [notic
{{% badge color="#7c3aed" icon="fa-fw far fa-gem" %}}Obsidian{{% /badge %}} Since Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}0.134.0{{% /badge %}} [Obsidian callouts](https://help.obsidian.md/Editing+and+formatting/Callouts#Change+the+title) are also supported. Which enables configurable title text and expand/collapse.
If you are in need of more advanced options to style your alerts, like icons, use the [notice shortcode](shortcodes/notice).
````md
> [!tip] Callouts can have custom titles
> Like this one.
@ -723,7 +725,7 @@ Images can also be linked by reference ID to later define the URL location. This
### Image Effects
{{% badge color="#7dc903" icon="fa-fw fas fa-puzzle-piece" %}}Relearn{{% /badge %}} This theme allows additional non-standard formatting by setting query parameter at the end of the image URL. The default [behavior is configurable](configuration/customization/imageeffects) through your `hugo.toml` or front matter parameter.
{{% badge color="#7dc903" icon="fa-fw fas fa-puzzle-piece" %}}Relearn{{% /badge %}} This theme allows additional non-standard formatting by setting query parameter at the end of the image URL. See the [image effects docs](authoring/imageeffects) for a detailed example and how to configure it.
#### Resizing

4
exampleSite/content/authoring/markdown.pir.md
View file

@ -1,7 +1,7 @@
+++
description = "Reference of Commonmark and Markdown extensions"
description = "Reference of CommonMark and Markdown extensions"
tags = ["reference"]
title = "Marrrkdown Rules"
weight = 3
weight = 4
+++
{{< piratify >}}

68
exampleSite/content/authoring/meta/_index.en.md Normal file
View file

@ -0,0 +1,68 @@
+++
description = "What page meta information are available"
frontmatter = ["headingPost", "headingPre", "hidden", "LastModifierDisplayName", "LastModifierEmail"]
title = "Meta Information"
weight = 3
+++
## Page Title
The `title` will be used in the heading and meta information of your HTML.
A page without a title is [treated as if `hidden=true`](#hidden) has been set.
{{< multiconfig fm=true >}}
title = 'Example Title'
{{< /multiconfig >}}
## Page Description
The `description` is used for generating HTML meta information, in the [children](shortcodes/children) shortcode and in social media meta information.
If not set, the set value of your site's hugo.toml is used for the HTML meta information and social media meta information. It appears empty for the [children](shortcodes/children) shortcode.
{{< multiconfig fm=true >}}
description = 'Some lenghty example description'
{{< /multiconfig >}}
## Social Media Images
The theme adds social media meta tags including feature images for the [Open Graph](https://gohugo.io/templates/internal/#open-graph) protocol and [Twitter Cards](https://gohugo.io/templates/internal/#twitter-cards) to your site. These are configured as mentioned in the linked Hugo docs.
{{< multiconfig fm=true >}}
images = [ 'images/hero.png' ]
{{< /multiconfig >}}
## Hidden
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can hide your pages from the menu by setting `hidden=true`.
[See how you can further configure visibility](configuration/content/hidden) throughout your site.
{{< multiconfig fm=true >}}
hidden = true
{{< /multiconfig >}}
## Add Icon to the Title Heading
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} In the page front matter, add a `headingPre` to insert any HTML code before the title heading. You can also set `headingPost` to insert HTML code after the title heading.
You also may want to [apply further CSS](configuration/customization/dependencies#adding-javascript-or-stylesheets-to-all-pages) in this case.
{{< multiconfig fm=true >}}
headingPre = '<i class="fab fa-github"></i> '
{{< /multiconfig >}}
## Footer Information
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} If you use the default `layouts/partials/content-footer.html` is not overridden by you, it will display authoring information, namely
- `AuthorName` if [GitInfo](https://gohugo.io/methods/page/gitinfo/) is active, otherwise `LastModifierDisplayName` front matter
- `AuthorEmail` if [GitInfo](https://gohugo.io/methods/page/gitinfo/) is active, otherwise `LastModifierEmail` front matter
- `AuthorDate` if [GitInfo](https://gohugo.io/methods/page/gitinfo/) is active, otherwise [Hugo's `date` front matter](https://gohugo.io/methods/page/date/)
{{< multiconfig fm=true >}}
LastModifierDisplayName = 'Santa Claus'
LastModifierEmail = 'santa@example.com'
date = 2000-12-24T00:00:00-12:00
{{< /multiconfig >}}

7
exampleSite/content/authoring/meta/_index.pir.md Normal file
View file

@ -0,0 +1,7 @@
+++
description = "What page meta information are available"
frontmatter = ["headingPost", "headingPre", "hidden", "LastModifierDisplayName", "LastModifierEmail"]
title = "Meta Information"
weight = 3
+++
{{< piratify >}}

7
exampleSite/content/configuration/appearance/_index.pir.md
View file

@ -1,7 +0,0 @@
+++
alwaysopen = false
description = "Change colors, logos and the overall appearance of your site"
title = "Appearance"
weight = 2
+++
{{< piratify >}}

7
exampleSite/content/configuration/appearance/branding/_index.pir.md
View file

@ -1,7 +0,0 @@
+++
description = "Learn how to customize your site's colors, fonts, favicon, and logo"
options = ["themeVariant"]
title = "Brrrand'n"
weight = 1
+++
{{< piratify >}}

7
exampleSite/content/configuration/appearance/topbar/_index.pir.md
View file

@ -1,7 +0,0 @@
+++
description = "Configure the site's topbar"
options = ["disableBreadcrumb", "disableNextPrev", "disableToc", "editURL"]
title = "Topbarrr"
weight = 2
+++
{{< piratify >}}

4
exampleSite/content/configuration/appearance/_index.en.md → exampleSite/content/configuration/branding/_index.en.md
View file

@ -1,7 +1,7 @@
+++
alwaysopen = false
description = "Change colors, logos and the overall appearance of your site"
title = "Appearance"
description = "Change colors and logos of your site"
title = "Branding"
weight = 2
+++

7
exampleSite/content/configuration/branding/_index.pir.md Normal file
View file

@ -0,0 +1,7 @@
+++
alwaysopen = false
description = "Change colors and logos of your site"
title = "Brrrand'n"
weight = 2
+++
{{< piratify >}}

96
exampleSite/content/configuration/appearance/branding/_index.en.md → exampleSite/content/configuration/branding/colors/_index.en.md
View file

@ -1,13 +1,13 @@
+++
description = "Learn how to customize your site's colors, fonts, favicon, and logo"
description = "Learn how to customize your site's colors"
options = ["themeVariant"]
title = "Branding"
weight = 1
title = "Colors"
weight = 2
+++
The Relearn theme offers color variants to change your site's appearance. Each color variant contains of a CSS file and optional settings in your `hugo.toml`.
You can use the pre-made variants, [customize them](#modifying-variants), or create your own. The [interactive variant generator](configuration/appearance/generator) can help you with this.
You can use the pre-made variants, [customize them](#modifying-variants), or create your own. The [interactive variant generator](configuration/branding/generator) can help you with this.
Once set up in `hugo.toml`, you can switch variants using the selector at the bottom of the menu.
@ -25,7 +25,7 @@ Set `themeVariant` to your theme CSS file name:
{{< multiconfig file=hugo >}}
[params]
themeVariant = "relearn-light"
themeVariant = 'relearn-light'
{{< /multiconfig >}}
Place your theme file in `assets/css` or `themes/hugo-theme-relearn/assets/css`. Name it `theme-*.css`.
@ -38,7 +38,7 @@ To let the reader choose between multiple variants, set `themeVariant` like this
{{< multiconfig file=hugo >}}
[params]
themeVariant = [ "relearn-light", "relearn-dark" ]
themeVariant = [ 'relearn-light', 'relearn-dark' ]
{{< /multiconfig >}}
The first variant is the default, and a selector will appear if there's more than one.
@ -49,7 +49,7 @@ Use the `auto` value to match OS light/dark settings. Usually it makes sense to
{{< multiconfig file=hugo >}}
[params]
themeVariant = [ "auto", "red" ]
themeVariant = [ 'auto', 'red' ]
{{< /multiconfig >}}
If you don't configure anything else, the theme will default to use `relearn-light` for light mode and `relearn-dark` for dark mode.
@ -60,7 +60,7 @@ You can override the default with `themeVariantAuto`:
{{< multiconfig file=hugo >}}
[params]
themeVariantAuto = [ "learn", "neon" ]
themeVariantAuto = [ 'learn', 'neon' ]
{{< /multiconfig >}}
### Advanced {#theme-variant-advanced}
@ -73,7 +73,7 @@ Again, in this case, the first variant is the default chosen on first view and a
{{< multiconfig file=hugo >}}
[params]
themeVariant = [ "relearn-light", "relearn-dark" ]
themeVariant = [ 'relearn-light', 'relearn-dark' ]
{{< /multiconfig >}}
you now write it that way:
@ -81,9 +81,9 @@ you now write it that way:
{{< multiconfig file=hugo >}}
[params]
[[params.themeVariant]]
identifier = "relearn-light"
identifier = 'relearn-light'
[[params.themeVariant]]
identifier = "relearn-dark"
identifier = 'relearn-dark'
{{< /multiconfig >}}
The `identifier` option is mandatory and equivalent to the string in the first example. Further options can be configured, see the table below.
@ -101,16 +101,16 @@ The `identifier` option is mandatory and equivalent to the string in the first e
{{< multiconfig file=hugo >}}
[params]
themeVariant = [
{ identifier = "relearn-auto", name = "Relearn Light/Dark", auto = [] },
{ identifier = "relearn-light" },
{ identifier = "relearn-dark" },
{ identifier = "relearn-bright" },
{ identifier = "zen-auto", name = "Zen Light/Dark", auto = [ "zen-light", "zen-dark" ] },
{ identifier = "zen-light" },
{ identifier = "zen-dark" },
{ identifier = "retro-auto", name = "Retro Learn/Neon", auto = [ "learn", "neon" ] },
{ identifier = "neon" },
{ identifier = "learn" }
{ identifier = 'relearn-auto', name = 'Relearn Light/Dark', auto = [] },
{ identifier = 'relearn-light' },
{ identifier = 'relearn-dark' },
{ identifier = 'relearn-bright' },
{ identifier = 'zen-auto', name = 'Zen Light/Dark', auto = [ 'zen-light', 'zen-dark' ] },
{ identifier = 'zen-light' },
{ identifier = 'zen-dark' },
{ identifier = 'retro-auto', name = 'Retro Learn/Neon', auto = [ 'learn', 'neon' ] },
{ identifier = 'neon' },
{ identifier = 'learn' }
]
{{< /multiconfig >}}
@ -144,7 +144,7 @@ In case you like a shipped variant but only want to tweak some aspects, you have
{{< multiconfig file=hugo >}}
[params]
themeVariant = "my-branding"
themeVariant = 'my-branding'
{{< /multiconfig >}}
In comparison to _copy and change_, this has the advantage that you profit from any adjustments to the `relearn-light` variant while keeping your modifications.
@ -158,55 +158,3 @@ document.addEventListener( 'themeVariantLoaded', function( e ){
console.log( e.detail.variant ); // `relearn-light`
});
````
## Change Syntax Highlighting
If you want to switch the syntax highlighting theme together with your color variant, first you need to configure your installation [according to Hugo's documentation](https://gohugo.io/content-management/syntax-highlighting/#generate-syntax-highlighter-css) to provide a syntax highlighting stylesheet file.
{{< multiconfig file=hugo >}}
markup.highlight.noClasses=false
{{< /multiconfig >}}
You can use one of the shipped stylesheet files or use Hugo to generate a file for you.
````shell
hugo gen chromastyles --style=monokai > chroma-mycode.css
````
The file must be written to `assets/css/chroma-<NAME>.css`. To use it with your color variant, you have to modify `--CODE-theme: <NAME>` in the color variant stylesheet file.
````css {title="assets/css/theme-my-branding.css"}
@import "theme-relearn-light.css";
:root {
--CODE-theme: mycode; /* name of the chroma stylesheet file */
}
````
## Change 3rd-Party Libraries Theming
Some of the shipped shortcodes are using 3rd-party libraries. See the individual shortcode documentation on how to change their theming.
- [`mermaid` shortcode](shortcodes/mermaid#setting-a-specific-mermaid-theme)
- [`openapi` shortcode](shortcodes/openapi#setting-a-specific-swagger-ui-theme)
## Change the Favicon
If your favicon is an SVG, PNG, or ICO, just drop your image in your site's `static/images/` directory and name it `favicon.svg`, `favicon.png`, or `favicon.ico` respectively.
If you want to adjust your favicon according to your OS settings for light/dark mode, add the image files `static/images/favicon-light.svg` and `static/images/favicon-dark.svg` to your site's directory, respectively, corresponding to your file format. In case some of the files are missing, the theme falls back to `favicon.svg` for each missing file. All supplied favicons must be of the same file format.
If no favicon file is found, the theme will look up the alternative filename `logo` in the same location and will repeat the search for the list of supported file types.
If you need to change this default behavior, create a new file `layouts/partials/favicon.html` in your site's directory and write something like this:
````html {title="layouts/partials/favicon.html"}
<link rel="icon" href="/images/favicon.bmp" type="image/bmp">
````
## Change the Logo
By default, only your site title will be shown at the top of the menu. You can [configure this](configuration/sitemanagement/meta#menu-title), or override the logo partial.
Create a new file in `layouts/partials/logo.html` of your site. Then write any HTML you want. You could use an `img` HTML tag and reference an image, or you could paste an SVG definition!
The size of the logo will adapt automatically.

7
exampleSite/content/configuration/branding/colors/_index.pir.md Normal file
View file

@ -0,0 +1,7 @@
+++
description = "Learn how to customize your site's colors"
options = ["themeVariant"]
title = "Brrrand'n"
weight = 2
+++
{{< piratify >}}

4
exampleSite/content/configuration/appearance/generator/_index.en.md → exampleSite/content/configuration/branding/generator/_index.en.md
View file

@ -3,7 +3,7 @@ description = "An interactive tool to generate color variant stylesheets"
mermaid.force = true
options = ["themeVariant"]
title = "Stylesheet Generator"
weight = 3
weight = 4
+++
This interactive tool may help you to generate your own color variant stylesheet.
@ -23,7 +23,7 @@ Once you are satisfied, you can download the new variants file and copy it into
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Afterwards, you have to adjust the `themeVariant` option in your `hugo.toml` to your chosen file name. For example, if your new variants file is named `theme-my-custom-variant.css`, you have to set `themeVariant='my-custom-variant'` to use it.
See the docs for [further configuration options](configuration/appearance/branding).
See the docs for [further configuration options](configuration/branding/colors).
{{% /expand %}}
{{% button style="secondary" icon="download" href="javascript:window.variants&&variants.getStylesheet();this.blur();" %}}Download variant{{% /button %}}

2
exampleSite/content/configuration/appearance/generator/_index.pir.md → exampleSite/content/configuration/branding/generator/_index.pir.md
View file

@ -3,6 +3,6 @@ description = "An interactive tool to generate color variant stylesheets"
mermaid.force = true
options = ["themeVariant"]
title = "Stylesheet Generrrat'r"
weight = 3
weight = 4
+++
{{< piratify >}}

27
exampleSite/content/configuration/branding/logo/_index.en.md Normal file
View file

@ -0,0 +1,27 @@
+++
description = "Provide your own logo and favicon"
title = "Logo"
weight = 1
+++
## Change the Favicon
If your favicon is an SVG, PNG, or ICO, just drop your image in your site's `static/images/` directory and name it `favicon.svg`, `favicon.png`, or `favicon.ico` respectively.
If you want to adjust your favicon according to your OS settings for light/dark mode, add the image files `static/images/favicon-light.svg` and `static/images/favicon-dark.svg` to your site's directory, respectively, corresponding to your file format. In case some of the files are missing, the theme falls back to `favicon.svg` for each missing file. All supplied favicons must be of the same file format.
If no favicon file is found, the theme will look up the alternative filename `logo` in the same location and will repeat the search for the list of supported file types.
If you need to change this default behavior, create a new file `layouts/partials/favicon.html` in your site's directory and write something like this:
````html {title="layouts/partials/favicon.html"}
<link rel="icon" href="/images/favicon.bmp" type="image/bmp">
````
## Change the Logo
By default, only your site title will be shown at the top of the menu. You can [configure this](configuration/sidebar/headerfooter#title), or override the logo partial.
Create a new file in `layouts/partials/logo.html` of your site. Then write any HTML you want. You could use an `img` HTML tag and reference an image, or you could paste an SVG definition!
The size of the logo will adapt automatically.

6
exampleSite/content/configuration/branding/logo/_index.pir.md Normal file
View file

@ -0,0 +1,6 @@
+++
description = "Provide your own logo and favicon"
title = "Logo"
weight = 1
+++
{{< piratify >}}

35
exampleSite/content/configuration/branding/modules/_index.en.md Normal file
View file

@ -0,0 +1,35 @@
+++
description = "Colors of syntax highlighting and 3rd-party modules"
title = "Module Theming"
weight = 3
+++
## Change Syntax Highlighting
If you want to switch the syntax highlighting theme together with your color variant, first you need to configure your installation [according to Hugo's documentation](https://gohugo.io/content-management/syntax-highlighting/#generate-syntax-highlighter-css) to provide a syntax highlighting stylesheet file.
{{< multiconfig file=hugo >}}
markup.highlight.noClasses=false
{{< /multiconfig >}}
You can use one of the shipped stylesheet files or use Hugo to generate a file for you.
````shell
hugo gen chromastyles --style=monokai > chroma-mycode.css
````
The file must be written to `assets/css/chroma-<NAME>.css`. To use it with your color variant, you have to modify `--CODE-theme: <NAME>` in the color variant stylesheet file.
````css {title="assets/css/theme-my-branding.css"}
@import "theme-relearn-light.css";
:root {
--CODE-theme: mycode; /* name of the chroma stylesheet file */
}
````
## Change 3rd-Party Libraries Theming
Some of the shipped shortcodes are using 3rd-party libraries. See the individual shortcode documentation on how to change their theming.
- [`mermaid` shortcode](shortcodes/mermaid#setting-a-specific-mermaid-theme)
- [`openapi` shortcode](shortcodes/openapi#setting-a-specific-swagger-ui-theme)

6
exampleSite/content/configuration/branding/modules/_index.pir.md Normal file
View file

@ -0,0 +1,6 @@
+++
description = "Colors of syntax highlighting and 3rd-party modules"
title = "Module Theming"
weight = 3
+++
{{< piratify >}}

9
exampleSite/content/configuration/content/hidden/_index.en.md
View file

@ -1,20 +1,19 @@
+++
description = "Learn about the hidden pages feature"
frontmatter = ["hidden"]
options = ["disableSearchHiddenPages", "disableSeoHiddenPages", "disableTagHiddenPages"]
title = "Hidden Pages"
weight = 5
+++
This theme allows you to create hidden pages.
This theme allows you to [create hidden pages](authoring/meta#hidden).
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Hidden pages are created but not shown in the navigation. To make a page hidden, set `hidden=true` in its front matter. This is useful for pages you only want to access via a direct link.
Hidden pages are created but not shown in the navigation. This is useful for pages you only want to access via a direct link.
When you visit a hidden page's URL, it will appear in the navigation menu.
Hidden pages can also have hidden subpages.
Hidden pages can also have hidden subpages, creating multiple levels of hiding.
By default, hidden pages are only hidden from human visitors. Search engines can still find them by crawling your site. You can prevent this with these options:
By default, hidden pages are only hidden from human visitors. Search engines can still find them by crawling your site and the pages are linked in your taxonomies and site search. You can prevent this with these options.
## Hide from Search

1
exampleSite/content/configuration/content/hidden/_index.pir.md
View file

@ -1,6 +1,5 @@
+++
description = "Learn about the hidden pages feature"
frontmatter = ["hidden"]
options = ["disableSearchHiddenPages", "disableSeoHiddenPages", "disableTagHiddenPages"]
title = "Hidden Pages"
weight = 5

30
exampleSite/content/configuration/content/linking/index.en.md
View file

@ -1,35 +1,23 @@
+++
description = "What options are available for links and images"
options = ["disableDefaultRelref", "externalLinkTarget", "image.errorlevel", "link.errorlevel"]
options = ["disableDefaultRelref", "disableExplicitIndexURLs"]
title = "Linking"
weight = 4
+++
## Opening Links
Further [settings are available](authoring/frontmatter/linking) to be used in your configuration or front matter.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default, external links open in a new tab. To change this, use the `externalLinkTarget` setting with a proper [link target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).
## URL Management
For example, this will open links in the same tab
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default, the theme adds `index.html` to page links when `uglyURLs=false` (Hugo's default).
If you're only using a web server scenario and dislike this, you can reset to Hugo's default behavior by settings `disableExplicitIndexURLs=true`.
For the file system scenario, you are not allowed to change this value.
{{< multiconfig file=hugo >}}
[params]
externalLinkTarget = '_self'
{{< /multiconfig >}}
## Enabling Link and Image Link Warnings
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can use `link.errorlevel` and `image.errorlevel` to control what should happen if a local link can not be resolved to a resource.
If not set or empty, any unresolved link is written as given into the resulting output. If set to `warning` the same happens and an additional warning is printed in the built console. If set to `error` an error message is printed and the build is aborted.
Please note that this can not resolve files inside of your `static` directory. The file must be a resource of the page or the site.
Link warnings are also available for the [include](shortcodes/include#enabling-link-warnings) and [openapi](shortcodes/openapi#enabling-link-warnings) shortcodes.
{{< multiconfig file=hugo >}}
[params]
link.errorlevel = 'warning'
image.errorlevel = 'warning'
disableExplicitIndexURLs = true
{{< /multiconfig >}}
## Patching the `relref` Shortcode

2
exampleSite/content/configuration/content/linking/index.pir.md
View file

@ -1,6 +1,6 @@
+++
description = "What options are available for links and images"
options = ["disableDefaultRelref", "externalLinkTarget", "image.errorlevel", "link.errorlevel"]
options = ["disableDefaultRelref", "disableExplicitIndexURLs"]
title = "Linking"
weight = 4
+++

2
exampleSite/content/configuration/content/titles/index.en.md
View file

@ -7,7 +7,7 @@ weight = 2
## Breadcrumbs
Learn how to turn off the breadcrumbs completely and further [configure the topbar](configuration/appearance/topbar).
Learn how to turn off the breadcrumbs completely and further [configure the topbar](authoring/frontmatter/topbar).
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `disableRootBreadcrumb=true` to remove the root breadcrumb which often feels redundant. This will also apply to the breadcrumbs of the search results and taxonomy pages.

2
exampleSite/content/configuration/customization/dependencies/_index.en.md
View file

@ -32,7 +32,7 @@ For example, to create a shortcode called `myshortcode` that needs the `jquery`
{{< multiconfig file=hugo >}}
[params.relearn.dependencies]
[params.relearn.dependencies.myshortcode]
name = "MyShortcode"
name = 'MyShortcode'
{{< /multiconfig >}}
3. Create loader file `layouts/partials/dependencies/myshortcode.html`:

2
exampleSite/content/configuration/customization/imageeffects.en.md
View file

@ -7,7 +7,7 @@ weight = 3
This page shows you, how to configure custom [image effects](authoring/markdown#image-effects) on top of existing ones.
This setting can also be overridden by your front matter. For a detailed usage example, see [this page](authoring/imageeffects).
This setting can also [be overridden by your front matter](authoring/imageeffects).
If you don't configure anything in your `hugo.toml`, the image effects default to

12
exampleSite/content/configuration/customization/topbar/_index.en.md
View file

@ -5,7 +5,7 @@ title = "Topbar"
weight = 4
+++
The theme comes with a reasonably configured topbar. You can learn how to [configure the defaults in this section](configuration/appearance/topbar).
The theme comes with a reasonably configured topbar. You can learn how to [configure the defaults in this section](authoring/frontmatter/topbar).
![topbar on mobile devices](topbar-closed.png)
@ -32,11 +32,11 @@ While you cannot add additional areas in the topbar, you are free to configure a
The theme ships with the following predefined buttons (from left to right in the screenshot):
- {{% button style="transparent" icon="bars" %}}{{% /button %}} [**sidebar**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/sidebar.html): opens the sidebar flyout if in mobile layout
- {{% button style="transparent" icon="list-alt" %}}{{% /button %}} [**toc**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/toc.html): opens the table of contents in an overlay
- {{% button style="transparent" icon="pen" %}}{{% /button %}} [**edit**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/edit.html): browses to the editable page if the `editURL` [parameter is set](configuration/reference)
- {{% button style="transparent" icon="print" %}}{{% /button %}} [**print**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/print.html): browses to the chapter's printable page if [print support](configuration/appearance/topbar#print-support) was activated
- {{% button style="transparent" icon="chevron-left" %}}{{% /button %}} [**prev**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/prev.html): browses to the previous page if there is one
- {{% button style="transparent" icon="chevron-right" %}}{{% /button %}} [**next**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/next.html): browses to the next page if there is one
- {{% button style="transparent" icon="list-alt" %}}{{% /button %}} [**toc**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/toc.html): [opens the table of contents in an overlay](authoring/frontmatter/topbar#table-of-contents)
- {{% button style="transparent" icon="pen" %}}{{% /button %}} [**edit**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/edit.html): browses to the editable page if the `editURL` [parameter is set](authoring/frontmatter/topbar#edit-button)
- {{% button style="transparent" icon="print" %}}{{% /button %}} [**print**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/print.html): browses to the chapter's printable page if [print support](configuration/sitemanagement/outputformats#print-support) was activated
- {{% button style="transparent" icon="chevron-left" %}}{{% /button %}} [**prev**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/prev.html): browses to the [previous page](authoring/frontmatter/topbar#arrow-navigation) if there is one
- {{% button style="transparent" icon="chevron-right" %}}{{% /button %}} [**next**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/next.html): browses to the [next page]authoring/frontmatter/topbar(#arrow-navigation) if there is one
- {{% button style="transparent" icon="ellipsis-v" %}}{{% /button %}} [**more**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/more.html): opens the overlay for the _more_ area
Not all buttons are displayed at every given time. This is configurable (see below if interested).

17
exampleSite/content/configuration/sidebar/headerfooter/_index.en.md
View file

@ -1,10 +1,19 @@
+++
description = "Configure the header and footer"
options = ["disableLandingPageButton", "landingPageName", "showVisitedLinks"]
options = ["disableLandingPageButton", "landingPageName", "linkTitle", "showVisitedLinks"]
title = "Header & Footer"
weight = 2
+++
## Title
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} With the [default partials](configuration/branding/logo#change-the-logo) for the logo, The site title will also be used for the text at the top of the sidebar. If you want to show a different text in the sidebar, you can overwrite `linkTitle`.
{{< multiconfig file=hugo >}}
[params]
linkTitle = 'Relearn'
{{< /multiconfig >}}
## Home Button Configuration
By default, the theme displays a home button between search form and navigation menu. The Home button serves as an alternative to clicking the logo.
@ -24,18 +33,18 @@ By default, the theme displays a home button between search form and navigation
[languages]
[languages.en]
[languages.en.params]
landingPageName = "<i class='fa-fw fas fa-home'></i> Home"
landingPageName = '<i class="fa-fw fas fa-home"></i> Home'
[languages.pir]
[languages.pir.params]
landingPageName = "<i class='fa-fw fas fa-home'></i> Arrr! Homme"
landingPageName = '<i class="fa-fw fas fa-home"></i> Arrr! Homme'
{{< /multiconfig >}}
If this option isn't set for a specific language, it will use these default values
{{< multiconfig file=hugo >}}
[params]
landingPageName = "<i class='fa-fw fas fa-home'></i> Home"
landingPageName = '<i class="fa-fw fas fa-home"></i> Home'
{{< /multiconfig >}}
## History

2
exampleSite/content/configuration/sidebar/headerfooter/_index.pir.md
View file

@ -1,6 +1,6 @@
+++
description = "Configure the header and footer"
options = ["disableLandingPageButton", "landingPageName", "showVisitedLinks"]
options = ["disableLandingPageButton", "landingPageName", "linkTitle", "showVisitedLinks"]
title = "Header & Footer"
weight = 2
+++

46
exampleSite/content/configuration/sidebar/navigationmenu/_index.en.md
View file

@ -1,46 +0,0 @@
+++
description = "Default behavior of the navigation menu"
options = ["alwaysopen", "collapsibleMenu", "ordersectionsby"]
title = "Navigation Menu"
weight = 4
+++
The navigation menu is automatically created from [your content files](authoring/structure).
All configurations options apply to all pages but can be changed in each page's front matter.
## Expand State of Nested Sections
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Use `alwaysopen` to control how submenus appear. Set it to `true` to expand submenus, or `false` to collapse them. If not set, the first menu level is collapsed, and all others are expanded.
{{< multiconfig file=hugo >}}
[params]
alwaysopen = true
{{< /multiconfig >}}
See the [user guide](authoring/frontmatter/navigationmenu#expand-state-of-nested-sections) how this setting will be applied.
## Expander for Nested Sections
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `collapsibleMenu=true` to add an expander for submenus. This shows submenus as collapsible trees with a clickable expander.
{{< multiconfig file=hugo >}}
[params]
collapsibleMenu = true
{{< /multiconfig >}}
> [!WARNING]
> Using this option may slow down your build process, especially with many pages.
>
> We've seen builds taking 2 minutes with 1000+ pages, and over 30 minutes with 5000+ pages.
>
> This happens because each new page affects all other pages, leading to exponentially longer build times.
## Default Sort By
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Use `ordersectionsby` to choose how navigation menus are sorted. The default is `weight`. You can sort by `weight`, `title`, `linktitle`, `modifieddate`, `expirydate`, `publishdate`, `date`, `length`, or `default` (Hugo's standard order).
{{< multiconfig file=hugo >}}
[params]
ordersectionsby = 'weight'
{{< /multiconfig >}}

7
exampleSite/content/configuration/sidebar/navigationmenu/_index.pir.md
View file

@ -1,7 +0,0 @@
+++
description = "Default behavior of the navigation menu"
options = ["alwaysopen", "collapsibleMenu", "ordersectionsby"]
title = "Navigation Menu"
weight = 4
+++
{{< piratify >}}

4
exampleSite/content/configuration/sidebar/search/_index.en.md
View file

@ -35,8 +35,8 @@ Each level requires the previous one to be enabled. If no search is configured,
{{< multiconfig file=hugo >}}
[params]
searchIndexURL = 'mysearchindex.js'
searchPageURL = 'megasearch'
searchIndexURL = 'omnisearchindex.js'
searchPageURL = 'omnisearch'
{{< /multiconfig >}}
{{% notice note %}}

92
exampleSite/content/configuration/sidebar/shortcutmenu/_index.en.md
View file

@ -33,30 +33,30 @@ Edit `hugo.toml` and add `[[menu.shortcuts]]` entries for each link:
{{< multiconfig file=hugo >}}
[[menu.shortcuts]]
name = "<i class='fa-fw fab fa-github'></i> GitHub Repo"
identifier = "ds"
url = "https://github.com/McShelby/hugo-theme-relearn"
name = '<i class="fa-fw fab fa-github"></i> GitHub Repo'
identifier = 'ds'
url = 'https://github.com/McShelby/hugo-theme-relearn'
weight = 10
[[menu.shortcuts]]
name = "<i class='fa-fw fas fa-camera'></i> Showcases"
pageRef = "/showcase"
name = '<i class="fa-fw fas fa-camera"></i> Showcases'
pageRef = '/showcase'
weight = 11
[[menu.shortcuts]]
name = "<i class='fa-fw fas fa-bookmark'></i> Hugo Documentation"
identifier = "hugodoc"
url = "https://gohugo.io/"
name = '<i class="fa-fw fas fa-bookmark"></i> Hugo Documentation'
identifier = 'hugodoc'
url = 'https://gohugo.io/'
weight = 20
[[menu.shortcuts]]
name = "<i class='fa-fw fas fa-bullhorn'></i> Credits"
pageRef = "/more/credits"
name = '<i class="fa-fw fas fa-bullhorn"></i> Credits'
pageRef = '/more/credits'
weight = 30
[[menu.shortcuts]]
name = "<i class='fa-fw fas fa-tags'></i> Tags"
pageRef = "/tags"
name = '<i class="fa-fw fas fa-tags"></i> Tags'
pageRef = '/tags'
weight = 40
{{< /multiconfig >}}
@ -67,67 +67,67 @@ For multilingual sites, set different menus for each language in `hugo.toml`:
{{< multiconfig file=hugo >}}
[languages]
[languages.en]
title = "Hugo Relearn Theme"
title = 'Hugo Relearn Theme'
weight = 1
languageName = "English"
languageName = 'English'
[[languages.en.menu.shortcuts]]
name = "<i class='fa-fw fab fa-github'></i> GitHub Repo"
identifier = "ds"
url = "https://github.com/McShelby/hugo-theme-relearn"
name = '<i class="fa-fw fab fa-github"></i> GitHub Repo'
identifier = 'ds'
url = 'https://github.com/McShelby/hugo-theme-relearn'
weight = 10
[[languages.en.menu.shortcuts]]
name = "<i class='fa-fw fas fa-camera'></i> Showcases"
pageRef = "/showcase"
name = '<i class="fa-fw fas fa-camera"></i> Showcases'
pageRef = '/showcase'
weight = 11
[[languages.en.menu.shortcuts]]
name = "<i class='fa-fw fas fa-bookmark'></i> Hugo Documentation"
identifier = "hugodoc"
url = "https://gohugo.io/"
name = '<i class="fa-fw fas fa-bookmark"></i> Hugo Documentation'
identifier = 'hugodoc'
url = 'https://gohugo.io/'
weight = 20
[[languages.en.menu.shortcuts]]
name = "<i class='fa-fw fas fa-bullhorn'></i> Credits"
pageRef = "/more/credits"
name = '<i class="fa-fw fas fa-bullhorn"></i> Credits'
pageRef = '/more/credits'
weight = 30
[[languages.en.menu.shortcuts]]
name = "<i class='fa-fw fas fa-tags'></i> Tags"
pageRef = "/tags"
name = '<i class="fa-fw fas fa-tags"></i> Tags'
pageRef = '/tags'
weight = 40
[languages.pir]
title = "Cap'n Hugo Relearrrn Theme"
title = 'Captain Hugo Relearrrn Theme'
weight = 2
languageName = "Arrr! Pirrratish"
languageName = 'Arrr! Pirrratish'
[[languages.pir.menu.shortcuts]]
name = "<i class='fa-fw fab fa-github'></i> GitHub Repo"
identifier = "ds"
url = "https://github.com/McShelby/hugo-theme-relearn"
name = '<i class="fa-fw fab fa-github"></i> GitHub Repo'
identifier = 'ds'
url = 'https://github.com/McShelby/hugo-theme-relearn'
weight = 10
[[languages.pir.menu.shortcuts]]
name = "<i class='fa-fw fas fa-camera'></i> Showcases"
pageRef = "/showcase"
name = '<i class="fa-fw fas fa-camera"></i> Showcases'
pageRef = '/showcase'
weight = 11
[[languages.pir.menu.shortcuts]]
name = "<i class='fa-fw fas fa-bookmark'></i> Cap'n Hugo Documentat'n"
identifier = "hugodoc"
url = "https://gohugo.io/"
name = '<i class="fa-fw fas fa-bookmark"></i> Captain Hugo Documentation'
identifier = 'hugodoc'
url = 'https://gohugo.io/'
weight = 20
[[languages.pir.menu.shortcuts]]
name = "<i class='fa-fw fas fa-bullhorn'></i> Crrredits"
pageRef = "/more/credits"
name = '<i class="fa-fw fas fa-bullhorn"></i> Crrredits'
pageRef = '/more/credits'
weight = 30
[[languages.pir.menu.shortcuts]]
name = "<i class='fa-fw fas fa-tags'></i> Arrr! Tags"
pageRef = "/tags"
name = '<i class="fa-fw fas fa-tags"></i> Arrr! Tags'
pageRef = '/tags'
weight = 40
{{< /multiconfig >}}
@ -138,10 +138,10 @@ To show pages only in the shortcuts menu you have two choices
1. Create a [headless branch bundle](https://gohugo.io/content-management/page-bundles/#headless-bundle), `_index.md` in its own folder with the below front matter. The branch bundle will **not** be contained in the sitemap.
{{< multiconfig fm=true file="content/showcase/_index.en.md" >}}
title = "Showcase"
title = 'Showcase'
[_build]
render = "always"
list = "never"
render = 'always'
list = 'never'
publishResources = true
{{< /multiconfig >}}
@ -149,13 +149,13 @@ To show pages only in the shortcuts menu you have two choices
{{< multiconfig fm=true file="content/more/_index.en.md" >}}
[_build]
render = "never"
list = "never"
render = 'never'
list = 'never'
publishResources = false
{{< /multiconfig >}}
The child page can be any type of content.
{{< multiconfig fm=true file="content/more/credits_index.en.md" >}}
title = "Credits"
title = 'Credits'
{{< /multiconfig >}}

34
exampleSite/content/configuration/sitemanagement/deployment/_index.en.md
View file

@ -1,10 +1,15 @@
+++
description = "Options for specific deployment needs"
options = ["disableExplicitIndexURLs"]
title = "Deployment Scenarios"
weight = 4
+++
## Offline Usage
The theme is usable offline. No internet connection is required to load your page. This is achieved by storing all dependencies within the theme.
No calls to 3rd party servers, no calling home, no tracking. Privacy friendly.
## Server Deployment
If your server deployment has no special requirements, you can skip this section and use the [standard Hugo options](https://gohugo.io/content-management/urls/).
@ -14,13 +19,13 @@ For special requirements, the theme is capable of different scenarios, requiring
### Public Web Server from Root
{{< multiconfig file=hugo >}}
baseURL = "https://example.com/"
baseURL = 'https://example.com/'
{{< /multiconfig >}}
### Public Web Server from Subdirectory
{{< multiconfig file=hugo >}}
baseURL = "https://example.com/mysite/"
baseURL = 'https://example.com/mysite/'
relativeURLs = false
{{< /multiconfig >}}
@ -34,31 +39,22 @@ If you are still using Hugo's `relref` shortcode (which you shouldn't), you will
The same settings as with any of the public web server scenarios or
{{< multiconfig file=hugo >}}
baseURL = "/"
baseURL = '/'
relativeURLs = true
{{< /multiconfig >}}
### File System
Exclusively use
Your generated site can be used headless without a HTTP server.
This can be achieved by using the `file://` protocol in your browser's address bar or by double click on a generated `*.html` file in your file navigation tool.
Use the following settings
{{< multiconfig file=hugo >}}
baseURL = "/"
baseURL = '/'
relativeURLs = true
{{< /multiconfig >}}
> [!note]
> Pages like `sitemap.xml` and `rss.xml`, and social media links will always use absolute URLs. They won't work with `relativeURLs=true`.
## URL Management
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default, the theme adds `index.html` to page links when `uglyURLs=false` (Hugo's default).
If you're only using a web server scenario and dislike this, you can reset to Hugo's default behavior by settings `disableExplicitIndexURLs=true`.
For the file system scenario, you are not allowed to change this value.
{{< multiconfig file=hugo >}}
[params]
disableExplicitIndexURLs = true
{{< /multiconfig >}}

1
exampleSite/content/configuration/sitemanagement/deployment/_index.pir.md
View file

@ -1,6 +1,5 @@
+++
description = "Options for specific deployment needs"
options = ["disableExplicitIndexURLs"]
title = "Deployment Scenarios"
weight = 4
+++

13
exampleSite/content/configuration/sitemanagement/meta/_index.en.md
View file

@ -1,7 +1,7 @@
+++
description = "What site-wide meta information can be set"
frontmatter = ["description"]
options = ["author.email", "author.name", "linkTitle"]
options = ["author.email", "author.name"]
title = "Meta Information"
weight = 3
+++
@ -25,15 +25,6 @@ The `title` will be used in meta information of your HTML.
title = 'Hugo Relearn Theme'
{{< /multiconfig >}}
## Menu Title
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} With the [default partials](configuration/appearance/branding#change-the-logo) for the logo, The site title will also be used for the text at the top of the sidebar. If you want to show a different text in the sidebar, you can overwrite `linkTitle`.
{{< multiconfig file=hugo >}}
[params]
linkTitle = "Relearn"
{{< /multiconfig >}}
## Site Description
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The theme shows a site description in various places, such as RSS feeds and meta tags. For this, it uses the `description` field from your home page's front matter.
@ -43,7 +34,7 @@ title = 'Hugo Relearn Theme'
When your page is shared on social media, you can set a site-wide image to display with the link
{{< multiconfig file=hugo >}}
images = [ "images/hero.png" ]
images = [ 'images/hero.png' ]
{{< /multiconfig >}}
## More Social Media Options

2
exampleSite/content/configuration/sitemanagement/meta/_index.pir.md
View file

@ -1,7 +1,7 @@
+++
description = "What site-wide meta information can be set"
frontmatter = ["description"]
options = ["author.email", "author.name", "linkTitle"]
options = ["author.email", "author.name"]
title = "Meta Information"
weight = 3
+++

16
exampleSite/content/configuration/sitemanagement/multilingual/_index.en.md
View file

@ -42,21 +42,21 @@ Here's how to make your site multilingual using [translations by file name](http
1. Set up languages in your `hugo.toml` file:
{{< multiconfig file=hugo >}}
defaultContentLanguage = "en"
defaultContentLanguage = 'en'
[languages]
[languages.en]
weight = 1
languageName = "English"
languageCode = "en"
title = "My Website"
languageName = 'English'
languageCode = 'en'
title = 'My Website'
[languages.pir]
weight = 2
languageName = "Pirrratish"
languageCode = "art-x-pir"
languageDirection = "rtl"
title = "Arrr, my Website"
languageName = 'Pirrratish'
languageCode = 'art-x-pir'
languageDirection = 'rtl'
title = 'Arrr, my Website'
{{< /multiconfig >}}
2. Duplicate your content files and add language codes to their file names:

10
exampleSite/content/configuration/sitemanagement/outputformats/_index.en.md
View file

@ -10,9 +10,9 @@ Enable print support to print entire chapters or the whole site. Add the `print`
{{< multiconfig file=hugo >}}
[outputs]
home = ["html", "rss", "print"]
section = ["html", "rss", "print"]
page = ["html", "rss", "print"]
home = ['html', 'rss', 'print']
section = ['html', 'rss', 'print']
page = ['html', 'rss', 'print']
{{< /multiconfig >}}
This adds a printer icon in the topbar. Clicking it switches to print preview, showing the page and its [visible subpages](configuration/content/hidden) in a printer-friendly format. Use your browser's print function to print or save as PDF.
@ -24,8 +24,8 @@ If you don't like the URLs, you can reconfigure `outputFormats.print` in your `h
{{< multiconfig file=hugo >}}
[outputFormats]
[outputFormats.print]
name= "print"
baseName = "index.print"
name= 'print'
baseName = 'index.print'
isHTML = true
mediaType = 'text/html'
permalinkable = false

2
exampleSite/content/configuration/sitemanagement/stableoutput/_index.en.md
View file

@ -18,6 +18,8 @@ To turn this off, set `disableGeneratorVersion=true`.
disableGeneratorVersion = true
{{< /multiconfig >}}
If you also want to turn off [Hugo's version meta tag](https://gohugo.io/getting-started/configuration/#disablehugogeneratorinject), use `disableHugoGeneratorInject=true`.
## Disabling IDs for Referenced Assets
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} The theme creates a unique ID for each build and adds it to each referenced asset's URL to make browsers not keep outdated cached assets.

2
exampleSite/content/development/_index.en.md
View file

@ -1,5 +1,5 @@
+++
menuPre = "<i class='fa-fw fab fa-git-alt'></i> "
menuPre = "<i class='fa-fw fas fa-code-pull-request'></i> "
hidden = true
title = "Development"
type = "chapter"

2
exampleSite/content/development/_index.pir.md
View file

@ -1,5 +1,5 @@
+++
menuPre = "<i class='fa-fw fas fa-code-branch'></i> "
menuPre = "<i class='fa-fw fas fa-code-pull-request'></i> "
hidden = true
title = "Development"
type = "chapter"

4
exampleSite/content/frontmatter/_index.pir.md
View file

@ -1,5 +1,5 @@
+++
title = "Frontmatter"
singulartitle = "Frontmatter"
title = "Front Matter"
singulartitle = "Front Matter"
+++
{{< piratify >}}

2
exampleSite/content/introduction/changelog/_index.en.md
View file

@ -4,7 +4,7 @@ description = "The detailed changelog"
disableToc = false
title = "Changelog"
type = "changelog"
weight = 3
weight = 4
+++
{{% pages showdivider="true" showhidden="true" hidevisible="true" showtitle="true" %}}

2
exampleSite/content/introduction/changelog/_index.pir.md
View file

@ -4,6 +4,6 @@ description = "The detailed changelog"
disableToc = false
title = "Changelog"
type = "changelog"
weight = 3
weight = 4
+++
{{< piratify >}}

4
exampleSite/content/introduction/quickstart/_index.en.md
View file

@ -37,7 +37,7 @@ You can [download the theme as a .zip file](https://github.com/McShelby/hugo-the
Then add this at the top of your `hugo.toml`
{{< multiconfig file=hugo >}}
theme = "hugo-theme-relearn"
theme = 'hugo-theme-relearn'
{{< /multiconfig >}}
### Use Hugo's Module System
@ -73,7 +73,7 @@ git submodule add --depth 1 https://github.com/McShelby/hugo-theme-relearn.git t
Then add this at the top of your `hugo.toml`
{{< multiconfig file=hugo >}}
theme = "hugo-theme-relearn"
theme = 'hugo-theme-relearn'
{{< /multiconfig >}}
## Create your Home Page

2
exampleSite/content/introduction/releasenotes/2/8.en.md
View file

@ -14,6 +14,6 @@ weight = -8
### New
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now supports favicons served from `static/images/` named as `favicon` or `logo` in SVG, PNG or ICO format [out of the box](configuration/appearance/branding#change-the-favicon). An overridden partial `layouts/partials/favicon.html` may not be necessary anymore in most cases.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now supports favicons served from `static/images/` named as `favicon` or `logo` in SVG, PNG or ICO format [out of the box](configuration/branding/logo#change-the-favicon). An overridden partial `layouts/partials/favicon.html` may not be necessary anymore in most cases.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can hide the table of contents menu for the whole site by setting the `disableToc` option in your `hugo.toml`. For an example see [the example configuration](configuration/reference).

8
exampleSite/content/introduction/releasenotes/3/0.en.md
View file

@ -16,7 +16,7 @@ weight = -0
- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} We have changed the default colors from the original Learn theme (the purple menu header) to the Relearn defaults (the light green menu header) as used in the official documentation.
This change will only affect your installation if you've not set the `themeVariant` parameter in your `hugo.toml`. [If you still want to use the Learn color variant](configuration/appearance/branding#theme-variant), you have to explicitly set `themeVariant="learn"` in your `hugo.toml`.
This change will only affect your installation if you've not set the `themeVariant` parameter in your `hugo.toml`. [If you still want to use the Learn color variant](configuration/branding/colors#theme-variant), you have to explicitly set `themeVariant="learn"` in your `hugo.toml`.
Note, that this will also affect your site if viewed with Internet Explorer 11 but in this case it can not be reconfigured as Internet Explorer does not support CSS variables.
@ -30,12 +30,12 @@ weight = -0
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} With this release you are now capable to define your own _dark mode_ variants.
To make this possible, we have introduced a lot more color variables you can use in [your color variants](configuration/appearance/branding#theme-variant). Your old variants will still work and don't need to be changed as appropriate fallback values are used by the theme. Nevertheless, the new colors allow for much more customization.
To make this possible, we have introduced a lot more color variables you can use in [your color variants](configuration/branding/colors#theme-variant). Your old variants will still work and don't need to be changed as appropriate fallback values are used by the theme. Nevertheless, the new colors allow for much more customization.
To see what's now possible, see the new variants `relearn-dark` and `neon` that are coming with this release.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} To make the creation of new variants easier for you, we've added a new interactive [theme variant generator](configuration/appearance/generator). This feature will not work with Internet Explorer 11.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} To make the creation of new variants easier for you, we've added a new interactive [theme variant generator](configuration/branding/generator). This feature will not work with Internet Explorer 11.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can now configure multiple color variants in your `hugo.toml`. In this case, the first variant is the default chosen on first view and a variant selector will be shown in the menu footer. See the [documentation](configuration/appearance/branding#multiple-variants) for configuration.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can now configure multiple color variants in your `hugo.toml`. In this case, the first variant is the default chosen on first view and a variant selector will be shown in the menu footer. See the [documentation](configuration/branding/colors#multiple-variants) for configuration.
Note, that the new variant selector will not work with Internet Explorer 11 as it does not support CSS variables. Therefore, the variant selector will not be displayed with Internet Explorer 11.

2
exampleSite/content/introduction/releasenotes/3/2.en.md
View file

@ -16,7 +16,7 @@ weight = -2
- {{% badge style="note" title=" " %}}Change{{% /badge %}} In this release the Mermaid JavaScript library will only be loaded on demand if the page contains a Mermaid shortcode or is using Markdown codefences. This changes the behavior of `disableMermaid` config option as follows: If a Mermaid shortcode or Markdown codefence is found, the option will be ignored and Mermaid will be loaded regardlessly.
The option is still useful in case you are using scripting to set up your graph. In this case no shortcode or Markdown codefence is involved and the library is not loaded by default. In this case you can set `disableMermaid=false` in your front matter to force the library to be loaded. See the [theme variant generator](configuration/appearance/generator) of the exampleSite for an example.
The option is still useful in case you are using scripting to set up your graph. In this case no shortcode or Markdown codefence is involved and the library is not loaded by default. In this case you can set `disableMermaid=false` in your front matter to force the library to be loaded. See the [theme variant generator](configuration/branding/generator) of the exampleSite for an example.
### New

2
exampleSite/content/introduction/releasenotes/3/3.en.md
View file

@ -10,6 +10,6 @@ weight = -3
### New
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Introduction of new CSS variables to set the font. The theme distinguishes between `--MAIN-font` for all content text and `--CODE-font` for inline or block code. There are additional overrides for all headings. See the [theme variant generator](configuration/appearance/generator) of the exampleSite for all available variables.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Introduction of new CSS variables to set the font. The theme distinguishes between `--MAIN-font` for all content text and `--CODE-font` for inline or block code. There are additional overrides for all headings. See the [theme variant generator](configuration/branding/generator) of the exampleSite for all available variables.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The new shortcode `swagger` is available to include a UI for REST OpenAPI specifications. See the [documentation](shortcodes/openapi) for available features. This feature will not work with Internet Explorer 11.

2
exampleSite/content/introduction/releasenotes/3/4.en.md
View file

@ -16,6 +16,6 @@ weight = -4
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} If you prefer expandable/collapsible menu items, you can now set `collapsibleMenu=true` in your `hugo.toml`. This will add arrows to all menu items that contain sub menus. The menu will expand/collapse without navigation if you click on an arrow.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can activate [print support](configuration/appearance/topbar#print-support) in your `hugo.toml` to add the capability to print whole chapters or even the complete site.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can activate [print support](configuration/sitemanagement/outputformats#print-support) in your `hugo.toml` to add the capability to print whole chapters or even the complete site.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Translation into Traditional Chinese.

2
exampleSite/content/introduction/releasenotes/4/2.en.md
View file

@ -18,7 +18,7 @@ weight = -2
- {{% badge style="note" title=" " %}}Change{{% /badge %}} Previously, if the [`tabs` shortcode](shortcodes/tabs) could not find a tab item because, the tabs ended up empty. Now the first tab is selected instead.
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The `landingPageURL` was removed from `hugo.toml`. You can safely remove this as well from your configuration as it is not used anymore. The theme will detect the landing page URL automatically and will point to the project's homepage. If you want to support a different link, overwrite the `logo.html` partial.
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The `landingPageURL` was removed from `hugo.toml`. You can safely remove this as well from your configuration as it is not used anymore. The theme will detect the landing page URL automatically and will point to the project's home page. If you want to support a different link, overwrite the `logo.html` partial.
### New

4
exampleSite/content/introduction/releasenotes/5/0.en.md
View file

@ -22,11 +22,11 @@ weight = -0
Your existing markdown files will still work like before and therefore you don't need to change anything after the upgrade. Nevertheless, it is recommended to adapt your existing markdown files to the new way as follows:
- for your home page, add the frontmatter parameter `archetype = "home"` and remove the leading heading
- for your home page, add the front matter parameter `archetype = "home"` and remove the leading heading
- for all files containing the deprecated front matter parameter `chapter = true`, replace it with `archetype = "chapter"` and remove the leading headings
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The frontmatter options `pre` / `post` were renamed to `menuPre` / `menuPost`. The old options will still be used if the new options aren't set. Therefore you don't need to change anything after the upgrade.
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The front matter options `pre` / `post` were renamed to `menuPre` / `menuPost`. The old options will still be used if the new options aren't set. Therefore you don't need to change anything after the upgrade.
### New

6
exampleSite/content/introduction/releasenotes/5/1.en.md
View file

@ -21,9 +21,9 @@ weight = -1
{{< multiconfig file=hugo >}}
[outputFormats]
[outputFormats.print]
name= "print"
baseName = "index"
path = "_print"
name= 'print'
baseName = 'index'
path = '_print'
isHTML = true
mediaType = 'text/html'
permalinkable = false

2
exampleSite/content/introduction/releasenotes/5/11.en.md
View file

@ -22,7 +22,7 @@ weight = -11
The default setting of `on`, in effect since 1.1.0, changed back to `off` as there was interference with scrolling on mobile and big pages.
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The theme is now capable to visually [adapt to your OS's light/dark mode setting](configuration/appearance/branding#adjust-to-os-settings).
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The theme is now capable to visually [adapt to your OS's light/dark mode setting](configuration/branding/colors#adjust-to-os-settings).
This is also the new default setting if you haven't configured `themeVariant` in your `hugo.toml`.

2
exampleSite/content/introduction/releasenotes/5/16.en.md
View file

@ -26,4 +26,4 @@ weight = -16
Additionally the `name` parameter was renamed to `title` but you don't need to change anything yet as the old name will be used as a fallback. Nevertheless you will get deprecation warnings while executing Hugo.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now optionally supports [separate favicons](configuration/appearance/branding#change-the-favicon) for light & dark mode.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now optionally supports [separate favicons](configuration/branding/logo#change-the-favicon) for light & dark mode.

2
exampleSite/content/introduction/releasenotes/5/19.en.md
View file

@ -14,7 +14,7 @@ weight = -19
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme has added two new color variants `zen-light` and `zen-dark`. Check it out!
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now [dispatches the custom event](configuration/appearance/branding#react-to-variant-switches-in-javascript) `themeVariantLoaded` on the `document` when the variant is fully loaded either initially or by switching the variant manually with the variant selector.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now [dispatches the custom event](configuration/branding/colors#react-to-variant-switches-in-javascript) `themeVariantLoaded` on the `document` when the variant is fully loaded either initially or by switching the variant manually with the variant selector.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme has updated its Mermaid dependency to 10.3.1. This adds support for the [sankey diagram type](shortcodes/mermaid#sankey) and now comes with full support for YAML inside Mermaid graphs (previously, the theme ignored explicit Mermaid theme settings in YAML).

15
exampleSite/content/introduction/releasenotes/5/23.en.md
View file

@ -16,14 +16,14 @@ weight = -23
{{< multiconfig file=hugo >}}
[params]
author = "Hugo"
author = 'Hugo'
{{< /multiconfig >}}
to
{{< multiconfig file=hugo >}}
[params]
author.name = "Hugo"
author.name = 'Hugo'
{{< /multiconfig >}}
- {{% badge style="note" title=" " %}}Change{{% /badge %}} Taxonomy [term pages](https://gohugo.io/content-management/taxonomies#add-custom-metadata-to-a-taxonomy-or-term) now add the breadcrumb for each listed page. If this gets too crowded for you, you can turn the breadcrumbs off in your `hugo.toml` by adding `disableTermBreadcrumbs=true`.
@ -36,7 +36,7 @@ weight = -23
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to adjust the menu width for your whole site. [See the docs](configuration/sidebar/width).
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release adds social media meta tags for the Open Graph protocol and Twitter Cards to your site. [See the docs](authoring/frontmatter/meta).
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release adds social media meta tags for the Open Graph protocol and Twitter Cards to your site. [See the docs](authoring/meta).
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release comes with additional sort options for the menu and the [`children` shortcode](shortcodes/children). Both will now accept the following values: `weight`, `title`, `linktitle`, `modifieddate`, `expirydate`, `publishdate`, `date`, `length` or `default` (adhering to Hugo's default sort order).
@ -56,10 +56,9 @@ weight = -23
| link | description |
| ---------------------------------- | ------------------------------------------- |
| `[generator](en/configuration/appearance/generator)` | absolute from your project root (multilang) |
| `[generator](/en/configuration/appearance/generator)`| absolute from your project root (multilang) |
| `[generator](configuration/appearance/generator)` | absolute from your current language root |
| `[generator](/configuration/appearance/generator)` | absolute from your current language root |
| `[generator](en/configuration/branding/generator)` | absolute from your project root (multilang) |
| `[generator](/en/configuration/branding/generator)`| absolute from your project root (multilang) |
| `[generator](configuration/branding/generator)` | absolute from your current language root |
| `[generator](/configuration/branding/generator)` | absolute from your current language root |
| `[generator](./../generator)` | relative from the current page |
| `[generator](../generator)` | relative from the current page |

4
exampleSite/content/introduction/releasenotes/5/24.en.md
View file

@ -18,7 +18,7 @@ weight = -24
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The front matter option `menuTitle` is now deprecated in favor for Hugo's own `linkTitle`. You don't need to change anything as the old `menuTitle` option is still supported.
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The light themes have a bit more contrast for content text and headings. Also the syntaxhighlighting was changed to the more colorful MonokaiLight. This brings the syntaxhighlighting in sync with the corresponding dark theme variants, which are using Monokai. If you dislike this, you can create your own color variant file as [described here](configuration/appearance/branding#modifying-variants).
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The light themes have a bit more contrast for content text and headings. Also the syntaxhighlighting was changed to the more colorful MonokaiLight. This brings the syntaxhighlighting in sync with the corresponding dark theme variants, which are using Monokai. If you dislike this, you can create your own color variant file as [described here](configuration/branding/colors#modifying-variants).
### New
@ -28,7 +28,7 @@ weight = -24
Please note that an image link will generate false negatives if the file resides in your `static` directory.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You now can configure additional options for every theme variant in your `hugo.toml`. This allows for optional [advanced functionality](configuration/appearance/branding#theme-variant-advanced). You don't need to change anything as the old configuration options will still work (but may generate warnings now).
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You now can configure additional options for every theme variant in your `hugo.toml`. This allows for optional [advanced functionality](configuration/branding/colors#theme-variant-advanced). You don't need to change anything as the old configuration options will still work (but may generate warnings now).
The advanced functionality allows you to set an explicit name for a theme variant and now allows for multiple auto mode variants that adjust to the light/dark preference of your OS settings.

2
exampleSite/content/introduction/releasenotes/5/3.en.md
View file

@ -16,4 +16,4 @@ weight = -3
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} [Image formatting](authoring/markdown#css-classes) has two new classes to align images to the `left` or `right`. Additionally, the already existing `inline` option is now documented.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Printing for the [`swagger` shortcode](shortcodes/openapi) was optimized to expand sections that are usually closed in interactive mode. This requires [print support](configuration/appearance/topbar#print-support) to be configured.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Printing for the [`swagger` shortcode](shortcodes/openapi) was optimized to expand sections that are usually closed in interactive mode. This requires [print support](configuration/sitemanagement/outputformats#print-support) to be configured.

2
exampleSite/content/introduction/releasenotes/5/4.en.md
View file

@ -12,7 +12,7 @@ weight = -4
- {{% badge style="note" title=" " %}}Change{{% /badge %}} [With the proper settings](configuration/sitemanagement/deployment) in your `hugo.toml` your page is now servable from the local file system using `file://` URLs.
Please note that the searchbox will only work for this if you reconfigure your outputformat for the homepage in your `hugo.toml` from `json` to `search`. The now deprecated `json` outputformat still works as before, so there is no need to reconfigure your installation if it is only served from `http://` or `https://`.
Please note that the searchbox will only work for this if you reconfigure your outputformat for the home page in your `hugo.toml` from `json` to `search`. The now deprecated `json` outputformat still works as before, so there is no need to reconfigure your installation if it is only served from `http://` or `https://`.
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The [`button` shortcode](shortcodes/button) has a new parameter `target` to set the destination frame/window for the URL to open. If not given, it defaults to a new window/tab for external URLs or is not set at all for internal URLs. Previously even internal URLs where opened in a new window/tab.

12
exampleSite/content/introduction/releasenotes/5/9.en.md
View file

@ -19,10 +19,10 @@ weight = -9
1. Make the page file a [headless branch bundle](https://gohugo.io/content-management/page-bundles/#headless-bundle) (contained in its own subdirectory and called `_index.md`) and add the following front matter configuration to the file (see exampleSite's `content/showcase/_index.en.md`). This causes its content to **not** be ontained in the sitemap.
{{< multiconfig fm=true >}}
title = "Showcase"
title = 'Showcase'
[_build]
render = "always"
list = "never"
render = 'always'
list = 'never'
publishResources = true
{{< /multiconfig >}}
@ -30,15 +30,15 @@ weight = -9
{{< multiconfig fm=true >}}
[_build]
render = "never"
list = "never"
render = 'never'
list = 'never'
publishResources = false
{{< /multiconfig >}}
In this case, the file itself can be a branch bundle, leaf bundle or simple page (see exampleSite's `content/more/credits.en.md`). This causes its content to be contained in the sitemap.
{{< multiconfig fm=true >}}
title = "Credits"
title = 'Credits'
{{< /multiconfig >}}
### Change

6
exampleSite/content/introduction/releasenotes/6/2.en.md
View file

@ -18,8 +18,8 @@ weight = -2
### New
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} If you are running Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.132.0{{% /badge %}} or later, the theme is now capable to print [GitHub styled alerts](authoring/markdown#github-styled-alerts).
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} If you are running Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.132.0{{% /badge %}} or later, the theme is now capable to print [GitHub alerts](authoring/markdown#github-alerts).
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} To support new severity levels for GitHub styled alerts, all shortcodes that support severity levels with their `style` parameter were expanded with the new severities `caution` and `important` and the `color` parameter was expanded with `cyan` and `magenta`. Please note, that coloring and icons of severities may defer from the [display you see on GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} To support new severity levels for GitHub alerts, all shortcodes that support severity levels with their `style` parameter were expanded with the new severities `caution` and `important` and the `color` parameter was expanded with `cyan` and `magenta`. Please note, that coloring and icons of severities may defer from the [display you see on GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} To support new severity levels for GitHub styled alerts, the new severities and their according colors are also available as CSS variables `BOX-MAGENTA-color`, `BOX-MAGENTA-TEXT-color`, `BOX-CAUTION-color`, `BOX-CAUTION-TEXT-color`, `BOX-CYAN-color`, `BOX-CYAN-TEXT-color`, `BOX-IMPORTANT-color`, `BOX-IMPORTANT-TEXT-color`. You don't need to change anything in your custom color stylesheet as appropriate default colors will be used.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} To support new severity levels for GitHub alerts, the new severities and their according colors are also available as CSS variables `BOX-MAGENTA-color`, `BOX-MAGENTA-TEXT-color`, `BOX-CAUTION-color`, `BOX-CAUTION-TEXT-color`, `BOX-CYAN-color`, `BOX-CYAN-TEXT-color`, `BOX-IMPORTANT-color`, `BOX-IMPORTANT-TEXT-color`. You don't need to change anything in your custom color stylesheet as appropriate default colors will be used.

8
exampleSite/content/introduction/releasenotes/7/0.en.md
View file

@ -19,7 +19,7 @@ weight = -0
- suffered from poor build performance for sites with 1000 or more pages
- reinvented the wheel instead of using available Hugo mechanisms
_What do I gain_, you may ask. A significant performance boost during build! Usually, the build time has been cut at least in half for bigger sites. It is now possible to build even larger sites with 5000 or more pages. This was previously almost impossible due to rapidly increasing build time with the more pages you've introduced. For even bigger sites, the theme now has [configurable performance optimizations](configuration/sidebar/navigationmenu#expander-for-nested-sections) - at the price of feature limitations.
_What do I gain_, you may ask. A significant performance boost during build! Usually, the build time has been cut at least in half for bigger sites. It is now possible to build even larger sites with 5000 or more pages. This was previously almost impossible due to rapidly increasing build time with the more pages you've introduced. For even bigger sites, the theme now has [configurable performance optimizations](authoring/frontmatter/navigationmenu#expander-for-nested-sections) - at the price of feature limitations.
If you haven't done customizations to any partials, you can update right away.
@ -38,7 +38,7 @@ weight = -0
{{< multiconfig file=hugo >}}
[outputs]
home = ["html", "rss", "print"]
home = ['html', 'rss', 'print']
{{< /multiconfig >}}
After that, your build will succeed but will most likely cause new defaults to be applied. With no further settings, in-page search, search popup and dedicated search page are all active by default. This can be reconfigured.
@ -73,7 +73,7 @@ weight = -0
This is to avoid usage of the theme's branding throughout the web in non-modified installations.
In addition, the default text for the logo partial is now [taken from the `linkTitle` setting](configuration/sitemanagement/meta#site-title) of your `hugo.toml`.
In addition, the default text for the logo partial is now [taken from the `linkTitle` setting](configuration/sidebar/headerfooter#title) of your `hugo.toml`.
## New
@ -88,7 +88,7 @@ weight = -0
Also, a lot of previously undocumented features are now included, namely
- the [hidden pages](configuration/content/hidden) feature
- options of the [navigation menu](configuration/sidebar/navigationmenu)
- options of the [navigation menu](authoring/frontmatter/navigationmenu)
- configuring [breadcrumb, titles](configuration/content/titles) and [headings](configuration/content/headings) of your content
- [options for using links](configuration/content/linking)
- adding [custom output formats](configuration/customization/outputformats)

2
exampleSite/content/introduction/releasenotes/_index.en.md
View file

@ -4,7 +4,7 @@ description = "What's new in this version"
disableToc = false
title = "What's New"
type = "releasenotes"
weight = 2
weight = 3
+++
{{% pages showdivider="true" showhidden="true" hidevisible="true" showtitle="true" %}}

2
exampleSite/content/introduction/releasenotes/_index.pir.md
View file

@ -4,6 +4,6 @@ description = "What's new in this version"
disableToc = false
title = "What's New"
type = "releasenotes"
weight = 2
weight = 3
+++
{{< piratify >}}

23
exampleSite/content/introduction/tools/_index.en.md Normal file
View file

@ -0,0 +1,23 @@
+++
description = "All about supported 3rd party tools"
title = "Tool Integration"
weight = 2
+++
## Front Matter CMS
The theme supports the great [VSCode Front Matter CMS extension](https://github.com/estruyf/vscode-front-matter) which provides on-premise CMS capabilties to Hugo.
For that, the theme provides a snippets file so you can use shortcodes from inside the Front Matter CMS.
Currently only English and German is supported.
To use them in your Front Matter CMS, put a reference into your `frontmatter.json` like this
````json {title="frontmatter.json"}
{
"frontMatter.extends": [
"./vscode-frontmatter/snippets.en.json"
]
}
````

6
exampleSite/content/introduction/tools/_index.pir.md Normal file
View file

@ -0,0 +1,6 @@
+++
description = "All about supported 3rd party tools"
title = "Tool Integration"
weight = 2
+++
{{< piratify >}}

2
exampleSite/content/shortcodes/children/_index.pir.md
View file

@ -1,5 +1,7 @@
+++
alwaysopen = false
frontmatter = ["ordersectionsby"]
options = ["ordersectionsby"]
description = "List th' child planks on a plank"
title = "Children"
+++

16
exampleSite/content/shortcodes/highlight.en.md
View file

@ -110,21 +110,35 @@ If used together with wrapping of long lines, use this recommended settings. Oth
You can disable wrapping by setting `highlightWrap=false` or by setting the [`wrap` parameter](#parameter) individually for each code block.
{{< multiconfig fm=true >}}
highlightWrap=false
{{< /multiconfig >}}
### Copy to Clipboard for Inline Code
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default inline code has a button to copy the code to the clipboard.
If you want to disable this feature, set `disableInlineCopyToClipBoard=true`.
{{< multiconfig file=hugo >}}
[params]
disableInlineCopyToClipBoard = true
{{< /multiconfig >}}
### Copy to Clipboard for Block Code
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default block code has a button to copy the code to the clipboard that is only visible on hover.
Set `disableHoverBlockCopyToClipBoard=true` to disable the hover effect and always show the button.
{{< multiconfig file=hugo >}}
[params]
disableHoverBlockCopyToClipBoard = true
{{< /multiconfig >}}
### Setting a Specific Color Scheme
You can configure the color style used for code blocks in your [color variants stylesheet](configuration/appearance/branding#change-syntax-highlighting) file using the `--CODE-theme` variable. This requires further configuration as described in the above link.
You can configure the color style used for code blocks in your [color variants stylesheet](configuration/branding/modules#change-syntax-highlighting) file using the `--CODE-theme` variable. This requires further configuration as described in the above link.
## Examples

6
exampleSite/content/shortcodes/include/index.en.md
View file

@ -55,7 +55,11 @@ If not set or empty, any unresolved link is written as given into the resulting
Please note that this can not resolve files inside of your `static` directory. The file must be a resource of the page or the site.
Link warnings are also available for [images & links](configuration/content/linking#enabling-link-and-image-link-warnings) and the [openapi](shortcodes/openapi#enabling-link-warnings) shortcode.
Link warnings are also available for [images & links](authoring/frontmatter/linking#enabling-link-and-image-link-warnings) and the [openapi](shortcodes/openapi#enabling-link-warnings) shortcode.
{{< multiconfig fm=true >}}
include.errorlevel = 'warning'
{{< /multiconfig >}}
## Examples

18
exampleSite/content/shortcodes/math.en.md
View file

@ -5,8 +5,6 @@ options = ["customMathJaxURL", "math", "math.force", "mathJaxInitialize"]
title = "Math"
+++
You can use [pure Markdown](authoring/markdown#subscript-and-superscript) for writing simple math expressions.
If this is not enough, the `math` shortcode helps you rendering math and chemical formulae using the [MathJax](https://mathjax.org/) library.
{{< math align="center" >}}
@ -54,6 +52,8 @@ $$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \
{{% /tab %}}
{{< /tabs >}}
You can also use [pure Markdown](authoring/markdown#subscript-and-superscript) for writing simple math expressions.
Passthrough syntax is only available by [further configuration](#passthrough-configuration) and has limited features as it does not provide any of the below parameter. Nevertheless, it is widely available in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.
### Parameter
@ -73,9 +73,8 @@ You can overwrite the settings by providing a JSON object in `mathJaxInitialize`
Keep in mind that initialization settings of your pages front matter overwrite all settings of your configuration options.
{{< multiconfig file=hugo >}}
[params]
mathJaxInitialize = "{ \"chtml\": { \"displayAlign\": \"left\" }, { \"tex\": { \"inlineMath\": [[\"\\(\", \"\\)\"], [\"@\", \"@\"]], displayMath: [[\"\\[\", \"\\]\"], [\"@@\", \"@@\"]] }, \"options\": { \"enableMenu\": false }"
{{< multiconfig fm=true >}}
mathJaxInitialize = '{ "chtml": { "displayAlign": "left" }, { "tex": { "inlineMath": [["\(", "\)"], ["@", "@"]], displayMath: [["\[", "\]"], ["@@", "@@"]] }, "options": { "enableMenu": false }'
{{< /multiconfig >}}
### Loading an External Version of the MathJax Library
@ -84,9 +83,8 @@ mathJaxInitialize = "{ \"chtml\": { \"displayAlign\": \"left\" }, { \"tex\": { \
In case you want do use a different version of the MathJax library but don't want to override the shipped version, you can set `customMathJaxURL` to the URL of the external MathJax library.
{{< multiconfig file=hugo >}}
[params]
customMathJaxURL = "https://unpkg.com/mathjax/es5/tex-mml-chtml.js"
{{< multiconfig fm=true >}}
customMathJaxURL = 'https://unpkg.com/mathjax/es5/tex-mml-chtml.js'
{{< /multiconfig >}}
### Force Loading of the MathJax Library
@ -97,6 +95,10 @@ You can force loading the MathJax library if no shortcode or codefence was used
Instead of `math=true` you can also use the alias `math.force=true`.
{{< multiconfig fm=true >}}
math = true
{{< /multiconfig >}}
### Passthrough Configuration
You can use your math without enclosing it in a shortcode or codefence by using a [passthrough configuration](https://gohugo.io/content-management/mathematics/#step-1)

19
exampleSite/content/shortcodes/mermaid.en.md
View file

@ -73,6 +73,10 @@ By default this is disabled. Set `mermaidZoom=true` to enable it.
Individual settings of a graphs [`zoom` parameter](#parameter) have precedence over the page's front matter and configuration options in that order.
{{< multiconfig fm=true >}}
mermaidZoom = true
{{< /multiconfig >}}
### Providing Initialization Options for the Mermaid Library
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The Mermaid library is configured with default settings for initialization.
@ -83,15 +87,18 @@ Keep in mind that initialization settings of your pages front matter overwrite a
In addition, you can merge settings for each individual graph through [diagram directives](https://mermaid-js.github.io/mermaid/#/directives?id=directives) on top of the settings of your page's front matter or configuration options.
{{< multiconfig fm=true >}}
mermaidInitialize = '{ "securityLevel": "loose" }'
{{< /multiconfig >}}
### Loading an External Version of the Mermaid Library
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The theme uses the shipped Mermaid library by default.
In case you want do use a different version of the Mermaid library but don't want to override the shipped version, you can set `customMermaidURL` to the URL of the external Mermaid library.
{{< multiconfig file=hugo >}}
[params]
customMermaidURL = "https://unpkg.com/mermaid/dist/mermaid.min.js"
{{< multiconfig fm=true >}}
customMermaidURL = 'https://unpkg.com/mermaid/dist/mermaid.min.js'
{{< /multiconfig >}}
### Force Loading of the Mermaid Library
@ -100,9 +107,13 @@ customMermaidURL = "https://unpkg.com/mermaid/dist/mermaid.min.js"
You can force loading the Mermaid library if no shortcode or codefence was used by setting `mermaid.force=true`. If a shortcode or codefence was found, this option has no effect. This comes handy in case you are using scripting to render a graph.
{{< multiconfig fm=true >}}
mermaid.force = true
{{< /multiconfig >}}
### Setting a Specific Mermaid Theme
While you can configure the Mermaid theme to render your graph by using one of the [initialization options](#providing-initialization-options-for-the-mermaid-library), the recommended way is to set the default value using the `--MERMAID-theme` variable in your [color variant stylesheet](configuration/appearance/generator). This allows your graphs to look pretty when the user switches the color variant.
While you can configure the Mermaid theme to render your graph by using one of the [initialization options](#providing-initialization-options-for-the-mermaid-library), the recommended way is to set the default value using the `--MERMAID-theme` variable in your [color variant stylesheet](configuration/branding/generator). This allows your graphs to look pretty when the user switches the color variant.
## Examples

4
exampleSite/content/shortcodes/notice.en.md
View file

@ -54,7 +54,7 @@ It is all about the boxes.
{{% /tab %}}
{{< /tabs >}}
Callout syntax has limited features as it does not provide all of the below parameter. Nevertheless, it is widely available in other Markdown parsers like with [GitHub styled alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) or [Obsidian callouts](https://help.obsidian.md/Editing+and+formatting/Callouts#Change+the+title) and therefore is the recommend syntax for generating portable Markdown.
Callout syntax has limited features as it does not provide all of the below parameter. Nevertheless, it is widely available in other Markdown parsers like with [GitHub alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) or [Obsidian callouts](https://help.obsidian.md/Editing+and+formatting/Callouts#Change+the+title) and therefore is the recommend syntax for generating portable Markdown.
If you want to display a transparent expandable box without any border, you can also use the [`expand` shortcode](/shortcodes/expand).
@ -78,7 +78,7 @@ If you want to display a transparent expandable box without any border, you can
{{< multiconfig file=hugo >}}
[params]
boxStyle = [
{ identifier = "magic", i18n = "", title = "Magic", icon = "rainbow", color = "gold" }
{ identifier = 'magic', i18n = '', title = 'Magic', icon = 'rainbow', color = 'gold' }
]
{{< /multiconfig >}}

19
exampleSite/content/shortcodes/openapi/_index.en.md
View file

@ -32,7 +32,7 @@ The `openapi` shortcode displays your OpenAPI / Swagger specifications using the
If you want to print out (or generate a PDF) from your OpenAPI documentation, don't initiate printing directly from the page because the elements are optimized for interactive usage in a browser.
Instead, open the [print preview](configuration/appearance/topbar#print-support) in your browser and initiate printing from that page. This page is optimized for reading and expands most of the available sections.
Instead, open the [print preview](authoring/frontmatter/topbar) in your browser and initiate printing from that page. This page is optimized for reading and expands most of the available sections.
### Parameter
@ -50,7 +50,11 @@ If not set or empty, any unresolved link is written as given into the resulting
Please note that this can not resolve files inside of your `static` directory. The file must be a resource of the page or the site.
Link warnings are also available for [images & links](configuration/content/linking#enabling-link-and-image-link-warnings) and the [include](shortcodes/include#enabling-link-warnings) shortcode.
Link warnings are also available for [images & links](authoring/frontmatter/linking#enabling-link-and-image-link-warnings) and the [include](shortcodes/include#enabling-link-warnings) shortcode.
{{< multiconfig fm=true >}}
openapi.errorlevel = 'warning'
{{< /multiconfig >}}
### Loading an External Version of the Swagger UI Library
@ -58,9 +62,8 @@ Link warnings are also available for [images & links](configuration/content/link
In case you want do use a different version of the Swagger UI library but don't want to override the shipped version, you can set `customOpenapiURL` to the URL of the external Swagger UI library.
{{< multiconfig file=hugo >}}
[params]
customOpenapiURL = "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
{{< multiconfig fm=true >}}
customOpenapiURL = 'https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js'
{{< /multiconfig >}}
### Force Loading of the Swagger UI Library
@ -69,9 +72,13 @@ customOpenapiURL = "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
You can force loading the Swagger UI library if no shortcode or codefence was used by setting `openapi.force=true`. If a shortcode or codefence was found, the option has no effect. This comes handy in case you are using scripting to render a spec.
{{< multiconfig fm=true >}}
openapi.force = true
{{< /multiconfig >}}
### Setting a Specific Swagger UI Theme
The recommended way to configure your Swagger UI theme is to set the default value using the `--OPENAPI-theme` variable in your [color variant stylesheet](configuration/appearance/generator). This allows your specs to look pretty when the user switches the color variant.
The recommended way to configure your Swagger UI theme is to set the default value using the `--OPENAPI-theme` variable in your [color variant stylesheet](configuration/branding/generator). This allows your specs to look pretty when the user switches the color variant.
## Example

2
exampleSite/content/shortcodes/siteparam.en.md
View file

@ -64,7 +64,7 @@ Now values containing Markdown will be formatted correctly.
{{< multiconfig file=hugo >}}
[params]
[params.siteparam.test]
text = "A **nested** parameter <b>with</b> formatting"
text = 'A **nested** parameter <b>with</b> formatting'
{{< /multiconfig >}}
```go

24
hugo.toml
View file

@ -1,15 +1,15 @@
[module]
[module.hugoVersion]
min = "0.126.0"
min = '0.126.0'
[mediaTypes]
[mediaTypes."text/javascript"]
suffixes = ["js"]
[mediaTypes.'text/javascript']
suffixes = ['js']
[outputFormats]
[outputFormats.print]
name= "print"
baseName = "index.print"
name= 'print'
baseName = 'index.print'
isHTML = true
mediaType = 'text/html'
permalinkable = false
@ -17,8 +17,8 @@
# unused since 7.0.0 but left in here to generate warnings
[outputFormats.search]
name= "search"
baseName = "index.searchindex"
name= 'search'
baseName = 'index.searchindex'
isHTML = true
mediaType = 'text/html'
permalinkable = false
@ -26,8 +26,8 @@
# unused since 7.0.0 but left in here to generate warnings
[outputFormats.searchpage]
name= "searchpage"
baseName = "index.searchpage"
name= 'searchpage'
baseName = 'index.searchpage'
isHTML = true
mediaType = 'text/html'
permalinkable = false
@ -35,8 +35,8 @@
[params.relearn.dependencies]
[params.relearn.dependencies.math]
name = "Math"
name = 'Math'
[params.relearn.dependencies.mermaid]
name = "Mermaid"
name = 'Mermaid'
[params.relearn.dependencies.openapi]
name = "OpenApi"
name = 'OpenApi'

2
layouts/partials/version.txt
View file

@ -1 +1 @@
6.4.0+21e80798f30a5a86c5b2cdccb1990c7ee9adaf97
6.4.0+dcaeb1386051e27116d0a4039e26d832d9985c9e

60
theme.toml
View file

@ -1,39 +1,39 @@
name = "Relearn"
license = "MIT"
licenselink = "https://github.com/McShelby/hugo-theme-relearn/blob/main/LICENSE"
description = "A theme for Hugo designed for documentation"
homepage = "https://github.com/McShelby/hugo-theme-relearn"
demosite = "https://mcshelby.github.io/hugo-theme-relearn"
tags = ["dark", "dark mode", "docs", "light", "multilingual", "responsive"]
name = 'Relearn'
license = 'MIT'
licenselink = 'https://github.com/McShelby/hugo-theme-relearn/blob/main/LICENSE'
description = 'A theme for Hugo designed for documentation'
homepage = 'https://github.com/McShelby/hugo-theme-relearn'
demosite = 'https://mcshelby.github.io/hugo-theme-relearn'
tags = ['dark', 'dark mode', 'docs', 'light', 'multilingual', 'responsive']
features = [
"alerts",
"badges", "breadcrumbs", "boxes", "buttons",
"callouts", "categories", "chemical formulae", "customizable", "color variants",
"dark", "dark mode", "docs", "documentation",
"expand",
"favicon", "file inclusion", "file system support", "font awesome", "front matter cms",
"gfm", "github flavored markdown",
"hidden pages",
"i18n", "icons", "image resizing", "include",
"light", "lightbox", "logo",
"math", "mathjax", "menu", "mermaid", "multilingual", "mobile",
"nested menus", "nested sections", "notice",
"oas", "offline usable", "openapi", "open graph",
"print", "printable",
"responsive", "rss", "rtl",
"schema", "search", "search page", "sidebar", "sitemap", "subtheme", "swagger", "swaggerui", "syntax highlighting",
"table of contents", "tab", "tabs", "tags", "taxonomy", "themeable", "themes", "toc", "topbar buttons", "twitter cards"
'alerts',
'badges', 'breadcrumbs', 'boxes', 'buttons',
'callouts', 'categories', 'chemical formulae', 'customizable', 'color variants',
'dark', 'dark mode', 'docs', 'documentation',
'expand',
'favicon', 'file inclusion', 'file system support', 'font awesome', 'front matter cms',
'gfm', 'github flavored markdown',
'hidden pages',
'i18n', 'icons', 'image resizing', 'include',
'light', 'lightbox', 'logo',
'math', 'mathjax', 'menu', 'mermaid', 'multilingual', 'mobile',
'nested menus', 'nested sections', 'notice',
'oas', 'offline usable', 'openapi', 'open graph',
'print', 'printable',
'responsive', 'rss', 'rtl',
'schema', 'search', 'search page', 'sidebar', 'sitemap', 'subtheme', 'swagger', 'swaggerui', 'syntax highlighting',
'table of contents', 'tab', 'tabs', 'tags', 'taxonomy', 'themeable', 'themes', 'toc', 'topbar buttons', 'twitter cards'
]
[module]
[module.hugoVersion]
min = "0.126.0"
min = '0.126.0'
[author]
name = "Sören Weber"
homepage = "https://github.com/McShelby"
name = 'Sören Weber'
homepage = 'https://github.com/McShelby'
[original]
author = "Mathieu Cornic"
homepage = "https://learn.netlify.app"
repo = "https://github.com/matcornic/hugo-theme-learn"
author = 'Mathieu Cornic'
homepage = 'https://learn.netlify.app'
repo = 'https://github.com/matcornic/hugo-theme-learn'