From 2a011b7cff65dd23b1de4b355f6e985512312f72 Mon Sep 17 00:00:00 2001 From: Ryan Watters Date: Fri, 10 Mar 2017 16:18:34 -0600 Subject: [PATCH] Add admonition note for Snap users in install docs --- content/functions/range.md | 2 +- content/getting-started/installing.md | 8 +++++--- content/templates/alternatives.md | 2 +- content/templates/base.md | 2 +- content/templates/homepage.md | 13 +++++++------ .../{go-templates.md => introduction.md} | 6 +++--- content/templates/lookup-order.md | 10 +++++----- content/templates/partials.md | 4 ++-- content/templates/rss.md | 18 ++++++++++-------- content/templates/template-debugging.md | 8 ++++---- content/themes/_index.md | 2 +- content/tutorials/creating-a-new-theme.md | 2 +- content/variables/_index.md | 2 +- 13 files changed, 42 insertions(+), 37 deletions(-) rename content/templates/{go-templates.md => introduction.md} (99%) diff --git a/content/functions/range.md b/content/functions/range.md index ccd02db48..e8aeebf13 100644 --- a/content/functions/range.md +++ b/content/functions/range.md @@ -19,4 +19,4 @@ aliases: [] Just like in the Go programming language, Go and Hugo templates make heavy use of `range` to iterate over a map, array or slice. -`range` is fundamental to templating in Hugo. (See the [Go Template Primer](/templates/go-templates/) for more examples. +`range` is fundamental to templating in Hugo. (See the [Introduction to Hugo Templates](/templates/introduction/) for more examples. diff --git a/content/getting-started/installing.md b/content/getting-started/installing.md index 03822e9be..6d44775b8 100644 --- a/content/getting-started/installing.md +++ b/content/getting-started/installing.md @@ -416,13 +416,15 @@ In any of the [Linux distributions that support snaps](http://snapcraft.io/docs/ snap install hugo ``` +{{% note %}} +Snap Hugo users may get a `Resource temporarily unavailable` runtime error. This is because non-root users may only write inside two specific directories for most snaps. You can find a workaround using the `home` plug at [snapcraft.io](https://snapcraft.io/docs/reference/interfaces). More information is also available [in this related GitHub issue](https://github.com/spf13/hugo/issues/3143). +{{% /note %}} + ### Arch-based distributions Install Hugo from the [Arch user repository](https://aur.archlinux.org/) on Arch Linux or derivatives like Manjaro. -{{% note %}} -Be aware that Hugo is built from source. This means that additional tools like Git and Go (the programming language Hugo is written in) will be installed as well. -{{% /note %}} +Be aware that Hugo is built from source. This means that additional tools like [Git](https://git-scm.com) and [Go](https://golang.org/doc/install) will be installed as well. ```bash sudo pacman -S yaourt diff --git a/content/templates/alternatives.md b/content/templates/alternatives.md index e45b68098..d9435ad49 100644 --- a/content/templates/alternatives.md +++ b/content/templates/alternatives.md @@ -70,5 +70,5 @@ For Amber template documentation, follow the links from the [Amber project][]. [aceinheritance]: https://github.com/yosssi/ace/tree/master/examples/base_inner_template [Amber Project]: https://github.com/eknkc/amber [template functions]: /functions/ -[Go templates]: /templates/go-templates/ +[Go templates]: /templates/introduction/ [Go base templates]: /templates/base/ \ No newline at end of file diff --git a/content/templates/base.md b/content/templates/base.md index 2c92a6739..c249f2bc9 100644 --- a/content/templates/base.md +++ b/content/templates/base.md @@ -97,7 +97,7 @@ From the above base template, you can define a [default list template][hugolists {{% /code %}} {{% note "No Go Context \"the dot\" in Block Definitions" %}} -When using the `define` keyword, you do *not* need to use Go templates context reference (i.e., "the dot"). (Read more on ["the dot" in the Go Template Primer](/templates/go-templates/).) +When using the `define` keyword, you do *not* need to use Go templates context reference (i.e., "the dot"). (Read more on "the dot" in [Templates Introduction](/templates/introduction/).) {{% /note %}} This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists. diff --git a/content/templates/homepage.md b/content/templates/homepage.md index 11885b90a..046b464c7 100644 --- a/content/templates/homepage.md +++ b/content/templates/homepage.md @@ -13,7 +13,7 @@ aliases: [/layout/homepage/,/templates/homepage-template/] toc: false --- -The homepage of a website is often formatted differently than the other pages. In Hugo you can define your own homepage template. +The homepage of a website often has a unique design. In Hugo, you can define your own homepage template. Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use. @@ -26,8 +26,8 @@ The homepage template is the *only* required template for building a site and th The [lookup order][lookup] for the homepage template is as follows: 1. `/layouts/index.html` -2. `/layouts/\_default/list.html` -3. `/layouts/\_default/single.html` +2. `/layouts/_default/list.html` +3. `/layouts/_default/single.html` 4. `/themes//layouts/index.html` 5. `/themes//layouts/_default/list.html` 6. `/themes//layouts/_default/single.html` @@ -36,13 +36,14 @@ The [lookup order][lookup] for the homepage template is as follows: In addition to the standard [page variables][pagevars], the homepage template has access to *all* site content via `.Data.Pages`. -`.Data.Pages` usually refers to the list of pages available within a given section or taxonomy. However, since `index.html` is the homepage of your Hugo project (i.e., in essence, the top or master section), `Data.Pages` for `layouts/index.html` is interchangeable with `.Site.Pages` when written on the homepage template. -Note that a homepage can also have a content file with front matter. This content file lives at `content/_index.md`. See [Content Organization][contentorg] for more information. +## Homepage Content and Front Matter + +A homepage can also have a content file with front matter: `content/_index.md`. See [Content Organization][contentorg] for more information. ## Example Homepage Template -The following is an example of a homepage template makes use of [partial][partials] and [block][] templates. +The following is an example of a homepage template that uses [partial][partials] and [block][] templates. {{% code file="layouts/index.html" download="index.html" %}} ```html diff --git a/content/templates/go-templates.md b/content/templates/introduction.md similarity index 99% rename from content/templates/go-templates.md rename to content/templates/introduction.md index 8178bdc5d..396c48486 100644 --- a/content/templates/go-templates.md +++ b/content/templates/introduction.md @@ -1,6 +1,6 @@ --- -title: Go Template Primer -linktitle: Go Template Primer +title: Introduction to Hugo Templating +linktitle: Introduction description: Hugo uses Go's html/template library, an extremely lightweight and performant engine, as the basis for all Hugo templating. godocref: https://golang.org/pkg/html/template/ date: 2017-02-01 @@ -10,7 +10,7 @@ categories: [templates] tags: [go,fundamentals] weight: 10 draft: false -aliases: [/templates/go-template-primer/,/layouts/go-templates/,/layout/go-templates/] +aliases: [/templates/introduction/,/layouts/introduction/,/layout/introduction/] toc: true --- diff --git a/content/templates/lookup-order.md b/content/templates/lookup-order.md index 1e510e299..4d1d63aef 100644 --- a/content/templates/lookup-order.md +++ b/content/templates/lookup-order.md @@ -18,7 +18,7 @@ Before creating your templates, it's important to know how Hugo looks for files Hugo uses a prioritized list called the **lookup order** as it traverses your `layouts` folder in your Hugo project *looking* for the appropriate template to render your content. -The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C...and so on until it reaches the `_default/` directory for your project or theme. In many ways, the lookup order is similar to the control mechanism of a [switch statement (i.e. without fallthrough)][switch] seen in many programming languages. +The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C...and so on until it reaches the `_default/` directory for your project or theme. In many ways, the lookup order is similar to the programming concept of a [switch statement without fallthrough][switch]. The power of the lookup order is that it enables you to craft specific layouts and keep your templating [DRY][]. @@ -28,9 +28,9 @@ Most Hugo websites will only need the default template files at the end of the l ## Single Page Template Lookup Examples -The lookup order is best illustrated by example. The following shows you the process Hugo uses for finding the appropriate template to render your [single content][], but the concept holds true for all templates in Hugo. +The lookup order is best illustrated through examples. The following shows you the process Hugo uses for finding the appropriate template to render your [single content][], but the concept holds true for all templates in Hugo. -1. The project is using the theme `mytheme`, which would be specified as `theme = "mytheme" or `theme: mytheme` in the project's [`config.toml` or `config.yaml`][config], respectively. +1. The project is using the theme `mytheme` (specified in the project's [configuration][config]). 2. The layouts and content directories for the project are as follows: ```bash @@ -64,7 +64,7 @@ The lookup order is best illustrated by example. The following shows you the pro Now we can look at the front matter for the three content (i.e.`.md`) files. {{% note %}} -There are four markdown files but we are only going to review three for the *single* page lookup order. `_index.md` may seem like a single page of content but is actually a specific `kind` in Hugo. Whereas `my-first-post.md`, `my-second-post.md`, and `my-first-event.md` are all of kind `page`, all `_index.md` files in a Hugo project are used to add content and front matter to list pages. In this example, `events/_index.md` will render according to its [section template](/templates/section-templates/) and respective lookup order. +Only three of the four markdown files in the above project are subject to the *single* page lookup order. `_index.md` is a specific `kind` in Hugo. Whereas `my-first-post.md`, `my-second-post.md`, and `my-first-event.md` are all of kind `page`, all `_index.md` files in a Hugo project are used to add content and front matter to [list pages](/templates/lists/). In this example, `events/_index.md` will render according to its [section template](/templates/section-templates/) and respective lookup order. {{% /note %}} ### Example: `my-first-post.md` @@ -79,7 +79,7 @@ description: This is my first post. ``` {{% /code %}} -When it comes time for Hugo to render the content to the page, it will go through the single page template lookup order until it finds what it needs for `my-first-post.md`: +When building your site, Hugo will go through the lookup order until it finds what it needs for `my-first-post.md`: 1. ~~`/layouts/UNSPECIFIED/UNSPECIFIED.html`~~ 2. ~~`/layouts/posts/UNSPECIFIED.html`~~ diff --git a/content/templates/partials.md b/content/templates/partials.md index e8314abf6..d4e3d8f88 100644 --- a/content/templates/partials.md +++ b/content/templates/partials.md @@ -53,7 +53,7 @@ All partials are called within your templates using the following pattern: ``` {{% note %}} -One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Go Template Primer](/templates/go-templates/). +One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [templating introduction](/templates/introduction/). {{% /note %}} As shown in the above example directory structure, you can nest your directories within `partials` for better source organization. You only need to call the nested partial's path relative to the `partials` directory: @@ -160,7 +160,7 @@ The following `footer.html` partial template is used for [spf13.com](http://spf1 ``` {{% /code %}} -[context]: /templates/go-templates/ "The most easily overlooked concept to understand about Go templating is how the dot always refers to the current context." +[context]: /templates/introduction/ "The most easily overlooked concept to understand about Go templating is how the dot always refers to the current context." [customize]: /themes/customizing/ [disqus]: https://disqus.com [disqussignup]: https://disqus.com/profile/signup/ diff --git a/content/templates/rss.md b/content/templates/rss.md index d35b5cb9d..1d2c419ec 100644 --- a/content/templates/rss.md +++ b/content/templates/rss.md @@ -16,15 +16,15 @@ wip: true ## RSS Template Lookup Order -Like all other templates, you can use a single RSS template to generate all of your RSS feeds, or you can create a specific template for each individual feed. +You can use a single RSS template to generate all of your RSS feeds or create a specific template for each individual feed. 1. `/layouts/section/
.rss.xml` -2. `/layouts/\_default/rss.xml` +2. `/layouts/_default/rss.xml` 3. `/themes//layouts/section/
.rss.xml` -4. `/themes//layouts/\_default/rss.xml` +4. `/themes//layouts/_default/rss.xml` {{% note "Hugo Ships with an RSS Template" %}} -Unlike other Hugo templates, Hugo ships with its own [RSS 2.0 template](#the-embedded-rss-xml). The embedded template will be sufficient in most cases, and an RSS template will not need to be provided by the user. But you can provide an RSS template, as you can see in the next section. +Hugo ships with its own [RSS 2.0 template](#the-embedded-rss-xml). The embedded template will be sufficient for most use cases. {{% /note %}} RSS pages are of the type `Page` and have all the [page variables](/layout/variables/) available to use in the templates. @@ -41,7 +41,7 @@ Hugo provides the ability for you to define any RSS type you wish and can have d 1. `/layouts/rss.xml` 2. `/layouts/\_default/rss.xml` -3. [Embedded rss.xml][embedded] +3. Embedded rss.xml ### Section RSS @@ -49,7 +49,7 @@ Hugo provides the ability for you to define any RSS type you wish and can have d 2. `/layouts/\_default/rss.xml` 3. `/themes//layouts/section/
.rss.xml` 4. `/themes//layouts/\_default/rss.xml` -5. [Embedded rss.xml][embedded] +5. Embedded rss.xml ### Taxonomy RSS @@ -57,11 +57,13 @@ Hugo provides the ability for you to define any RSS type you wish and can have d 2. `/layouts/\_default/rss.xml` 3. `/themes//layouts/taxonomy/.rss.xml` 4. `/themes//layouts/\_default/rss.xml` -5. [Embedded rss.xml][embedded] +5. Embedded rss.xml ## Configuring RSS -Hugo's default behavior is to create an unlimited number of RSS entries. You can customize this behavior vi`rssLimit:` in your [`config`][config] file. The following values will also be included in the RSS output if specified in your site’s configuration: +By default, Hugo will create an unlimited number of RSS entries. You can limit this number via the `rssLimit:` field in your [`config` file](/getting-started/configuration). + +The following values will also be included in the RSS output if specified in your site’s configuration: ```toml languageCode = "en-us" diff --git a/content/templates/template-debugging.md b/content/templates/template-debugging.md index 7865c089c..e72600d1f 100644 --- a/content/templates/template-debugging.md +++ b/content/templates/template-debugging.md @@ -35,7 +35,7 @@ This will print out the value of `.Permalink`: This will print out a list of all the variables scoped to the current context -(`.`, aka ["the dot"][primer]). +(`.`, aka ["the dot"][tempintro]). ```html @@ -64,13 +64,13 @@ Check that you are passing variables in the `partial` function: {{ partial "header" }} ``` -This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example, note the addition of ["the dot"][primer]. +This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example, note the addition of ["the dot"][tempintro]. ```html {{ partial "header" . }} ``` -The dot (`.`) is considered fundamental to understanding Hugo templating. For more information, see the [Go Template Primer][primer]. +The dot (`.`) is considered fundamental to understanding Hugo templating. For more information, see [Introduction to Hugo Templating][tempintro]. [homepage]: /templates/homepage/ -[primer]: /templates/go-templates/ \ No newline at end of file +[tempintro]: /templates/introduction/ \ No newline at end of file diff --git a/content/themes/_index.md b/content/themes/_index.md index 6e2530510..b7ade8196 100644 --- a/content/themes/_index.md +++ b/content/themes/_index.md @@ -19,5 +19,5 @@ The Hugo community has created a large number of diverse themes, all of which ar Hugo themes are powered by the excellent Go template library. If you are new to Go templates, see our [primer on Go templates][goprimer] and are structured in such a way to eliminate code duplication. They are easy to simultaneously customize while retaining upgradability with the upstream theme. -[goprimer]: /templates/go-templates/ +[goprimer]: /templates/introduction/ [hugothemes]: http://themes.gohugo.io/ diff --git a/content/tutorials/creating-a-new-theme.md b/content/tutorials/creating-a-new-theme.md index 243343bf8..0ef66c7b8 100644 --- a/content/tutorials/creating-a-new-theme.md +++ b/content/tutorials/creating-a-new-theme.md @@ -815,7 +815,7 @@ $ vi themes/zafta/layouts/index.html #### Engine Hugo uses the [Go language's template -engine](https://gohugo.io/templates/go-templates/). +engine](https://gohugo.io/templates/introduction/). That engine scans your template files for commands enclosed between "{{" and "}}" (these are doubled, curly braces — affectionately known as "mustaches"). diff --git a/content/variables/_index.md b/content/variables/_index.md index ff29af9c7..4b61f1faf 100644 --- a/content/variables/_index.md +++ b/content/variables/_index.md @@ -15,4 +15,4 @@ toc: false Hugo's templates are context aware and make a large number of values available to you as you're creating views for your website. -[Go templates]: /templates/go-templates/ "Understand context in Go templates by learning the language's fundamental templating functions." \ No newline at end of file +[Go templates]: /templates/introduction/ "Understand context in Go templates by learning the language's fundamental templating functions." \ No newline at end of file