TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-19 11:34:44 -04:00
Code Issues Packages Projects Releases Wiki Activity

Add admonition note for Snap users in install docs

Browse Source
This commit is contained in:
Ryan Watters 2017-03-10 16:18:34 -06:00
parent b841193d49
commit 2a011b7cff
13 changed files with 42 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
content/functions/range.md
View File

@ -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.

8
content/getting-started/installing.md
View File

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

2
content/templates/alternatives.md
View File

@ -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/

2
content/templates/base.md
View File

@ -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.

13
content/templates/homepage.md
View File

@ -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/<THEME>/layouts/index.html`
5. `/themes/<THEME>/layouts/_default/list.html`
6. `/themes/<THEME>/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

6
content/templates/go-templates.md → content/templates/introduction.md
View File

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

10
content/templates/lookup-order.md
View File

@ -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`~~

4
content/templates/partials.md
View File

@ -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/

18
content/templates/rss.md
View File

@ -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/<section>.rss.xml`
2. `/layouts/\_default/rss.xml`
2. `/layouts/_default/rss.xml`
3. `/themes/<theme>/layouts/section/<section>.rss.xml`
4. `/themes/<theme>/layouts/\_default/rss.xml`
4. `/themes/<theme>/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/<THEME>/layouts/section/<SECTION>.rss.xml`
4. `/themes/<THEME>/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/<THEME>/layouts/taxonomy/<SINGULAR>.rss.xml`
4. `/themes/<THEME>/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"

8
content/templates/template-debugging.md
View File

@ -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/
[tempintro]: /templates/introduction/

2
content/themes/_index.md
View File

@ -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/

2
content/tutorials/creating-a-new-theme.md
View File

@ -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 &mdash; affectionately
known as "mustaches").

2
content/variables/_index.md
View File

@ -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."
[Go templates]: /templates/introduction/ "Understand context in Go templates by learning the language's fundamental templating functions."