feat: add multilingual mode support (#241)

BREAKING CHANGE:  Layout file renamed ´layouts/partials/page-footer.html → layouts/partials/menu-nextprev.html`. If you use overrides, you might need to change the filenames as well.

exampleSite/content/en/_includes/_index.md

@@ -0,0 +1,3 @@
+---
+GeekdocHidden: true
+---

exampleSite/content/en/_includes/include-page.md

@@ -0,0 +1,10 @@
+_**Example page include**_
+
+{{< hint info >}}
+**Example Shortcode**\
+Shortcode used in an include page.
+{{< /hint >}}
+
+| Head 1 | Head 2 | Head 3 |
+| ------ | ------ | ------ |
+| 1      | 2      | 3      |

exampleSite/content/en/_index.md

@@ -0,0 +1,64 @@
+---
+title: Welcome to the documentation
+description: Geekdoc is a simple Hugo theme for documentations. It is intentionally designed as a fast and lean theme and may not fit the requirements of complex projects. If a more feature-complete theme is required there are a lot of good alternatives out there.
+geekdocNav: false
+geekdocAlign: center
+geekdocAnchor: false
+---
+
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable MD033 -->
+
+<span class="badge-placeholder">[![Build Status](https://img.shields.io/drone/build/thegeeklab/hugo-geekdoc?logo=drone&server=https%3A%2F%2Fdrone.thegeeklab.de)](https://drone.thegeeklab.de/thegeeklab/hugo-geekdoc)</span>
+<span class="badge-placeholder">[![Hugo Version](https://img.shields.io/badge/hugo-0.83-blue.svg)](https://gohugo.io)</span>
+<span class="badge-placeholder">[![GitHub release](https://img.shields.io/github/v/release/thegeeklab/hugo-geekdoc)](https://github.com/thegeeklab/hugo-geekdoc/releases/latest)</span>
+<span class="badge-placeholder">[![GitHub contributors](https://img.shields.io/github/contributors/thegeeklab/hugo-geekdoc)](https://github.com/thegeeklab/hugo-geekdoc/graphs/contributors)</span>
+<span class="badge-placeholder">[![License: MIT](https://img.shields.io/github/license/thegeeklab/hugo-geekdoc)](https://github.com/thegeeklab/hugo-geekdoc/blob/main/LICENSE)</span>
+
+<!-- markdownlint-restore -->
+
+Geekdoc is a simple Hugo theme for documentations. It is intentionally designed as a fast and lean theme and may not fit the requirements of complex projects. If a more feature-complete theme is required there are a lot of got alternatives out there.
+
+{{< button size="large" relref="usage/getting-started/" >}}Getting Started{{< /button >}}
+
+## Feature overview
+
+{{< columns >}}
+
+### Clean and simple design
+
+Stay focused on exploring the content and don't get overwhelmed by a complex design.
+
+<--->
+
+### Light and mobile-friendly
+
+The theme is powered by less than 1 MB and looks impressive on mobile devices as well as on a regular Desktop.
+
+<--->
+
+### Easy customization
+
+The look and feel can be easily customized by CSS custom properties (variables), features can be adjusted by Hugo parameters.
+
+{{< /columns >}}
+
+{{< columns >}}
+
+### Zero initial configuration
+
+Getting started in minutes. The theme is shipped with a default configuration and works out of the box.
+
+<--->
+
+### Handy shortcodes
+
+We included some (hopefully) useful custom shortcodes so you don't have to and can focus on writing amazing docs.
+
+<--->
+
+### Dark mode
+
+Powerful dark mode that detects your system preferences or can be controlled by a toggle switch.
+
+{{< /columns >}}

exampleSite/content/en/collapse/_index.md

@@ -0,0 +1,6 @@
+---
+title: Collapse
+geekdocCollapseSection: true
+---
+
+Demo collapsible menu entries.

exampleSite/content/en/collapse/level-1/_index.md

@@ -0,0 +1,7 @@
+Level 1
+
+<!-- spellchecker-disable -->
+
+{{< toc-tree >}}
+
+<!-- spellchecker-enable -->

exampleSite/content/en/collapse/level-1/level-1-1.md

@@ -0,0 +1,5 @@
+---
+title: Level 1.1
+---
+
+Level 1.1

exampleSite/content/en/collapse/level-1/level-1-2.md

@@ -0,0 +1,5 @@
+---
+title: Level 1.2
+---
+
+Level 1.2

exampleSite/content/en/collapse/level-2/_index.md

@@ -0,0 +1,5 @@
+---
+geekdocCollapseSection: true
+---
+
+Level-2

exampleSite/content/en/collapse/level-2/level-2-1.md

@@ -0,0 +1,5 @@
+---
+title: Level 2.1
+---
+
+Level 2.1

exampleSite/content/en/collapse/level-2/level-2-2.md

@@ -0,0 +1,5 @@
+---
+title: Level 2.2
+---
+
+Level 2.2

exampleSite/content/en/features/_index.md

@@ -0,0 +1,4 @@
+---
+title: Features
+weight: -15
+---

exampleSite/content/en/features/code-blocks.md

@@ -0,0 +1,95 @@
+---
+title: Code Blocks
+---
+
+There are several ways to add code blocks. Most of them work out of the box, only the Hugo short code `<highlight>` needs to be configured to work properly. The theme also provides some additional features like a copy button and an option to set the maximum length of code blocks. Both of these functions and the dependent formatting rely on the `.highlight` CSS class. You must ensure that you always assign a language to your code blocks if you want to use these functions. If you do not want to apply syntax highlighting, you can also specify `plain` or `text` as the language.
+
+{{< toc >}}
+
+## Inline code
+
+To display an inline shortcode use single quotes:
+
+```plain
+`some code`
+```
+
+**Example:** `some code`
+
+## Code blocks
+
+Code blocks can be uses without language specification:
+
+````markdown
+```Plain
+some code
+```
+````
+
+**Example:**
+
+```Plain
+some code
+```
+
+... or if you need language specific syntax highlighting:
+
+````markdown
+```Shell
+# some code
+echo "Hello world"
+```
+````
+
+**Example:**
+
+```Shell
+# some code
+echo "Hello World"
+```
+
+## Highlight shortcode
+
+Hugo has a build-in shortcode for syntax highlighting. To work properly with this theme, you have to set following options in your site configuration:
+
+{{< tabs "uniqueid" >}}
+{{< tab "TOML" >}}
+
+```TOML
+pygmentsUseClasses=true
+pygmentsCodeFences=true
+```
+
+{{< /tab >}}
+{{< tab "YAML" >}}
+
+```YAML
+pygmentsUseClasses: true
+pygmentsCodeFences: true
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
+You can use it like every other shortcode:
+
+<!-- prettier-ignore -->
+```markdown
+{{</* highlight Shell "linenos=table" */>}}
+# some code
+echo "Hello World"
+{{</* /highlight */>}}
+```
+
+**Example:**
+
+<!-- markdownlint-disable -->
+
+<!-- prettier-ignore-start -->
+{{< highlight Shell "linenos=table" >}}
+# some code
+echo "Hello World"
+{{< /highlight >}}
+<!-- prettier-ignore-end-->
+
+<!-- markdownlint-enable -->

exampleSite/content/en/features/dark-mode/_index.md

@@ -0,0 +1,13 @@
+---
+title: Dark Mode
+---
+
+Say hello to the dark mode of the Geekdoc theme!
+
+[![Geekdoc in dark mode](images/geekdoc-dark.png)](images/geekdoc-dark.png)
+
+The dark mode can be used in two different ways. If you have JavaScript disabled in your browser, the dark mode automatically detects the preferred system settings via the `prefers-color-scheme` parameter. Depending on the value, the theme will automatically switch between dark and light mode if this feature is supported by your operating system and browser.
+
+The second mode requires JavaScript and is controlled by a dark mode switch in the upper right corner. You can switch between three modes: Auto, Dark and Light. Auto mode works the same as the first method mentioned above and automatically detects the system setting. Dark and Light modes allow you to force one of them for your Geekdoc page only, regardless of the system setting. This works even if your browser or operating system does not support the system setting. The current selection is stored locally via the Web Storage API.
+
+To avoid very bright spots often caused by images while using the dark mode we have added an optional auto-dim feature that can be enabled with the site parameter `geekdocDarkModeDim` (see [Configuration](/usage/configuration/)). As this may have an impact on the quality of the images it is disabled by default.

exampleSite/content/en/features/icon-sets.md

@@ -0,0 +1,48 @@
+---
+title: Icon Sets
+---
+
+{{< toc >}}
+
+## Custom icon sets
+
+The only supported source for custom icons are SVG sprites. Some icon frameworks provides ready to use sprites e.g. FontAwesome. If the framework don't provide sprites, you can create your own from raw SVG icons. There are a lot of tools available to create sprites, please choose one that fits your need. One solution could be [svgsprit.es](https://svgsprit.es/).
+
+Regardless of which tool (or existing sprite) you choose, there are a few requirements that must be met:
+
+1. The sprite must be a valid **SVG** file.
+2. You have to ensure to **hide the sprite**. Apply the predefined class `svg-sprite` or `hidden` to the root element of your sprite or add a small piece of inline CSS e.g. `style="display: none;"`.
+3. Save the sprite to the folder `assets/sprites` right beside your `content` folder.
+
+The result of a valid minimal SVG sprite file could look like this:
+
+```XML
+<svg class="svg-sprite" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <symbol viewBox="-2.29 -2.29 28.57 28.57" id="arrow_back" xmlns="http://www.w3.org/2000/svg">
+        <path d="M24 10.526v2.947H5.755l8.351 8.421-2.105 2.105-12-12 12-12 2.105 2.105-8.351 8.421H24z"/>
+    </symbol>
+</svg>
+```
+
+**Example:**
+
+FontAwesome provides three pre-build sprites included in the regular Web download pack, `sprites/brands.svg`, `sprites/regular.svg` and `sprites/solid.svg`. Choose your sprite to use and copy it to your projects root directory into `assets/sprites`, right beside your `content` folder:
+
+```Bash
+my_projcet/
+├── assets
+│   └── sprites
+│       └── regular.svg
+├── config.yaml
+├── content
+│   ├── _index.md
+│   ├── ...
+```
+
+That's it! The theme will auto-load all available SVG sprites provided in the assets folder. To use the icons e.g. in the [bundle menu](/usage/menus/#bundle-menu), you need to lookup the id of the icon. An example would be `thumbs-up` {{< icon "thumbs-up" >}}. There is also a [shortcode](/shortcodes/icons/) available.
+
+## Build-in icons
+
+The theme bundles just a small set of hand crafted icons.
+
+{{< sprites >}}

exampleSite/content/en/features/multilingual/_index.md

@@ -0,0 +1,78 @@
+---
+title: Multilingual
+resources:
+  - name: translation-available
+    src: images/translation-available.png
+    title: ""
+---
+
+{{< toc >}}
+
+Hugo supports the creation of websites with multiple languages. In this post we will explain how to get configure Multilingual Mode with this theme.
+
+## Configuration
+
+### Languages
+
+You need to set a default language and configure at least two different languages used by your site to your configuration file at `config.toml`:
+
+```Toml
+defaultContentLanguage = "en"
+
+[languages.en]
+languageName = "English"
+contentDir = "content/en"
+weight = 10
+
+[languages.de]
+languageName = "German"
+contentDir = "content/de"
+weight = 20
+```
+
+### Translation Strings
+
+To customize translation strings used by the theme you can create a file `i18n/<languagecode>.toml` for every language you want to use e.g. `i18n/en.toml`. You can lookup all used strings in the [default](https://github.com/thegeeklab/hugo-geekdoc/blob/main/i18n/en.yaml) translation file.
+
+### Menus
+
+For the [Bundle Menu](/usage/menus/#bundle-menu) as well as for the [Extra Header Menu](/usage/menus/#extra-header-menu) you can translate the name within the data file of the menu:
+
+```YAML
+---
+more:
+  # If `name` is a text, this text will be used as name for each language.
+  - name: News
+    ref: "/#"
+    icon: "gdoc_notification"
+  # To translate the name you can add a sub-item per language. Important: If you miss a language key
+  # that is configured in the languages list of your `config.toml` the name will be empty for this language!
+  - name:
+      en: Releases
+      de: Veröffentlichung
+    ref: "https://github.com/thegeeklab/hugo-geekdoc/releases"
+    external: true
+    icon: "gdoc_download"
+```
+
+## Add Content
+
+To translate your content you need to create a directory `content/<languagecode>/` for each language you want to use e.g. `content/en/`. This language directories will hold the translated pages for the particular language.
+
+## Switch Content
+
+If you have configured at least two different languages, the language switcher will be enabled in the UI automatically. The switcher is as part of the header menu and displayed on all pages.
+
+{{< columns >}}
+
+[![Beach Color Palette](images/translation-available.png)](images/translation-available.png)
+
+On pages for which a translation is available it will be displayed in the selection list and links to the translated page.
+
+<--->
+
+[![Beach Color Palette](images/translation-not-available.png)](images/translation-not-available.png)
+
+Pages without a translation will be displayed in the selection list as well but are marked with an asterisk and link to the start page of the respective language.
+
+{{< /columns >}}

exampleSite/content/en/features/theming/_index.md

@@ -0,0 +1,61 @@
+---
+title: Theming
+---
+
+{{< toc >}}
+
+## Color Scheme
+
+If you want to customize the theme's color scheme to give it your individual touch, you are only a few lines of CSS away. Generally, you need to override the default settings. The easiest way to do this is to create a file named `static/custom.css` right at the root of your site.
+
+All the necessary CSS customization properties are listed below. If you want to customize elements that don't use these properties, you can always look up the class name and override it directly. For inspiration, you can also take a look at [https://www.color-hex.com/color-palettes/](https://www.color-hex.com/). In this simple example, we'll use the [_Beach_](https://www.color-hex.com/color-palette/895) color palette.
+
+[![Beach Color Palette](images/theme-example.png)](images/theme-example.png)
+
+**Custom CSS:**
+
+<!-- prettier-ignore-start -->
+<!-- spellchecker-disable -->
+{{< include file="/static/custom.css.example" language="CSS" options="linenos=table" >}}
+<!-- spellchecker-enable -->
+<!-- prettier-ignore-end -->
+
+## Favicons
+
+The Theme is shipped with a set of default Favicons in various formats generated by a [Favicon Generator](https://realfavicongenerator.net/). All files can be found in the `static/favicon` folder of the release tarball. To make the replacement of the default Favicons as simple as possible, the theme loads only a very small subset of the Favicon formats.
+
+<!-- prettier-ignore -->
+```tpl
+<link rel="icon" type="image/svg+xml" href="{{ "favicon/favicon.svg" | relURL }}">
+<link rel="icon" type="image/png" sizes="32x32" href="{{ "favicon/favicon-32x32.png" | relURL }}">
+<link rel="icon" type="image/png" sizes="16x16" href="{{ "favicon/favicon-16x16.png" | relURL }}">
+```
+
+### Simple replacement
+
+The minimal steps to load a custom Favicon is to overwrite tree default Favicon files. Therefor place these files into your projects root folder:
+
+- `static/favicon/favicon.svg`
+- `static/favicon/favicon-32x32.png`
+- `static/favicon/favicon-16x16.png`
+
+### Full replacement
+
+If you want to add more Favicon formats you have to [overwrite](https://gohugo.io/templates/partials/#partial-template-lookup-order) the default partial that is used to load the files. In the next step you have to place the required files in the `static` folder of your project as well.
+
+**Example:**
+
+<!-- prettier-ignore -->
+```tpl
+<!-- layouts/partials/head/favicons.html -->
+<link rel="icon" type="image/svg+xml" href="{{ "favicon/favicon.svg" | relURL }}">
+<link rel="apple-touch-icon" sizes="180x180" href="{{ "favicon/apple-touch-icon.png" | relURL }}">
+<link rel="icon" type="image/png" sizes="32x32" href="{{ "favicon/favicon-32x32.png" | relURL }}">
+<link rel="icon" type="image/png" sizes="16x16" href="{{ "favicon/favicon-16x16.png" | relURL }}">
+<link rel="manifest" href="{{ "favicon/site.webmanifest" | relURL }}">
+<link rel="mask-icon" href="{{ "favicon/safari-pinned-tab.svg" | relURL }}" color="#2f333e">
+<meta name="msapplication-TileColor" content="#2f333e">
+<meta name="theme-color" content="#2f333e">
+```
+
+Happy customizing!

exampleSite/content/en/posts/_index.md

@@ -0,0 +1,6 @@
+---
+title: News
+type: posts
+weight: 10
+geekdocHidden: true
+---

exampleSite/content/en/posts/hello_geekdoc.md

@@ -0,0 +1,13 @@
+---
+title: Hello Geekdoc
+type: posts
+date: 2020-01-06
+tags:
+  - Documentation
+---
+
+This is the first release of the Geekdoc theme.
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious copious quo ad. Stet probates in duo.
+
+Amalia id per in minimum facility, quid facet modifier ea ma. Ill um select ma ad, en ferric patine sentient vim. Per expendable foreordained interpretations cu, maxim sole pertinacity in ram. Que no rota alters, ad sea sues exercise main rum, cu diam mas facility sea.

exampleSite/content/en/posts/initial-release.md

@@ -0,0 +1,9 @@
+---
+title: Initial release
+type: posts
+date: 2020-01-08
+---
+
+This is the first release of the Geekdoc theme.
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious copious quo ad. Stet probates in duo.

exampleSite/content/en/shortcodes/_index.md

@@ -0,0 +1,4 @@
+---
+title: Shortcodes
+weight: -10
+---

exampleSite/content/en/shortcodes/buttons.md

@@ -0,0 +1,17 @@
+---
+title: Buttons
+---
+
+Buttons are styled links that can lead to local page or external link.
+
+<!-- prettier-ignore-start -->
+```tpl
+{{</* button relref="/" [class="...", size="large|regular"] */>}}Get Home{{</* /button */>}}
+{{</* button href="https://github.com/thegeeklab/hugo-geekdoc" */>}}Contribute{{</* /button */>}}
+```
+<!-- prettier-ignore-end -->
+
+## Example
+
+{{< button relref="/" >}}Get Home{{< /button >}}
+{{< button href="https://github.com/thegeeklab/hugo-geekdoc" >}}Contribute{{< /button >}}

exampleSite/content/en/shortcodes/columns.md

@@ -0,0 +1,50 @@
+---
+title: Columns
+---
+
+The Columns shortcode can be used to organize content side-by-side (horizontally) for better readability.
+
+```html
+{{</* columns */>}} <!-- begin columns block -->
+## Left Content
+Dolor sit, sumo unique argument um no ...
+
+<---> <!-- magic separator, between columns -->
+
+## Mid Content
+Dolor sit, sumo unique argument um no ...
+
+<---> <!-- magic separator, between columns -->
+
+## Right Content
+Dolor sit, sumo unique argument um no ...
+{{</* /columns */>}}
+```
+
+## Example
+
+{{< columns >}}
+
+## Left
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts
+feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious
+copious quo ad. Stet probates in duo.
+
+<--->
+
+## Mid Content
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re.
+
+<--->
+
+## Right Content
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts
+feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious
+copious quo ad. Stet probates in duo.
+{{< /columns >}}

exampleSite/content/en/shortcodes/expand.md

@@ -0,0 +1,46 @@
+---
+title: Expand
+---
+
+Expand shortcode can help to decrease clutter on screen by hiding part of text. Expand content by clicking on it.
+
+## Example
+
+### Default
+
+<!-- prettier-ignore-start -->
+```tpl
+{{</* expand */>}}
+## Markdown content
+Dolor sit, sumo unique ...
+{{</* /expand */>}}
+```
+<!-- prettier-ignore-end -->
+
+{{< expand >}}
+
+## Markdown content
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.
+{{< /expand >}}
+
+### With Custom Label
+
+<!-- prettier-ignore-start -->
+```tpl
+{{</* expand "Custom Label" "..." */>}}
+## Markdown content
+Dolor sit, sumo unique ...
+{{</* /expand */>}}
+```
+<!-- prettier-ignore-end -->
+
+{{< expand "Custom Label" "..." >}}
+
+## More markdown
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts
+feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious
+copious quo ad. Stet probates in duo.
+{{< /expand >}}

exampleSite/content/en/shortcodes/hints.md

@@ -0,0 +1,42 @@
+---
+title: Hints
+---
+
+Hint shortcode can be used as hint/alerts/notification block.
+There are four colors to choose: `info`, `ok`, `warning` and `danger`.
+
+<!-- prettier-ignore-start -->
+```tpl
+{{</* hint [info|ok|warning|danger] */>}}
+**Markdown content**\
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+ Ornateness bland it ex enc, est yeti am bongo detract re.
+{{</* /hint */>}}
+```
+<!-- prettier-ignore-end -->
+
+## Example
+
+{{< hint info >}}
+**Markdown content**\
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+{{< /hint >}}
+
+{{< hint ok >}}
+**Markdown content**\
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+{{< /hint >}}
+
+{{< hint warning >}}
+**Markdown content**\
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+{{< /hint >}}
+
+{{< hint danger >}}
+**Markdown content**\
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+{{< /hint >}}

exampleSite/content/en/shortcodes/icons.md

@@ -0,0 +1,21 @@
+---
+title: Icons
+---
+
+Simple shortcode to include icons from SVG sprites outside of menus.
+
+<!-- prettier-ignore-start -->
+```tpl
+{{</* icon "thumbs-up" */>}}
+```
+<!-- prettier-ignore-end -->
+
+**Example:**
+
+| Result                     | Usage                            |
+| -------------------------- | -------------------------------- |
+| {{< icon "thumbs-up" >}}   | `{{</* icon "thumbs-up" */>}}`   |
+| {{< icon "thumbs-down" >}} | `{{</* icon "thumbs-down" */>}}` |
+| {{< icon "laugh" >}}       | `{{</* icon "laugh" */>}}`       |
+| {{< icon "lemon" >}}       | `{{</* icon "lemon" */>}}`       |
+| {{< icon "moon" >}}        | `{{</* icon "moon" */>}}`        |

exampleSite/content/en/shortcodes/images/_index.md

@@ -0,0 +1,146 @@
+---
+title: Images
+resources:
+  - name: forest-1
+    src: "forest-1.jpg"
+    title: Forest (1)
+    params:
+      credits: "[Jay Mantri](https://unsplash.com/@jaymantri) on [Unsplash](https://unsplash.com/s/photos/forest)"
+  - name: forest-2
+    src: "forest-2.jpg"
+    title: Forest (2)
+    params:
+      credits: "[Jay Mantri](https://unsplash.com/@jaymantri) on [Unsplash](https://unsplash.com/s/photos/forest)"
+  - name: forest-3
+    src: "forest-3.jpg"
+    title: Forest (3)
+    params:
+      credits: "[Jay Mantri](https://unsplash.com/@jaymantri) on [Unsplash](https://unsplash.com/s/photos/forest)"
+  - name: forest-4
+    src: "forest-4.jpg"
+    title: Forest (4)
+    params:
+      credits: "[Jay Mantri](https://unsplash.com/@jaymantri) on [Unsplash](https://unsplash.com/s/photos/forest)"
+  - name: forest-5
+    src: "forest-5.jpg"
+    title: Forest (5)
+    params:
+      credits: "[Jay Mantri](https://unsplash.com/@jaymantri) on [Unsplash](https://unsplash.com/s/photos/forest)"
+  - name: forest-6
+    src: "forest-6.jpg"
+    title: Forest (6)
+    params:
+      credits: "[Asher Ward](https://unsplash.com/@the_asher_ward) on [Unsplash](https://unsplash.com/s/photos/forest)"
+  - name: forest-7
+    src: "forest-7.jpg"
+    title: Forest (7)
+    params:
+      credits: "[Asher Ward](https://unsplash.com/@the_asher_ward) on [Unsplash](https://unsplash.com/s/photos/forest)"
+---
+
+If you need more flexibility for your embedded images, you could use the `img` shortcode. It is using Hugo's
+[page resources](https://gohugo.io/content-management/page-resources/) and supports lazy loading of your images.
+
+**Attributes:**
+
+| Name          | Usage                                                                                                         | default           |
+| ------------- | ------------------------------------------------------------------------------------------------------------- | ----------------- |
+| name (string) | Name of the image resource defined in your front matter.                                                      | empty             |
+| alt (string)  | Description for displayed image.                                                                              | resource `.Title` |
+| size (string) | Thumbnail size (tiny\|small\|medium\|large).                                                                  | empty             |
+| lazy (bool)   | Enable or disable image lazy loading. Can be controlled globally by site parameter `geekdocImageLazyLoading`. | true              |
+
+**Example:**
+
+Define your resources in the page front matter, custom parameter `params.credits` is optional.
+
+<!-- spellchecker-disable -->
+
+```md
+---
+resources:
+  - name: forest-1
+    src: "forest-1.jpg"
+    title: Forest (1)
+    params:
+      credits: "[Jay Mantri](https://unsplash.com/@jaymantri) on [Unsplash](https://unsplash.com/s/photos/forest)"
+---
+
+{{</* img name="forest-1" size="large" lazy=false */>}}
+```
+
+<!-- spellchecker-enable -->
+
+**Demo:**
+
+<!-- spellchecker-disable -->
+
+{{< img name="forest-1" lazy=false >}}
+
+<!-- spellchecker-enable -->
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts
+feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious
+copious quo ad. Stet probates in duo.
+
+<!-- spellchecker-disable -->
+
+{{< img name="forest-2" lazy=true >}}
+
+<!-- spellchecker-enable -->
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts
+feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious
+copious quo ad. Stet probates in duo.
+
+<!-- spellchecker-disable -->
+
+{{< img name="forest-3" lazy=true >}}
+
+<!-- spellchecker-enable -->
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts
+feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious
+copious quo ad. Stet probates in duo.
+
+<!-- spellchecker-disable -->
+
+{{< img name="forest-4" lazy=true >}}
+
+<!-- spellchecker-enable -->
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts
+feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious
+copious quo ad. Stet probates in duo.
+
+<!-- spellchecker-disable -->
+
+{{< img name="forest-5" lazy=true >}}
+
+<!-- spellchecker-enable -->
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts
+feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious
+copious quo ad. Stet probates in duo.
+
+<!-- spellchecker-disable -->
+
+{{< img name="forest-6" lazy=true >}}
+
+<!-- spellchecker-enable -->
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts
+feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious
+copious quo ad. Stet probates in duo.
+
+<!-- spellchecker-disable -->
+
+{{< img name="forest-7" lazy=true >}}
+
+<!-- spellchecker-enable -->

exampleSite/content/en/shortcodes/includes.md

@@ -0,0 +1,93 @@
+---
+title: Includes
+---
+
+{{< toc >}}
+
+Include shortcode can include files of different types. By specifying a language, the included file will have syntax highlighting.
+
+<!-- prettier-ignore-start -->
+```tpl
+{{</* include file="relative/path/from/hugo/root" language="go" */>}}
+```
+<!-- prettier-ignore-end -->
+
+Attributes:
+
+| Name     | Usage                                                                                                                               | default                          |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| file     | path to the included file relative to the Hugo root                                                                                 | undefined                        |
+| language | language for [syntax highlighting](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) | undefined                        |
+| type     | special include type (`html,page`)                                                                                                  | undefined (rendered as markdown) |
+| options  | highlighting [options](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode)                               | `linenos=table`                  |
+
+## Examples
+
+### Markdown file (default)
+
+If no other options are specified, files will be rendered as Markdown using the `RenderString` [function](https://gohugo.io/functions/renderstring/).
+
+{{< hint warning >}}
+**Location of markdown files**\
+If you include markdown files that should not get a menu entry, place them outside the content folder or exclude them otherwise.
+{{< /hint >}}
+
+<!-- prettier-ignore -->
+```tpl
+{{</* include file="/static/_includes/example.md.part" */>}}
+```
+
+<!-- prettier-ignore-start -->
+<!-- spellchecker-disable -->
+{{< include file="/static/_includes/example.md.part" >}}
+<!-- spellchecker-enable -->
+<!-- prettier-ignore-end -->
+
+### Language files
+
+This method can be used to include source code files and keep them automatically up to date.
+
+<!-- prettier-ignore -->
+```tpl
+{{</* include file="config/_default/config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100" */>}}
+```
+
+Result:
+
+<!-- prettier-ignore-start -->
+<!-- spellchecker-disable -->
+{{< include file="config/_default/config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100" >}}
+<!-- spellchecker-enable -->
+<!-- prettier-ignore-end -->
+
+### Special include types
+
+#### HTML
+
+HTML content will be filtered by the `safeHTML` filter and added to the rendered page output.
+
+<!-- prettier-ignore -->
+```tpl
+{{</* include file="/static/_includes/example.html.part" type="html" */>}}
+```
+
+{{< include file="/static/_includes/example.html.part" type="html" >}}
+
+#### Pages
+
+In some situations, it can be helpful to include Markdown files that also contain shortcodes. While the [default method](#markdown-file-default) works fine to render plain Markdown, shortcodes are not parsed. The only way to get this to work is to use Hugo pages. There are several ways to structure these include pages, so whatever you do, keep in mind that Hugo needs to be able to render and serve these files as regular pages! How it works:
+
+1. First you need to create a directory **within** your content directory. For this example site `_includes` is used.
+2. To prevent the theme from embedding the page in the navigation, create a file `_includes/_index.md` and add `GeekdocHidden: true` to the front matter.
+3. Place your Markdown files within the `_includes` folder e.g. `/_includes/include-page.md`. Make sure to name it `*.md`.
+4. Include the page using `{{</* include file="/_includes/include-page.md" type="page" */>}}`.
+
+Resulting structure should look like this:
+
+```Shell
+_includes/
+ ├── include-page.md
+ └── _index.md
+```
+
+{{< include file="/_includes/include-page.md" type="page" >}}

exampleSite/content/en/shortcodes/katex.md

@@ -0,0 +1,39 @@
+---
+title: KaTeX
+---
+
+[KaTeX](https://katex.org/) shortcode let you render math typesetting in markdown document.
+
+## Example
+
+{{< columns >}}
+
+```latex
+{{</* katex [display] [class="text-center"] */>}}
+f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
+{{</* /katex */>}}
+```
+
+<--->
+
+<!-- spellchecker-disable -->
+<!-- prettier-ignore -->
+{{< katex display >}}
+f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
+{{< /katex >}}
+
+<!-- spellchecker-enable -->
+
+{{< /columns >}}
+
+KaTeX can also be used inline, for example {{< katex >}}\pi(x){{< /katex >}} or used with a `display` setting. for example `display: block`:
+
+<!-- spellchecker-disable -->
+<!-- prettier-ignore -->
+{{< katex display >}}
+f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
+{{< /katex >}}
+
+<!-- spellchecker-enable -->
+
+Text continues here.

exampleSite/content/en/shortcodes/mermaid.md

@@ -0,0 +1,46 @@
+---
+title: Mermaid
+---
+
+[Mermaid](https://mermaidjs.github.io/) is library for generating SVG charts and diagrams from text.
+
+## Example
+
+{{< columns >}}
+
+<!-- prettier-ignore -->
+```tpl
+{{</* mermaid class="text-center"*/>}}
+sequenceDiagram
+    Alice->>Bob: Hello Bob, how are you?
+    alt is sick
+        Bob->>Alice: Not so good :(
+    else is well
+        Bob->>Alice: Feeling fresh like a daisy
+    end
+    opt Extra response
+        Bob->>Alice: Thanks for asking
+    end
+{{</* /mermaid */>}}
+```
+
+<--->
+
+<!-- spellchecker-disable -->
+<!-- prettier-ignore -->
+{{< mermaid class="text-center" >}}
+sequenceDiagram
+    Alice->>Bob: Hello Bob, how are you?
+    alt is sick
+        Bob->>Alice: Not so good :(
+    else is well
+        Bob->>Alice: Feeling fresh like a daisy
+    end
+    opt Extra response
+        Bob->>Alice: Thanks for asking
+    end
+{{< /mermaid >}}
+
+<!-- spellchecker-enable -->
+
+{{< /columns >}}

exampleSite/content/en/shortcodes/tabs.md

@@ -0,0 +1,54 @@
+---
+title: Tabs
+---
+
+Tabs let you organize content by context, for example installation instructions for each supported platform.
+
+<!-- prettier-ignore-start -->
+```tpl
+{{</* tabs "uniqueid" */>}}
+{{</* tab "macOS" */>}} # macOS Content {{</* /tab */>}}
+{{</* tab "Linux" */>}} # Linux Content {{</* /tab */>}}
+{{</* tab "Windows" */>}} # Windows Content {{</* /tab */>}}
+{{</* /tabs */>}}
+```
+<!-- prettier-ignore-end -->
+
+## Example
+
+{{< tabs "uniqueid" >}}
+{{< tab "macOS" >}}
+
+## macOS
+
+This is tab **macOS** content.
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad
+prompts feud gait, quid exercise emeritus bis e. In pro quints consequent, denim
+fastidious copious quo ad. Stet probates in duo.
+{{< /tab >}}
+
+{{< tab "Linux" >}}
+
+## Linux
+
+This is tab **Linux** content.
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad
+prompts feud gait, quid exercise emeritus bis e. In pro quints consequent, denim
+fastidious copious quo ad. Stet probates in duo.
+{{< /tab >}}
+
+{{< tab "Windows" >}}
+
+## Windows
+
+This is tab **Windows** content.
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
+investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad
+prompts feud gait, quid exercise emeritus bis e. In pro quints consequent.
+{{< /tab >}}
+{{< /tabs >}}

exampleSite/content/en/shortcodes/toc-tree.md

@@ -0,0 +1,15 @@
+---
+title: ToC-Tree
+---
+
+The `toc-tree` shortcode will generate a Table of Content from a section file tree of your content directory. The root of the resulting ToC will be the page on which you define the shortcode.
+
+<!-- prettier-ignore-start -->
+```tpl
+{{</* toc-tree */>}}
+```
+<!-- prettier-ignore-end -->
+
+## Example
+
+As said, the root will be the site on which the shortcode was used, you can see a demo including nesting in the [ToC Tree](/toc-tree/) section.

exampleSite/content/en/shortcodes/toc.md

@@ -0,0 +1,43 @@
+---
+title: ToC
+---
+
+Simple wrapper to generate a page Table of Content from a shortcode.
+
+<!-- prettier-ignore-start -->
+```tpl
+{{</* toc */>}}
+```
+<!-- prettier-ignore-end -->
+
+{{< toc >}}
+
+## Level 1
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious copious quo ad. Stet probates in duo.
+
+## Level 2
+
+Amalia id per in minimum facility, quid facet modifier ea ma. Ill um select ma ad, en ferric patine sentient vim. Per expendable foreordained interpretations cu, maxim sole pertinacity in ram.
+
+### Level 2.1
+
+Amalia id per in minimum facility, quid facet modifier ea ma. Ill um select ma ad, en ferric patine sentient vim. Per expendable foreordained interpretations cu, maxim sole pertinacity in ram.
+
+#### Level 2.1.1
+
+Amalia id per in minimum facility, quid facet modifier ea ma. Ill um select ma ad, en ferric patine sentient vim.
+
+##### Level 2.1.1.1
+
+In pro quints consequent, denim fastidious copious quo ad.
+
+###### Level 2.1.1.1.1
+
+In pro quints consequent, denim fastidious copious quo ad.
+
+### Level 2.2
+
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts feud gait, quid exercise emeritus bis e.
+
+Amalia id per in minimum facility, quid facet modifier ea ma. Ill um select ma ad, en ferric patine sentient vim. Per expendable foreordained interpretations cu, maxim sole pertinacity in ram.

exampleSite/content/en/toc-tree/_index.md

@@ -0,0 +1,12 @@
+---
+title: ToC-Tree
+geekdocFlatSection: true
+---
+
+This is just a demo section for the <!-- spellchecker-disable -->[toc-tree](/shortcodes/toc-tree/)<!-- spellchecker-enable --> shortcode.
+
+<!-- spellchecker-disable -->
+
+{{< toc-tree >}}
+
+<!-- spellchecker-enable -->

exampleSite/content/en/toc-tree/level-1/_index.md

@@ -0,0 +1,11 @@
+---
+geekdocCollapseSection: true
+---
+
+Level 1
+
+<!-- spellchecker-disable -->
+
+{{< toc-tree >}}
+
+<!-- spellchecker-enable -->

exampleSite/content/en/toc-tree/level-1/level-1-1.md

@@ -0,0 +1,5 @@
+---
+title: Level 1.1
+---
+
+Level 1.1

exampleSite/content/en/toc-tree/level-1/level-1-2.md

@@ -0,0 +1,5 @@
+---
+title: Level 1.2
+---
+
+Level 1.2

exampleSite/content/en/toc-tree/level-1/level-1-3/_index.md

@@ -0,0 +1,11 @@
+---
+title: Level 1.3
+---
+
+Level 1.3
+
+<!-- spellchecker-disable -->
+
+{{< toc-tree >}}
+
+<!-- spellchecker-enable -->

exampleSite/content/en/toc-tree/level-1/level-1-3/level-1-3-1.md

@@ -0,0 +1,5 @@
+---
+title: Level 1.3.1
+---
+
+Level 1.3.1

exampleSite/content/en/toc-tree/level-2/_index.md

@@ -0,0 +1 @@
+Level-2

exampleSite/content/en/toc-tree/level-2/level-2-1.md

@@ -0,0 +1,5 @@
+---
+title: Level 2.1
+---
+
+Level 2.1

exampleSite/content/en/toc-tree/level-2/level-2-2.md

@@ -0,0 +1,5 @@
+---
+title: Level 2.2
+---
+
+Level 2.2

exampleSite/content/en/usage/_index.md

@@ -0,0 +1,4 @@
+---
+title: Usage
+weight: -20
+---

exampleSite/content/en/usage/configuration.md

@@ -0,0 +1,360 @@
+---
+title: Configuration
+weight: -10
+---
+
+{{< toc >}}
+
+## Site configuration
+
+{{< tabs "site-config" >}}
+{{< tab "TOML" >}}
+
+```Toml
+baseURL = "http://localhost"
+title = "Geekdocs"
+theme = "hugo-geekdoc"
+
+# Required to get well formatted code blocks
+pygmentsUseClasses = true
+pygmentsCodeFences = true
+disablePathToLower = true
+enableGitInfo = true
+
+# Required if you want to render robots.txt template
+enableRobotsTXT = true
+
+[markup]
+  [markup.goldmark.renderer]
+    # Needed for mermaid shortcode
+    unsafe = true
+  [markup.tableOfContents]
+    startLevel = 1
+    endLevel = 9
+
+[taxonomies]
+  tag = "tags"
+
+[params]
+  # (Optional, default 6) Set how many table of contents levels to be showed on page.
+  # Use false to hide ToC, note that 0 will default to 6 (https://gohugo.io/functions/default/)
+  # You can also specify this parameter per page in front matter.
+  geekdocToC = 3
+
+  # (Optional, default static/brand.svg) Set the path to a logo for the Geekdoc
+  # relative to your 'static/' folder.
+  geekdocLogo = "logo.png"
+
+  # (Optional, default false) Render menu from data file in 'data/menu/main.yaml'.
+  # See also https://geekdocs.de/usage/menus/#bundle-menu.
+  geekdocMenuBundle = true
+
+  # (Optional, default false) Collapse all menu entries, can not be overwritten
+  # per page if enabled. Can be enabled per page via `geekdocCollapseSection`.
+  geekdocCollapseAllSections = true
+
+  # (Optional, default true) Show page navigation links at the bottom of each
+  # docs page (bundle menu only).
+  geekdocNextPrev = false
+
+  # (Optional, default true) Show a breadcrumb navigation bar at the top of each docs page.
+  # You can also specify this parameter per page in front matter.
+  geekdocBreadcrumb = false
+
+  # (Optional, default none) Set source repository location. Used for 'Edit page' links.
+  # You can also specify this parameter per page in front matter.
+  geekdocRepo = "https://github.com/thegeeklab/hugo"
+
+  # (Optional, default none) Enable 'Edit page' links. Requires 'GeekdocRepo' param
+  # and path must point to 'content' directory of repo.
+  # You can also specify this parameter per page in front matter.
+  geekdocEditPath = "edit/main/exampleSite/content"
+
+  # (Optional, default true) Enables search function with flexsearch.
+  # Index is built on the fly and might slow down your website.
+  geekdocSearch = false
+
+  # (Optional, default false) Display search results with the parent folder as prefix. This
+  # option allows you to distinguish between files with the same name in different folders.
+  # NOTE: This parameter only applies when 'geekdocSearch = true'.
+  geekdocSearchShowParent = true
+
+  # (Optional, default none) Add a link to your Legal Notice page to the site footer.
+  # It can be either a remote url or a local file path relative to your content directory.
+  geekdocLegalNotice = "https://blog.example.com/legal"
+
+  # (Optional, default none) Add a link to your Privacy Policy page to the site footer.
+  # It can be either a remote url or a local file path relative to your content directory.
+  geekdocPrivacyPolicy = "/privacy"
+
+  # (Optional, default true) Add an anchor link to headlines.
+  geekdocAnchor = true
+
+  # (Optional, default true) Copy anchor url to clipboard on click.
+  geekdocAnchorCopy = true
+
+  # (Optional, default true) Enable or disable image lazy loading for images rendered
+  # by the 'img' shortcode.
+  geekdocImageLazyLoading = true
+
+  # (Optional, default false) Set HTMl <base> to .Site.BaseURL if enabled. It might be required
+  # if a subdirectory is used within Hugos BaseURL.
+  # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base.
+  geekdocOverwriteHTMLBase = false
+
+  # (Optional, default false) Auto-decrease brightness of images and add a slightly grayscale to avoid
+  # bright spots while using the dark mode.
+  geekdocDarkModeDim = false
+
+  # (Optional, default true) Display a "Back to top" link in the site footer.
+  geekdocBackToTop = true
+
+  # (Optional, default false) Enable or disable adding tags for post pages automatically to the navigation sidebar.
+  geekdocTagsToMenu = true
+
+  # (Optional, default 'title') Configure how to sort file-tree menu entries. Possible options are 'title', 'linktitle',
+  # 'date', 'publishdate', 'expirydate' or 'lastmod'. Every option can be used with a reverse modifier as well
+  # e.g. 'title_reverse'.
+  geekdocFileTreeSortBy = "title"
+```
+
+{{< /tab >}}
+{{< tab "YAML" >}}
+
+```Yaml
+---
+baseURL: "http://localhost"
+title: "Geekdocs"
+theme: "hugo-geekdoc"
+
+# Required to get well formatted code blocks
+pygmentsUseClasses: true
+pygmentsCodeFences: true
+disablePathToLower: true
+enableGitInfo: true
+
+# Required if you want to render robots.txt template
+enableRobotsTXT: true
+
+markup:
+  goldmark:
+    # Needed for mermaid shortcode
+    renderer:
+      unsafe: true
+  tableOfContents:
+    startLevel: 1
+    endLevel: 9
+
+taxonomies:
+  tag: tags
+
+params:
+  # (Optional, default 6) Set how many table of contents levels to be showed on page.
+  # Use false to hide ToC, note that 0 will default to 6 (https://gohugo.io/functions/default/)
+  # You can also specify this parameter per page in front matter.
+  geekdocToC: 3
+
+  # (Optional, default static/brand.svg) Set the path to a logo for the Geekdoc
+  # relative to your 'static/' folder.
+  geekdocLogo: logo.png
+
+  # (Optional, default false) Render menu from data file in 'data/menu/main.yaml'.
+  # See also https://geekdocs.de/usage/menus/#bundle-menu.
+  geekdocMenuBundle: true
+
+  # (Optional, default false) Collapse all menu entries, can not be overwritten
+  # per page if enabled. Can be enabled per page via `geekdocCollapseSection`.
+  geekdocCollapseAllSections: true
+
+  # (Optional, default true) Show page navigation links at the bottom of each
+  # docs page (bundle menu only).
+  geekdocNextPrev: false
+
+  # (Optional, default true) Show a breadcrumb navigation bar at the top of each docs page.
+  # You can also specify this parameter per page in front matter.
+  geekdocBreadcrumb: false
+
+  # (Optional, default none) Set source repository location. Used for 'Edit page' links.
+  # You can also specify this parameter per page in front matter.
+  geekdocRepo: "https://github.com/thegeeklab/hugo-geekdoc"
+
+  # (Optional, default none) Enable "Edit page" links. Requires 'GeekdocRepo' param
+  # and path must point to 'content' directory of repo.
+  # You can also specify this parameter per page in front matter.
+  geekdocEditPath: edit/main/exampleSite/content
+
+  # (Optional, default true) Enables search function with flexsearch.
+  # Index is built on the fly and might slow down your website.
+  geekdocSearch: false
+
+  # (Optional, default false) Display search results with the parent folder as prefix. This
+  # option allows you to distinguish between files with the same name in different folders.
+  # NOTE: This parameter only applies when 'geekdocSearch: true'.
+  geekdocSearchShowParent: true
+
+  # (Optional, default none) Add a link to your Legal Notice page to the site footer.
+  # It can be either a remote url or a local file path relative to your content directory.
+  geekdocLegalNotice: "https://blog.example.com/legal"
+
+  # (Optional, default none) Add a link to your Privacy Policy page to the site footer.
+  # It can be either a remote url or a local file path relative to your content directory.
+  geekdocPrivacyPolicy: "/privacy"
+
+  # (Optional, default true) Add an anchor link to headlines.
+  geekdocAnchor: true
+
+  # (Optional, default true) Copy anchor url to clipboard on click.
+  geekdocAnchorCopy: true
+
+  # (Optional, default true) Enable or disable image lazy loading for images rendered
+  # by the 'img' shortcode.
+  geekdocImageLazyLoading: true
+
+  # (Optional, default false) Set HTMl <base> to .Site.BaseURL if enabled. It might be required
+  # if a subdirectory is used within Hugos BaseURL.
+  # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base.
+  geekdocOverwriteHTMLBase: false
+
+  # (Optional, default false) Auto-decrease brightness of images and add a slightly grayscale to avoid
+  # bright spots while using the dark mode.
+  geekdocDarkModeDim: false
+
+  # (Optional, default true) Display a "Back to top" link in the site footer.
+  geekdocBackToTop: true
+
+  # (Optional, default false) Enable or disable adding tags for post pages automatically to the navigation sidebar.
+  geekdocTagsToMenu: true
+
+  # (Optional, default 'title') Configure how to sort file-tree menu entries. Possible options are 'title', 'linktitle',
+  # 'date', 'publishdate', 'expirydate' or 'lastmod'. Every option can be used with a reverse modifier as well
+  # e.g. 'title_reverse'.
+  geekdocFileTreeSortBy: "title"
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
+## Page configuration
+
+{{< tabs "page-config" >}}
+{{< tab "TOML" >}}
+
+```Toml
+# Set type to 'posts' if you want to render page as blogpost
+type = "posts"
+
+# Set page weight to re-arrange items in file-tree menu.
+weight = 10
+
+# Set how many table of contents levels to be showed on page.
+geekdocToC = 3
+
+# Set a description for the current page. This will be shown in toc-trees objects.
+geekdocDescription =
+
+# Set false to hide the whole left navigation sidebar. Beware that it will make
+# navigation pretty hard without adding some kind of on-page navigation.
+geekdocNav = true
+
+# Show a breadcrumb navigation bar at the top of each docs page.
+geekdocBreadcrumb = false
+
+# Set source repository location.
+geekdocRepo = "https://github.com/thegeeklab/hugo-geekdoc"
+
+# Enable "Edit page" links. Requires 'GeekdocRepo' param and path must point
+# to 'content' directory of repo.
+geekdocEditPath = "edit/main/exampleSite/content"
+
+# Used for 'Edit page' link, set to '.File.Path' by default.
+# Can be overwritten by a path relative to 'geekdocEditPath'
+geekdocFilePath =
+
+# Set to mark page as flat section (file-tree menu only).
+geekdocFlatSection = true
+
+# Set true to hide page or section from side menu (file-tree menu only).
+geekdocHidden = true
+
+# Set false to show this page as a file-tree menu entry when you want it to be hidden in the sidebar.
+# NOTE: Only applies when 'geekdocHidden = true'.
+geekdocHiddenTocTree = true
+
+# Set to true to make a section foldable in side menu.
+geekdocCollapseSection = true
+
+# Add an anchor link to headlines.
+geekdocAnchor = true
+
+# If you have protected some pages with e.g. basic authentication you may want to exclude these pages
+# from data file, otherwise information may be leaked. Setting this parameter to 'true' will exclude the
+# page from search data, feeds, etc.
+# WARNING: Consider hosting a standalone, fully auth-protected static page for secret information instead!
+geekdocProtected = false
+
+# Set 'left' (default), 'center' or 'right' to configure the text align of a page.
+geekdocAlign = "left"
+```
+
+{{< /tab >}}
+{{< tab "YAML" >}}
+
+```Yaml
+# Set type to 'posts' if you want to render page as blogpost.
+type: "posts"
+
+# Set page weight to re-arrange items in file-tree menu.
+weight: 10
+
+# Set how many table of contents levels to be showed on page.
+geekdocToC: 3
+
+# Set a description for the current page. This will be shown in toc-trees objects.
+geekdocDescription:
+
+# Set false to hide the whole left navigation sidebar. Beware that it will make
+# navigation pretty hard without adding some kind of on-page navigation.
+geekdocNav: true
+
+# Show a breadcrumb navigation bar at the top of each docs page.
+geekdocBreadcrumb: false
+
+# Set source repository location.
+geekdocRepo: "https://github.com/thegeeklab/hugo-geekdoc"
+
+# Enable "Edit page" links. Requires 'GeekdocRepo' param and path must point
+# to 'content' directory of repo.
+geekdocEditPath: "edit/main/exampleSite/content"
+
+# Used for 'Edit page' link, set to '.File.Path' by default.
+# Can be overwritten by a path relative to 'geekdocEditPath'
+geekdocFilePath:
+
+# Set to mark page as flat section (file-tree menu only).
+geekdocFlatSection: true
+
+# Set true to hide page or section from side menu (file-tree menu only).
+geekdocHidden: true
+
+# Set false to show this page as a file-tree menu entry when you want it to be hidden in the sidebar.
+# NOTE: Only applies when 'geekdocHidden: true'.
+geekdocHiddenTocTree: true
+
+# Set to true to make a section foldable in side menu.
+geekdocCollapseSection: true
+
+# Add an anchor link to headlines.
+geekdocAnchor: true
+
+# If you have protected some pages with e.g. basic authentication you may want to exclude these pages
+# from data file, otherwise information may be leaked. Setting this parameter to 'true' will exclude the
+# page from search data, feeds, etc.
+# WARNING: Consider hosting a standalone, fully auth-protected static page for secret information instead!
+geekdocProtected: false
+
+# Set 'left' (default), 'center' or 'right' to configure the text align of a page.
+geekdocAlign: "left"
+```
+
+{{< /tab >}}
+{{< /tabs >}}

exampleSite/content/en/usage/getting-started.md

@@ -0,0 +1,197 @@
+---
+title: Getting Started
+weight: -20
+---
+
+This page tells you how to get started with the Geekdoc theme, including installation and basic configuration.
+
+<!--more-->
+
+{{< toc >}}
+
+## Install requirements
+
+You need a recent version of Hugo for local builds and previews of sites that use Geekdoc. As we are using [gulp](https://gulpjs.com/) as pre-processor the normal version of Hugo is sufficient. If you prefer the extended version of Hugo anyway this will work as well. For comprehensive Hugo documentation, see [gohugo.io](https://gohugo.io/documentation/).
+
+If you want to use the theme from a cloned branch instead of a release tarball you'll need to install `gulp` locally and run the default pipeline once to create all required assets.
+
+```Shell
+# install required packages from package.json
+npm install
+
+# run gulp pipeline to build required assets
+npx gulp default
+```
+
+## Using the theme
+
+To prepare your new site environment just a few steps are required:
+
+1. Create a new empty Hugo site.
+
+   ```Shell
+   hugo new site demosite
+   ```
+
+2. Switch to the root of the new site.
+
+   ```Shell
+   cd demosite
+   ```
+
+3. Install the Geekdoc theme from a [release bundle](#option-1-download-pre-build-release-bundle) (recommended) or from [Git branch](#option-2-clone-the-github-repository).
+
+4. Create the minimal required Hugo configuration `config.toml`. For all configuration options take a look at the [configuration](/usage/configuration/) page.
+
+   ```Toml
+   baseURL = "http://localhost"
+   title = "Geekdocs"
+   theme = "hugo-geekdoc"
+
+   pluralizeListTitles = false
+
+   # Geekdoc required configuration
+   pygmentsUseClasses = true
+   pygmentsCodeFences = true
+   disablePathToLower = true
+
+   # Required if you want to render robots.txt template
+   enableRobotsTXT = true
+
+   # Needed for mermaid shortcodes
+   [markup]
+     [markup.goldmark.renderer]
+       # Needed for mermaid shortcode
+       unsafe = true
+     [markup.tableOfContents]
+       startLevel = 1
+       endLevel = 9
+
+   [taxonomies]
+      tag = "tags"
+   ```
+
+5. Test your site.
+
+   ```Shell
+   hugo server -D
+   ```
+
+### Option 1: Download pre-build release bundle
+
+Download and extract the latest release bundle into the theme directory.
+
+```Shell
+mkdir -p themes/hugo-geekdoc/
+curl -L https://github.com/thegeeklab/hugo-geekdoc/releases/latest/download/hugo-geekdoc.tar.gz | tar -xz -C themes/hugo-geekdoc/ --strip-components=1
+```
+
+### Option 2: Clone the GitHub repository
+
+{{< hint info >}}
+**Info**\
+Keep in mind this method is not recommended and needs some extra steps to get it working.
+If you want to use the Theme as submodule keep in mind that your build process need to
+run the described steps as well.
+{{< /hint >}}
+
+Clone the Geekdoc git repository.
+
+```Shell
+git clone https://github.com/thegeeklab/hugo-geekdoc.git themes/hugo-geekdoc
+```
+
+Build required theme assets e.g. CSS files and SVG sprites with `gulp`.
+
+```Shell
+npx gulp default
+```
+
+## Deployments
+
+### Netlify
+
+There are several ways to deploy your site with this theme on Netlify. Regardless of which solution you choose, the main goal is to ensure that the prebuilt theme release tarball is used or to run the [required commands](#option-2-clone-the-github-repository) to prepare the theme assets before running the Hugo build command.
+
+Here are some possible solutions:
+
+**Use a Makefile:**
+
+Add a Makefile to your repository to bundle the required steps.
+
+```Makefile
+THEME_VERSION := v0.8.2
+THEME := hugo-geekdoc
+BASEDIR := docs
+THEMEDIR := $(BASEDIR)/themes
+
+.PHONY: doc
+doc: doc-assets doc-build
+
+.PHONY: doc-assets
+doc-assets:
+   mkdir -p $(THEMEDIR)/$(THEME)/ ; \
+   curl -sSL "https://github.com/thegeeklab/$(THEME)/releases/download/${THEME_VERSION}/$(THEME).tar.gz" | tar -xz -C $(THEMEDIR)/$(THEME)/ --strip-components=1
+
+.PHONY: doc-build
+doc-build:
+        cd $(BASEDIR); hugo
+
+.PHONY: clean
+clean:
+   rm -rf $(THEMEDIR) && \
+   rm -rf $(BASEDIR)/public
+```
+
+This Makefile can be used in your `netlify.toml`, take a look at the Netlify [example](https://docs.netlify.com/configure-builds/file-based-configuration/#sample-file) for more information:
+
+```toml
+[build]
+publish = "docs/public"
+command = "make doc"
+```
+
+**Chain required commands:**
+
+Chain all required commands to prepare the theme and build your site on the `command` option in your `netlify.toml` like this:
+
+```toml
+[build]
+publish = "docs/public"
+command = "command1 && command 2 && command3 && hugo"
+```
+
+### Subdirectories
+
+{{< hint danger >}}
+**Warning**\
+As deploying Hugo sites on subdirectories is not as robust as on subdomains, we do not recommend this.
+If you have a choice, using a domain/subdomain should always be the preferred solution!
+{{< /hint >}}
+
+If you want to deploy your side to a subdirectory of your domain, some extra steps are required:
+
+- Configure your Hugo base URL e.g. `baseURL = http://localhost/demo/`.
+- Don't use `relativeURLs: false` nor `canonifyURLs: true` as is can cause unwanted side effects!
+
+There are two ways to get Markdown links or images working:
+
+- Use the absolute path including your subdirectory e.g. `[testlink](/demo/example-site)`
+- Overwrite the HTML base in your site configuration with `geekdocOverwriteHTMLBase = true` and use the relative path e.g. `[testlink](example-site)`
+
+But there is another special case if you use `geekdocOverwriteHTMLBase = true`. If you use anchors in your Markdown links you have to ensure to always include the page path. As an example `[testlink](#some-anchor)` will resolve to `http://localhost/demo/#some-anchor` and not automatically include the current page!
+
+## Known Limitations
+
+### Minify HTML results in spacing issues
+
+Using `hugo --minify` without further configuration or using other minify tools that also minify HTML files might result in spacing issues in the theme and is **not** supported.
+
+After some testing we decided to not spend effort to fix this issue for now as the benefit is very low. There are some parts of the theme where spaces between HTML elements matters but were stripped by minify tools. Some of these issues are related to <!-- spellchecker-disable -->[gohugoio/hugo#6892](https://github.com/gohugoio/hugo/issues/6892).<!-- spellchecker-enable --> While recommendation like "don't depend on whitespace in your layout" sounds reasonable, it seems to be not that straight forward especially for something like embedded icons into the text flow.
+
+If you still want to use Hugo's minify flag you should at least exclude HTML file in your site [configuration](https://gohugo.io/getting-started/configuration/#configure-minify):
+
+```toml
+[minify]
+  disableHTML = true
+```

exampleSite/content/en/usage/menus.md

@@ -0,0 +1,111 @@
+---
+title: Menus
+---
+
+The theme supports two different kinds of menus. File-tree menu is the default one and does not require further configuration to work. If you want full control about your menu the bundle menu is a powerful option to accomplish it.
+
+{{< toc >}}
+
+## File-tree menu
+
+As the name already suggests, the file tree menu builds a menu from the file system structure of the content folder. By default, areas and subareas are sorted alphabetically by the title of the pages. To manipulate the order the `weight` parameter in a page [front matter](https://gohugo.io/content-management/front-matter/) can be used. To structure your content folder you have to use [page bundles](https://gohugo.io/content-management/organization/#page-bundles), single files are **not** supported. Hugo will render build single files in the content folder just fine but it will not be added to the menu.
+
+**Example:**
+
+File system structure:
+
+```plain
+content/
+├── level-1
+│   ├── _index.md
+│   ├── level-1-1.md
+│   ├── level-1-2.md
+│   └── level-1-3
+│       ├── _index.md
+│       └── level-1-3-1.md
+└── level-2
+    ├── _index.md
+    ├── level-2-1.md
+    └── level-2-2.md
+```
+
+[![Example file-tree menu](/media/file-tree.png)](/media/file-tree.png)
+
+## Bundle menu
+
+This type of navigation needs to be enabled first by setting `geekdocMenuBundle` to `true` in your [site configuration](/usage/configuration/#site-configuration). After you have activated the bundle menu, you start with an empty navigation. This is intentional because bundle menus have to be defined manually in a data file. While this increases the effort it also offers maximum flexibility in the design. The data file needs to be written in YAML and placed at `data/menu/main.yaml`.
+
+**Example:**
+
+```YAML
+---
+main:
+  - name: Level 1
+    ref: "/level-1"
+    icon: "gdoc_notification"
+    sub:
+      - name: Level 1.1
+        ref: "/level-1/level-1-1"
+      - name: Level 1.2
+        ref: "/level-1/level-1-2"
+      - name: Level 1.3
+        ref: "/level-1/level-1-3"
+        sub:
+          - name: Level 1.3.1
+            ref: "/level-1/level-1-3/level-1-3-1"
+  - name: Level 2
+    ref: "/level-2"
+    sub:
+      - name: Level 2.1
+        ref: "/level-2/level-2-1"
+      - name: Level 2.2
+        ref: "/level-2/level-2-2"
+```
+
+As an advantage you can add [icons](/features/icon-sets/) to your menu entries e.g. `icon: "gdoc_notification"`.
+
+[![Example bundle menu](/media/bundle-menu.png)](/media/bundle-menu.png)
+
+### More menu
+
+{{< hint ok >}}
+**Tip**\
+The more menu is special type of the bundle menu and can be combined with the default file-tree menu.
+{{< /hint >}}
+
+As this is a special type of the bundle menu it is basically working in the same way. To enable it just add a data file to `data/menu/more.yaml`. The more menu will also work with the file-tree menu and therefor **don't need to be enabled** by the `geekdocMenuBundle` parameter.
+
+**Example:**
+
+```YAML
+---
+more:
+  - name: News
+    ref: "/#"
+    icon: "gdoc_notification"
+  - name: Releases
+    ref: "https://github.com/thegeeklab/hugo-geekdoc/releases"
+    external: true
+    icon: "gdoc_download"
+  - name: "View Source"
+    ref: "https://github.com/thegeeklab/hugo-geekdoc"
+    external: true
+    icon: "gdoc_github"
+```
+
+[![Example bundle menu](/media/more-menu.png)](/media/more-menu.png)
+
+## Extra Header Menu
+
+If you want to customize the header menu, this can be achieved by using a data file written in YAML and placed at `data/menu/extra.yaml`.
+
+**Example:**
+
+```Yaml
+---
+header:
+  - name: GitHub
+    ref: https://github.com/thegeeklab/hugo-geekdoc
+    icon: gdoc_github
+    external: true
+```