From c9ab88ea8d823e692a6be18536a2674beabde1f9 Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Sun, 23 May 2021 22:58:37 +0200 Subject: [PATCH] fix: remove relURL from markdown render image hook (#44) --- .dictionary | 4 + exampleSite/content/posts/deployments.md | 78 ++++++++++++++++++++ exampleSite/content/posts/getting-started.md | 10 +++ layouts/_default/_markup/render-image.html | 2 +- layouts/partials/head/others.html | 4 + 5 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 exampleSite/content/posts/deployments.md diff --git a/.dictionary b/.dictionary index bd0cdd8..4c3c5bd 100644 --- a/.dictionary +++ b/.dictionary @@ -25,3 +25,7 @@ ToC relref href Emojify +Netlify +Makefile +prebuilt +(S|s)ubdirector(ies|y) diff --git a/exampleSite/content/posts/deployments.md b/exampleSite/content/posts/deployments.md new file mode 100644 index 0000000..648f7ee --- /dev/null +++ b/exampleSite/content/posts/deployments.md @@ -0,0 +1,78 @@ +--- +title: Deployments +date: 2021-05-23T20:00:00+01:00 +authors: + - john-doe +tags: + - Documentation + - Shortcodes +weight: 5 +--- + +## 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](/posts/getting-started/#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/exampleSite/content/posts/getting-started.md b/exampleSite/content/posts/getting-started.md index 74d9a8f..a4ce125 100644 --- a/exampleSite/content/posts/getting-started.md +++ b/exampleSite/content/posts/getting-started.md @@ -251,6 +251,11 @@ enableGitInfo = true # by the 'img' shortcode. geekblogImageLazyLoading = true + # (Optional, default false) Set HTMl to .Site.BaseURL if enabled. It might be required + # if a subdirectory is used within Hugo's BaseURL. + # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base. + geekblogOverwriteHTMLBase = false + # (Optional, default none) Adds a "Hosted on " line to the footer. # Could be used if you want to give credits to your hosting provider. [params.geekblogHostedOn] @@ -365,6 +370,11 @@ params: # by the 'img' shortcode. geekblogImageLazyLoading: true + # (Optional, default false) Set HTMl to .Site.BaseURL if enabled. It might be required + # if a subdirectory is used within Hugo's BaseURL. + # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base. + geekblogOverwriteHTMLBase: false + # (Optional, default none) Adds a "Hosted on " line to the footer. # Could be used if you want to give credits to your hosting provider. geekblogHostedOn: 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/others.html b/layouts/partials/head/others.html index 55c191d..d550669 100644 --- a/layouts/partials/head/others.html +++ b/layouts/partials/head/others.html @@ -23,4 +23,8 @@ {{ printf `` .Rel .MediaType.Type .Permalink $.Site.Title | safeHTML }} {{ end }} +{{ if (default false $.Site.Params.GeekblogOverwriteHTMLBase) }} + +{{ end }} + {{ printf "" "Made with Geekblog theme https://github.com/thegeeklab/hugo-geekblog" | safeHTML }}