From 1eaa287faa456be277e6b65f40b08b821ac02fff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Thu, 13 Feb 2025 22:25:56 +0100 Subject: [PATCH] docs: split config and add more comments #1003 --- docs/config/_default/hugo.toml | 312 ++-------------------------- docs/config/_default/languages.toml | 181 ++++++++++++++++ docs/config/_default/markup.toml | 50 +++++ docs/config/_default/module.toml | 50 +++++ docs/config/_default/params.toml | 10 +- docs/config/github/hugo.toml | 2 + docs/config/testing/hugo.toml | 3 + layouts/partials/version.txt | 2 +- 8 files changed, 314 insertions(+), 296 deletions(-) create mode 100644 docs/config/_default/languages.toml create mode 100644 docs/config/_default/markup.toml create mode 100644 docs/config/_default/module.toml diff --git a/docs/config/_default/hugo.toml b/docs/config/_default/hugo.toml index 4e474fe3d4..1910bd9dd3 100644 --- a/docs/config/_default/hugo.toml +++ b/docs/config/_default/hugo.toml @@ -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 = ' Home' - - [[languages.en.menu.shortcuts]] - pre = ' ' - 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 = ' ' - name = 'Tags' - pageRef = '/tags' - weight = 40 - [[languages.en.menu.shortcuts]] - pre = ' ' - name = 'Categories' - pageRef = '/categories' - weight = 50 - - [[languages.en.menu.devshortcuts]] - identifier = 'devshortcuts' - name = 'Dev Shortcuts' - [[languages.en.menu.devshortcuts]] - parent = 'devshortcuts' - pre = ' ' - name = 'Hugo' - url = 'https://gohugo.io/documentation/' - weight = 1 - [[languages.en.menu.devshortcuts]] - parent = 'devshortcuts' - pre = ' ' - identifier = 'theme' - name = 'Theme' - weight = 2 - [[languages.en.menu.devshortcuts.params]] - alwaysopen = true - [[languages.en.menu.devshortcuts]] - parent = 'theme' - pre = ' ' - identifier = 'configoptions' - pageRef = 'configuration/reference' - weight = 1 - [[languages.en.menu.devshortcuts]] - parent = 'theme' - pre = ' ' - identifier = 'frontmatter' - title = 'Front Matter Reference' - pageRef = 'authoring/frontmatter/reference#annotated-front-matter' - weight = 2 - [[languages.en.menu.devshortcuts]] - parent = 'theme' - pre = ' ' - identifier = 'screenshotframe' - title = 'Screenshot Frame' - pageRef = 'images/hero.zip' - weight = 3 - [[languages.en.menu.devshortcuts]] - parent = 'theme' - pre = ' ' - 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 = ' Arrr! Home' - errorignore = ['.*'] - - [[languages.pir.menu.shortcuts]] - pre = ' ' - name = 'GitHub Repo' - url = 'https://github.com/McShelby/hugo-theme-relearn' - weight = 10 - [[languages.pir.menu.shortcuts]] - pre = ' ' - 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 = ' ' - name = 'Categorrries' - pageRef = '/categories' - weight = 50 - - [[languages.pir.menu.devshortcuts]] - identifier = 'devshortcuts' - name = 'Dev Shortcuts' - [[languages.pir.menu.devshortcuts]] - parent = 'devshortcuts' - pre = ' ' - name = "Cap'n Hugo" - url = 'https://gohugo.io/documentation/' - weight = 1 - [[languages.pir.menu.devshortcuts]] - parent = 'devshortcuts' - pre = ' ' - identifier = 'theme' - name = "Th' Theme" - weight = 2 - [[languages.pir.menu.devshortcuts.params]] - alwaysopen = true - [[languages.pir.menu.devshortcuts]] - parent = 'theme' - pre = ' ' - identifier = 'configoptions' - pageRef = 'configuration/reference' - weight = 1 - [[languages.pir.menu.devshortcuts]] - parent = 'theme' - pre = ' ' - identifier = 'frontmatter' - title = 'Front Matter Reference' - pageRef = 'authoring/frontmatter/reference#annotated-front-matter' - weight = 2 - [[languages.pir.menu.devshortcuts]] - parent = 'theme' - pre = ' ' - identifier = 'screenshotframe' - title = 'Screenshot Frame' - pageRef = 'images/hero.zip' - weight = 3 - [[languages.pir.menu.devshortcuts]] - parent = 'theme' - pre = ' ' - 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 with 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] - # This is for support of the variantgenerator in the docs, you don't need this! - [params.relearn.dependencies.variantgenerator] - name = 'VariantGenerator' + [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' diff --git a/docs/config/_default/languages.toml b/docs/config/_default/languages.toml new file mode 100644 index 0000000000..241affa2f2 --- /dev/null +++ b/docs/config/_default/languages.toml @@ -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 = ' Home' + errorignore = ['exampleSite'] + +[[en.menu.shortcuts]] + pre = ' ' + name = 'Example Site' + url = 'exampleSite/index.html' + weight = 1 +[[en.menu.shortcuts]] + pre = ' ' + 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 = ' ' + name = 'Tags' + pageRef = '/tags' + weight = 40 +[[en.menu.shortcuts]] + pre = ' ' + name = 'Categories' + pageRef = '/categories' + weight = 50 + +[[en.menu.devshortcuts]] + identifier = 'devshortcuts' + name = 'Dev Shortcuts' +[[en.menu.devshortcuts]] + parent = 'devshortcuts' + pre = ' ' + name = 'Hugo' + url = 'https://gohugo.io/documentation/' + weight = 1 +[[en.menu.devshortcuts]] + parent = 'devshortcuts' + pre = ' ' + identifier = 'theme' + name = 'Theme' + weight = 2 + [[en.menu.devshortcuts.params]] + alwaysopen = true +[[en.menu.devshortcuts]] + parent = 'theme' + pre = ' ' + identifier = 'configoptions' + pageRef = 'configuration/reference' + weight = 1 +[[en.menu.devshortcuts]] + parent = 'theme' + pre = ' ' + identifier = 'frontmatter' + title = 'Front Matter Reference' + pageRef = 'authoring/frontmatter/reference#annotated-front-matter' + weight = 2 +[[en.menu.devshortcuts]] + parent = 'theme' + pre = ' ' + identifier = 'screenshotframe' + title = 'Screenshot Frame' + pageRef = 'images/hero.zip' + weight = 3 +[[en.menu.devshortcuts]] + parent = 'theme' + pre = ' ' + 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 = ' Arrr! Home' + errorignore = ['exampleSite', '.*'] + +[[pir.menu.shortcuts]] + pre = ' ' + name = 'Example Site' + url = 'exampleSite/index.html' + weight = 1 +[[pir.menu.shortcuts]] + pre = ' ' + name = 'GitHub Repo' + url = 'https://github.com/McShelby/hugo-theme-relearn' + weight = 10 +[[pir.menu.shortcuts]] + pre = ' ' + 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 = ' ' + name = 'Categorrries' + pageRef = '/categories' + weight = 50 + +[[pir.menu.devshortcuts]] + identifier = 'devshortcuts' + name = 'Dev Shortcuts' +[[pir.menu.devshortcuts]] + parent = 'devshortcuts' + pre = ' ' + name = "Cap'n Hugo" + url = 'https://gohugo.io/documentation/' + weight = 1 +[[pir.menu.devshortcuts]] + parent = 'devshortcuts' + pre = ' ' + identifier = 'theme' + name = "Th' Theme" + weight = 2 + [[pir.menu.devshortcuts.params]] + alwaysopen = true +[[pir.menu.devshortcuts]] + parent = 'theme' + pre = ' ' + identifier = 'configoptions' + pageRef = 'configuration/reference' + weight = 1 +[[pir.menu.devshortcuts]] + parent = 'theme' + pre = ' ' + identifier = 'frontmatter' + title = 'Front Matter Reference' + pageRef = 'authoring/frontmatter/reference#annotated-front-matter' + weight = 2 +[[pir.menu.devshortcuts]] + parent = 'theme' + pre = ' ' + identifier = 'screenshotframe' + title = 'Screenshot Frame' + pageRef = 'images/hero.zip' + weight = 3 +[[pir.menu.devshortcuts]] + parent = 'theme' + pre = ' ' + title = 'Maaagic Download' + pageRef = 'images/magic.gif?download' + weight = 4 diff --git a/docs/config/_default/markup.toml b/docs/config/_default/markup.toml new file mode 100644 index 0000000000..540bbe3dca --- /dev/null +++ b/docs/config/_default/markup.toml @@ -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 = [['\[', '\]'], ['$$', '$$']] diff --git a/docs/config/_default/module.toml b/docs/config/_default/module.toml new file mode 100644 index 0000000000..92368fdf44 --- /dev/null +++ b/docs/config/_default/module.toml @@ -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' diff --git a/docs/config/_default/params.toml b/docs/config/_default/params.toml index 75efdc8ffb..80c1416f8b 100644 --- a/docs/config/_default/params.toml +++ b/docs/config/_default/params.toml @@ -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' }, diff --git a/docs/config/github/hugo.toml b/docs/config/github/hugo.toml index b80b9e5d03..0d921d55f3 100644 --- a/docs/config/github/hugo.toml +++ b/docs/config/github/hugo.toml @@ -1,2 +1,4 @@ +# Configuration to release this site on GitHub Pages + baseURL = 'https://mcshelby.github.io/hugo-theme-relearn/' relativeURLs = false diff --git a/docs/config/testing/hugo.toml b/docs/config/testing/hugo.toml index be1e2b06d7..26d4309033 100644 --- a/docs/config/testing/hugo.toml +++ b/docs/config/testing/hugo.toml @@ -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 diff --git a/layouts/partials/version.txt b/layouts/partials/version.txt index 2350664ce0..ec926e5a09 100644 --- a/layouts/partials/version.txt +++ b/layouts/partials/version.txt @@ -1 +1 @@ -7.3.2+88c37300827cf1c2ba1c53a43304ebc9ec286a15 \ No newline at end of file +7.3.2+cd4a8363be3170bf6931bbe8abd29b0ece2548fc \ No newline at end of file