Squashed 'docs/' changes from a4fa0d1d6..81847981f

81847981f Add notes for installing "extended" Sass/SCSS version
02da3bb58 Include usage of disqus internal template
9b53380c4 Update sitemap-template.md
f3417dd52 Update sitemap-template.md
aae33d9a8 Update sitemap-template.md
834edc205 Release 0.45.1
fb93ab905 Merge branch 'temp451'
79f350906 releaser: Prepare repository for 0.46-DEV
25cd2352c releaser: Add release notes to /docs for release of 0.45.1
e60377c71 releaser: Bump versions for release of 0.45.1
873f6dce2 Update features.md
ecc116642 Update link for Azure
cb88c3185 Added .Site.Home to Site Variiables (#541)
975a88791 Document includePaths
56c4e332f Release Hugo 0.45
c22b25210 Merge branch 'temp45'
0ffad3ada releaser: Prepare repository for 0.46-DEV
08d494cc3 releaser: Add release notes to /docs for release of 0.45
ad546ba45 releaser: Bump versions for release of 0.45
971c46bb2 Fixed "Sratch" to become "Scratch" on line 44
a28255bf3 Clarify the meaning of .Pages vs .Site.Pages
127aeee09 docs: Update ref, relref, GetPage docs
350d674ec resources.Concat doesn't have an alias
1fd1219b0 docs: Document refLinksErrorLevel and refLinksNotFoundURL
af2252ff6 Merge commit 'a3535c8486b2ce762b1a8a9c30b03985c3e02cee'
a11486805 Merge commit 'b6b37a1f00f808f3c0d2715f65ca2d3091f36495'
1c8896cb1 Fix addkit link to account for i18n
468aef3fc releaser: Prepare repository for 0.45-DEV
c6f4b97a2 releaser: Add release notes to /docs for release of 0.44
d3985afb7 releaser: Bump versions for release of 0.44
2c59a330c Adjust release notes
83966769a releaser: Prepare repository for 0.44-DEV
e539613f7 releaser: Add release notes to /docs for release of 0.43
2bf648944 releaser: Bump versions for release of 0.43
d9d6e4bf7 Fix typos
d6798afda Merge commit '98293eaa1570b5aff4452021c8b6d6c8560b3f06'
37cc52261 Add a newScratch template func
1f7f09613 Merge branch 'release-0.42.2'
857b0b26a releaser: Prepare repository for 0.43-DEV

git-subtree-dir: docs
git-subtree-split: 81847981f1f2cb1ebc83d42d275a2afb2bb22df1

config.toml

@@ -69,7 +69,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.44"
+  release = "0.45.1"
   ## Setting this to true will add a "noindex" to *EVERY* page on the site
   removefromexternalsearch = false
   ## Gh repo for site footer (include trailing slash)

content/en/about/features.md

@@ -53,12 +53,13 @@ toc: true
 * Integrated [Google Analytics][] support
 * Automatic [RSS][] creation
 * Support for [Go][], [Amber], and [Ace][] HTML templates
-* [Syntax highlighting][] powered by [Pygments][]
+* [Syntax highlighting][] powered by [Chroma][] (partly compatible with Pygments)
 
 
 [Ace]: /templates/alternatives/
 [aliases]: /content-management/urls/#aliases
 [Amber]: https://github.com/eknkc/amber
+[Chroma]: https://github.com/alecthomas/chroma
 [content summaries]: /content-management/summaries/
 [content types]: /content-management/types/
 [Disqus]: https://disqus.com/
@@ -77,7 +78,6 @@ toc: true
 [Permalink]: /content-management/urls/#permalinks
 [Powerful theming]: /themes/
 [Pretty URLs]: /content-management/urls/
-[Pygments]: http://pygments.org/
 [RSS]: /templates/rss/
 [Shortcodes]: /content-management/shortcodes/
 [sort content]: /templates/

content/en/about/what-is-hugo.md

@@ -44,7 +44,7 @@ Hugo is for people building a blog, a company site, a portfolio site, documentat
 [@spf13]: https://twitter.com/@spf13
 [Aerobatic]: https://www.aerobatic.com/
 [Amazon S3]: https://aws.amazon.com/s3/
-[Azure]: https://blogs.msdn.microsoft.com/acoat/2016/01/28/publish-a-static-web-site-using-azure-web-apps/
+[Azure]: https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website
 [CloudFront]: https://aws.amazon.com/cloudfront/ "Amazon CloudFront"
 [DreamHost]: https://www.dreamhost.com/
 [Firebase]: https://firebase.google.com/docs/hosting/ "Firebase static hosting"

content/en/content-management/comments.md

@@ -41,7 +41,11 @@ For many websites, this is enough configuration. However, you also have the opti
 
 ### Render Hugo's Built-in Disqus Partial Template
 
-See [Partial Templates][partials] to learn how to add the Disqus partial to your Hugo website's templates.
+Disqus has its own [internal template](https://gohugo.io/templates/internal/#disqus) available, to render it add the following code where you want comments to appear:
+
+```
+{{ template "_internal/disqus.html" . }}
+```
 
 ## Comments Alternatives
 

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,114 +16,72 @@ 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:
 
+```go-html-template
+{{</* relref path="document.md" lang="jp" */>}}
 ```
-.
-└── content
-    ├── events
-    │   └── my-birthday.md
-    ├── galleries
-    │   └── my-birthday.md
-    ├── meta
-    │   └── my-article.md
-    └── posts
-        └── my-birthday.md
-```
-
-To be sure to get the correct reference in this case, use the full path: 
 
-{{< code file="content/meta/my-article.md" copy="false" >}}
-{{</* relref "events/my-birthday.md" */>}} => /events/my-birthday/
-{{< /code >}}
+### Get another Output Format
 
-### With Multiple Output Formats
+To link to a given Output Format of a document, you can use this syntax:
 
-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
+## Ref and RelRef Configuration
 
-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.
+The behaviour can, since Hugo 0.45, be configured in `config.toml`:
 
-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`.
+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`).
 
-`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.)
+refLinksNotFoundURL
+: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
 
-```
-{{</* 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}
-```
 
-[built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes
 [lists]: /templates/lists/
 [output formats]: /templates/output-formats/
 [shortcode]: /content-management/shortcodes/

content/en/content-management/image-processing/index.md

@@ -17,10 +17,10 @@ menu:
 
 ## The Image Page Resource
 
-The `image` is a [Page Resource]({{< relref "content-management/page-resources" >}}), and the processing methods listed below does not work on images inside your `/static` folder.
+The `image` is a [Page Resource]({{< relref "/content-management/page-resources" >}}), and the processing methods listed below does not work on images inside your `/static` folder.
 
 
-To get all images in a [Page Bundle]({{< relref "content-management/organization#page-bundles" >}}):
+To get all images in a [Page Bundle]({{< relref "/content-management/organization#page-bundles" >}}):
 
 
 ```go-html-template

content/en/content-management/multilingual.md

@@ -231,7 +231,7 @@ By setting the `translationKey` front matter param to `about` in all three pages
 
 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. 
+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.
 

content/en/content-management/organization/index.md

@@ -21,7 +21,7 @@ toc: true
 
 Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`. 
 
-These terms are connected, and you also need to read about [Page Resources]({{< relref "content-management/page-resources" >}}) and [Image Processing]({{< relref "content-management/image-processing" >}}) to get the full picture.
+These terms are connected, and you also need to read about [Page Resources]({{< relref "/content-management/page-resources" >}}) and [Image Processing]({{< relref "/content-management/image-processing" >}}) to get the full picture.
 
 {{% imgproc 1-featured Resize "300x" %}}
 The illustration shows 3 bundles. Note that the home page bundle cannot contain other content pages, but other files (images etc.) are fine.

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 }}

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,43 +10,50 @@ menu:
   docs:
     parent: "functions"
 keywords: [sections,lists,indexes]
