From 2e07b80460cf06aa304b9ca6d99d7a1ca8eac6d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Thu, 16 Nov 2023 00:21:08 +0100 Subject: [PATCH] docs: comprehensivly document config.toml #721 --- exampleSite/config/_default/config.toml | 40 +- exampleSite/config/_default/params.toml | 372 ++++++++++++++++++ .../content/basics/configuration/_index.en.md | 94 +---- 3 files changed, 384 insertions(+), 122 deletions(-) create mode 100644 exampleSite/config/_default/params.toml diff --git a/exampleSite/config/_default/config.toml b/exampleSite/config/_default/config.toml index 72a8d8b3b9..5513ff3b9b 100644 --- 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 with 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 with formatting" + # Extension to the image effects only for the docs. + imageEffects.bg-white = true diff --git a/exampleSite/config/_default/params.toml b/exampleSite/config/_default/params.toml new file mode 100644 index 0000000000..925831fc4d --- /dev/null +++ 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" diff --git a/exampleSite/content/basics/configuration/_index.en.md b/exampleSite/content/basics/configuration/_index.en.md index a5daceb0af..9a16e5e99c 100644 --- 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