docs: Update ref, relref, GetPage docs

3 files changed, 44 insertions, 92 deletions

diff --git a/docs/content/en/content-management/cross-references.md b/docs/content/en/content-management/cross-references.md
index 56599e47c..00f6ad1c1 100644
--- a/docs/content/en/content-management/cross-references.md
+++ b/docs/content/en/content-management/cross-references.md
@@ -1,6 +1,6 @@
 ---
 title: Links and Cross References
-description: Hugo makes it easy to link documents together.
+description: Shortcodes for creating links to documents.
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-03-31
@@ -16,119 +16,65 @@ toc: true
 ---
 
 
- The `ref` and `relref` shortcodes link documents together, both of which are [built-in Hugo shortcodes][]. These shortcodes are also used to provide links to headings inside of your content, whether across documents or within a document. The only difference between `ref` and `relref` is whether the resulting URL is absolute (`http://1.com/about/`) or relative (`/about/`), respectively.
+The `ref` and `relref` shortcode resolves the absolute or relative permalink given a path to a document.
 
 ## Use `ref` and `relref`
 
-```
+```go-html-template
 {{</* ref "document.md" */>}}
 {{</* ref "#anchor" */>}}
 {{</* ref "document.md#anchor" */>}}
+{{</* ref "/blog/my-post" */>}}
+{{</* ref "/blog/my-post.md" */>}}
 {{</* relref "document.md" */>}}
 {{</* relref "#anchor" */>}}
 {{</* relref "document.md#anchor" */>}}
 ```
 
-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.
+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.
 
-### Document Names
+**Paths without a leading `/` will first  be tried resolved relative to the current page.**
 
-The `documentname` is the name of a document, including the format extension; this may be just the filename, or the relative path from the `content/` directory. With a document `content/blog/post.md`, either format will produce the same result:
+You will get an error if you document could not be uniquely resolved. The error behaviour can be configured, see below.
 
-```
-{{</* relref "blog/post.md" */>}} => `/blog/post/`
-{{</* relref "post.md" */>}} => `/blog/post/`
-```
+### Link to another language version
 
-If you have the same filename used across multiple sections, you should only use the relative path format; otherwise, the behavior will be `undefined`. This is best illustrated with an example `content` directory:
+Link to another language version of a document, you need to use this syntax:
 
-```
-.
-└── content
-    ├── events
-    │   └── my-birthday.md
-    ├── galleries
-    │   └── my-birthday.md
-    ├── meta
-    │   └── my-article.md
-    └── posts
-        └── my-birthday.md
+```go-html-template
+{{</* relref path="document.md" lang="jp" */>}}
 ```
 
-To be sure to get the correct reference in this case, use the full path: 
+### Get another Output Format
 
-{{< code file="content/meta/my-article.md" copy="false" >}}
-{{</* relref "events/my-birthday.md" */>}} => /events/my-birthday/
-{{< /code >}}
+To link to a given Output Format of a document, you can use this syntax:
 
-### With Multiple Output Formats
-
-If the page exists in multiple [output formats][], `ref` or `relref` can be used with a output format name:
-
-```
- [Neat]({{</* ref "blog/neat.md" "amp" */>}})
+```go-html-template
+{{</* relref path="document.md" outputFormat="rss" */>}}
 ```
 
 ### Anchors
 
 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:
 
-```
+```go-html-template
 {{</* relref "#anchors" */>}} => #anchors:9decaf7
-{{</* relref "about-hugo/hugo-features.md#content" */>}} => /blog/post/#who:badcafe
 ```
 
 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
 
-```
+```go-html-template
 {{</* relref "#who" */>}} => #who:9decaf7
-{{</* relref "blog/post.md#who" */>}} => /blog/post/#who:badcafe
+{{</* relref "/blog/post.md#who" */>}} => /blog/post/#who:badcafe
 ```
 
 More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}).
 
-### Examples
-
-* `{{</* ref "blog/post.md" */>}}` => `https://example.com/blog/post/`
-* `{{</* ref "post.md#tldr" */>}}` => `https://example.com/blog/post/#tldr:caffebad`
-* `{{</* relref "post.md" */>}}` => `/blog/post/`
-* `{{</* relref "blog/post.md#tldr" */>}}` => `/blog/post/#tldr:caffebad`
-* `{{</* ref "#tldr" */>}}` => `#tldr:badcaffe`
-* `{{</* relref "#tldr" */>}}` => `#tldr:badcaffe`
-
-## Hugo Heading Anchors
-
-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.
-
-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`.
-
-`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.)
-
-```
-{{</* relref "content-management/cross-references.md#hugo-heading-anchors" */>}}
-/content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242
-```
-
-### Manually Specifying Anchors
-
-For Markdown content files, if the `headerIds` [Blackfriday extension][bfext] is
-enabled (which it is by default), user can manually specify the anchor for any
-heading.
-
-Few examples:
-
-```
-## Alpha 101 {#alpha}
-
-## Version 1.0 {#version-1-dot-0}
-```
-
 
 ## Ref and RelRef Configuration
 
 The behaviour 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 logg level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
 
@@ -136,7 +82,6 @@ refLinksNotFoundURL
 : URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
 
 
-[built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes
 [lists]: /templates/lists/
 [output formats]: /templates/output-formats/
 [shortcode]: /content-management/shortcodes/
diff --git a/docs/content/en/content-management/page-bundles.md b/docs/content/en/content-management/page-bundles.md
index 639d81eff..1c99d6a56 100644
--- a/docs/content/en/content-management/page-bundles.md
+++ b/docs/content/en/content-management/page-bundles.md
@@ -97,7 +97,7 @@ anywhere:
 But you can get it by `.Site.GetPage`. Here is an example:
 
 ```go-html-template
-{{ $headless := .Site.GetPage "page" "some-headless-bundle" }}
+{{ $headless := .Site.GetPage "/some-headless-bundle" }}
 {{ $reusablePages := $headless.Resources.Match "author*" }}
 <h2>Authors</h2>
 {{ range $reusablePages }}
diff --git a/docs/content/en/functions/GetPage.md b/docs/content/en/functions/GetPage.md
index 1a8a51c13..2d9de4d7a 100644
--- a/docs/content/en/functions/GetPage.md
+++ b/docs/content/en/functions/GetPage.md
@@ -1,6 +1,6 @@
 ---
 title: .GetPage
-description: "Gets a `Page` of a given `Kind` and `path`."
+description: "Gets a `Page` of a given `path`."
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
@@ -10,7 +10,7 @@ menu:
   docs:
     parent: "functions"
 keywords: [sections,lists,indexes]
-signature: [".GetPage KIND PATH"]
+signature: [".GetPage PATH"]
 workson: []
 hugoversion:
 relatedfuncs: []
@@ -18,35 +18,42 @@ deprecated: false
 aliases: []
 ---
 
-Every `Page` has a [`Kind` attribute][page_kinds] that shows what kind of page it is. While this attribute can be used to list pages of a certain `kind` using `where`, often it can be useful to fetch a single page by its path.
-
-`.GetPage` returns a page of a given `Kind` and `path`.
+`.GetPage` returns a page of a given `path`. Both `Site` and `Page` implements this method. The `Page` variant will, if given a relative path -- i.e. a path without a leading `/` -- try look for the page relative to the current page.
 
 {{% note %}}
-If the `path` is `"foo/bar.md"`, it can be written as exactly that, or broken up
-into multiple strings as `"foo" "bar.md"`.
+**Note:** We overhauled and simplified the `.GetPage` API in Hugo 0.45. Before that you needed to provide a `Kind` attribute in addition to the path, e.g. `{{ .Site.GetPage "section" "blog" }}`. This will still work, but is now superflous.
 {{% /note %}}
 
-```
-{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}
+
+```go-html-template
+{{ with .Site.GetPage "/blog" }}{{ .Title }}{{ end }}
 ```
 
 This method wil return `nil` when no page could be found, so the above will not print anything if the blog section is not found.
 
-For a regular page (whose `Kind` is `page`):
+To fund a regular page in the blog section::
 
-```
-{{ with .Site.GetPage "page" "blog/my-post.md" }}{{ .Title }}{{ end }}
+```go-html-template
+{{ with .Site.GetPage "/blog/my-post.md" }}{{ .Title }}{{ end }}
 ```
 
-Note that the `path` can also be supplied like this, where the slash-separated
-path elements are added as separate strings:
+And since `Page` also provides a `.GetPage` method, the above is the same as:
 
+```go-html-template
+{{ with .Site.GetPage "/blog" }}
+{{ with .GetPage "my-post.md" }}{{ .Title }}{{ end }}
+{{ end }}
 ```
-{{ with .Site.GetPage "page" "blog" "my-post.md" }}{{ .Title }}{{ end }}
+
+## .GetPage and Multilingual Sites
+
+The previous examples have used the full content filename to lookup the post. Depending on how you have organized your content (whether you have the language code in the file name or not, e.g. `my-post.en.md`), you may want to do the lookup without extension. This will get you the current language's version of the page:
+
+```go-html-template
+{{ with .Site.GetPage "/blog/my-post" }}{{ .Title }}{{ end }}
 ```
 
-## `.GetPage` Example
+## .GetPage Example
 
 This code snippet---in the form of a [partial template][partials]---allows you to do the following:
 
@@ -57,7 +64,7 @@ This code snippet---in the form of a [partial template][partials]---allows you t
 
 {{< code file="grab-top-two-tags.html" >}}
 <ul class="most-popular-tags">
-{{ $t := .Site.GetPage "taxonomyTerm" "tags" }}
+{{ $t := .Site.GetPage "/tags" }}
 {{ range first 2 $t.Data.Terms.ByCount }}
     <li>{{ . }}</li>
 {{ end }}