docs: comprehensivly document config.toml #721

2025-01-18 19:00:24 +00:00 · 2023-11-16 00:21:08 +01:00 · 2023-11-16 00:21:08 +01:00 · 2e07b80460
commit 2e07b80460
parent b91fb6e9e7
3 changed files with 384 additions and 122 deletions
--- a/exampleSite/config/_default/config.toml
+++ b/exampleSite/config/_default/config.toml
@ -191,6 +191,7 @@ title = "Hugo Relearn Theme"
  [[module.mounts]]
    source = 'i18n'
    target = 'i18n'
+  # just for this documentation to expose the GitHub hero image in the docs
  [[module.mounts]]
    source = '../images'
    target = 'static/images'
@ -203,36 +204,13 @@ title = "Hugo Relearn Theme"
  [[module.mounts]]
    source = 'static'
    target = 'static'
+  # just for this documentation to expose our config in the docs
+  [[module.mounts]]
+    source = 'config'
+    target = 'static/config'

-# settings specific to this theme's features; choose to your likings and
-# consult this documentation for explaination
 [params]
-  images = ["images/hero.png"]
-  editURL = "https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/"
-  description = "Documentation for Hugo Relearn Theme"
-  author.name = "Sören Weber"
-  showVisitedLinks = true
-  collapsibleMenu = true
-  disableBreadcrumb = false
-  disableRootBreadcrumb = true
-  disableInlineCopyToClipBoard = true
-  disableNextPrev = false
-  disableLandingPageButton = true
-  breadcrumbSeparator = ">"
-  titleSeparator = "::"
-  themeVariant = [ "auto", "relearn-bright", "relearn-light", "relearn-dark", "zen-light", "zen-dark", "neon", "learn", "blue", "green", "red" ]
-  themeVariantAuto = [ "relearn-light", "relearn-dark" ]
-  disableSeoHiddenPages = true
-  # this is to index search for your native language in other languages, too (eg.
-  # pir in this showcase)
-  additionalContentLanguage = [ "en" ]
-  # this is for the stylesheet generator to allow for interactivity in Mermaid
-  # graphs; you usually will not need it and you should remove this for
-  # security reasons
-  mermaidInitialize = "{ \"securityLevel\": \"loose\" }"
-  mermaidZoom = true
-  [params.siteparam.test]
-    text = "A **nested** parameter <b>with</b> formatting"
-  [params.imageEffects]
-    bg-white = true # extension, not supported by the theme
-    border = true
+  # Demo setting for displaying the siteparam shortcode the docs.
+  siteparam.test.text = "A **nested** option <b>with</b> formatting"
+  # Extension to the image effects only for the docs.
+  imageEffects.bg-white = true
--- a/exampleSite/config/_default/params.toml
+++ b/exampleSite/config/_default/params.toml
@ -0,0 +1,372 @@
+# This is the file `config/_default/params.toml`.
+# You can also store the below options directly in your `hugo.toml` but then
+# need to contain them within the `params` key. See Hugo's documentation how
+# to do this.
+
+# If an option value is said to be not set, you can achieve the same behavior
+# by given it an empty string value.
+
+###############################################################################
+# Hugo
+# These options usually apply to other themes aswell.
+
+# 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"
+
+# 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"]
+
+# The description of your site.
+# Default: not set
+# This is used for generating HTML meta tags, social media meta information
+# for the opengraph protocol and twitter cards.
+# This can be overridden in the page's frontmatter.
+description = "Documentation for Hugo Relearn Theme"
+
+###############################################################################
+# Relearn Theme
+# These options are specific to the Relearn theme.
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Variants
+# These options set your color variant.
+
+# Used color variants.
+# Default: "auto"
+# This sets one or more color variants, available to your readers to choose
+# from. You can either set a single value eg. "zen-light" or an array like
+# [ "neon", "learn" ]. 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: "auto", "relearn-bright",
+# "relearn-light", "relearn-dark", "zen-light", "zen-dark", "neon", "learn",
+# "blue", "green", "red". The auto variant is somewhat special. See the
+# option for themeVariantAuto below.
+# 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 = [ "auto", "relearn-bright", "relearn-light", "relearn-dark", "zen-light", "zen-dark", "neon", "learn", "blue", "green", "red" ]
+
+# The color variants used for auto mode.
+# Default: [ "relearn-light", "relearn-dark" ], overwritten by the first
+# two non-auto options from themeVariant if existant.
+# The auto variant defines how your site adjusts to your selected OS settings
+# for light/dark mode. The first array element is the variant for light mode,
+# the second for dark mode.
+themeVariantAuto = [ "relearn-light", "relearn-dark" ]
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# General
+# These options are defining general, non visual behavior.
+
+# Avoid new asset URLs on build.
+# Default: false
+# By default JavaScript-files and CSS-files get a unique ID on each rebuild.
+# This makes sure, the user always has the latest version and not some stale
+# copy of his browser cache. Anyways, it can be desireable to turn this
+# off in certain circumstances. For example if you have Hugo's dev server
+# running. Also some proxies dislike this optimization.
+disableAssetsBusting = false
+
+# Avoid generator meta tags.
+# Default: false
+# Set this to true if you want to disable generation for generator meta tags
+# of Hugo and the theme in your HTML head. In tihs case also don't forget to
+# set Hugo's disableHugoGeneratorInject=true. Otherwise Hugo will generate a
+# meta tag into your home page anyways.
+disableGeneratorVersion = 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
+
+# Multilanguage content.
+# Default: not set
+# If your pages contain further languages besides the main one used, add all
+# those auxiliary languages here. This 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" ]
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Topbar
+# These options modify the topbar appearance.
+
+# Hide the table of contents button.
+# Default: false
+# If the TOC button is hidden, also the keyboard shortcut is disabled.
+# This can be overridden in the page's frontmatter.
+disableToc = false
+
+# Hide the breadcrumbs.
+# Default: false
+# If the breadcrumbs are hidden, the title of the displayed page will still be
+# shown in the topbar.
+disableBreadcrumb = false
+
+# Hide Next and Previous navigation buttons.
+# Default: false
+# If the navigation buttons are hidden, also the keyboard shortcuts are
+# disabled.
+disableNextPrev = false
+
+# The URL prefix to edit a page.
+# Default: not set
+# If set, an edit button will be shown in the topbar. If the button is hidden,
+# also the keyboard shortcuts are disabled. The given URL is prepended to the
+# relative file path of a the displayed page. The URL must end with a `/`.
+# This is useful if you wnat 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/"
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Menu
+# These options modify the menu apperance.
+
+# Hide the search box.
+# Default: false
+# If the searc box is sisabled, the search functionality is disabled too.
+# This will also cause the keyboard shortcut to be disabled and the dedicated
+# search page is not linked although it mighty be configured.
+disableSearch = false
+
+# Hide the Home entry.
+# Default: false
+# If shown, a Home button will appear below the search bar and the main menu.
+# It links to your the home page of the current language.
+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
+# Hugo's default sort order). This can be overridden in the pages frontmatter.
+ordersectionsby = "weight"
+
+# The initial expand state of submenus.
+# Default: not set
+# This controls whether submenus will be expanded (true), or collapsed (false)
+# in the menu. If not set, the first menu level is set to false, all others
+# 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 = "" # this has the effect as if not set at all
+
+# Shows expander for submenus.
+# Default: false
+# If set to true, a submenu in the sidebar will be displayed in a collapsible
+# tree view and a clickable expander is set in front of the entry.
+collapsibleMenu = true
+
+# Shows checkmarks for visited pages of the main menu.
+# Default: false
+# This also causes the display of the `Clear History` entry in the lower part
+# of the menu to remove all checkmarks. The checkmarks will also been removed
+# if you regenerate your site as the ids are not stable.
+showVisitedLinks = true
+
+# Hide heading above the shortcut menu.
+# Default: false
+# The title for the heading can be overwritten in your i18n files. See Hugo's
+# documentation how to do this.
+disableShortcutsTitle = false
+
+# Hide the language switcher.
+# Default: false
+# If you have more than one language configured, a language switcher is
+# displayed in the lower part of the menu. This opition lets you explicitly
+# turn this behavior off.
+disableLanguageSwitchingButton = false
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Hidden pages
+# These options configure how hidden pages are treated.
+# A page flagged as hidden, is only removed from the main menu but behaves
+# like any other page for all other functionality in Hugo.
+
+# Hide hidden pages from search.
+# Default: false
+# Hides hidden pages from the suggestions of the search box and the dedicated
+# search page.
+disableSearchHiddenPages = false
+
+# Hide hidden pages for web crawlers.
+# Default: false
+# Avoids hidden pages from showing up in the sitemap and on Google (et all),
+# otherwise they may be indexed by search engines
+disableSeoHiddenPages = true
+
+# Hide hidden pages for taxonomies.
+# Default: false
+# Hides hidden pages from showing up on the taxonomy and terms pages. If this
+# reduces term counters to zero, an empty but not linked term page will be
+# created anyhow.
+disableTagHiddenPages = false
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Content
+# These options modify how your content is displayed.
+
+# Title separator.
+# Default: "::"
+# Changes the title separator used when concatenating the page title with the
+# site title. This is consistently used throughout the theme.
+titleSeparator = "::"
+
+# Breadcrumb separator.
+# Default: ">"
+# Changes the breadcrumb separator used in the topbars breadcrumb area and for
+# search results and term pages.
+breadcrumbSeparator = ">"
+
+# Hide the root breadcrumb.
+# Default: false
+# The root breadcrumb is usually the home page of your site. Because this is
+# always accessible by clicking on the logo, you may want to reduce clutter
+# by removing this from your breadcrumb.
+disableRootBreadcrumb = true
+
+# Hide breadcrumbs term pages.
+# Default: false
+# If you have lots of taxonomy terms, the term pages may seem cluttered with
+# breadcrumbs to you, so this is the option to turn off breadcrumbs on term
+# pages. Only the page title will then be shown on the term pages.
+disableTermBreadcrumbs = false
+
+# Hide copy-to-clipboard for inline code.
+# Default: false
+# This removes the copy-to-clipboard button from your inline code.
+disableInlineCopyToClipBoard = true
+
+# Always show copy-to-clipboard for block code.
+# Default: false
+# The theme only shows the copy-to-clipboard button if you hover over the code
+# block. Set this to true to disable the hover effect and always show the
+# button.
+disableHoverBlockCopyToClipBoard = false
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Links
+# These options configure how links are displayed.
+
+# 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".
+externalLinkTarget = "_blank"
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Images
+# These options configure how images are displayed.
+
+# Image effects.
+# See the documentation for how you can even add your own arbitrary effects to
+# the list.
+# All effects can be overridden in the page's frontmatter or thru URL parameter
+# given to the image. See the documentation for details.
+
+# Default: false
+imageEffects.border = true
+# Default: true
+imageEffects.lightbox = true
+# Default: false
+imageEffects.shadow = false
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Mermaid
+# These options configure how Mermaid graphs are displayed.
+
+# Make graphs panable and zoomable
+# Default: false
+# For huge graphs it can be helpful to make them zoomable. Zoomable graphs come
+# with a reset button for the zoom.
+# This can be overridden in the page's frontmatter or given as a parameter to
+# individual graphs.
+mermaidZoom = true
+
+# Initialization options for Mermaid.
+# 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\" }"
+
+# Only load Mermaid if needed.
+# Default: true
+# If a Mermaid shortcode or 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
+# codefence is involved and the library is not loaded by default. In this case
+# you can set `disableMermaid=false` in your frontmatter to force the library to
+# be loaded.
+# This can be overridden in the page's frontmatter.
+disableMermaid = true
+
+# URL for external Mermaid library.
+# Default: not set
+# 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"
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# MathJax
+# These options configure how math formulae are displayed.
+
+# Initialization options for MathJax.
+# Default: not set
+# A JSON value. See the MathJaxdocumentation for possible parameter.
+# This can be overridden in the page's frontmatter.
+mathJaxInitialize = "{}"
+
+# Only load MathJax if needed.
+# Default: true
+# If a Math shortcode is found, the option will be ignored and
+# MathJax 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
+# codefence is involved and the library is not loaded by default. In this case
+# you can set `disableMathJax=false` in your frontmatter to force the library to
+# be loaded.
+# This can be overridden in the page's frontmatter.
+disableMathJax = true
+
+# URL for external MathJax library.
+# Default: not set
+# 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"
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# OpenApi
+# These options configure how OpenAPI specifications are displayed.
+
+# Only load OpenAPI if needed.
+# Default: true
+# If a OpenAPI shortcode is found, the option will be ignored and
+# OpenAPI 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
+# codefence is involved and the library is not loaded by default. In this case
+# you can set `disableOpenapi=false` in your frontmatter to force the library to
+# be loaded.
+# This can be overridden in the page's frontmatter.
+disableOpenapi = true
+
+# URL for external OpenAPI library.
+# Default: not set
+# 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"
--- a/exampleSite/content/basics/configuration/_index.en.md
+++ b/exampleSite/content/basics/configuration/_index.en.md
@ -10,97 +10,9 @@ On top of [Hugo global configuration](https://gohugo.io/overview/configuration/)

 Note that some of these parameters are explained in details in other sections of this documentation.

-```toml
-[params]
-  # This controls whether submenus will be expanded (true), or collapsed (false) in the
-  # menu; if no setting is given, the first menu level is set to false, all others to true;
-  # this can be overridden in the pages frontmatter
-  alwaysopen = true
-  # Prefix URL to edit current page. Will display an "Edit" button on top right hand corner of every page.
-  # Useful to give opportunity to people to create merge request for your doc.
-  # See the config.toml file from this documentation site to have an example.
-  editURL = ""
-  # Author of the site, will be used in meta information
-  author.name = ""
-  # Description of the site, will be used in meta information
-  description = ""
-  # Shows a checkmark for visited pages on the menu
-  showVisitedLinks = false
-  # Disable search function. It will hide search bar
-  disableSearch = false
-  # Disable search in hidden pages, otherwise they will be shown in search box
-  disableSearchHiddenPages = false
-  # Disables hidden pages from showing up in the sitemap and on Google (et all), otherwise they may be indexed by search engines
-  disableSeoHiddenPages = false
-  # Disables hidden pages from showing up on the tags page although the tag term will be displayed even if all pages are hidden
-  disableTagHiddenPages = false
-  # Javascript and CSS cache are automatically busted when new version of site is generated.
-  # Set this to true to disable this behavior (some proxies don't handle well this optimization)
-  disableAssetsBusting = false
-  # Set this to true if you want to disable generation for generator version meta tags of hugo and the theme;
-  # don't forget to also set Hugo's disableHugoGeneratorInject=true, otherwise it will generate a meta tag into your home page
-  disableGeneratorVersion = false
-  # Set this to true to disable copy-to-clipboard button for inline code.
-  disableInlineCopyToClipBoard = false
-  # Set this to true to disable the hover effect for copy-to-clipboard buttons for block code.
-  disableHoverBlockCopyToClipBoard = false
-  # A title for shortcuts in menu is set by default. Set this to true to disable it.
-  disableShortcutsTitle = false
-  # If set to false, a Home button will appear below the search bar on the menu.
-  # It is redirecting to the landing page of the current language if specified. (Default is "/")
-  disableLandingPageButton = true
-  # When using mulitlingual website, disable the switch language button.
-  disableLanguageSwitchingButton = false
-  # Hide breadcrumbs in the header and only show the current page title
-  disableBreadcrumb = true
-  # Hide breadcrumbs in the term pages and only show the current page title
-  disableTermBreadcrumbs = true
-  # Hide the root (first) breadcrumb in the header
-  disableRootBreadcrumb = true
-  # If set to true, hide table of contents menu in the header of all pages
-  disableToc = false
-  # If set to false, load the MathJax module on every page regardless if a MathJax shortcode is present
-  disableMathJax = false
-  # Specifies the remote location of the MathJax js
-  customMathJaxURL = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
-  # Initialization parameter for MathJax, see MathJax documentation
-  mathJaxInitialize = "{}"
-  # If set to false, load the Mermaid module on every page regardless if a Mermaid shortcode or Mermaid codefence is present
-  disableMermaid = false
-  # Specifies the remote location of the Mermaid js
-  customMermaidURL = "https://unpkg.com/mermaid/dist/mermaid.min.js"
-  # Initialization parameter for Mermaid, see Mermaid documentation
-  mermaidInitialize = "{ \"theme\": \"default\" }"
-  # If set to false, load the OpenAPI module on every page regardless if a OpenAPI shortcode is present
-  disableOpenapi = false
-  # Specifies the remote location of the swagger-ui js
-  customOpenapiURL = "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
-  # Hide Next and Previous page buttons displayed in topbar
-  disableNextPrev = true
-  # Order menu sections by "weight", "title", "linktitle", "modifieddate", "expirydate", "publishdate", "date", "length" or "default" (adhering to Hugo's default sort order). Default to "weight";
-  # this can be overridden in the pages frontmatter
-  ordersectionsby = "weight"
-  # Change default color scheme with a variant one. Eg. can be "auto", "red", "blue", "green" or an array like [ "blue", "green" ].
-  themeVariant = "auto"
-  # Change the breadcrumb separator. Default to ">".
-  breadcrumbSeparator = "|"
-  # Change the title separator. Default to "::".
-  titleSeparator = "-"
-  # If set to true, the menu in the sidebar will be displayed in a collapsible tree view. Although the functionality works with old browsers (IE11), the display of the expander icons is limited to modern browsers
-  collapsibleMenu = false
-  # If a single page can contain content in multiple languages, add those here
-  additionalContentLanguage = [ "en" ]
-  # If set to true, no index.html will be appended to prettyURLs; this will cause pages not
-  # to be servable from the file system
-  disableExplicitIndexURLs = false
-  # For external links you can define how they are opened in your browser; this setting will only be applied to the content area but not the shortcut menu
-  externalLinkTarget = "_blank"
-  # Override default values for image effects, you can even add your own arbitrary effects to the list
-  [params.imageEffects]
-    border = false
-    lightbox = true
-    shadow = false
-```
+````toml {title="params.toml"}
+{{% include "config/_default/params.toml" %}}
+````

 ## Serving your page from a subfolder