Merge commit '7d7771b673e5949f554515a2c236b23192c765c8'

2 files changed, 99 insertions, 31 deletions

diff --git a/docs/content/en/content-management/cross-references.md b/docs/content/en/content-management/cross-references.md
index 21a73b861..9570a8fa4 100644
--- a/docs/content/en/content-management/cross-references.md
+++ b/docs/content/en/content-management/cross-references.md
@@ -15,31 +15,39 @@ aliases: [/extras/crossreferences/]
 toc: true
 ---
 
-
-The `ref` and `relref` shortcode resolves the absolute or relative permalink given a path to a document.
+The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively.
 
 ## Use `ref` and `relref`
 
 ```go-html-template
+{{</* ref "document" */>}}
+{{</* ref "document#anchor" */>}}
 {{</* ref "document.md" */>}}
-{{</* ref "#anchor" */>}}
 {{</* ref "document.md#anchor" */>}}
+{{</* ref "#anchor" */>}}
 {{</* ref "/blog/my-post" */>}}
 {{</* ref "/blog/my-post.md" */>}}
+{{</* relref "document" */>}}
 {{</* relref "document.md" */>}}
 {{</* relref "#anchor" */>}}
-{{</* relref "document.md#anchor" */>}}
+{{</* relref "/blog/my-post.md" */>}}
+```
+
+To generate a hyperlink using `ref` or `relref` in markdown:
+
+```md
+[About]({{</* ref "/page/about" */>}} "About Us")
 ```
 
-The single parameter to `ref` is a string with a content `documentname` (e.g., `about.md`) with or without an appended in-document `anchor` (`#who`) without spaces. Hugo is flexible in how we search for documents, so the file suffix may be omitted.
+The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor.
 
-**Paths without a leading `/` will first  be tried resolved relative to the current page.**
+**Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
 
-You will get an error if your document could not be uniquely resolved. The error behaviour can be configured, see below.
+Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below.
 
 ### Link to another language version
 
-Link to another language version of a document, you need to use this syntax:
+To link to another language version of a document, use this syntax:
 
 ```go-html-template
 {{</* relref path="document.md" lang="ja" */>}}
@@ -47,45 +55,66 @@ Link to another language version of a document, you need to use this syntax:
 
 ### Get another Output Format
 
-To link to a given Output Format of a document, you can use this syntax:
+To link to another Output Format of a document, use this syntax:
 
 ```go-html-template
 {{</* relref path="document.md" outputFormat="rss" */>}}
 ```
 
-### Anchors
+### Heading IDs
 
-When an `anchor` is provided by itself, the current page’s unique identifier will be appended; when an `anchor` is provided appended to `documentname`, the found page's unique identifier will be appended:
+When using Markdown document types, Hugo generates element IDs for every heading on a page. For example:
 
-```go-html-template
-{{</* relref "#anchors" */>}} => #anchors:9decaf7
+```md
+## Reference
 ```
 
-The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite
+produces this HTML:
 
-```go-html-template
-{{</* relref "#who" */>}} => #who:9decaf7
-{{</* relref "/blog/post.md#who" */>}} => /blog/post/#who:badcafe
+```html
+<h2 id="reference">Reference</h2>
 ```
 
-More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}).
+Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes:
 
-## Hugo Heading Anchors
+```md
+{{</* ref "document.md#reference */>}}
+{{</* relref "document.md#reference */>}}
+```
 
-When using Markdown document types, Hugo generates heading anchors automatically. The generated anchor for this section is `hugo-heading-anchors`. Because the heading anchors are generated automatically, Hugo takes some effort to ensure that heading anchors are unique both inside a document and across the entire site.
+Generate a custom heading ID by including an attribute. For example:
 
-Ensuring heading uniqueness across the site is accomplished with a unique identifier for each document based on its path. Unless a document is renamed or moved between sections *in the filesystem*, the unique identifier for the document will not change: `blog/post.md` will always have a unique identifier of `81df004c333b392d34a49fd3a91ba720`.
+```md
+## Reference A {#foo}
+## Reference B {id="bar"}
+```
 
-`ref` and `relref` were added so you can make these reference links without having to know the document’s unique identifier. (The links in document tables of contents are automatically up-to-date with this value.)
+produces this HTML:
 
+```html
+<h2 id="foo">Reference A</h2>
+<h2 id="bar">Reference B</h2>
 ```
-{{</* relref "content-management/cross-references.md#hugo-heading-anchors" */>}}
-/content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242
+
+Hugo will generate unique element IDs if the same heading appears more than once on a page. For example:
+
+```md
+## Reference
+## Reference
+## Reference
+```
+
+produces this HTML:
+
+```html
+<h2 id="reference">Reference</h2>
+<h2 id="reference-1">Reference</h2>
+<h2 id="reference-2">Reference</h2>
 ```
 
 ## Ref and RelRef Configuration
 
-The behaviour can, since Hugo 0.45, be configured in `config.toml`:
+The behavior can, since Hugo 0.45, be configured in `config.toml`:
 
 refLinksErrorLevel ("ERROR") 
 : When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
diff --git a/docs/content/en/content-management/multilingual.md b/docs/content/en/content-management/multilingual.md
index ccf794b2e..224f38d7a 100644
--- a/docs/content/en/content-management/multilingual.md
+++ b/docs/content/en/content-management/multilingual.md
@@ -316,44 +316,83 @@ See https://github.com/gohugoio/hugo/issues/3564
 
 {{% /note %}}
 
+### Query basic translation
+
 From within your templates, use the `i18n` function like this:
 
 ```
 {{ i18n "home" }}
 ```
 
-This uses a definition like this one in `i18n/en-US.toml`:
+The function will search for the `"home"` id from `i18n/en-US.toml` file:
 
 ```
 [home]
 other = "Home"
 ```
 
-Often you will want to use to the page variables in the translations strings. To do that, pass on the "." context when calling `i18n`:
+The result will be
+
+```
+Home
+```
+
+### Query a flexible translation with variables
+
+Often you will want to use to the page variables in the translations strings. To do that, pass on the `.` context when calling `i18n`:
 
 ```
 {{ i18n "wordCount" . }}
 ```
 
-This uses a definition like this one in `i18n/en-US.toml`:
+The function will pass the `.` context to the `"wordCount"` id in `i18n/en-US.toml` file:
 
 ```
 [wordCount]
 other = "This article has {{ .WordCount }} words."
 ```
-An example of singular and plural form:
+
+Assume `.WordCount` in the context has value is 101. The result will be:
+
+```
+This article has 101 words.
+```
+
+### Query a singular/plural translation
+
+In other to meet singular/plural requirement, you must pass a dictionary (map) data with a numeric `.Count` property to the `i18n` function. The below example uses `.ReadingTime` variable which has a built-in `.Count` property.
+
+```
+{{ i18n "readingTime" .ReadingTime }}
+```
+
+The function will read `.Count` from `.ReadingTime` and evaluate where the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file:
 
 ```
 [readingTime]
 one = "One minute to read"
 other = "{{.Count}} minutes to read"
 ```
-And then in the template:
+
+Assume `.ReadingTime.Count` in the context has value is 525600. The result will be:
 
 ```
-{{ i18n "readingTime" .ReadingTime }}
+525600 minutes to read
+```
+
+If `.ReadingTime.Count` in the context has value is 1. The result is:
+
+```
+One minutes to read
 ```
 
+In case you need to pass a custom data: (`"(dict Count" 25)` is minimum requirment)
+
+```
+{{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }}
+```
+
+
 ## Customize Dates
 
 At the time of this writing, Go does not yet have support for internationalized locales for dates, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content: