Squashed 'docs/' changes from 501c6e2..f59b3ab

f59b3ab Fix typo in template lookup order 1e5536d Mutlilingual: Document "content directory per language" system (#509) 849a860 Update index.md 0c24d22 Polish Hugo Next a4c9b0e Polish bbec2c7 Some more in birthday post fc9681e More on contributors 09fe3ea Some more on the birthday post 8da3572 Content and images for the 5th birthday blog post fb45bb8 Add draft for anniversary blog post 4666d0a Release 0.42.2 9b74d28 Merge branch 'temp422' 354e7b6 releaser: Add release notes to /docs for release of 0.42.2 57a617f releaser: Bump versions for release of 0.42.2 ccc3ac1 Update errorf.md 35706c2 Update errorf.md 1c0f35f Update errorf.md b617077 Add syntax highlighting gallery links for Chroma f91d9da Update usage.md c9a8f01 Improve theme components documentation 3c4e39d Release 0.42.1 b45eb45 Merge branch 'temp421' c74682a releaser: Prepare repository for 0.43-DEV 321e07f releaser: Add release notes to /docs for release of 0.42.1 7154271 releaser: Bump versions for release of 0.42.1 360d824 Add link to Privacy Config 1f24542 Fix typo a8f5f99 Fix typo d9f3f07 Update simple variants documentation (#500) f5cfd44 Release 0.42 fe604b3 releaser: Prepare repository for 0.43-DEV c3e5b3ca0 releaser: Add release notes to /docs for release of 0.42 3174d1b releaser: Bump versions for release of 0.42 48cc2d5 docs: Update theme documentation 1922fb1 docs: Remove some files now moved d7e4c45 Merge commit 'b239595af5a9fc1fc9a1ccc666c3ab06ccc32f04' c40964c tplimpl: Remove speakerdeck shortcode 081f8a0 tpl/strings: strings.RuneCount 828ea5f tpl: Add strings.Repeat a6b9f65 Add a BlackFriday option for rel="noreferrer" on external links edb7865 Add a BlackFriday option for rel="nofollow" on external links e437497 releaser: Prepare repository for 0.42-DEV git-subtree-dir: docs git-subtree-split: f59b3ab
gohugoio · Jul 6, 2018 · 98293ea · 98293ea
1 parent b239595
commit 98293ea
Show file tree

Hide file tree

Showing 34 changed files with 568 additions and 241 deletions.
diff --git a/config.toml b/config.toml
@@ -70,7 +70,7 @@ twitter = "GoHugoIO"
 [params]
   description = "The world’s fastest framework for building websites"
   ## Used for views in rendered HTML (i.e., rather than using the .Hugo variable)
-  release = "0.41"
+  release = "0.42.2"
   ## Setting this to true will add a "noindex" to *EVERY* page on the site
   removefromexternalsearch = false
   ## Gh repo for site footer (include trailing slash)

diff --git a/content/en/about/hugo-and-gdpr.md b/content/en/about/hugo-and-gdpr.md
@@ -46,13 +46,13 @@ useSessionStorage = false
 [privacy.instagram]
 disable = false
 simple = false
-[privacy.speakerDeck]
-disable = false
 [privacy.twitter]
 disable = false
 enableDNT = false
+simple = false
 [privacy.vimeo]
 disable = false
+simple = false
 [privacy.youtube]
 disable = false
 privacyEnhanced = false
@@ -71,8 +71,6 @@ disable = true
 disable = true
 [privacy.instagram]
 disable = true
-[privacy.speakerDeck]
-disable = true
 [privacy.twitter]
 disable = true
 [privacy.vimeo]
@@ -112,8 +110,25 @@ disableInlineCSS = true
 enableDNT
 : Enabling this for the twitter/tweet shortcode, the tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads.
 
+simple
+: If simple mode is enabled, a static and no-JS version of a tweet will be built.
+
+
+**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inlines styles provided by Hugo:
+
+ {{< code-toggle file="config">}}
+[services]
+[services.twitter]
+disableInlineCSS = true
+{{< /code-toggle >}}
+
 ### YouTube
 
 privacyEnhanced
 : When you turn on privacy-enhanced mode, YouTube won’t store information about visitors on your website unless the user plays the embedded video.
 
+### Vimeo
+
+simple
+: If simple mode is enabled, the video thumbnail is fetched from Vimeo's servers and it is overlayed with a play button. If the user clicks to play the video, it will open in a new tab directly on Vimeo's website.
+
diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md
@@ -35,14 +35,13 @@ help  = "Help"
 title = "My blog"
 weight = 1
 [languages.en.params]
-linkedin = "english-link"
+linkedin = "https://linkedin.com/whoever"
 
 [languages.fr]
-copyright = "Tout est à moi"
-title = "Mon blog"
+title = "Mon blogue"
 weight = 2
 [languages.fr.params]
-linkedin = "lien-francais"
+linkedin = "https://linkedin.com/fr/whoever"
 [languages.fr.params.navigation]
 help  = "Aide"
 {{< /code-toggle >}}
@@ -55,11 +54,13 @@ and taxonomy pages will be rendered below `/` in English (your default content l
 
 When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation.
 
-If you want all of the languages to be put below their respective language code, enable `defaultContentLanguageInSubdir: true`.
+`defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`.
+
+If the default language needs to be rendererd below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`.
 
 Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc.
 
-## Disable a Language
+### Disable a Language
 
 You can disable one or more languages. This can be useful when working on a new translation.
 
@@ -81,7 +82,7 @@ HUGO_DISABLELANGUAGES=" " hugo server
 ```
 
 
-## Configure Multilingual Multihost
+### Configure Multilingual Multihost
 
 From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details.
 
@@ -94,11 +95,11 @@ Example:
 
 {{< code-toggle file="config" >}}
 [languages]
-[languages.no]
-baseURL = "https://example.no"
-languageName = "Norsk"
+[languages.fr]
+baseURL = "https://example.fr"
+languageName = "Français"
 weight = 1
-title = "På norsk"
+title = "En Français"
 
 [languages.en]
 baseURL = "https://example.com"
@@ -127,7 +128,7 @@ Press Ctrl+C to stop
 
 Live reload and `--navigateToChanged` between the servers work as expected.
 
-## Taxonomies and Blackfriday
+### Taxonomies and Blackfriday
 
 Taxonomies and [Blackfriday configuration][config] can also be set per language:
 
@@ -156,40 +157,113 @@ plaque = "plaques"
 
 ## Translate Your Content
 
-Translated articles are identified by the name of the content file.
+There are two ways to manage your content translation, both ensures each page is assigned a language and linked to its translations.
+
+### Translation by filename
 
-### Examples of Translated Articles
+Considering the following example:
 
 1. `/content/about.en.md`
 2. `/content/about.fr.md`
 
-In this example, the `about.md` will be assigned the configured `defaultContentLanguage`. 
+The first file is assigned the english language and linked to the second.
+The second file is assigned the french language and linked to the first.
 
-1. `/content/about.md`
-2. `/content/about.fr.md`
+Their language is __assigned__ according to the language code added as __suffix to the filename__. 
+
+By having the same **path and base filename**, the content pieces are __linked__ together as translated pages.
+{{< note >}}
+
+If a file is missing any language code, it will be assigned the default language.
+
+{{</ note >}}
+### Translation by content directory
+
+This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` param.
+
+{{< code-toggle file="config" >}}
+
+languages:
+  en:
+    weight: 10
+    languageName: "English"
+    contentDir: "content/english"
+  nn:
+    weight: 20
+    languageName: "Français"
+    contentDir: "content/french"
+
+{{< /code-toggle >}}
+
+The value of `contentDir` can be any valid path, even absolute path references. The only restriction is that the content directories cannot overlap.
+
+Considering the following example in conjunction with the configuration above: 
+
+1. `/content/english/about.md`
+2. `/content/french/about.md`
+
+The first file is assigned the english language and is linked to the second.
+<br>The second file is assigned the french language and is linked to the first.
+
+Their language is __assigned__ according to the content directory they are __placed__ in.
+
+By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages.
 
-This way, you can slowly start to translate your current content without having to rename everything. If left unspecified, the default value for `defaultContentLanguage` is `en`.
+### Bypassing default linking.
 
-By having the same **directory and base filename**, the content pieces are linked together as translated pieces.
+Any pages sharing the same `translationKey`  set in front matter will be linked as translated pages regardless of basename or location.
 
-You can also set the key used to link the translations explicitly in front matter:
+Considering the following example:
+
+1. `/content/about-us.en.md`
+2. `/content/om.nn.md`
+3. `/content/presentation/a-propos.fr.md`
 
 ```yaml
-translationKey: "my-story"
+# set in all three pages
+translationKey: "about"
 ```
 
-If you need distinct URLs per language, you can set the slug in the non-default language file. For example, you can define a custom slug for a French translation in the front matter of `content/about.fr.md` as follows:
+By setting the `translationKey` front matter param to `about` in all three pages, they will be __linked__ as translated pages.
 
-```yaml
+
+### Localizing permalinks
+
+Because paths and filenames are used to handle linking, all translated pages, except for the language part, will be sharing the same url.
+
+To localize the URLs, the [`slug`]({{< ref "content-management/organization/index.md#slug" >}}) or [`url`]({{< ref "content-management/organization/index.md#url" >}}) front matter param can be set in any of the non-default language file. 
+
+For example, a french translation (`content/about.fr.md`) can have its own localized slug.
+
+{{< code-toggle >}}
+Title: A Propos
 slug: "a-propos"
+{{< /code-toggle >}}
 
-```
 
-At render, Hugo will build both `/about/` and `/a-propos/` as properly linked translated pages.
+At render, Hugo will build both `/about/` and `fr/a-propos/` while maintaning their translation linking.
+{{% note %}}
+If using `url`, remember to include the language part as well: `fr/compagnie/a-propos/`.
+{{%/ note %}}
 
-For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/).
+### Page Bundles
+
+To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (markdown files, html files etc...).
+
+Therefore, from within a template, the page will have access to the files from all linked pages' bundles.
+
+If, across the linked bundles, two or more files share the same basenname, only one will be included and chosen as follows:
+
+* File from current language Bundle, if present.
+* First file found across bundles by order of language `Weight`.
+
+{{% note %}}
+
+Page Bundle's resources follow the same language assignement logic as content files, be it by filename (`image.jpg`, `image.fr.jpg`) or by directory (`english/about/header.jpg`, `french/about/header.jpg`).
+
+{{%/ note %}}
 
-## Link to Translated Content
+## Reference the Translated Content
 
 To create a list of links to translated content, use a template similar to the following:
 
@@ -210,7 +284,7 @@ The above can be put in a `partial` (i.e., inside `layouts/partials/`) and inclu
 
 The above also uses the [`i18n` function][i18func] described in the next section.
 
-## List All Available Languages
+### List All Available Languages
 
 `.AllTranslations` on a `Page` can be used to list all translations, including itself. Called on the home page it can be used to build a language navigator:
 
@@ -366,7 +440,7 @@ For merging of content from other languages (i.e. missing content translations),
 
 To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria:
 
-* Come from the built-in `.Permalink` or `.URL`
+* Come from the built-in `.Permalink` or `.RelPermalink`
 * Be constructed with
     * The [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR**
     * Prefixed with `{{ .LanguagePrefix }}`

diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md
@@ -374,6 +374,10 @@ Using the preceding `youtube` example (without `autoplay="true"`), the following
 
 {{< youtube w7Ft2ymGmfc >}}
 
+## Privacy Config
+
+To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR][].
+
 ## Create Custom Shortcodes
 
 To learn more about creating custom shortcodes, see the [shortcode template documentation][].
@@ -382,6 +386,7 @@ To learn more about creating custom shortcodes, see the [shortcode template docu
 [contentmanagementsection]: /content-management/formats/
 [examplegist]: https://gist.github.com/spf13/7896402
 [figureelement]: http://html5doctor.com/the-figure-figcaption-elements/ "An article from HTML5 doctor discussing the fig and figcaption elements."
+[Hugo and the GDPR]: /about/hugo-and-gdpr/
 [Instagram]: https://www.instagram.com/
 [pagevariables]: /variables/page/
 [partials]: /templates/partials/
@@ -390,7 +395,6 @@ To learn more about creating custom shortcodes, see the [shortcode template docu
 [sctemps]: /templates/shortcode-templates/
 [scvars]: /variables/shortcodes/
 [shortcode template documentation]: /templates/shortcode-templates/
-[Speaker Deck]: https://speakerdeck.com/
 [templatessection]: /templates/
 [Vimeo]: https://vimeo.com/
 [YouTube Videos]: https://www.youtube.com/
diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md
@@ -72,7 +72,13 @@ pygmentsCodefences
 : Set to true to enable syntax highlighting in code fences with a language tag in markdown (see below for an example).
 
 pygmentsStyle
-: The style of code highlighting. See https://help.farbox.com/pygments.html for a gallery. Note that this option is not relevant when `pygmentsUseClasses` is set.
+: The style of code highlighting. Note that this option is not
+  relevant when `pygmentsUseClasses` is set.
+
+  Syntax highlighting galleries:
+  **Chroma** ([short snippets](https://xyproto.github.io/splash/docs/all.html),
+  [long snippets](https://xyproto.github.io/splash/docs/longer/all.html)),
+  [Pygments](https://help.farbox.com/pygments.html)
 
 pygmentsUseClasses
 : Set to `true` to use CSS classes to format your highlighted code. See [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css).

diff --git a/content/en/functions/errorf.md b/content/en/functions/errorf.md
@@ -1,7 +1,7 @@
 ---
 title: errorf
 linktitle: errorf
-description: Evaluates a format string and logs it to ERROR.
+description: Log ERROR and fail the build from the templates.
 date: 2017-09-30
 publishdate: 2017-09-30
 lastmod: 2017-09-30
@@ -18,9 +18,12 @@ deprecated: false
 aliases: []
 ---
 
-`errorf` will evaluate a format string, then output the result to the ERROR log.
-This will also cause the build to fail.
+`errorf` will evaluate a format string, then output the result to the ERROR log (and only once per error message to avoid flooding the log).
+
+This will also cause the build to fail (the `hugo` command will `exit -1`).
 
 ```
-{{ errorf "Something went horribly wrong! %s" err }}
+{{ errorf "Failed to handle page %q" .Path }}
 ```
+
+Note that `errorf` supports all the formatting verbs of the [fmt](https://golang.org/pkg/fmt/) package.
diff --git a/content/en/functions/strings.Repeat.md b/content/en/functions/strings.Repeat.md
@@ -0,0 +1,31 @@
+---
+title: strings.Repeat
+# linktitle:
+description: Returns a string consisting of count copies of the string s.
+godocref:
+date: 2018-05-31
+publishdate: 2018-05-31
+lastmod: 2018-05-31
+categories: [functions]
+menu:
+  docs:
+    parent: "functions"
+keywords: [strings]
+signature: ["strings.Repeat INPUT COUNT"]
+workson: []
+hugoversion:
+relatedfuncs: []
+deprecated: false
+---
+
+`strings.Repeat` provides the Go [`strings.Repeat`](https://golang.org/pkg/strings/#Repeat) function for Hugo templates. It takes a string and a count, and returns a string with consisting of count copies of the string argument.
+
+```
+{{ strings.Repeat "yo" 3 }} → "yoyoyo"
+```
+
+`strings.Repeat` *requires* the second argument, which tells the function how many times to repeat the first argument; there is no default. However, it can be used as a pipeline:
+
+```
+{{ "yo" | strings.Repeat 3 }} → "yoyoyo"
+```