diff --git a/config.toml b/config.toml index 203508ce0..e386aef1e 100644 --- a/config.toml +++ b/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) diff --git a/content/en/about/features.md b/content/en/about/features.md index 9d29c5bd3..e6ab6eea4 100644 --- a/content/en/about/features.md +++ b/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/ diff --git a/content/en/about/what-is-hugo.md b/content/en/about/what-is-hugo.md index de7344866..257c7e82d 100644 --- a/content/en/about/what-is-hugo.md +++ b/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" diff --git a/content/en/content-management/comments.md b/content/en/content-management/comments.md index 1152c843c..268dc4c0e 100644 --- a/content/en/content-management/comments.md +++ b/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 diff --git a/content/en/content-management/cross-references.md b/content/en/content-management/cross-references.md index 2980719e9..00f6ad1c1 100644 --- a/content/en/content-management/cross-references.md +++ b/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 {{}} {{}} {{}} +{{}} +{{}} {{}} {{}} {{}} ``` -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. -``` -{{}} => `/blog/post/` -{{}} => `/blog/post/` +### Link to another language version + +Link to another language version of a document, you need to use this syntax: + +```go-html-template +{{}} ``` -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: +### Get another Output Format -``` -. -└── content - ├── events - │   └── my-birthday.md - ├── galleries - │   └── my-birthday.md - ├── meta - │   └── my-article.md - └── posts - └── my-birthday.md -``` +To link to a given Output Format of a document, you can use this syntax: -To be sure to get the correct reference in this case, use the full path: - -{{< code file="content/meta/my-article.md" copy="false" >}} -{{}} => /events/my-birthday/ -{{< /code >}} - -### With Multiple Output Formats - -If the page exists in multiple [output formats][], `ref` or `relref` can be used with a output format name: - -``` - [Neat]({{}}) +```go-html-template +{{}} ``` ### 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 {{}} => #anchors:9decaf7 -{{}} => /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 {{}} => #who:9decaf7 -{{}} => /blog/post/#who:badcafe +{{}} => /blog/post/#who:badcafe ``` More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}). -### Examples -* `{{}}` => `https://example.com/blog/post/` -* `{{}}` => `https://example.com/blog/post/#tldr:caffebad` -* `{{}}` => `/blog/post/` -* `{{}}` => `/blog/post/#tldr:caffebad` -* `{{}}` => `#tldr:badcaffe` -* `{{}}` => `#tldr:badcaffe` +## Ref and RelRef Configuration -## Hugo Heading Anchors +The behaviour can, since Hugo 0.45, be configured in `config.toml`: -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. +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`). -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`. +refLinksNotFoundURL +: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. -`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.) -``` -{{}} -/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/ diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index 954ff7395..b26a9c059 100644 --- a/content/en/content-management/image-processing/index.md +++ b/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 diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md index 5894a16e5..32eeb7799 100644 --- a/content/en/content-management/multilingual.md +++ b/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. diff --git a/content/en/content-management/organization/index.md b/content/en/content-management/organization/index.md index b810f6179..b1bc8b368 100644 --- a/content/en/content-management/organization/index.md +++ b/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. diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md index 639d81eff..1c99d6a56 100644 --- a/content/en/content-management/page-bundles.md +++ b/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*" }}

Authors

{{ range $reusablePages }} diff --git a/content/en/functions/GetPage.md b/content/en/functions/GetPage.md index 1a8a51c13..2d9de4d7a 100644 --- a/content/en/functions/GetPage.md +++ b/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: -``` -{{ with .Site.GetPage "page" "blog" "my-post.md" }}{{ .Title }}{{ end }} +```go-html-template +{{ with .Site.GetPage "/blog" }} +{{ with .GetPage "my-post.md" }}{{ .Title }}{{ end }} +{{ end }} ``` -## `.GetPage` Example +## .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 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" >}}