docs: split config and add more comments #1003

This commit is contained in:
Sören Weber 2025-02-13 22:25:56 +01:00
parent cd4a8363be
commit 1eaa287faa
No known key found for this signature in database
GPG key ID: BEC6D55545451B6D
8 changed files with 314 additions and 296 deletions

View file

@ -3,14 +3,17 @@
# set it like 'https://example.com/mysite/'
baseURL = 'https://example.com/'
# required value to serve this page from a webserver AND the file system;
# required to be set to `true` to serve this page from a webserver AND the file system;
# if you set this value to `true`, `baseURL` must not contain a subdirectory;
# if you don't want to serve your page from the file system, you can also set this value
# to false
# to `false`
relativeURLs = true # true -> rewrite all site-relative URLs (those with a leading slash) to be relative to the current content
# if you set uglyURLs to false, this theme will append 'index.html' to any page bundle link
# if you set uglyURLs to `false`, this theme will append 'index.html' to any page bundle link
# so your site can be also served from the file system; if you don't want that,
# set disableExplicitIndexURLs=true in the [params] section
# set `disableExplicitIndexURLs=true` in the [params] section,
# if st to `true`, adjusting the link is not necessary, so `disableExplicitIndexURLs` has
# no effect
uglyURLs = false # true -> basic/index.html -> basic.html
# the directory where Hugo reads the themes from; this is specific to your
@ -26,303 +29,27 @@ 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'
# Don't use any auto-generated summaries
# don't use any auto-generated summaries
summaryLength = 10
# add showcase-specific output formats
[outputs]
# add `print` to home, section and page to activate the feature to print whole
# chapters
# `print` - activate the themes feature to print whole chapters or leaf pages
home = ['html', 'rss', 'print']
section = ['html', 'rss', 'print']
page = ['html', 'rss', 'print']
[markup]
[markup.highlight]
# line numbers in a table layout will shift if code is wrapping, so better
# not use it; visually both layouts have the same look and behavior
lineNumbersInTable = false
# the shipped variants come with their own modified chroma syntax highlighting
# stylesheets which are linked in your generated HTML pages; you can use Hugo to generate
# own stylesheets to your liking and use them in your variant;
# if you want to use Hugo's internal styles instead of the shipped stylesheets:
# - remove `noClasses` or set `noClasses = true`
# - set `style` to a predefined style name
# note: with using the internal styles, the `--CODE-theme` setting in your variant
# stylesheet will be ignored and the internal style is used for all variants and
# even print
noClasses = false
# style = 'tango'
[markup.goldmark]
# this is required for the themes docs to make the piratify shortcode work
duplicateResourceFiles = true
# activated for this showcase to use HTML and JavaScript; decide on your own needs;
# if in doubt, remove this line
renderer.unsafe = true
[markup.goldmark.extensions]
strikethrough = false
# use Markdown extensions for this showcase
[markup.goldmark.extensions.extras]
[markup.goldmark.extensions.extras.delete]
enable = true
[markup.goldmark.extensions.extras.insert]
enable = true
[markup.goldmark.extensions.extras.mark]
enable = true
[markup.goldmark.extensions.extras.subscript]
enable = true
[markup.goldmark.extensions.extras.superscript]
enable = true
[markup.goldmark.extensions.passthrough]
enable = true
[markup.goldmark.extensions.passthrough.delimiters]
# the settings chosen here match the default initialization
# of the MathJax library chosen by the theme;
# if you want to adjust to different values you also need
# to set them in `[params] mathJaxInitialize`
inline = [['\(', '\)'], ['$', '$']]
block = [['\[', '\]'], ['$$', '$$']]
# showcase of the menu shortcuts; you can use relative URLs linking
# to your content or use fully-qualified URLs to link outside of
# your project
[languages]
[languages.en]
title = 'Hugo Relearn Theme'
weight = 1
languageCode = 'en'
languageName = 'English'
# Language dependent settings:
# Use case https://gohugo.io/content-management/multilingual/#translation-by-content-directory
#contentDir = 'content/en'
[languages.en.params]
landingPageName = '<i class="fa-fw fas fa-home"></i> Home'
[[languages.en.menu.shortcuts]]
pre = '<i class="fa-fw fab fa-github"></i> '
name = 'GitHub Repo'
url = 'https://github.com/McShelby/hugo-theme-relearn'
weight = 10
[[languages.en.menu.shortcuts]]
name = 'Showcases'
pageRef = '/showcase'
weight = 20
[[languages.en.menu.shortcuts]]
name = 'Credits'
pageRef = '/more/credits'
weight = 30
[[languages.en.menu.shortcuts]]
pre = '<i class="fa-fw fas fa-tags"></i> '
name = 'Tags'
pageRef = '/tags'
weight = 40
[[languages.en.menu.shortcuts]]
pre = '<i class="fa-fw fas fa-layer-group"></i> '
name = 'Categories'
pageRef = '/categories'
weight = 50
[[languages.en.menu.devshortcuts]]
identifier = 'devshortcuts'
name = 'Dev Shortcuts'
[[languages.en.menu.devshortcuts]]
parent = 'devshortcuts'
pre = '<i class="fa-fw fab fa-hackerrank"></i> '
name = 'Hugo'
url = 'https://gohugo.io/documentation/'
weight = 1
[[languages.en.menu.devshortcuts]]
parent = 'devshortcuts'
pre = '<i class="fa-fw fas fa-puzzle-piece"></i> '
identifier = 'theme'
name = 'Theme'
weight = 2
[[languages.en.menu.devshortcuts.params]]
alwaysopen = true
[[languages.en.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-gears"></i> '
identifier = 'configoptions'
pageRef = 'configuration/reference'
weight = 1
[[languages.en.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fab fa-markdown"></i> '
identifier = 'frontmatter'
title = 'Front Matter Reference'
pageRef = 'authoring/frontmatter/reference#annotated-front-matter'
weight = 2
[[languages.en.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-image"></i> '
identifier = 'screenshotframe'
title = 'Screenshot Frame'
pageRef = 'images/hero.zip'
weight = 3
[[languages.en.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-wand-magic-sparkles"></i> '
title = 'Maaagic Download'
pageRef = 'images/magic.gif?download'
weight = 4
# this is ourrr way t' showcase th' multilang settings by
# doing autotrrranlat'n of th' english content; we are
# lazy and don't supporrt furrrther trrranslations; arrr,
# don't take it t' serrrious, fello'; it's prrretty hacky and:
# NOT MEANT FER PRRRODUCTION! ARRR!
[languages.pir]
title = "Cap'n Hugo Relearrrn Theme"
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 ☠'
# Language dependent settings:
# Use case https://gohugo.io/content-management/multilingual/#translation-by-content-directory
#contentDir = 'content/pir'
[languages.pir.params]
landingPageName = '<i class="fa-fw fas home"></i> Arrr! Home'
errorignore = ['.*']
[[languages.pir.menu.shortcuts]]
pre = '<i class="fa-fw fab fa-github"></i> '
name = 'GitHub Repo'
url = 'https://github.com/McShelby/hugo-theme-relearn'
weight = 10
[[languages.pir.menu.shortcuts]]
pre = '<i class="fa-fw fas fa-camera"></i> '
name = 'Showcases'
pageRef = '/showcase'
weight = 20
[[languages.pir.menu.shortcuts]]
name = 'Crrredits'
pageRef = '/more/credits'
weight = 30
[[languages.pir.menu.shortcuts]]
name = 'Arrr! Tags'
pageRef = '/tags'
weight = 40
[[languages.pir.menu.shortcuts]]
pre = '<i class="fa-fw fas fa-layer-group"></i> '
name = 'Categorrries'
pageRef = '/categories'
weight = 50
[[languages.pir.menu.devshortcuts]]
identifier = 'devshortcuts'
name = 'Dev Shortcuts'
[[languages.pir.menu.devshortcuts]]
parent = 'devshortcuts'
pre = '<i class="fa-fw fab fa-hackerrank"></i> '
name = "Cap'n Hugo"
url = 'https://gohugo.io/documentation/'
weight = 1
[[languages.pir.menu.devshortcuts]]
parent = 'devshortcuts'
pre = '<i class="fa-fw fas fa-puzzle-piece"></i> '
identifier = 'theme'
name = "Th' Theme"
weight = 2
[[languages.pir.menu.devshortcuts.params]]
alwaysopen = true
[[languages.pir.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-gears"></i> '
identifier = 'configoptions'
pageRef = 'configuration/reference'
weight = 1
[[languages.pir.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fab fa-markdown"></i> '
identifier = 'frontmatter'
title = 'Front Matter Reference'
pageRef = 'authoring/frontmatter/reference#annotated-front-matter'
weight = 2
[[languages.pir.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-image"></i> '
identifier = 'screenshotframe'
title = 'Screenshot Frame'
pageRef = 'images/hero.zip'
weight = 3
[[languages.pir.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-wand-magic-sparkles"></i> '
title = 'Maaagic Download'
pageRef = 'images/magic.gif?download'
weight = 4
# mounts are only needed in this showcase to access the publicly available screenshots and CHANGELOG;
# remove this section if you don't need further mounts
[module]
[[module.mounts]]
source = 'archetypes'
target = 'archetypes'
[[module.mounts]]
source = 'assets'
target = 'assets'
# Language dependent settings:
# Use case https://gohugo.io/content-management/multilingual/#translation-by-filename
[[module.mounts]]
source = 'content'
target = 'content'
# Use case https://gohugo.io/content-management/multilingual/#translation-by-content-directory
#[[module.mounts]]
# lang = 'en'
# source = 'content/en'
# target = 'content'
#[[module.mounts]]
# lang = 'pir'
# source = 'content/pir'
# target = 'content'
[[module.mounts]]
source = 'data'
target = 'data'
[[module.mounts]]
source = 'i18n'
target = 'i18n'
[[module.mounts]]
source = 'layouts'
target = 'layouts'
[[module.mounts]]
source = 'static'
target = 'static'
# just for this documentation to expose our config in the docs
[[module.mounts]]
source = 'config'
target = 'assets/config'
# just for this documentation to expose the GitHub hero image in the docs
[[module.mounts]]
source = '../images'
target = 'assets/images'
# just for this documentation to expose the CHANGELOG.md in the docs
[[module.mounts]]
source = '../CHANGELOG.md'
target = 'assets/CHANGELOG.md'
# just for this documentation to expose the README.md in the docs
[[module.mounts]]
source = '../README.md'
target = 'assets/README.md'
# add two showcase specific taxonomies for the parameter documentation;
# the standard taxonomies must be repeated if they should be available
# in such a case
[taxonomies]
category = 'categories'
tag = 'tags'
frontmatter = 'frontmatter'
option = 'options'
# Showcase-specific non-standard theme parameter that should be not
# contained in the defauzlt params.toml; delete it!
[params]
# Demo setting for displaying the siteparam shortcode the docs.
siteparam.test.text = 'A **nested** option <b>with</b> formatting'
@ -331,7 +58,8 @@ summaryLength = 10
# This is for support of the variantgenerator in the docs, you don't need this!
variantgenerator.force = true
[params.relearn.dependencies]
[params.relearn]
[params.relearn.dependencies]
# This is for support of the variantgenerator in the docs, you don't need this!
[params.relearn.dependencies.variantgenerator]
name = 'VariantGenerator'

View file

@ -0,0 +1,181 @@
# showcase of the menu shortcuts; you can use relative URLs linking
# to your content or use fully-qualified URLs to link outside of
# your project
[en]
title = 'Hugo Relearn Theme'
weight = 1
languageCode = 'en'
languageName = 'English'
# Language dependent settings:
# Use case https://gohugo.io/content-management/multilingual/#translation-by-content-directory
#contentDir = 'content/en'
[en.params]
landingPageName = '<i class="fa-fw fas fa-home"></i> Home'
errorignore = ['exampleSite']
[[en.menu.shortcuts]]
pre = '<i class="fa-fw fas fa-anchor"></i> '
name = 'Example Site'
url = 'exampleSite/index.html'
weight = 1
[[en.menu.shortcuts]]
pre = '<i class="fa-fw fab fa-github"></i> '
name = 'GitHub Repo'
url = 'https://github.com/McShelby/hugo-theme-relearn'
weight = 10
[[en.menu.shortcuts]]
name = 'Showcases'
pageRef = '/showcase'
weight = 20
[[en.menu.shortcuts]]
name = 'Credits'
pageRef = '/more/credits'
weight = 30
[[en.menu.shortcuts]]
pre = '<i class="fa-fw fas fa-tags"></i> '
name = 'Tags'
pageRef = '/tags'
weight = 40
[[en.menu.shortcuts]]
pre = '<i class="fa-fw fas fa-layer-group"></i> '
name = 'Categories'
pageRef = '/categories'
weight = 50
[[en.menu.devshortcuts]]
identifier = 'devshortcuts'
name = 'Dev Shortcuts'
[[en.menu.devshortcuts]]
parent = 'devshortcuts'
pre = '<i class="fa-fw fab fa-hackerrank"></i> '
name = 'Hugo'
url = 'https://gohugo.io/documentation/'
weight = 1
[[en.menu.devshortcuts]]
parent = 'devshortcuts'
pre = '<i class="fa-fw fas fa-puzzle-piece"></i> '
identifier = 'theme'
name = 'Theme'
weight = 2
[[en.menu.devshortcuts.params]]
alwaysopen = true
[[en.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-gears"></i> '
identifier = 'configoptions'
pageRef = 'configuration/reference'
weight = 1
[[en.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fab fa-markdown"></i> '
identifier = 'frontmatter'
title = 'Front Matter Reference'
pageRef = 'authoring/frontmatter/reference#annotated-front-matter'
weight = 2
[[en.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-image"></i> '
identifier = 'screenshotframe'
title = 'Screenshot Frame'
pageRef = 'images/hero.zip'
weight = 3
[[en.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-wand-magic-sparkles"></i> '
title = 'Maaagic Download'
pageRef = 'images/magic.gif?download'
weight = 4
# this is ourrr way t' showcase th' multilang settings by
# doing autotrrranlat'n of th' english content; we are
# lazy and don't supporrt furrrther trrranslations; arrr,
# don't take it t' serrrious, fello'; it's prrretty hacky and:
# NOT MEANT FER PRRRODUCTION! ARRR!
[pir]
title = "Cap'n Hugo Relearrrn Theme"
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' # you can explicitly override the reading direction here, otherwise the translation file contains a default
languageName = 'Arrr! ☠ Pirrratish ☠'
# Language dependent settings:
# Use case https://gohugo.io/content-management/multilingual/#translation-by-content-directory
#contentDir = 'content/pir'
[pir.params]
landingPageName = '<i class="fa-fw fas home"></i> Arrr! Home'
errorignore = ['exampleSite', '.*']
[[pir.menu.shortcuts]]
pre = '<i class="fa-fw fas fa-anchor"></i> '
name = 'Example Site'
url = 'exampleSite/index.html'
weight = 1
[[pir.menu.shortcuts]]
pre = '<i class="fa-fw fab fa-github"></i> '
name = 'GitHub Repo'
url = 'https://github.com/McShelby/hugo-theme-relearn'
weight = 10
[[pir.menu.shortcuts]]
pre = '<i class="fa-fw fas fa-camera"></i> '
name = 'Showcases'
pageRef = '/showcase'
weight = 20
[[pir.menu.shortcuts]]
name = 'Crrredits'
pageRef = '/more/credits'
weight = 30
[[pir.menu.shortcuts]]
name = 'Arrr! Tags'
pageRef = '/tags'
weight = 40
[[pir.menu.shortcuts]]
pre = '<i class="fa-fw fas fa-layer-group"></i> '
name = 'Categorrries'
pageRef = '/categories'
weight = 50
[[pir.menu.devshortcuts]]
identifier = 'devshortcuts'
name = 'Dev Shortcuts'
[[pir.menu.devshortcuts]]
parent = 'devshortcuts'
pre = '<i class="fa-fw fab fa-hackerrank"></i> '
name = "Cap'n Hugo"
url = 'https://gohugo.io/documentation/'
weight = 1
[[pir.menu.devshortcuts]]
parent = 'devshortcuts'
pre = '<i class="fa-fw fas fa-puzzle-piece"></i> '
identifier = 'theme'
name = "Th' Theme"
weight = 2
[[pir.menu.devshortcuts.params]]
alwaysopen = true
[[pir.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-gears"></i> '
identifier = 'configoptions'
pageRef = 'configuration/reference'
weight = 1
[[pir.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fab fa-markdown"></i> '
identifier = 'frontmatter'
title = 'Front Matter Reference'
pageRef = 'authoring/frontmatter/reference#annotated-front-matter'
weight = 2
[[pir.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-image"></i> '
identifier = 'screenshotframe'
title = 'Screenshot Frame'
pageRef = 'images/hero.zip'
weight = 3
[[pir.menu.devshortcuts]]
parent = 'theme'
pre = '<i class="fa-fw fas fa-wand-magic-sparkles"></i> '
title = 'Maaagic Download'
pageRef = 'images/magic.gif?download'
weight = 4

View file

@ -0,0 +1,50 @@
[highlight]
# line numbers in a table layout will shift if code is wrapping, so better
# not use it; visually both layouts have the same look and behavior
lineNumbersInTable = false
# the shipped variants come with their own modified chroma syntax highlighting
# stylesheets which are linked in your generated HTML pages; you can use Hugo to generate
# own stylesheets to your liking and use them in your variant;
# if you want to use Hugo's internal styles instead of the shipped stylesheets:
# - remove `noClasses` or set `noClasses = true`
# - set `style` to a predefined style name
# note: with using the internal styles, the `--CODE-theme` setting in your variant
# stylesheet will be ignored and the internal style is used for all variants and
# even print
noClasses = false
# style = 'tango'
[goldmark]
# this is required for the themes docs to make the piratify shortcode work
duplicateResourceFiles = true
# activated for this showcase to use HTML and JavaScript; decide on your own needs;
# if in doubt, remove this line
renderer.unsafe = true
[goldmark.extensions]
strikethrough = false
# use Markdown extensions for this showcase
[goldmark.extensions.extras]
[goldmark.extensions.extras.delete]
enable = true
[goldmark.extensions.extras.insert]
enable = true
[goldmark.extensions.extras.mark]
enable = true
[goldmark.extensions.extras.subscript]
enable = true
[goldmark.extensions.extras.superscript]
enable = true
[goldmark.extensions.passthrough]
enable = true
[goldmark.extensions.passthrough.delimiters]
# the settings chosen here match the default initialization
# of the MathJax library chosen by the theme;
# if you want to adjust to different values you also need
# to set them in `[params] mathJaxInitialize`
inline = [['\(', '\)'], ['$', '$']]
block = [['\[', '\]'], ['$$', '$$']]

View file

@ -0,0 +1,50 @@
# mounts are only needed in this showcase to access the publicly available screenshots and CHANGELOG;
# remove this section if you don't need further mounts
[[mounts]]
source = 'archetypes'
target = 'archetypes'
[[mounts]]
source = 'assets'
target = 'assets'
# Language dependent settings:
# Use case https://gohugo.io/content-management/multilingual/#translation-by-filename
[[mounts]]
source = 'content'
target = 'content'
# Use case https://gohugo.io/content-management/multilingual/#translation-by-content-directory
#[[mounts]]
# lang = 'en'
# source = 'content/en'
# target = 'content'
#[[mounts]]
# lang = 'pir'
# source = 'content/pir'
# target = 'content'
[[mounts]]
source = 'data'
target = 'data'
[[mounts]]
source = 'i18n'
target = 'i18n'
[[mounts]]
source = 'layouts'
target = 'layouts'
[[mounts]]
source = 'static'
target = 'static'
# just for this documentation to expose our config in the docs
[[mounts]]
source = 'config'
target = 'assets/config'
# just for this documentation to expose the GitHub hero image in the docs
[[mounts]]
source = '../images'
target = 'assets/images'
# just for this documentation to expose the CHANGELOG.md in the docs
[[mounts]]
source = '../CHANGELOG.md'
target = 'assets/CHANGELOG.md'
# just for this documentation to expose the README.md in the docs
[[mounts]]
source = '../README.md'
target = 'assets/README.md'

View file

@ -1,3 +1,7 @@
# Theme-specific options;
# For a detailed explanation and many more options see
# https://mcshelby.github.io/hugo-theme-relearn/configuration/reference/index.html#annotated-configuration-options
# If an option value is said to be not set, you can achieve the same behavior
# by giving it an empty string value.
@ -60,13 +64,13 @@ social.twitter = ''
# 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-auto', name = 'Relearn Light/Dark', auto = [ 'relearn-light', 'relearn-dark' ] },
{ identifier = 'relearn-dark' },
{ identifier = 'relearn-light' },
{ identifier = 'relearn-bright' },
{ identifier = 'zen-auto', name = 'Zen Light/Dark', auto = [ 'zen-light', 'zen-dark' ] },
{ identifier = 'zen-light' },
{ identifier = 'zen-dark' },
{ identifier = 'zen-light' },
{ identifier = 'retro-auto', name = 'Retro Learn/Neon', auto = [ 'learn', 'neon' ] },
{ identifier = 'neon' },
{ identifier = 'learn' },

View file

@ -1,2 +1,4 @@
# Configuration to release this site on GitHub Pages
baseURL = 'https://mcshelby.github.io/hugo-theme-relearn/'
relativeURLs = false

View file

@ -1,3 +1,6 @@
# Configuration to test the exampleSite for changes in development
# This configuration will not result in a functioning website.
# We disable this for testing; you must do so too
# if you want to use the themes parameter disableGeneratorVersion=true;
# otherwise Hugo will create a generator tag on your home page

View file

@ -1 +1 @@
7.3.2+88c37300827cf1c2ba1c53a43304ebc9ec286a15
7.3.2+cd4a8363be3170bf6931bbe8abd29b0ece2548fc