From 72ffa013630d147bfa6dd2023cd83b0d2c5e154a Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Sun, 11 Apr 2021 13:58:06 +0200 Subject: [PATCH] docs: add known limitations (#94) * docs: add known limitations * fix typos --- .dictionary | 2 ++ exampleSite/content/usage/configuration.md | 4 ++-- exampleSite/content/usage/getting-started.md | 15 +++++++++++++++ 3 files changed, 19 insertions(+), 2 deletions(-) diff --git a/.dictionary b/.dictionary index dd59652..971906c 100644 --- a/.dictionary +++ b/.dictionary @@ -20,3 +20,5 @@ Netlify Makefile prebuilt (S|s)ubdirector(ies|y) +(M|m)inify +whitespace diff --git a/exampleSite/content/usage/configuration.md b/exampleSite/content/usage/configuration.md index c0b8374..f686e1d 100644 --- a/exampleSite/content/usage/configuration.md +++ b/exampleSite/content/usage/configuration.md @@ -87,7 +87,7 @@ enableGitInfo = true geekdocImageLazyLoading = true # (Optional, default false) Set HTMl to .Site.BaseURL if enabled. Is might be required - # a subdirectory is used within Hugos BaseURL. + # a subdirectory is used within Hugo's BaseURL. # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base. geekdocOverwriteHTMLBase = false ``` @@ -175,7 +175,7 @@ params: geekdocImageLazyLoading: true # (Optional, default false) Set HTMl to .Site.BaseURL if enabled. Is might be required - # a subdirectory is used within Hugos BaseURL. + # a subdirectory is used within Hugo's BaseURL. # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base. geekdocOverwriteHTMLBase: false ``` diff --git a/exampleSite/content/usage/getting-started.md b/exampleSite/content/usage/getting-started.md index 093bbdc..140bddc 100644 --- a/exampleSite/content/usage/getting-started.md +++ b/exampleSite/content/usage/getting-started.md @@ -172,3 +172,18 @@ There are two ways to get Markdown links or images working: - 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 [gohugoio/hugo#6892](https://github.com/gohugoio/hugo/issues/6892). 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 +```