From 766085c2dc6fc95ac30fda2a9ebde2355fc12554 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Wed, 1 Aug 2018 10:01:05 +0200 Subject: [PATCH] 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 | 2 +- content/en/about/features.md | 4 +- content/en/about/what-is-hugo.md | 2 +- content/en/content-management/comments.md | 6 +- .../en/content-management/cross-references.md | 96 +++++----------- .../image-processing/index.md | 4 +- content/en/content-management/multilingual.md | 2 +- .../content-management/organization/index.md | 2 +- content/en/content-management/page-bundles.md | 2 +- content/en/functions/GetPage.md | 43 ++++--- content/en/functions/scratch.md | 5 +- content/en/getting-started/configuration.md | 6 + content/en/getting-started/installing.md | 56 ++++----- content/en/hugo-pipes/introduction.md | 2 +- content/en/hugo-pipes/scss-sass.md | 7 +- content/en/news/0.35-relnotes/index.md | 2 +- content/en/news/0.36.1-relnotes/index.md | 2 +- content/en/news/0.42.1-relnotes/index.md | 2 + .../0.45-relnotes/featured-hugo-45-poster.png | Bin 0 -> 66863 bytes content/en/news/0.45-relnotes/index.md | 107 ++++++++++++++++++ content/en/news/0.45.1-relnotes/index.md | 26 +++++ content/en/readfiles/pages-vs-site-pages.md | 9 ++ content/en/templates/sitemap-template.md | 44 ++++++- content/en/tools/starter-kits.md | 4 +- .../en/troubleshooting/build-performance.md | 2 +- content/en/variables/page.md | 14 ++- content/en/variables/site.md | 16 ++- data/articles.toml | 2 +- netlify.toml | 8 +- ...403d34e039f_90587_300x0_resize_q10_box.jpg | Bin 1939 -> 0 bytes ...403d34e039f_90587_300x0_resize_q75_box.jpg | Bin 5141 -> 0 bytes ...2b1403d34e039f_90587_90x90_fit_q75_box.jpg | Bin 1295 -> 0 bytes ...039f_90587_200x200_fill_q75_box_smart1.jpg | Bin 3583 -> 0 bytes ...403d34e039f_90587_300x0_resize_q10_box.jpg | Bin 1939 -> 0 bytes ...403d34e039f_90587_300x0_resize_q75_box.jpg | Bin 5141 -> 0 bytes ...2b1403d34e039f_90587_90x90_fit_q75_box.jpg | Bin 1295 -> 0 bytes ...32acaa20f204198_63640_300x0_resize_box.png | Bin 21101 -> 0 bytes ...c5f4f5baccdcad4_70230_480x0_resize_box.png | Bin 66984 -> 0 bytes ...83849a78eea35dd_78317_480x0_resize_box.png | Bin 78872 -> 0 bytes ...4e02851ebf2f82e_88519_480x0_resize_box.png | Bin 90606 -> 0 bytes ...391758_66863_480x0_resize_catmullrom_2.png | Bin 0 -> 30118 bytes ...391758_66863_640x0_resize_catmullrom_2.png | Bin 0 -> 47821 bytes .../gohugoioTheme/static/dist/app.bundle.js | 16 +-- 43 files changed, 334 insertions(+), 159 deletions(-) create mode 100644 content/en/news/0.45-relnotes/featured-hugo-45-poster.png create mode 100644 content/en/news/0.45-relnotes/index.md create mode 100644 content/en/news/0.45.1-relnotes/index.md create mode 100644 content/en/readfiles/pages-vs-site-pages.md delete mode 100644 resources/_gen/images/about/new-in-032/sunset_hu59e56ffff1bc1d8d122b1403d34e039f_90587_300x0_resize_q10_box.jpg delete mode 100644 resources/_gen/images/about/new-in-032/sunset_hu59e56ffff1bc1d8d122b1403d34e039f_90587_300x0_resize_q75_box.jpg delete mode 100644 resources/_gen/images/about/new-in-032/sunset_hu59e56ffff1bc1d8d122b1403d34e039f_90587_90x90_fit_q75_box.jpg delete mode 100644 resources/_gen/images/content-management/image-processing/sunset_hu59e56ffff1bc1d8d122b1403d34e039f_90587_200x200_fill_q75_box_smart1.jpg delete mode 100644 resources/_gen/images/content-management/image-processing/sunset_hu59e56ffff1bc1d8d122b1403d34e039f_90587_300x0_resize_q10_box.jpg delete mode 100644 resources/_gen/images/content-management/image-processing/sunset_hu59e56ffff1bc1d8d122b1403d34e039f_90587_300x0_resize_q75_box.jpg delete mode 100644 resources/_gen/images/content-management/image-processing/sunset_hu59e56ffff1bc1d8d122b1403d34e039f_90587_90x90_fit_q75_box.jpg delete mode 100644 resources/_gen/images/content-management/organization/1-featured-content-bundles_hu3e3ae7839b071119f32acaa20f204198_63640_300x0_resize_box.png delete mode 100644 resources/_gen/images/news/0.33-relnotes/featured-hugo-33-poster_hu45ce9da1cdea6ca61c5f4f5baccdcad4_70230_480x0_resize_box.png delete mode 100644 resources/_gen/images/news/0.34-relnotes/featured-34-poster_hud8d73dc5df8d5a35383849a78eea35dd_78317_480x0_resize_box.png delete mode 100644 resources/_gen/images/news/0.35-relnotes/featured-hugo-35-poster_hua42b1310dd72f60a34e02851ebf2f82e_88519_480x0_resize_box.png create mode 100644 resources/_gen/images/news/0.45-relnotes/featured-hugo-45-poster_huea79995576e3b93a3041ae824a391758_66863_480x0_resize_catmullrom_2.png create mode 100644 resources/_gen/images/news/0.45-relnotes/featured-hugo-45-poster_huea79995576e3b93a3041ae824a391758_66863_640x0_resize_catmullrom_2.png 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" >}}