diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2018-08-01 10:01:49 +0200 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2018-08-01 10:01:49 +0200 |
commit | e6dd54943fd1d6129d73ecf7fc9bc6df26b75117 (patch) | |
tree | e953eb883f2144521f5ebe3d8a50f48c518260ad /docs/content | |
parent | b5d13ca16bf106c1bc29c2a5295cd231d1bf13fd (diff) | |
parent | 766085c2dc6fc95ac30fda2a9ebde2355fc12554 (diff) |
Merge commit '766085c2dc6fc95ac30fda2a9ebde2355fc12554'
Diffstat (limited to 'docs/content')
18 files changed, 123 insertions, 57 deletions
diff --git a/docs/content/en/about/features.md b/docs/content/en/about/features.md index 9d29c5bd3..e6ab6eea4 100644 --- a/docs/content/en/about/features.md +++ b/docs/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/docs/content/en/about/what-is-hugo.md b/docs/content/en/about/what-is-hugo.md index de7344866..257c7e82d 100644 --- a/docs/content/en/about/what-is-hugo.md +++ b/docs/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/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md index 1152c843c..268dc4c0e 100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/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/docs/content/en/content-management/image-processing/index.md b/docs/content/en/content-management/image-processing/index.md index 954ff7395..b26a9c059 100644 --- a/docs/content/en/content-management/image-processing/index.md +++ b/docs/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/docs/content/en/content-management/multilingual.md b/docs/content/en/content-management/multilingual.md index 5894a16e5..32eeb7799 100644 --- a/docs/content/en/content-management/multilingual.md +++ b/docs/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/docs/content/en/content-management/organization/index.md b/docs/content/en/content-management/organization/index.md index b810f6179..b1bc8b368 100644 --- a/docs/content/en/content-management/organization/index.md +++ b/docs/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/docs/content/en/functions/scratch.md b/docs/content/en/functions/scratch.md index c0ecaca80..1a64bb2e3 100644 --- a/docs/content/en/functions/scratch.md +++ b/docs/content/en/functions/scratch.md @@ -42,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 diff --git a/docs/content/en/getting-started/installing.md b/docs/content/en/getting-started/installing.md index a4cf0801f..c08a22835 100644 --- a/docs/content/en/getting-started/installing.md +++ b/docs/content/en/getting-started/installing.md @@ -34,7 +34,7 @@ Hugo currently provides pre-built binaries for the following: * OpenBSD * FreeBSD -Hugo may also be compiled from source wherever the Go compiler tool chain can run; e.g., on other operating systems such as DragonFly BSD, OpenBSD, Plan 9, Solaris, and others. See <https://golang.org/doc/install/source> for the full set of supported combinations of target operating systems and compilation architectures. +Hugo may also be compiled from source wherever the Go toolchain can run; e.g., on other operating systems such as DragonFly BSD, OpenBSD, Plan 9, Solaris, and others. See <https://golang.org/doc/install/source> for the full set of supported combinations of target operating systems and compilation architectures. ## Quick Install @@ -82,9 +82,11 @@ go get github.com/magefile/mage go get -d github.com/gohugoio/hugo cd ${GOPATH:-$HOME/go}/src/github.com/gohugoio/hugo mage vendor -mage install +HUGO_BUILD_TAGS=extended mage install {{< /code >}} +Remove `HUGO_BUILD_TAGS=extended` if you do not want Sass/SCSS support. + {{% note %}} If you are a Windows user, substitute the `$HOME` environment variable above with `%USERPROFILE%`. {{% /note %}} @@ -420,50 +422,43 @@ Directory of C:\hugo\sites\example.com ### Snap Package -In any of the [Linux distributions that support snaps][snaps]: +In any of the [Linux distributions that support snaps][snaps], you may install install the "extended" Sass/SCSS version with this command: -``` -snap install hugo -``` + snap install hugo --channel=extended -### Debian and Ubuntu +To install the non-extended version without Sass/SCSS support: -Debian and Ubuntu provide a `hugo` version via `apt-get`: + snap install hugo -``` -sudo apt-get install hugo -``` +To switch between the two, use either `snap refresh hugo --channel=extended` or `snap refresh hugo --channel=stable`. -#### Pros +{{% note %}} +Hugo-as-a-snap can write only inside the user’s `$HOME` directory---and gvfs-mounted directories owned by the user---because of Snaps’ confinement and security model. More information is also available [in this related GitHub issue](https://github.com/gohugoio/hugo/issues/3143). Use ```sudo snap install hugo --classic``` to disable the default security model if you want hugo to be able to have write access in other paths besides the user’s `$HOME` directory. +{{% /note %}} -* Native Debian/Ubuntu package maintained by Debian Developers -* Pre-installed bash completion script and `man` pages +### Debian and Ubuntu -#### Cons +[@anthonyfok](https://github.com/anthonyfok) and friends in the [Debian Go Packaging Team](https://go-team.pages.debian.net/) maintains an official hugo [Debian package](https://packages.debian.org/hugo) which is shared with [Ubuntu](https://packages.ubuntu.com/hugo) and is installable via `apt-get`: -* Might not be the latest version, especially if you are using an older, stable version (e.g., Ubuntu 16.04 LTS). Until backports and PPA are available, you may consider installing the Hugo snap package to get the latest version of Hugo. + sudo apt-get install hugo -{{% note %}} -Hugo-as-a-snap can write only inside the user’s `$HOME` directory---and gvfs-mounted directories owned by the user---because of Snaps’ confinement and security model. More information is also available [in this related GitHub issue](https://github.com/gohugoio/hugo/issues/3143). Use ```sudo snap install hugo --classic``` to disable the default security model if you want hugo to be able to have write access in other paths besides the user’s `$HOME` directory. -{{% /note %}} +This installs the "extended" Sass/SCSS version. ### Arch Linux -You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also for derivatives such as Manjaro. +You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also to derivatives such as Manjaro. ``` sudo pacman -Syu hugo ``` -### Fedora +### Fedora, Red Hat and CentOS -Fedora provides a package for Hugo. The installation is done with the command : +Fedora maintains an [official package for Hugo](https://apps.fedoraproject.org/packages/hugo) which may be installed with: -``` -sudo dnf install hugo -``` + sudo dnf install hugo -### CentOS, and Red Hat +For the latest version, the Hugo package maintained by [@daftaupe](https://github.com/daftaupe) at Fedora Copr is recommended: * <https://copr.fedorainfracloud.org/coprs/daftaupe/hugo/> @@ -471,11 +466,10 @@ See the [related discussion in the Hugo forums][redhatforum]. ## OpenBSD -OpenBSD provides a package for Hugo via `pkg_add`: +OpenBSD provides a package for Hugo via `pkg_add`: + + doas pkg_add hugo -``` -doas pkg_add hugo -``` ## Upgrade Hugo diff --git a/docs/content/en/hugo-pipes/introduction.md b/docs/content/en/hugo-pipes/introduction.md index 84ac4ec6d..3c42dc68f 100755 --- a/docs/content/en/hugo-pipes/introduction.md +++ b/docs/content/en/hugo-pipes/introduction.md @@ -43,7 +43,7 @@ For improved readability, the Hugo Pipes examples of this documentation will be ### Method aliases Each Hugo Pipes `resources` transformation method uses a __camelCased__ alias (`toCSS` for `resources.ToCSS`). -Non-transformation methods deprived of such aliases are `resources.Get`, `resources.FromString` and `resources.ExecuteAsTemplate`. +Non-transformation methods deprived of such aliases are `resources.Get`, `resources.FromString`, `resources.ExecuteAsTemplate` and `resources.Concat`. The example above can therefore also be written as follows: ```go-html-template diff --git a/docs/content/en/hugo-pipes/scss-sass.md b/docs/content/en/hugo-pipes/scss-sass.md index b08d4be08..baed2b4d0 100755 --- a/docs/content/en/hugo-pipes/scss-sass.md +++ b/docs/content/en/hugo-pipes/scss-sass.md @@ -36,7 +36,10 @@ precision [int] enableSourceMap [bool] : When enabled, a source map will be generated. +includePaths [string slice] +: Additional SCSS/SASS include paths. Paths must be relative to the project directory. + ```go-html-template -{{ $options := (dict "targetPath" "style.css" "outputStyle" "compressed" "enableSourceMap" true) }} +{{ $options := (dict "targetPath" "style.css" "outputStyle" "compressed" "enableSourceMap" true "includePaths" (slice "node_modules/myscss")) }} {{ $style := resources.Get "sass/main.scss" | resources.ToCSS $options }} -```
\ No newline at end of file +``` diff --git a/docs/content/en/news/0.45-relnotes/featured-hugo-45-poster.png b/docs/content/en/news/0.45-relnotes/featured-hugo-45-poster.png Binary files differnew file mode 100644 index 000000000..40f71daca --- /dev/null +++ b/docs/content/en/news/0.45-relnotes/featured-hugo-45-poster.png diff --git a/docs/content/en/news/0.45-relnotes/index.md b/docs/content/en/news/0.45-relnotes/index.md index 174ab8ead..b67a24de6 100644 --- a/docs/content/en/news/0.45-relnotes/index.md +++ b/docs/content/en/news/0.45-relnotes/index.md @@ -1,8 +1,8 @@ --- date: 2018-07-22 -title: "0.45" -description: "0.45" +title: "Hugo 0.45: Revival of ref, relref and GetPage" +description: "Hugo 0.45 adds relative page lookups, language support in ref/relref and several Hugo Pipes improvements." categories: ["Releases"] --- @@ -15,7 +15,7 @@ Now you can simply do: {{ with .Site.GetPage "/blog/my-post.md" }}{{ .Title }}{{ end }} ``` -Or two get a section page: +Or to get a section page: ```go-html-template diff --git a/docs/content/en/news/0.45.1-relnotes/index.md b/docs/content/en/news/0.45.1-relnotes/index.md index e5b652e31..84e0416c7 100644 --- a/docs/content/en/news/0.45.1-relnotes/index.md +++ b/docs/content/en/news/0.45.1-relnotes/index.md @@ -1,8 +1,8 @@ --- date: 2018-07-25 -title: "0.45.1" -description: "0.45.1" +title: "Hugo 0.45.1: Two Bug Fixes" +description: "Hugo 0.45.1 comes with two bug fixes ... and one enhancement." categories: ["Releases"] images: - images/blog/hugo-bug-poster.png diff --git a/docs/content/en/readfiles/pages-vs-site-pages.md b/docs/content/en/readfiles/pages-vs-site-pages.md new file mode 100644 index 000000000..77f829819 --- /dev/null +++ b/docs/content/en/readfiles/pages-vs-site-pages.md @@ -0,0 +1,9 @@ +| Variable | Current context | Pages included | +|----------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `.Site.Pages` | **any** page | ALL pages of the site: content, sections, taxonomies, etc. -- Superset of everything! | +| `.Site.RegularPages` | **any** page | Only regular (content) pages -- Subset of `.Site.Pages` | +| `.Pages` | _List_ page | Regular pages under that _list_ page representing the homepage, section, taxonomy term (`/tags`) or taxonomy (`/tags/foo`) page -- Subset of `.Site.Pages` or `.Site.RegularPages`, depending on context. | +| `.Pages` | _Single_ page | empty slice | + +Note +: In the **home** context (`index.html`), `.Pages` is the same as `.Site.RegularPages`. diff --git a/docs/content/en/templates/sitemap-template.md b/docs/content/en/templates/sitemap-template.md index 4df9c2490..7cbc7cefb 100644 --- a/docs/content/en/templates/sitemap-template.md +++ b/docs/content/en/templates/sitemap-template.md @@ -35,18 +35,35 @@ A sitemap is a `Page` and therefore has all the [page variables][pagevars] avail If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal `sitemap.xml` template that ships with Hugo. +## Sitemap Templates + +Hugo has built-on Sitemap templates, but you can provide your own if needed, in either `layouts/sitemap.xml` or `layouts/_default/sitemap.xml`. + +For multilingual sites, we also create a Sitemap index. You can provide a custom layout for that in either `layouts/sitemapindex.xml` or `layouts/_default/sitemapindex.xml`. + ## Hugo’s sitemap.xml This template respects the version 0.9 of the [Sitemap Protocol](http://www.sitemaps.org/protocol.html). -``` -<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> - {{ range .Pages }} +```xml +<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" + xmlns:xhtml="http://www.w3.org/1999/xhtml"> + {{ range .Data.Pages }} <url> <loc>{{ .Permalink }}</loc>{{ if not .Lastmod.IsZero }} <lastmod>{{ safeHTML ( .Lastmod.Format "2006-01-02T15:04:05-07:00" ) }}</lastmod>{{ end }}{{ with .Sitemap.ChangeFreq }} <changefreq>{{ . }}</changefreq>{{ end }}{{ if ge .Sitemap.Priority 0.0 }} - <priority>{{ .Sitemap.Priority }}</priority>{{ end }} + <priority>{{ .Sitemap.Priority }}</priority>{{ end }}{{ if .IsTranslated }}{{ range .Translations }} + <xhtml:link + rel="alternate" + hreflang="{{ .Lang }}" + href="{{ .Permalink }}" + />{{ end }} + <xhtml:link + rel="alternate" + hreflang="{{ .Lang }}" + href="{{ .Permalink }}" + />{{ end }} </url> {{ end }} </urlset> @@ -59,6 +76,23 @@ on render. Please don't include this in the template as it's not valid HTML. `<?xml version="1.0" encoding="utf-8" standalone="yes" ?>` {{% /note %}} +## Hugo's sitemapindex.xml + +This is used to create a Sitemap index in multilingual mode: + +```xml +<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> + {{ range . }} + <sitemap> + <loc>{{ .SitemapAbsURL }}</loc> + {{ if not .LastChange.IsZero }} + <lastmod>{{ .LastChange.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</lastmod> + {{ end }} + </sitemap> + {{ end }} +</sitemapindex> +``` + ## Configure `sitemap.xml` Defaults for `<changefreq>`, `<priority>` and `filename` values can be set in the site's config file, e.g.: @@ -72,4 +106,6 @@ Defaults for `<changefreq>`, `<priority>` and `filename` values can be set in th The same fields can be specified in an individual content file's front matter in order to override the value assigned to that piece of content at render time. + + [pagevars]: /variables/page/ diff --git a/docs/content/en/troubleshooting/build-performance.md b/docs/content/en/troubleshooting/build-performance.md index bc4d30d54..f2242ea2e 100644 --- a/docs/content/en/troubleshooting/build-performance.md +++ b/docs/content/en/troubleshooting/build-performance.md @@ -108,4 +108,4 @@ the memory usage per step, and the total memory allocations per step. To enable *step analysis*, use the `--stepAnalysis` option when running Hugo. -[partialCached]:{{< ref "functions/partialCached.md" >}} +[partialCached]:{{< ref "/functions/partialCached.md" >}} diff --git a/docs/content/en/variables/page.md b/docs/content/en/variables/page.md index 7279eec7e..a5de1b442 100644 --- a/docs/content/en/variables/page.md +++ b/docs/content/en/variables/page.md @@ -106,9 +106,8 @@ See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo]. : contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).) .Pages -: a collection of associated pages. `.Pages` is an alias for - `.Data.Pages`. This value will be `nil` within the context of - regular content pages. +: a collection of associated pages. This value will be `nil` within + the context of regular content pages. See [`.Pages`](#pages). .Permalink : the Permanent link for this page; see [Permalinks](/content-management/urls/) @@ -187,6 +186,15 @@ Also see [Sections](/content-management/sections/). {{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}} +## The `.Pages` Variable {#pages} + +`.Pages` is an alias to `.Data.Pages`. It is conventional to use the +aliased form `.Pages`. + +### `.Pages` compared to `.Site.Pages` + +{{< readfile file="/content/en/readfiles/pages-vs-site-pages.md" markdown="true" >}} + ## Page-level Params Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable. diff --git a/docs/content/en/variables/site.md b/docs/content/en/variables/site.md index a5909a563..eaacafa32 100644 --- a/docs/content/en/variables/site.md +++ b/docs/content/en/variables/site.md @@ -49,6 +49,9 @@ The following is a list of site-level (aka "global") variables. Many of these va .Site.GoogleAnalytics : a string representing your tracking code for Google Analytics as defined in the site configuration. +.Site.Home +: reference to the homepage's [page object](https://gohugo.io/variables/page/) + .Site.IsMultiLingual : whether there are more than one language in this site. See [Multilingual](/content-management/multilingual/) for more information. @@ -83,13 +86,13 @@ The following is a list of site-level (aka "global") variables. Many of these va : all of the menus in the site. .Site.Pages -: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. +: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. See [`.Site.Pages`](#site-pages). .Site.Permalinks : a string to override the default [permalink](/content-management/urls/) format as defined in the site configuration. .Site.RegularPages -: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. +: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. See [`.Site.Pages`](#site-pages). .Site.RSSLink : the URL for the site RSS. @@ -125,4 +128,13 @@ You can use `.Site.Params` in a [partial template](/templates/partials/) to call <meta name="description" content="{{if .IsHome}}{{ $.Site.Params.description }}{{else}}{{.Description}}{{end}}" /> {{< /code >}} +## The `.Site.Pages` Variable {#site-pages} + +### `.Site.Pages` compared to `.Pages` + +{{< readfile file="/content/en/readfiles/pages-vs-site-pages.md" markdown="true" >}} + + + + [config]: /getting-started/configuration/ |