Multi-language, i18n (#177)

* language menu
* allow for subdir in baseURL
* Update netlify.toml and github actions to use Hugo 0.121.1
* Documented i18n approaches in exampleSite
* Attempted & Abandoned images from assets as recommended approach in content pages- it seems Hugo expects to access those only programmatically, not via markdown.

---------

Co-authored-by: Zdenek K <[email protected]>

assets/css/theme.scss

@@ -66,7 +66,35 @@ body {
     text-shadow: var(--cover-title-text-shadow);
   }
 
+  #site-languages {
+    text-align: right;
+  }
+
+  #site-languages .btn-lang {
+    text-decoration: none;
+    background-color: var(--highlight);
+    color: var(--highlight-contrast);
+    border-radius: 5px;
+    -webkit-border-radius: 5px;
+    display: inline-block;
+    font-size: 70%;
+    margin: 0 0 0 0.7rem;
+    padding: 0.3rem 0.7rem;
+    position: relative;
+    text-transform: uppercase;
+
+    &.active,
+    &:hover {
+      color: var(--highlight-inverse-contrast);
+      background-color: var(--highlight-inverse);
+    }
+  }
+
   // Landing screen menu
+  a.btn, #site-languages .btn-lang {
+    font-family: "Oswald", sans-serif;
+  }
+
   a.btn {
     text-decoration: none;
     background-color: var(--highlight);
@@ -82,7 +110,6 @@ body {
     position: relative;
     margin-top: 2rem;
     cursor: pointer;
-    font-family: "Oswald", sans-serif;
     text-transform: uppercase;
     font-weight: lighter;
 

exampleSite/config.toml

@@ -40,6 +40,13 @@ title = "Jane Doe - Nutrition Coach & Chef Consultant"
     # The "description" of your website. This is used in the meta data of your generated html.
     description = "Nutrition Coach & Chef Consultant"
 
+    # Show a menu of languages available
+    language_menu = true
+
+    # Show also a language menu item for the current language, if false only
+    # show the remaining languages
+    show_current_lang = true
+
     # A "copyright"-line to be added at the bottom of the page.
     # Hint: Plain HTML is supported in here as well. So you may e.g. add a link to your legal imprint-page.
     copyright = "© Jane Doe"
@@ -79,3 +86,16 @@ title = "Jane Doe - Nutrition Coach & Chef Consultant"
     #     value = ""
     #     url = ""
     #     icon = ""
+
+# Define additіonal languages
+[languages]
+  [languages.en]
+    weight = 10
+    languageName = "English"
+    contentDir = "content/en"
+
+  [languages.de]
+    title = "Erika Musterfrau - Ernährungshilfe & Kochberatung"
+    weight = 20
+    contentDir = "content/de"
+    languageName = "Deutsch"

exampleSite/content/de/_index.md

@@ -0,0 +1,20 @@
+---
+# Striking header background image, Ideal images are homogenous around the centre and contrasting to the text. Non-ideal images can use `title_guard`
+header_image: "images/cover-image.jpg"
+#
+# When set true, uses video from custom_header_video.html partial, instead of header_image
+header_use_video: false
+#
+# Optional header logo. CSS: `#blog-logo`, with max-height defined, optimize to prevent scaling
+header_logo: "images/chef-hat.png"
+#
+# Headers are safeHTML, you can use HTML tags such as b,i,u,br
+header_headline: "Erika Musterfrau"
+header_subheadline: "<b>Ernährungs</b>hilfe & <b>Koch</b>beratung"
+
+# Add a 'Go back to top' item to the navigation menu
+# Title: name of navigation menu entry
+# Weight (i. e. position in menu): none = no menu entry, first = add as first entry, last = ad as last entry
+nav_to_top_title: "Nach oben"
+nav_to_top_weight: last
+---

exampleSite/content/de/homepage/about-me-local-img.md

@@ -0,0 +1,19 @@
+---
+title: "Über mich (DE folder)"
+weight: 3
+header_menu: true
+---
+
+This demonstates localized content placed in dedicated language folder, `content/de`. This way you won't have to use localization suffix with the `.md` file. Both localisation approaches (separate folder, suffixes in the same folder) can be used and even mixed.
+
+See i18n configuration in `[languages]` section of `config.toml`.
+
+#### Local content
+Localised content can be put in dedicated folder `content/de/`. Images should be naturally found from there:
+![Image from content/de ](de-happy-ethnic-woman-sitting-at-table-with-laptop-3769021.jpg)
+
+#### Assets
+Images in assets folder can be localised, conventionally by adding `.de` suffix. However, assets may be tricky, see next section for details
+![Broken DE Image from assets](images/asset-happy-ethnic-woman-sitting-at-table-with-laptop-3769021.de.jpg)
+
+Note the filename of this section is a bit artificial to avoid conflict with other examples in en folder. If named the same, this one wouldn't render. However normally you wouldn't have one page localized two ways.

exampleSite/content/de/homepage/opener.md

@@ -0,0 +1,16 @@
+---
+title: "Willkommen"
+weight: 1
+---
+
+Das ist die deutsche Beispielseite.
+
+`Hugo-Scroll` theme alternates colors of sections that are placed on single page.
+The landing screen is meant to be visually striking.
+
+Single-page approach is oriented towards small to medium content length, that won't overwhelm the user.
+You can also delegate lengthier, less important or more sizeable content to [dedicated pages](services).
+
+> The belly rules the mind. --- spanish proverb
+
+By the way this welcome section won't show in the cover menu.

exampleSite/content/de/homepage/services.md

@@ -0,0 +1,30 @@
+---
+title: "Das biete ich an"
+header_menu_title: "Angebot"
+navigation_menu_title: "Mein Angebot"
+weight: 2
+header_menu: true
+---
+
+Feature notice: This section displays options to customize title:
+
+- has a normal section title (`title` = "The Services I Offer"),
+- custom welcome screen title (`header_menu_title` = "Services"),
+- custom navigation menu title (`navigation_menu_title` = "My Services").
+
+That is the important part, right? You want to know what I can do for you. This is why I put this right up there into the header menu of the website.
+
+---
+
+### Nutrition Coaching
+
+This is not an easy task.
+You will likely have to pay money for this.
+
+### Chef Consulting
+
+I can raise your table culture!
+
+![Let us get started on a clean slate](/images/woman-pouring-juice-on-glass-3184192.jpg)
+
+Want to learn more about my services? See [dedicated page](services) with more details.

exampleSite/content/de/services.md

@@ -0,0 +1,42 @@
+---
+title: "Mein Angebot"
+---
+
+Das ist die deutsche Variante von meinem Angebot.
+
+It carries a lot more detail than what I put on the homepage - I swear!
+
+You want to know what I can do for you?
+
+Well, let me tell ya!
+
+---
+
+## Nutrition Coaching
+
+This is not an easy task. You will likely have to pay money for this. You know what - let us look at a nice picture first.
+
+<!-- Note how static images need to have leading slash from the dedicated pages -->
+
+![Nice picture to make you pay me ;-)](/images/selective-focus-photography-of-pasta-with-tomato-and-basil-1279330.jpg)
+
+Wow. That was nice, right? Well, call me and let us talk.
+
+---
+
+## Chef Consulting
+
+Did you see the picture above? I can show you how to go from
+
+![Let us get started on a clean slate](/images/board-bunch-cooking-food-349609.jpg)
+
+to
+
+![Let us get started on a clean slate](/images/woman-pouring-juice-on-glass-3184192.jpg)
+
+in estimated seconds.
+
+Don't believe me? Here are some bullets
+
+* If anyone can teach you to cook, I can
+* And if you already know how to cook, I will make you that much better

exampleSite/content/en/homepage/about-me.de.md

@@ -0,0 +1,29 @@
+---
+title: "Über mich (shared folder)"
+weight: 3
+header_menu: true
+---
+
+This demonstates localized variants `about-me.de.md` placed along the primary language content, such as `content/en`. Both localisation approaches (separate folder, suffixes in the same folder) can be used and mixed.
+
+#### Local content
+When localised page variants are placed along, images of other languages can't be used directly. You would need to use `.de`-suffixed copy of the image: `![Jane Doe](en-happy-ethnic-woman-sitting-at-table-with-laptop-3769021.de.jpg)` 
+Consider using assets instead.
+
+Images from local content location can't be pipeline-processed. 
+
+#### Static
+Alternatively, images can be injected from `static/images`:
+![Jane Doe](/images/static-happy-ethnic-woman-sitting-at-table-with-laptop-3769021.jpg)
+Note the leading `/` is required in this case.
+Images from static location can't be pipeline-processed and are always copied when publishing the site, even if not linked from any page.
+
+#### Assets
+Latest Hugo version supports injection from `assets` via natural Markdown notation, which empowers this approach for injecting images since pipeline processing (resizing etc) can be used. However, It only worked for me with the local test deployment, there were issues while deploying previews Netlify. Possible workaround would be to use custom shortcode to "touch" the image via [Resources.GetMatch](https://gohugo.io/functions/resources/getmatch/). I hope this gets fixed someday.
+
+![Broken image from assets](images/asset-happy-ethnic-woman-sitting-at-table-with-laptop-3769021.jpg)
+Historically, Linking image from `assets` folder worked only via Hugo-specific shortcode, there was [a discussion with suggestions](https://discourse.gohugo.io/t/how-to-show-images-on-post-pages-if-theyre-located-in-the-assets-folder/34276/14).
+
+Note that using images form assets folder is the only way to apply pipeline processing, such as resizing, when building the site. Fore more details, read about [asset vs static difference](https://discourse.gohugo.io/t/difference-between-asset-and-static-folder/41203)
+
+Assets are only published if linked from a content page.

exampleSite/content/homepage/about-me.md → exampleSite/content/en/homepage/about-me.md

@@ -4,12 +4,18 @@ weight: 3
 header_menu: true
 ---
 
-![Jane Doe](images/happy-ethnic-woman-sitting-at-table-with-laptop-3769021.jpg)
+<!-- 
+Neither embedded figure shortcode, nor Markdown hook were able to render image from asset. 
+You would have to .Resouces.GetMatch via custom shortcode.
+![Jane Doe](/images/asset-happy-ethnic-woman-sitting-at-table-with-laptop-3769021.jpg) 
+-->
+![Jane Doe](/images/static-happy-ethnic-woman-sitting-at-table-with-laptop-3769021.jpg) 
+See DE language for more examples of image management. There are multiple approaches.
 
 ##### Professional Experience
 
 A lot, but let us get into the details with some lorem ipsum. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent feugiat lectus et magna placerat tincidunt. Nullam sit amet lectus vitae elit mollis rhoncus non eget lorem. Ut tempor sed dui quis volutpat.
 
 ----
 
-In ultrices, est at lobortis pretium, magna quam mollis neque, id viverra odio est sit amet lorem. Mauris efficitur nunc vel lectus porttitor, sit amet sodales quam eleifend. Duis et felis ut mauris dignissim efficitur. Aliquam non sem eros. Integer elit ante, bibendum id hendrerit vitae, vestibulum eget risus. Nunc efficitur nisl in iaculis vestibulum.
+In ultrices, est at lobortis pretium, magna quam mollis neque, id viverra odio est sit amet lorem. Mauris efficitur nunc vel lectus porttitor, sit amet sodales quam eleifend. Duis et felis ut mauris dignissim efficitur. Aliquam non sem eros. Integer elit ante, bibendum id hendrerit vitae, vestibulum eget risus. Nunc efficitur nisl in iaculis vestibulum.

exampleSite/content/en/homepage/contact.md

@@ -0,0 +1,9 @@
+---
+title: "Contact"
+weight: 4
+header_menu: true
+---
+
+{{<contact_list>}}
+
+Let us get in touch!

exampleSite/content/homepage/credits.md → exampleSite/content/en/homepage/credits.md

@@ -7,3 +7,5 @@ In this section we give credit to authors of resources used on this demo page.
 
 - {{<extlink text="Chef-hat icons created by Cuputo - Flaticon" href="https://www.flaticon.com/free-icons/chef-hat" icon="fa fa-external-link">}}
 - {{<extlink text="sprinkle-of-rock-salt-on-sliced-vegetables-3209239 - Pexels" href="https://www.pexels.com/video/sprinkle-of-rock-salt-on-sliced-vegetables-3209239/" icon="fa fa-external-link">}}
+- {{<extlink text="Earth icon - Freepik" href="https://www.freepik.com/icon/earth_2072130" icon="fa fa-external-link">}}
+- {{<extlink text="happy-ethnic-woman - Pexels" href="https://www.pexels.com/photo/happy-ethnic-woman-sitting-at-table-with-laptop-3769021/" icon="fa fa-external-link">}}

exampleSite/content/en/homepage/external.md

@@ -0,0 +1,6 @@
+---
+title: "GitHub"
+weight: 99
+header_menu: true
+external: https://github.com/zjedi/hugo-scroll
+---

exampleSite/content/en/homepage/index.md

@@ -0,0 +1,3 @@
+---
+headless: true
+---

exampleSite/content/en/homepage/legal-brief.md

@@ -0,0 +1,16 @@
+---
+title: "Brief Legal Information"
+weight: 98
+header_menu_title: "Legal"
+navigation_menu_title: "Legal stuff"
+header_menu: true
+detailed_page_path: /legal/
+detailed_page_homepage_content: true
+---
+The file **legal-brief.md** creates an internal link on the cover page without the leading icon.
+
+If the parameter `detailed_page_homepage_content` is set to false neither this section nor the navigation menu entry will be shown (but the link on the cover page will be).
+
+If `detailed_page_homepage_content` is set to true or is missing at all, the link, navigation menu and the content will be rendered. In that case this section might contain less or just summarized information compared to the single page referenced by the parameter `detailed_page_path`.
+
+Want to see more about the details? See [dedicated page](legal) with more details or hit the button 'Legal' on the cover page.

exampleSite/content/en/homepage/license.md

@@ -0,0 +1,7 @@
+---
+footer_menu_title: License
+footer_menu: true
+detailed_page_path: /license/
+detailed_page_homepage_content: false
+weight: 91
+---

exampleSite/content/en/legal.md

@@ -0,0 +1,6 @@
+---
+title: "The single page referenced to by the Legal button on the cover page"
+---
+This file is a single page and is referenced by the button `Legal` on the cover start page.
+
+It can contain more or additional information than the dedicated section on the homepage.

exampleSite/content/en/license.md

@@ -0,0 +1,24 @@
+---
+title: Hugo Scroll License
+---
+
+The MIT License (MIT)
+
+Copyright (c) 2020 Jan Raasch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

exampleSite/content/services.md → exampleSite/content/en/services.md

@@ -16,7 +16,9 @@ Well, let me tell ya!
 
 This is not an easy task. You will likely have to pay money for this. You know what - let us look at a nice picture first.
 
-![Nice picture to make you pay me ;-)](../images/selective-focus-photography-of-pasta-with-tomato-and-basil-1279330.jpg)
+<!-- Note how static images need to have leading slash from the dedicated pages -->
+
+![Nice picture to make you pay me ;-)](/images/selective-focus-photography-of-pasta-with-tomato-and-basil-1279330.jpg)
 
 Wow. That was nice, right? Well, call me and let us talk.
 
@@ -26,11 +28,11 @@ Wow. That was nice, right? Well, call me and let us talk.
 
 Did you see the picture above? I can show you how to go from
 
-![Let us get started on a clean slate](../images/board-bunch-cooking-food-349609.jpg)
+![Let us get started on a clean slate](/images/board-bunch-cooking-food-349609.jpg)
 
 to
 
-![Let us get started on a clean slate](../images/woman-pouring-juice-on-glass-3184192.jpg)
+![Let us get started on a clean slate](/images/woman-pouring-juice-on-glass-3184192.jpg)
 
 in estimated seconds.
 

exampleSite/layouts/partials/custom_head.html

@@ -38,21 +38,8 @@
 <!-- Custom link-tags for different icons
      Generated via https://favicon.io/favicon-generator/ -->
 
+{{ with resources.Get "images/apple-touch-icon.png" }}<link rel="apple-touch-icon" sizes="180x180" href="{{ .RelPermalink }}" />{{ end }}
+{{ with resources.Get "images/favicon.svg" }}<link rel="icon" type="image/svg+xml" href="{{ .RelPermalink }}" />{{ end }}
+{{ range seq 9 4 }}{{ $size := pow 2 . }}{{ $file := replace "images/favicon-##x##.png" "##" $size }}{{ with resources.Get $file }}
+<link rel="icon" type="{{ .MediaType.Type }}" sizes="{{- $size -}}x{{- $size -}}" href="{{ .RelPermalink }}" />{{ end }}{{ end }}
 
-<link
-  rel="apple-touch-icon"
-  sizes="180x180"
-  href="{{ "images/apple-touch-icon.png" | absURL }}"
-/>
-<link
-  rel="icon"
-  type="image/png"
-  sizes="32x32"
-  href="{{ "images/favicon-32x32.png" | absURL }}"
-/>
-<link
-  rel="icon"
-  type="image/png"
-  sizes="16x16"
-  href="{{ "images/favicon-16x16.png" | absURL }}"
-/>