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.
This commit is contained in:
Robert Kaussow
GitHub
parent
42ebf067bb
commit
5c22ce57dc
88 changed files with 437 additions and 144 deletions
4
exampleSite/content/en/usage/_index.md
Normal file
4
exampleSite/content/en/usage/_index.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
---
|
||||
title: Usage
|
||||
weight: -20
|
||||
---
|
||||
360
exampleSite/content/en/usage/configuration.md
Normal file
360
exampleSite/content/en/usage/configuration.md
Normal file
|
|
@ -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 >}}
|
||||
197
exampleSite/content/en/usage/getting-started.md
Normal file
197
exampleSite/content/en/usage/getting-started.md
Normal file
|
|
@ -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
|
||||
```
|
||||
111
exampleSite/content/en/usage/menus.md
Normal file
111
exampleSite/content/en/usage/menus.md
Normal file
|
|
@ -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
|
||||
```
|
||||
|
||||
[](/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"`.
|
||||
|
||||
[](/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"
|
||||
```
|
||||
|
||||
[](/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
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue