docs: add known limitations (#94)

* docs: add known limitations

* fix typos
This commit is contained in:
Robert Kaussow 2021-04-11 13:58:06 +02:00 committed by GitHub
parent a8de42c489
commit 72ffa01363
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 19 additions and 2 deletions

View File

@ -20,3 +20,5 @@ Netlify
Makefile Makefile
prebuilt prebuilt
(S|s)ubdirector(ies|y) (S|s)ubdirector(ies|y)
(M|m)inify
whitespace

View File

@ -87,7 +87,7 @@ enableGitInfo = true
geekdocImageLazyLoading = true geekdocImageLazyLoading = true
# (Optional, default false) Set HTMl <base> to .Site.BaseURL if enabled. Is might be required # (Optional, default false) Set HTMl <base> 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. # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base.
geekdocOverwriteHTMLBase = false geekdocOverwriteHTMLBase = false
``` ```
@ -175,7 +175,7 @@ params:
geekdocImageLazyLoading: true geekdocImageLazyLoading: true
# (Optional, default false) Set HTMl <base> to .Site.BaseURL if enabled. Is might be required # (Optional, default false) Set HTMl <base> 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. # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base.
geekdocOverwriteHTMLBase: false geekdocOverwriteHTMLBase: false
``` ```

View File

@ -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)` - 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! 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
```