-signature: [".GetPage KIND PATH"]
+signature: [".GetPage PATH"]
 workson: []
 hugoversion:
 relatedfuncs: []
 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 }}

content/en/functions/scratch.md

@@ -22,6 +22,9 @@ aliases: [/extras/scratch/,/doc/scratch/]
 
 In most cases you can do okay without `Scratch`, but due to scoping issues, there are many use cases that aren't solvable in Go Templates without `Scratch`'s help.
 
+`.Scratch` is available as methods on `Page` and `Shortcode`. Since Hugo 0.43 you can also create a locally scoped `Scratch` using the template func `newScratch`.
+
+
 {{% note %}}
 See [this Go issue](https://github.com/golang/go/issues/10608) for the main motivation behind Scratch.
 {{% /note %}}
@@ -39,7 +42,7 @@ $scratch := newScratch
 $scratch.Set "greeting" "Hello"
 ```
 
-A `Scratch` is also added to both `Page` and `Shortcode`. `Sratch` have the following methods:
+A `Scratch` is also added to both `Page` and `Shortcode`. `Scratch` has the following methods:
 
 #### .Set
 

content/en/getting-started/configuration.md

@@ -183,6 +183,12 @@ related
 relativeURLs (false)
 : Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
 
+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`).
+
+refLinksNotFoundURL
+: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
+
 rssLimit (unlimited)
 : Maximum number of items in the RSS feed.