From a8de42c48909bdb6da68bcb369d7149b22583ccd Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Sat, 10 Apr 2021 15:52:27 +0200 Subject: [PATCH] fix: remove relURL from markdown render image hook (#93) * fix: remove relURL from markdown render image hook BREAKING CHANGE: As the relURL function in markdown render hooks caused some unwanted side effects we had to remove it. Related to this change the behavior for sites deployed to a subdirectory has changed as well! Please check the [documentation](https://geekdocs.de/usage/getting-started/#sub-directories) how to workaround subdirectory deployments. * restructure color-schemes page to work as image bundle example * fix wording --- .dictionary | 4 + .../_index.md} | 8 +- .../images}/colorscheme-example.png | Bin exampleSite/content/usage/configuration.md | 10 +++ exampleSite/content/usage/getting-started.md | 74 ++++++++++++++++++ layouts/_default/_markup/render-image.html | 2 +- layouts/partials/head.html | 4 + 7 files changed, 96 insertions(+), 6 deletions(-) rename exampleSite/content/usage/{color-schemes.md => color-schemes/_index.md} (95%) rename exampleSite/{static/media => content/usage/color-schemes/images}/colorscheme-example.png (100%) diff --git a/.dictionary b/.dictionary index 9e35787..dd59652 100644 --- a/.dictionary +++ b/.dictionary @@ -16,3 +16,7 @@ IcoMoon YAML ok FontAwesome +Netlify +Makefile +prebuilt +(S|s)ubdirector(ies|y) diff --git a/exampleSite/content/usage/color-schemes.md b/exampleSite/content/usage/color-schemes/_index.md similarity index 95% rename from exampleSite/content/usage/color-schemes.md rename to exampleSite/content/usage/color-schemes/_index.md index cb7551a..ca1e5ec 100644 --- a/exampleSite/content/usage/color-schemes.md +++ b/exampleSite/content/usage/color-schemes/_index.md @@ -2,10 +2,9 @@ If you want to customize the color scheme of the theme to give it your individua All necessary class names are listed below. If you miss some classes required for a color scheme you are very welcome to create an [Issue](https://github.com/thegeeklab/hugo-geekdoc/issues) or Pull Request. For some inspiration you can have a look at [https://www.color-hex.com/color-palettes/](https://www.color-hex.com/). The following listing use the _HC-primary_ color palette as an example: + - - {{< highlight CSS "linenos=table" >}} /* default link color */ a { color: #1c388e; } @@ -34,11 +33,10 @@ a:visited { color: #73bfb8 } .gdoc-hint.warning { background: #fef5dc; border-color: #e4ba48; color: black; } .gdoc-hint.danger { background: #fae1db; border-color: #cf5f46; color: black; } {{< /highlight >}} - - + And that is how the result will looks like. Happy customizing! -[![HC-primary Color Scheme](/media/colorscheme-example.png)](/media/colorscheme-example.png) +[![HC-primary Color Scheme](images/colorscheme-example.png)](images/colorscheme-example.png) diff --git a/exampleSite/static/media/colorscheme-example.png b/exampleSite/content/usage/color-schemes/images/colorscheme-example.png similarity index 100% rename from exampleSite/static/media/colorscheme-example.png rename to exampleSite/content/usage/color-schemes/images/colorscheme-example.png diff --git a/exampleSite/content/usage/configuration.md b/exampleSite/content/usage/configuration.md index 4bb0e74..c0b8374 100644 --- a/exampleSite/content/usage/configuration.md +++ b/exampleSite/content/usage/configuration.md @@ -85,6 +85,11 @@ enableGitInfo = true # (Optional, default true) Enable or disable image lazy loading for images rendered # by the 'img' shortcode. geekdocImageLazyLoading = true + + # (Optional, default false) Set HTMl to .Site.BaseURL if enabled. Is might be required + # a subdirectory is used within Hugos BaseURL. + # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base. + geekdocOverwriteHTMLBase = false ``` {{< /tab >}} @@ -168,6 +173,11 @@ params: # (Optional, default true) Enable or disable image lazy loading for images rendered # by the 'img' shortcode. geekdocImageLazyLoading: true + + # (Optional, default false) Set HTMl to .Site.BaseURL if enabled. Is might be required + # a subdirectory is used within Hugos BaseURL. + # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base. + geekdocOverwriteHTMLBase: false ``` {{< /tab >}} diff --git a/exampleSite/content/usage/getting-started.md b/exampleSite/content/usage/getting-started.md index b29f821..093bbdc 100644 --- a/exampleSite/content/usage/getting-started.md +++ b/exampleSite/content/usage/getting-started.md @@ -98,3 +98,77 @@ 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! diff --git a/layouts/_default/_markup/render-image.html b/layouts/_default/_markup/render-image.html index 2105412..5150177 100644 --- a/layouts/_default/_markup/render-image.html +++ b/layouts/_default/_markup/render-image.html @@ -1,2 +1,2 @@ -{{ .Text }} +{{ .Text }} {{- /* Drop trailing newlines */ -}} diff --git a/layouts/partials/head.html b/layouts/partials/head.html index 871a36f..9d283a8 100644 --- a/layouts/partials/head.html +++ b/layouts/partials/head.html @@ -31,4 +31,8 @@ {{ printf `` .Rel .MediaType.Type .Permalink $.Site.Title | safeHTML }} {{ end -}} +{{ if (default false $.Site.Params.GeekdocOverwriteHTMLBase) }} + +{{ end }} + {{ printf "" "Made with Geekdoc theme https://github.com/thegeeklab/hugo-geekdoc" | safeHTML }}