mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-20 21:31:32 +02:00
Merge commit 'f96384a3b596f9bc0a3a035970b09b2c601f0ccb'
This commit is contained in:
Bjørn Erik Pedersen
@@ -2,18 +2,13 @@
|
||||
title: Custom 404 Page
|
||||
linktitle: 404 Page
|
||||
description: If you know how to create a single page template, you have unlimited options for creating a custom 404.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [404, page not found]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 120
|
||||
weight: 120 #rem
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: false
|
||||
weight: 120
|
||||
---
|
||||
|
||||
When using Hugo with [GitHub Pages](https://pages.github.com/), you can provide your own template for a [custom 404 error page](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site) by creating a 404.html template file in the root of your `layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root.
|
||||
@@ -31,13 +26,13 @@ In addition to the standard page variables, the 404 page has access to all site
|
||||
|
||||
This is a basic example of a 404.html template:
|
||||
|
||||
{{< code file="layouts/404.html" download="404.html" >}}
|
||||
{{ define "main"}}
|
||||
<main id="main">
|
||||
<div>
|
||||
<h1 id="title"><a href="{{ "" | relURL }}">Go Home</a></h1>
|
||||
</div>
|
||||
</main>
|
||||
{{< code file="layouts/404.html" >}}
|
||||
{{ define "main" }}
|
||||
<main id="main">
|
||||
<div>
|
||||
<h1 id="title"><a href="{{ "" | relURL }}">Go Home</a></h1>
|
||||
</div>
|
||||
</main>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
@@ -45,7 +40,7 @@ This is a basic example of a 404.html template:
|
||||
|
||||
Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example:
|
||||
|
||||
* [GitHub Pages](/hosting-and-deployment/hosting-on-github/) and [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/). The 404 page is automatic.
|
||||
* [GitHub Pages](/hosting-and-deployment/hosting-on-github/), [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/) and [Cloudflare Pages](/hosting-and-deployment/hosting-on-cloudflare-pages/). The 404 page is automatic.
|
||||
* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site.
|
||||
* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. [Details here](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
|
||||
* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI.
|
||||
@@ -57,10 +52,4 @@ Your 404.html file can be set to load automatically when a visitor enters a mist
|
||||
* DigitalOcean App Platform. You can specify `error_document` in your app specification file or use control panel to set up error document. [Details here](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site).
|
||||
* [Firebase Hosting](https://firebase.google.com/docs/hosting/full-config#404): `/404.html` automatically gets used as the 404 page.
|
||||
|
||||
{{% note %}}
|
||||
`hugo server` will not automatically load your custom `404.html` file, but you
|
||||
can test the appearance of your custom "not found" page by navigating your
|
||||
browser to `/404.html`.
|
||||
{{% /note %}}
|
||||
|
||||
[pagevars]: /variables/page/
|
||||
|
||||
@@ -2,18 +2,12 @@
|
||||
title: Templates
|
||||
linktitle: Templates Overview
|
||||
description: Go templating, template types and lookup order, shortcodes, and data.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 01
|
||||
weight: 01 #rem
|
||||
weight: 01
|
||||
categories: [templates]
|
||||
keywords: []
|
||||
draft: false
|
||||
aliases: [/templates/overview/,/templates/content]
|
||||
toc: false
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
@@ -1,18 +1,13 @@
|
||||
---
|
||||
title: Base Templates and Blocks
|
||||
linktitle:
|
||||
description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page).
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
categories: [templates,fundamentals]
|
||||
keywords: [blocks,base]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 20
|
||||
weight: 20
|
||||
sections_weight: 20
|
||||
draft: false
|
||||
aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
|
||||
toc: true
|
||||
---
|
||||
@@ -31,7 +26,7 @@ See [Template Lookup Order](/templates/lookup-order/) for details and examples.
|
||||
|
||||
The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order.
|
||||
|
||||
{{< code file="layouts/_default/baseof.html" download="baseof.html" >}}
|
||||
{{< code file="layouts/_default/baseof.html" >}}
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
@@ -57,7 +52,7 @@ The following defines a simple base template at `_default/baseof.html`. As a def
|
||||
|
||||
From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
|
||||
|
||||
{{< code file="layouts/_default/list.html" download="list.html" >}}
|
||||
{{< code file="layouts/_default/list.html" >}}
|
||||
{{ define "main" }}
|
||||
<h1>Posts</h1>
|
||||
{{ range .Pages }}
|
||||
@@ -71,7 +66,7 @@ From the above base template, you can define a [default list template][hugolists
|
||||
|
||||
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.
|
||||
|
||||
{{% warning %}}
|
||||
{{% note %}}
|
||||
Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
|
||||
|
||||
```go-html-template
|
||||
@@ -81,13 +76,13 @@ Code that you put outside the block definitions *can* break your layout. This ev
|
||||
{{ end }}
|
||||
```
|
||||
[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6)
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]:
|
||||
|
||||
{{< code file="layouts/_default/single.html" download="single.html" >}}
|
||||
{{< code file="layouts/_default/single.html" >}}
|
||||
{{ define "title" }}
|
||||
<!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example-->
|
||||
<!-- This will override the default value set in baseof.html; i.e., "{{ .Site.Title }}" in the original example-->
|
||||
{{ .Title }} – {{ .Site.Title }}
|
||||
{{ end }}
|
||||
{{ define "main" }}
|
||||
|
||||
@@ -1,17 +1,13 @@
|
||||
---
|
||||
title: Data Templates
|
||||
linktitle:
|
||||
description: In addition to Hugo's built-in variables, you can specify your own custom data in templates or shortcodes that pull from both local and dynamic sources.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [data,dynamic,csv,json,toml,yaml,xml]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 80
|
||||
weight: 80
|
||||
sections_weight: 80
|
||||
aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/]
|
||||
toc: true
|
||||
---
|
||||
@@ -52,7 +48,7 @@ Data file|Template code
|
||||
|
||||
## Data Files in Themes
|
||||
|
||||
Data Files can also be used in [Hugo themes][themes].
|
||||
Data Files can also be used in themes.
|
||||
|
||||
However, note that the theme data files are merged with the project directory taking precedence. That is, Given two files with the same name and relative path, the data in the file in the root project `data` directory will override the data from the file in the `themes/<THEME>/data` directory *for keys that are duplicated*).
|
||||
|
||||
@@ -131,7 +127,7 @@ Achievements:
|
||||
You can use the following code to render the `Short Description` in your layout:
|
||||
|
||||
```go-html-template
|
||||
<div>Short Description of {{.Site.Data.User0123.Name}}: <p>{{ index .Site.Data.User0123 "Short Description" | markdownify }}</p></div>
|
||||
<div>Short Description of {{ .Site.Data.User0123.Name }}: <p>{{ index .Site.Data.User0123 "Short Description" | markdownify }}</p></div>
|
||||
```
|
||||
|
||||
Note the use of the [`markdownify` template function][markdownify]. This will send the description through the Markdown rendering engine.
|
||||
@@ -173,13 +169,13 @@ This will resolve internally to the following:
|
||||
Both `getJSON` and `getCSV` takes an optional map as the last argument, e.g.:
|
||||
|
||||
```go-html-template
|
||||
{{ $data := getJSON "https://example.org/api" (dict "Authorization" "Bearer abcd") }}
|
||||
{{ $data := getJSON "https://example.org/api" (dict "Authorization" "Bearer abcd") }}
|
||||
```
|
||||
|
||||
If you need multiple values for the same header key, use a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $data := getJSON "https://example.org/api" (dict "X-List" (slice "a" "b" "c")) }}
|
||||
{{ $data := getJSON "https://example.org/api" (dict "X-List" (slice "a" "b" "c")) }}
|
||||
```
|
||||
|
||||
### Example for CSV files
|
||||
@@ -209,7 +205,7 @@ For `getCSV`, the one-character-long separator must be placed in the first posit
|
||||
</table>
|
||||
{{< /code >}}
|
||||
|
||||
The expression `{{index $r number}}` must be used to output the nth-column from the current row.
|
||||
The expression `{{ index $r number }}` must be used to output the nth-column from the current row.
|
||||
|
||||
### Cache URLs
|
||||
|
||||
@@ -241,7 +237,7 @@ There is no chance to trigger a [LiveReload] when the content of a URL changes.
|
||||
|
||||
{{% warning "URL Data and LiveReload" %}}
|
||||
If you change any local file and the LiveReload is triggered, Hugo will read the data-driven (URL) content from the cache. If you have disabled the cache (i.e., by running the server with `hugo server --ignoreCache`), Hugo will re-download the content every time LiveReload triggers. This can create *huge* traffic. You may reach API limits quickly.
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
## Examples of Data-driven Content
|
||||
|
||||
@@ -258,14 +254,13 @@ If you change any local file and the LiveReload is triggered, Hugo will read the
|
||||
|
||||
[config]: /getting-started/configuration/
|
||||
[csv]: https://tools.ietf.org/html/rfc4180
|
||||
[customize]: /themes/customizing/
|
||||
[customize]: /hugo-modules/theme-components/
|
||||
[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
|
||||
[LiveReload]: /getting-started/usage/#livereload
|
||||
[lookup]: /templates/lookup-order/
|
||||
[markdownify]: /functions/markdownify/
|
||||
[OAuth]: https://en.wikipedia.org/wiki/OAuth
|
||||
[partials]: /templates/partials/
|
||||
[themes]: /themes/
|
||||
[toml]: https://github.com/toml-lang/toml
|
||||
[variadic]: https://en.wikipedia.org/wiki/Variadic_function
|
||||
[vars]: /variables/
|
||||
|
||||
@@ -1,19 +1,13 @@
|
||||
---
|
||||
title: Local File Templates
|
||||
linktitle: Local File Templates
|
||||
description: Hugo's `readDir` and `readFile` functions make it easy to traverse your project's directory structure and write file contents to your templates.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [files,directories]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 110
|
||||
weight: 110
|
||||
sections_weight: 110
|
||||
draft: false
|
||||
aliases: [/extras/localfiles/,/templates/local-files/]
|
||||
toc: true
|
||||
---
|
||||
@@ -49,12 +43,11 @@ As `readFile` is a function, it is only available to you in your templates and n
|
||||
{{</* readfile file="/path/to/local/file.txt" markdown="true" */>}}
|
||||
```
|
||||
|
||||
{{% warning %}}
|
||||
{{% note %}}
|
||||
If you are going to create [custom shortcodes](/templates/shortcode-templates/) with `readFile` for a theme, note that usage of the shortcode will refer to the project root and *not* your `themes` directory.
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
[called directly in the Hugo docs]: https://github.com/gohugoio/hugoDocs/blob/master/content/en/templates/files.md
|
||||
[dirindex]: https://github.com/gohugoio/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html
|
||||
[osfileinfo]: https://golang.org/pkg/os/#FileInfo
|
||||
[readDir]: /functions/readdir/
|
||||
[readFile]: /functions/readfile/
|
||||
|
||||
@@ -2,25 +2,20 @@
|
||||
title: Homepage Template
|
||||
linktitle: Homepage Template
|
||||
description: The homepage of a website is often formatted differently than the other pages. For this reason, Hugo makes it easy for you to define your new site's homepage as a unique template.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [homepage]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 30
|
||||
weight: 30
|
||||
sections_weight: 30
|
||||
draft: false
|
||||
aliases: [/layout/homepage/,/templates/homepage-template/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use.
|
||||
|
||||
{{% note "The Only Required Template" %}}
|
||||
{{% note %}}
|
||||
The homepage template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website.
|
||||
{{% /note %}}
|
||||
|
||||
@@ -38,27 +33,27 @@ See the homepage template below or [Content Organization][contentorg] for more i
|
||||
|
||||
## Example Homepage Template
|
||||
|
||||
The following is an example of a homepage template that uses [partial][partials], [base] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{.Content}}` [page variables][pagevars].
|
||||
The following is an example of a homepage template that uses [partial][partials], [base] templates, and a content file at `content/_index.md` to populate the `{{ .Title }}` and `{{ .Content }}` [page variables][pagevars].
|
||||
|
||||
{{< code file="layouts/index.html" download="index.html" >}}
|
||||
{{< code file="layouts/index.html" >}}
|
||||
{{ define "main" }}
|
||||
<main aria-role="main">
|
||||
<header class="homepage-header">
|
||||
<h1>{{.Title}}</h1>
|
||||
{{ with .Params.subtitle }}
|
||||
<span class="subtitle">{{.}}</span>
|
||||
{{ end }}
|
||||
</header>
|
||||
<div class="homepage-content">
|
||||
<!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
|
||||
{{.Content}}
|
||||
</div>
|
||||
<div>
|
||||
{{ range first 10 .Site.RegularPages }}
|
||||
{{ .Render "summary"}}
|
||||
{{ end }}
|
||||
</div>
|
||||
</main>
|
||||
<main aria-role="main">
|
||||
<header class="homepage-header">
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ with .Params.subtitle }}
|
||||
<span class="subtitle">{{ . }}</span>
|
||||
{{ end }}
|
||||
</header>
|
||||
<div class="homepage-content">
|
||||
<!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
|
||||
{{ .Content }}
|
||||
</div>
|
||||
<div>
|
||||
{{ range first 10 .Site.RegularPages }}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
</div>
|
||||
</main>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
@@ -1,29 +1,21 @@
|
||||
---
|
||||
title: Internal Templates
|
||||
linktitle: Internal Templates
|
||||
description: Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites.
|
||||
date: 2017-03-06
|
||||
publishdate: 2017-03-06
|
||||
lastmod: 2017-03-06
|
||||
categories: [templates]
|
||||
keywords: [internal, analytics,]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 168
|
||||
weight: 168
|
||||
sections_weight: 168
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: true
|
||||
wip: true
|
||||
---
|
||||
<!-- reference: https://discourse.gohugo.io/t/lookup-order-for-partials/5705/6
|
||||
code: https://github.com/gohugoio/hugo/blob/e445c35d6a0c7f5fc2f90f31226cd1d46e048bbc/tpl/template_embedded.go#L147 -->
|
||||
|
||||
{{% warning %}}
|
||||
{{% note %}}
|
||||
While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order.
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
## Google Analytics
|
||||
|
||||
@@ -98,7 +90,7 @@ Users have noticed that enabling Disqus comments when running the Hugo web serve
|
||||
|
||||
You can create the following `layouts/partials/disqus.html`:
|
||||
|
||||
{{< code file="layouts/partials/disqus.html" download="disqus.html" >}}
|
||||
{{< code file="layouts/partials/disqus.html" >}}
|
||||
<div id="disqus_thread"></div>
|
||||
<script type="text/javascript">
|
||||
|
||||
|
||||
@@ -2,18 +2,13 @@
|
||||
title: Introduction to Hugo Templating
|
||||
linktitle: Templating
|
||||
description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2022-09-20
|
||||
categories: [templates,fundamentals]
|
||||
keywords: [go]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 10
|
||||
weight: 10
|
||||
sections_weight: 10
|
||||
draft: false
|
||||
aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/]
|
||||
toc: true
|
||||
---
|
||||
@@ -31,8 +26,7 @@ Go Templates are HTML files with the addition of [variables][variables] and [fun
|
||||
### Access a Predefined Variable
|
||||
|
||||
A _predefined variable_ could be a variable already existing in the
|
||||
current scope (like the `.Title` example in the [Variables]({{< relref
|
||||
"#variables" >}}) section below) or a custom variable (like the
|
||||
current scope (like the `.Title` example in the [Variables](#variables) section below) or a custom variable (like the
|
||||
`$address` example in that same section).
|
||||
|
||||
|
||||
@@ -142,7 +136,7 @@ Go Templates only ship with a few basic functions but also provide a mechanism f
|
||||
|
||||
Note that both examples make use of Go Template's [math][math] functions.
|
||||
|
||||
{{% note "Additional Boolean Operators" %}}
|
||||
{{% note %}}
|
||||
There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](https://golang.org/pkg/text/template/#hdr-Functions).
|
||||
{{% /note %}}
|
||||
|
||||
@@ -242,7 +236,7 @@ If the _map_, _array_, or _slice_ passed into the range is zero-length then the
|
||||
```go-html-template
|
||||
{{ range $array }}
|
||||
{{ . }}
|
||||
{{else}}
|
||||
{{ else }}
|
||||
<!-- This is only evaluated if $array is empty -->
|
||||
{{ end }}
|
||||
```
|
||||
@@ -415,7 +409,7 @@ The following shows how to define a variable independent of the context.
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well.
|
||||
Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside the loop (`{{ $title }}`) that we've assigned a value so that we have access to the value from within the loop as well.
|
||||
{{% /note %}}
|
||||
|
||||
### 2. Use `$.` to Access the Global Context
|
||||
@@ -435,7 +429,7 @@ Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}`
|
||||
|
||||
{{% warning "Don't Redefine the Dot" %}}
|
||||
The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value.
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
## Whitespace
|
||||
|
||||
@@ -529,7 +523,7 @@ The templating engine will strip the content within the HTML comment, but will f
|
||||
|
||||
## Hugo Parameters
|
||||
|
||||
Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the [front matter format]({{< ref "front-matter.md#front-matter-formats" >}}).
|
||||
Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the [front matter format](/content-management/front-matter#front-matter-formats).
|
||||
|
||||
## Use Content (`Page`) Parameters
|
||||
|
||||
@@ -537,28 +531,24 @@ You can provide variables to be used by templates in individual content's [front
|
||||
|
||||
An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`.
|
||||
|
||||
Here is the example front matter (YAML):
|
||||
Here is the example front matter:
|
||||
|
||||
```yml
|
||||
---
|
||||
title: Roadmap
|
||||
lastmod: 2017-03-05
|
||||
date: 2013-11-18
|
||||
{{< code-toggle file="content/example.md" fm=true copy=false >}}
|
||||
title: Example
|
||||
notoc: true
|
||||
---
|
||||
```
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]:
|
||||
|
||||
{{< code file="layouts/partials/toc.html" download="toc.html" >}}
|
||||
{{< code file="layouts/partials/toc.html" >}}
|
||||
{{ if not .Params.notoc }}
|
||||
<aside>
|
||||
<header>
|
||||
<a href="#{{.Title | urlize}}">
|
||||
<h3>{{.Title}}</h3>
|
||||
<a href="#{{ .Title | urlize }}">
|
||||
<h3>{{ .Title }}</h3>
|
||||
</a>
|
||||
</header>
|
||||
{{.TableOfContents}}
|
||||
{{ .TableOfContents }}
|
||||
</aside>
|
||||
<a href="#" id="toc-toggle"></a>
|
||||
{{ end }}
|
||||
@@ -584,7 +574,7 @@ Within a footer layout, you might then declare a `<footer>` that is only rendere
|
||||
```go-html-template
|
||||
{{ if .Site.Params.copyrighthtml }}
|
||||
<footer>
|
||||
<div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div>
|
||||
<div class="text-center">{{ .Site.Params.CopyrightHTML | safeHTML }}</div>
|
||||
</footer>
|
||||
{{ end }}
|
||||
```
|
||||
@@ -594,8 +584,8 @@ An alternative way of writing the "`if`" and then referencing the same value is
|
||||
{{< code file="layouts/partials/twitter.html" >}}
|
||||
{{ with .Site.Params.twitteruser }}
|
||||
<div>
|
||||
<a href="https://twitter.com/{{.}}" rel="author">
|
||||
<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" alt="Twitter"></a>
|
||||
<a href="https://twitter.com/{{ . }}" rel="author">
|
||||
<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{ . }}" alt="Twitter"></a>
|
||||
</div>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
@@ -607,7 +597,7 @@ Finally, you can pull "magic constants" out of your layouts as well. The followi
|
||||
<h1>Recent Posts</h1>
|
||||
<ul>
|
||||
{{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}}
|
||||
<li><a href="{{.RelPermalink}}">{{.Title}}</a></li>
|
||||
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
|
||||
{{- end -}}
|
||||
</ul>
|
||||
</nav>
|
||||
@@ -625,7 +615,7 @@ content/
|
||||
└── event-3.md
|
||||
```
|
||||
|
||||
{{< code-toggle file="content/events/event-1.md" copy="false" >}}
|
||||
{{< code-toggle file="content/events/event-1.md" copy=false >}}
|
||||
title = 'Event 1'
|
||||
date = 2021-12-06T10:37:16-08:00
|
||||
draft = false
|
||||
@@ -663,19 +653,19 @@ If you restrict front matter to the TOML format, and omit quotation marks surrou
|
||||
</ul>
|
||||
{{< /code >}}
|
||||
|
||||
[config]: {{< relref "getting-started/configuration" >}}
|
||||
[dotdoc]: https://golang.org/pkg/text/template/#hdr-Variables
|
||||
[first]: {{< relref "functions/first" >}}
|
||||
[front matter]: {{< relref "content-management/front-matter" >}}
|
||||
[functions]: {{< relref "functions" >}}
|
||||
[internal templates]: {{< relref "templates/internal" >}}
|
||||
[isset]: {{< relref "functions/isset" >}}
|
||||
[math]: {{< relref "functions/math" >}}
|
||||
[pagevars]: {{< relref "variables/page" >}}
|
||||
[param]: {{< relref "functions/param" >}}
|
||||
[partials]: {{< relref "templates/partials" >}}
|
||||
[relpermalink]: {{< relref "variables/page#page-variables" >}}
|
||||
[safehtml]: {{< relref "functions/safehtml" >}}
|
||||
[sitevars]: {{< relref "variables/site" >}}
|
||||
[variables]: {{< relref "variables" >}}
|
||||
[with]: {{< relref "functions/with" >}}
|
||||
[config]: /getting-started/configuration
|
||||
[first]: /functions/first
|
||||
[front matter]: /content-management/front-matter
|
||||
[functions]: /functions
|
||||
[internal templates]: /templates/internal
|
||||
[isset]: /functions/isset
|
||||
[math]: /functions/math
|
||||
[pagevars]: /variables/page
|
||||
[param]: /functions/param
|
||||
[partials]: /templates/partials
|
||||
[relpermalink]: /variables/page#page-variables
|
||||
[safehtml]: /functions/safehtml
|
||||
[sitevars]: /variables/site
|
||||
[variables]: /variables
|
||||
[with]: /functions/with
|
||||
|
||||
@@ -2,18 +2,13 @@
|
||||
title: Lists of Content in Hugo
|
||||
linktitle: List Templates
|
||||
description: Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [lists,sections,rss,taxonomies,terms]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 22
|
||||
weight: 22
|
||||
sections_weight: 22
|
||||
draft: false
|
||||
aliases: [/templates/list/,/layout/indexes/]
|
||||
toc: true
|
||||
---
|
||||
@@ -35,7 +30,7 @@ For template lookup order, see [Template Lookup](/templates/lookup-order/).
|
||||
|
||||
The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually:
|
||||
|
||||
[](/images/site-hierarchy.svg)
|
||||
[](site-hierarchy.svg)
|
||||
|
||||
## List Defaults
|
||||
|
||||
@@ -89,31 +84,31 @@ Follow my journey through this new blog.
|
||||
|
||||
You can now access this `_index.md`'s' content in your list template:
|
||||
|
||||
{{< code file="layouts/_default/list.html" download="list.html" >}}
|
||||
{{< code file="layouts/_default/list.html" >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
<article>
|
||||
<header>
|
||||
<h1>{{.Title}}</h1>
|
||||
</header>
|
||||
<!-- "{{.Content}}" pulls from the markdown content of the corresponding _index.md -->
|
||||
{{.Content}}
|
||||
</article>
|
||||
<ul>
|
||||
<article>
|
||||
<header>
|
||||
<h1>{{ .Title} }</h1>
|
||||
</header>
|
||||
<!-- "{{ .Content} }" pulls from the markdown content of the corresponding _index.md -->
|
||||
{{ .Content }}
|
||||
</article>
|
||||
<ul>
|
||||
<!-- Ranges through content/posts/*.md -->
|
||||
{{ range .Pages }}
|
||||
<li>
|
||||
<a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Date.Format "2006-01-02" }} | {{ .Title }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
</ul>
|
||||
</main>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
This above will output the following HTML:
|
||||
|
||||
{{< code file="example.com/posts/index.html" copy="false" >}}
|
||||
{{< code file="example.com/posts/index.html" copy=false >}}
|
||||
<!--top of your baseof code-->
|
||||
<main>
|
||||
<article>
|
||||
@@ -133,11 +128,11 @@ This above will output the following HTML:
|
||||
|
||||
### List Pages Without `_index.md`
|
||||
|
||||
You do *not* have to create an `_index.md` file for every list page (i.e. section, taxonomy, taxonomy terms, etc) or the homepage. If Hugo does not find an `_index.md` within the respective content section when rendering a list template, the page will be created but with no `{{.Content}}` and only the default values for `.Title` etc.
|
||||
You do *not* have to create an `_index.md` file for every list page (i.e. section, taxonomy, taxonomy terms, etc) or the homepage. If Hugo does not find an `_index.md` within the respective content section when rendering a list template, the page will be created but with no `{{ .Content }}` and only the default values for `.Title` etc.
|
||||
|
||||
Using this same `layouts/_default/list.html` template and applying it to the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from:
|
||||
|
||||
{{< code file="example.com/quote/index.html" copy="false" >}}
|
||||
{{< code file="example.com/quote/index.html" copy=false >}}
|
||||
<!--baseof-->
|
||||
<main>
|
||||
<article>
|
||||
@@ -173,7 +168,7 @@ This list template has been modified slightly from a template originally used in
|
||||
<ul>
|
||||
<!-- Renders the li.html content view for each content/posts/*.md -->
|
||||
{{ range .Pages }}
|
||||
{{ .Render "li"}}
|
||||
{{ .Render "li" }}
|
||||
{{ end }}
|
||||
</ul>
|
||||
</div>
|
||||
@@ -183,14 +178,14 @@ This list template has been modified slightly from a template originally used in
|
||||
|
||||
### Taxonomy Template
|
||||
|
||||
{{< code file="layouts/_default/taxonomy.html" download="taxonomy.html" >}}
|
||||
{{< code file="layouts/_default/taxonomy.html" >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
<div>
|
||||
<h1>{{ .Title }}</h1>
|
||||
<!-- ranges through each of the content files associated with a particular taxonomy term and renders the summary.html content view -->
|
||||
{{ range .Pages }}
|
||||
{{ .Render "summary"}}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
</div>
|
||||
</main>
|
||||
@@ -381,14 +376,14 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
In the above example, you may want `{{.Title}}` to point the `title` field you have added to your `_index.md` file instead. You can access this value using the [`.GetPage` function][getpage]:
|
||||
In the above example, you may want `{{ .Title }}` to point the `title` field you have added to your `_index.md` file instead. You can access this value using the [`.GetPage` function][getpage]:
|
||||
|
||||
{{< code file="layouts/partials/by-page-field.html" >}}
|
||||
<!-- Groups content according to content section.-->
|
||||
{{ range .Pages.GroupBy "Section" }}
|
||||
<!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter -->
|
||||
{{ with $.Site.GetPage "section" .Key }}
|
||||
<h3>{{.Title}}</h3>
|
||||
<h3>{{ .Title }}</h3>
|
||||
{{ else }}
|
||||
<!-- If no _index.md is available, ".Key" defaults to the section title and filters to title casing -->
|
||||
<h3>{{ .Key | title }}</h3>
|
||||
@@ -544,7 +539,7 @@ While these are logical defaults, they are not always the desired order. There a
|
||||
|
||||
### Order Within Groups
|
||||
|
||||
Because Grouping returns a `{{.Key}}` and a slice of pages, all the ordering methods listed above are available.
|
||||
Because Grouping returns a `{{ .Key }}` and a slice of pages, all the ordering methods listed above are available.
|
||||
|
||||
Here is the ordering for the example that follows:
|
||||
|
||||
1
docs/content/en/templates/lists/site-hierarchy.svg
Normal file
1
docs/content/en/templates/lists/site-hierarchy.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 193 KiB |
@@ -2,21 +2,14 @@
|
||||
title: Hugo's Lookup Order
|
||||
linktitle: Template Lookup Order
|
||||
description: Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-07-05
|
||||
categories: [templates,fundamentals]
|
||||
keywords: [templates]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 15
|
||||
quicklinks:
|
||||
weight: 15
|
||||
sections_weight: 15
|
||||
draft: false
|
||||
aliases: [/templates/lookup/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Hugo Layouts Lookup Rules
|
||||
|
||||
@@ -1,183 +1,126 @@
|
||||
---
|
||||
title: Menu Templates
|
||||
linktitle: Menu Templates
|
||||
description: Menus are a powerful but simple feature for content management but can be easily manipulated in your templates to meet your design needs.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
description: Use menu variables and methods in your templates to render a menu.
|
||||
categories: [templates]
|
||||
keywords: [lists,sections,menus]
|
||||
menu:
|
||||
docs:
|
||||
title: "how to use menus in templates"
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 130
|
||||
toc: true
|
||||
weight: 130
|
||||
sections_weight: 130
|
||||
draft: false
|
||||
aliases: [/templates/menus/]
|
||||
toc: false
|
||||
---
|
||||
|
||||
Hugo makes no assumptions about how your rendered HTML will be
|
||||
structured. Instead, it provides all the functions you will need to
|
||||
build your menu however you want.
|
||||
## Overview
|
||||
|
||||
The following is an example:
|
||||
After [defining menu entries], use [menu variables and methods] to render a menu.
|
||||
|
||||
{{< code file="layouts/partials/sidebar.html" download="sidebar.html" >}}
|
||||
<!-- sidebar start -->
|
||||
<aside>
|
||||
Three factors determine how to render a menu:
|
||||
|
||||
1. The method used to define the menu entries: [automatic], [in front matter], or [in site configuration]
|
||||
1. The menu structure: flat or nested
|
||||
1. The method used to [localize the menu entries]: site configuration or translation tables
|
||||
|
||||
The example below handles every combination.
|
||||
|
||||
## Example
|
||||
|
||||
This partial template recursively "walks" a menu structure, rendering a localized, accessible nested list.
|
||||
|
||||
{{< code file="layouts/partials/menu.html" >}}
|
||||
{{- $page := .page }}
|
||||
{{- $menuID := .menuID }}
|
||||
|
||||
{{- with index site.Menus $menuID }}
|
||||
<nav>
|
||||
<ul>
|
||||
{{ $currentPage := . }}
|
||||
{{ range .Site.Menus.main }}
|
||||
{{ if .HasChildren }}
|
||||
<li class="{{ if $currentPage.HasMenuCurrent "main" . }}active{{ end }}">
|
||||
<a href="#">
|
||||
{{ .Pre }}
|
||||
<span>{{ .Name }}</span>
|
||||
</a>
|
||||
</li>
|
||||
<ul class="sub-menu">
|
||||
{{ range .Children }}
|
||||
<li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
|
||||
<a href="{{ .URL }}">{{ .Name }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ else }}
|
||||
<li>
|
||||
<a href="{{ .URL }}">
|
||||
{{ .Pre }}
|
||||
<span>{{ .Name }}</span>
|
||||
</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
<li>
|
||||
<a href="#" target="_blank">Hardcoded Link 1</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="#" target="_blank">Hardcoded Link 2</a>
|
||||
</li>
|
||||
{{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
|
||||
</ul>
|
||||
</aside>
|
||||
</nav>
|
||||
{{- end }}
|
||||
|
||||
{{- define "partials/inline/menu/walk.html" }}
|
||||
{{- $page := .page }}
|
||||
{{- range .menuEntries }}
|
||||
{{- $attrs := dict "href" .URL }}
|
||||
{{- if $page.IsMenuCurrent .Menu . }}
|
||||
{{- $attrs = merge $attrs (dict "class" "active" "aria-current" "page") }}
|
||||
{{- else if $page.HasMenuCurrent .Menu .}}
|
||||
{{- $attrs = merge $attrs (dict "class" "ancestor" "aria-current" "true") }}
|
||||
{{- end }}
|
||||
<li>
|
||||
<a
|
||||
{{- range $k, $v := $attrs }}
|
||||
{{- with $v }}
|
||||
{{- printf " %s=%q" $k $v | safeHTMLAttr }}
|
||||
{{- end }}
|
||||
{{- end -}}
|
||||
>{{ or (T .Identifier) .Name | safeHTML }}</a>
|
||||
{{- with .Children }}
|
||||
<ul>
|
||||
{{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
|
||||
</ul>
|
||||
{{- end }}
|
||||
</li>
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note "`absLangURL` and `relLangURL`" %}}
|
||||
Use the [`absLangURL`](/functions/abslangurl) or [`relLangURL`](/functions/rellangurl) functions if your theme makes use of the [multilingual feature](/content-management/multilingual/). In contrast to `absURL` and `relURL`, these two functions add the correct language prefix to the url.
|
||||
{{% /note %}}
|
||||
Call the partial above, passing a menu ID and the current page in context.
|
||||
|
||||
## Section Menu for Lazy Bloggers
|
||||
{{< code file="layouts/_default/single.html" >}}
|
||||
{{ partial "menu.html" (dict "menuID" "main" "page" .) }}
|
||||
{{ partial "menu.html" (dict "menuID" "footer" "page" .) }}
|
||||
{{< /code >}}
|
||||
|
||||
To enable this menu, configure `sectionPagesMenu` in your site `config`:
|
||||
## Page references
|
||||
|
||||
```yml
|
||||
sectionPagesMenu = "main"
|
||||
```
|
||||
Regardless of how you [define menu entries], an entry associated with a page has access to page variables and methods.
|
||||
|
||||
The menu name can be anything, but take a note of what it is.
|
||||
This simplistic example renders a page parameter named `version` next to each entry's `name`. Code defensively using `with` or `if` to handle entries where (a) the entry points to an external resource, or (b) the `version` parameter is not defined.
|
||||
|
||||
This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". Ensure that all first level directories that you would like to show up on this menu are [Branch Bundles](https://gohugo.io/content-management/sections/). Leaf Bundles do not form sections.
|
||||
{{< code file="layouts/_default/single.html" >}}
|
||||
{{- range site.Menus.main }}
|
||||
<a href="{{ .URL }}">
|
||||
{{ .Name }}
|
||||
{{- with .Page }}
|
||||
{{- with .Params.version -}}
|
||||
({{ . }})
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
</a>
|
||||
{{- end }}
|
||||
{{< /code >}}
|
||||
|
||||
The _shadow_ implies that the pages isn't represented by a menu-item themselves, but this enables you to create a top-level menu like this:
|
||||
## Menu entry parameters
|
||||
|
||||
```go-html-template
|
||||
<nav class="sidebar-nav">
|
||||
{{ $currentPage := . }}
|
||||
{{ range .Site.Menus.main }}
|
||||
<a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{ .URL }}" title="{{ .Title }}">{{ .Name }}</a>
|
||||
{{ end }}
|
||||
</nav>
|
||||
```
|
||||
When you define menu entries [in site configuration] or [in front matter], you can include a `params` key as shown in these examples:
|
||||
|
||||
In the above, the menu item is marked as active if on the current section's list page or on a page in that section.
|
||||
- [Menu entry defined in site configuration]
|
||||
- [Menu entry defined in front matter]
|
||||
|
||||
## Site Config menus
|
||||
This simplistic example renders a `class` attribute for each anchor element. Code defensively using `with` or `if` to handle entries where `params.class` is not defined.
|
||||
|
||||
The above is all that's needed. But if you want custom menu items, e.g. changing weight, name, or link title attribute, you can define them manually in the site config file:
|
||||
{{< code file="layouts/partials/menu.html" >}}
|
||||
{{- range site.Menus.main }}
|
||||
<a {{ with .Params.class -}} class="{{ . }}" {{ end -}} href="{{ .URL }}">
|
||||
{{ .Name }}
|
||||
</a>
|
||||
{{- end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{< code-toggle file="config" >}}
|
||||
[[menu.main]]
|
||||
name = "This is the blog section"
|
||||
title = "blog section"
|
||||
weight = -110
|
||||
identifier = "blog"
|
||||
url = "/blog/"
|
||||
{{</ code-toggle >}}
|
||||
## Localize
|
||||
|
||||
{{% note %}}
|
||||
The `identifier` *must* match the section name.
|
||||
{{% /note %}}
|
||||
Hugo provides two methods to localize your menu entries. See [multilingual].
|
||||
|
||||
## Menu Entries from the Page's front matter
|
||||
|
||||
It's also possible to create menu entries from the page (i.e. the `.md`-file).
|
||||
|
||||
Here is a `yaml` example:
|
||||
|
||||
```yml
|
||||
---
|
||||
title: Menu Templates
|
||||
linktitle: Menu Templates
|
||||
menu:
|
||||
docs:
|
||||
title: "how to use menus in templates"
|
||||
parent: "templates"
|
||||
weight: 130
|
||||
---
|
||||
...
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
You can define more than one menu. It also doesn't have to be a complex value,
|
||||
`menu` can also be a string, an array of strings, or an array of complex values
|
||||
like in the example above.
|
||||
{{% /note %}}
|
||||
|
||||
### Using .Page in Menus
|
||||
|
||||
If you use the front matter method of defining menu entries, you'll get access to the `.Page` variable.
|
||||
This allows to use every variable that's reachable from the [page variable](/variables/page/).
|
||||
|
||||
This variable is only set when the menu entry is defined in the page's front matter.
|
||||
Menu entries from the site config don't know anything about `.Page`.
|
||||
|
||||
That's why you have to use the go template's `with` keyword or something similar in your templating language.
|
||||
|
||||
Here's an example:
|
||||
|
||||
```go-html-template
|
||||
<nav class="sidebar-nav">
|
||||
{{ range .Site.Menus.main }}
|
||||
<a href="{{ .URL }}" title="{{ .Title }}">
|
||||
{{- .Name -}}
|
||||
{{- with .Page -}}
|
||||
<span class="date">
|
||||
{{- dateFormat " (2006-01-02)" .Date -}}
|
||||
</span>
|
||||
{{- end -}}
|
||||
</a>
|
||||
{{ end }}
|
||||
</nav>
|
||||
```
|
||||
|
||||
## Using .Params in Menus
|
||||
|
||||
User-defined content on menu items are accessible via `.Params`.
|
||||
|
||||
Here's an example:
|
||||
|
||||
```go-html-template
|
||||
<nav class="sidebar-nav">
|
||||
{{ range .Site.Menus.main }}
|
||||
<a href="{{ .URL }}" title="{{ .Title }}" class="{{ with .Params.class }}{{ . }}{{ end }}">
|
||||
{{- .Name -}}
|
||||
</a>
|
||||
{{ end }}
|
||||
</nav>
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
With Menu-level .Params they can easily exist on one menu item but not another. It's recommended to access them gracefully using the [with function](/functions/with).
|
||||
{{% /note %}}
|
||||
[automatic]: /content-management/menus/#define-automatically
|
||||
[define menu entries]: /content-management/menus/
|
||||
[defining menu entries]: /content-management/menus/
|
||||
[in front matter]: /content-management/menus/#define-in-front-matter
|
||||
[in site configuration]: /content-management/menus/#define-in-site-configuration
|
||||
[localize the menu entries]: /content-management/multilingual/#menus
|
||||
[menu entry defined in front matter]: /content-management/menus/#example-front-matter
|
||||
[menu entry defined in site configuration]: /content-management/menus/#example-site-configuration
|
||||
[menu variables and methods]: /variables/menus/
|
||||
[multilingual]: /content-management/multilingual/#menus
|
||||
|
||||
@@ -1,19 +1,13 @@
|
||||
---
|
||||
title: Custom Output Formats
|
||||
linktitle: Custom Output Formats
|
||||
description: Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format.
|
||||
date: 2017-03-22
|
||||
publishdate: 2017-03-22
|
||||
lastmod: 2019-12-11
|
||||
categories: [templates]
|
||||
keywords: ["amp", "outputs", "rss"]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 18
|
||||
weight: 18
|
||||
sections_weight: 18
|
||||
draft: false
|
||||
aliases: [/templates/outputs/,/extras/output-formats/,/content-management/custom-outputs/]
|
||||
toc: true
|
||||
---
|
||||
@@ -49,16 +43,16 @@ The above example adds one new media type, `text/enriched`, and changes the suff
|
||||
|
||||
**Note:** these media types are configured for **your output formats**. If you want to redefine one of Hugo's default output formats (e.g. `HTML`), you also need to redefine the media type. So, if you want to change the suffix of the `HTML` output format from `html` (default) to `htm`:
|
||||
|
||||
```toml
|
||||
{{< code-toggle file="config" >}}
|
||||
[mediaTypes]
|
||||
[mediaTypes."text/html"]
|
||||
suffixes = ["htm"]
|
||||
[mediaTypes."text/html"]
|
||||
suffixes = ["htm"]
|
||||
|
||||
# Redefine HTML to update its media type.
|
||||
[outputFormats]
|
||||
[outputFormats.HTML]
|
||||
mediaType = "text/html"
|
||||
```
|
||||
[outputFormats.HTML]
|
||||
mediaType = "text/html"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
**Note** that for the above to work, you also need to add an `outputs` definition in your site config.
|
||||
|
||||
@@ -168,17 +162,15 @@ Note that in the above examples, the _output formats_ for `section`,
|
||||
* These names are case insensitive.
|
||||
* These can be overridden per `Page` in the front matter of content files.
|
||||
|
||||
The following is an example of `YAML` front matter in a content file that defines output formats for the rendered `Page`:
|
||||
The following is an example of front matter in a content file that defines output formats for the rendered `Page`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
date: "2016-03-19"
|
||||
{{< code-toggle file="content/example.md" fm=true copy=false >}}
|
||||
title: Example
|
||||
outputs:
|
||||
- html
|
||||
- amp
|
||||
- json
|
||||
---
|
||||
```
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## List Output formats
|
||||
|
||||
@@ -251,7 +243,7 @@ The partial below is a plain text template (Output Format is `CSV`, and since th
|
||||
|
||||
[base]: /templates/base/
|
||||
[config]: /getting-started/configuration/
|
||||
[lookup order]: /templates/lookup/
|
||||
[lookup order]: /templates/lookup-order/
|
||||
[media type]: https://en.wikipedia.org/wiki/Media_type
|
||||
[partials]: /templates/partials/
|
||||
[page_kinds]: /templates/section-templates/#page-kinds
|
||||
|
||||
@@ -2,16 +2,13 @@
|
||||
title: Pagination
|
||||
linktitle: Pagination
|
||||
description: Hugo supports pagination for your homepage, section pages, and taxonomies.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [lists,sections,pagination]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 140
|
||||
weight: 140
|
||||
sections_weight: 140
|
||||
aliases: [/extras/pagination,/doc/pagination/]
|
||||
toc: true
|
||||
---
|
||||
@@ -34,9 +31,9 @@ Setting `paginate` to a positive value will split the list pages for the homepag
|
||||
|
||||
## List Paginator Pages
|
||||
|
||||
{{% warning %}}
|
||||
{{% note %}}
|
||||
`.Paginator` is provided to help you build a pager menu. This feature is currently only supported on homepage and list pages (i.e., taxonomies and section lists).
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
There are two ways to configure and use a `.Paginator`:
|
||||
|
||||
@@ -59,7 +56,7 @@ The global page size setting (`Paginate`) can be overridden by providing a posit
|
||||
It is also possible to use the `GroupBy` functions in combination with pagination:
|
||||
|
||||
```go-html-template
|
||||
{{ range (.Paginate (.Pages.GroupByDate "2006")).PageGroups }}
|
||||
{{ range (.Paginate (.Pages.GroupByDate "2006")).PageGroups }}
|
||||
```
|
||||
|
||||
## Build the navigation
|
||||
@@ -72,7 +69,7 @@ The easiest way to add this to your pages is to include the built-in template (w
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
```
|
||||
|
||||
{{% note "When to Create `.Paginator`" %}}
|
||||
{{% note %}}
|
||||
If you use any filters or ordering functions to create your `.Paginator` *and* you want the navigation buttons to be shown before the page listing, you must create the `.Paginator` before it's used.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
@@ -1,19 +1,13 @@
|
||||
---
|
||||
title: Partial Templates
|
||||
linktitle: Partial Templates
|
||||
description: Partials are smaller, context-aware components in your list and page templates that can be used economically to keep your templating DRY.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [lists,sections,partials]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 90
|
||||
weight: 90
|
||||
sections_weight: 90
|
||||
draft: false
|
||||
aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/]
|
||||
toc: true
|
||||
---
|
||||
@@ -160,7 +154,7 @@ Note that the variant parameters are not made available to the underlying partia
|
||||
|
||||
The following `header.html` partial template is used for [spf13.com](https://spf13.com/):
|
||||
|
||||
{{< code file="layouts/partials/header.html" download="header.html" >}}
|
||||
{{< code file="layouts/partials/header.html" >}}
|
||||
<!DOCTYPE html>
|
||||
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
|
||||
<head>
|
||||
@@ -185,7 +179,7 @@ The `header.html` example partial was built before the introduction of block tem
|
||||
|
||||
The following `footer.html` partial template is used for [spf13.com](https://spf13.com/):
|
||||
|
||||
{{< code file="layouts/partials/footer.html" download="footer.html" >}}
|
||||
{{< code file="layouts/partials/footer.html" >}}
|
||||
<footer>
|
||||
<div>
|
||||
<p>
|
||||
@@ -197,10 +191,10 @@ The following `footer.html` partial template is used for [spf13.com](https://spf
|
||||
</footer>
|
||||
{{< /code >}}
|
||||
|
||||
[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/ "Hugo provides easy means to customize themes as long as users are familiar with Hugo's template lookup order."
|
||||
[listtemps]: /templates/lists/ "To effectively leverage Hugo's system, see how Hugo handles list pages, where content for sections, taxonomies, and the homepage are listed and ordered."
|
||||
[lookup order]: /templates/lookup-order/ "To keep your templating dry, read the documentation on Hugo's lookup order."
|
||||
[partialcached]: /functions/partialcached/ "Use the partial cached function to improve build times in cases where Hugo can cache partials that don't need to be rendered with every page."
|
||||
[singletemps]: /templates/single-page-templates/ "The most common form of template in Hugo is the single content template. Read the docs on how to create templates for individual pages."
|
||||
[context]: /templates/introduction/
|
||||
[customize]: /hugo-modules/theme-components/
|
||||
[listtemps]: /templates/lists/
|
||||
[lookup order]: /templates/lookup-order/
|
||||
[partialcached]: /functions/partialcached/
|
||||
[singletemps]: /templates/single-page-templates/
|
||||
[themes]: /themes/
|
||||
|
||||
@@ -2,14 +2,12 @@
|
||||
title: "Markdown Render Hooks"
|
||||
linkTitle: "Render Hooks"
|
||||
description: "Render Hooks allow custom templates to override markdown rendering functionality."
|
||||
date: 2017-03-11
|
||||
categories: [templates]
|
||||
keywords: [markdown]
|
||||
toc: true
|
||||
menu:
|
||||
docs:
|
||||
title: "Markdown Render Hooks"
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 20
|
||||
---
|
||||
|
||||
@@ -49,6 +47,8 @@ Some use cases for the above:
|
||||
|
||||
## Render Hooks for Headings, Links and Images
|
||||
|
||||
### Context passed to `render-link` and `render-image`
|
||||
|
||||
The `render-link` and `render-image` templates will receive this context:
|
||||
|
||||
Page
|
||||
@@ -66,6 +66,8 @@ Text
|
||||
PlainText
|
||||
: The plain variant of the above.
|
||||
|
||||
### Context passed to `render-heading`
|
||||
|
||||
The `render-heading` template will receive this context:
|
||||
|
||||
Page
|
||||
@@ -104,7 +106,7 @@ Ordinal {{< new-in "0.108.0" >}}
|
||||
Here is a code example for how the render-link.html template could look:
|
||||
|
||||
{{< code file="layouts/_default/_markup/render-link.html" >}}
|
||||
<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>
|
||||
<a href="{{ .Destination | safeURL }}"{{ with .Title }} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>
|
||||
{{< /code >}}
|
||||
|
||||
### Image Markdown example
|
||||
@@ -117,7 +119,7 @@ Here is a code example for how the render-image.html template could look:
|
||||
|
||||
{{< code file="layouts/_default/_markup/render-image.html" >}}
|
||||
<p class="md__image">
|
||||
<img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />
|
||||
<img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title }} title="{{ . }}"{{ end }} />
|
||||
</p>
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
@@ -2,20 +2,14 @@
|
||||
title: Robots.txt File
|
||||
linktitle: Robots.txt
|
||||
description: Hugo can generate a customized robots.txt in the same way as any other template.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [robots,search engines]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 165
|
||||
weight: 165
|
||||
sections_weight: 165
|
||||
draft: false
|
||||
aliases: [/extras/robots-txt/]
|
||||
toc: false
|
||||
---
|
||||
|
||||
To generate a robots.txt file from a template, change the [site configuration][config]:
|
||||
@@ -41,7 +35,7 @@ You may overwrite the internal template with a custom template. Hugo selects the
|
||||
|
||||
## Robots.txt Template Example
|
||||
|
||||
{{< code file="layouts/robots.txt" download="robots.txt" >}}
|
||||
{{< code file="layouts/robots.txt" >}}
|
||||
User-agent: *
|
||||
{{ range .Pages }}
|
||||
Disallow: {{ .RelPermalink }}
|
||||
|
||||
@@ -1,19 +1,13 @@
|
||||
---
|
||||
title: RSS Templates
|
||||
linktitle: RSS Templates
|
||||
description: Hugo ships with its own RSS 2.0 template that requires almost no configuration, or you can create your own RSS templates.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
keywords: [rss, xml, templates]
|
||||
categories: [templates]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 150
|
||||
weight: 150
|
||||
sections_weight: 150
|
||||
draft: false
|
||||
toc: true
|
||||
---
|
||||
|
||||
@@ -21,7 +15,7 @@ toc: true
|
||||
|
||||
See [Template Lookup Order](/templates/lookup-order/) for the complete reference.
|
||||
|
||||
{{% note "Hugo Ships with an RSS Template" %}}
|
||||
{{% note %}}
|
||||
Hugo ships with its own [RSS 2.0 template](#the-embedded-rssxml). The embedded template will be sufficient for most use cases.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
@@ -2,18 +2,13 @@
|
||||
title: Section Page Templates
|
||||
linktitle: Section Templates
|
||||
description: Templates used for section pages are **lists** and therefore have all the variables and methods available to list pages.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [lists,sections,templates]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 40
|
||||
weight: 40
|
||||
sections_weight: 40
|
||||
draft: false
|
||||
aliases: [/templates/sections/]
|
||||
toc: true
|
||||
---
|
||||
@@ -48,13 +43,13 @@ Examples:
|
||||
|
||||
## Example: Creating a Default Section Template
|
||||
|
||||
{{< code file="layouts/_default/section.html" download="section.html" >}}
|
||||
{{< code file="layouts/_default/section.html" >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
{{ .Content }}
|
||||
<ul class="contents">
|
||||
{{ range .Paginator.Pages }}
|
||||
<li>{{.Title}}
|
||||
<li>{{ .Title }}
|
||||
<div>
|
||||
{{ partial "summary.html" . }}
|
||||
</div>
|
||||
|
||||
@@ -2,19 +2,13 @@
|
||||
title: Create Your Own Shortcodes
|
||||
linktitle: Shortcode Templates
|
||||
description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [shortcodes,templates]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 100
|
||||
weight: 100
|
||||
sections_weight: 100
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: true
|
||||
---
|
||||
|
||||
@@ -32,7 +26,7 @@ Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, H
|
||||
|
||||
### File Location
|
||||
|
||||
To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose.
|
||||
To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}`.
|
||||
|
||||
You can organize your shortcodes in subfolders, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g:
|
||||
|
||||
@@ -102,16 +96,16 @@ most helpful when the condition depends on either of the values, or both:
|
||||
|
||||
If a closing shortcode is used, the `.Inner` variable will be populated with the content between the opening and closing shortcodes. If a closing shortcode is required, you can check the length of `.Inner` as an indicator of its existence.
|
||||
|
||||
A shortcode with content declared via the `.Inner` variable can also be declared without the content and without the closing by using the self-closing syntax:
|
||||
A shortcode with content declared via the `.Inner` variable can also be declared without the content and without the closing tag by using the self-closing syntax:
|
||||
|
||||
```go-html-template
|
||||
{{</* innershortcode /*/>}}
|
||||
```
|
||||
|
||||
{{% warning %}}
|
||||
{{% note %}}
|
||||
Any shortcode that refers to `.Inner` must be closed or self-closed.
|
||||
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
#### `.Params`
|
||||
|
||||
@@ -148,9 +142,9 @@ You could then include the following as part of your shortcode templating:
|
||||
|
||||
See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action.
|
||||
|
||||
{{% warning %}}
|
||||
{{% note %}}
|
||||
While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
You can also use the variable `.Page` to access all the normal [page variables][pagevars].
|
||||
|
||||
@@ -193,7 +187,7 @@ Would load the template at `/layouts/shortcodes/youtube.html`:
|
||||
</div>
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file="youtube-embed.html" copy="false" >}}
|
||||
{{< code file="youtube-embed.html" copy=false >}}
|
||||
<div class="embed video-player">
|
||||
<iframe class="youtube-player" type="text/html"
|
||||
width="640" height="385"
|
||||
@@ -215,33 +209,33 @@ You have created the shortcode at `/layouts/shortcodes/img.html`, which loads th
|
||||
|
||||
{{< code file="/layouts/shortcodes/img.html" >}}
|
||||
<!-- image -->
|
||||
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
|
||||
{{ with .Get "link" }}<a href="{{ . }}">{{ end }}
|
||||
<img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt" }}{{ . }}{{ else }}{{ .Get "caption" }}{{ end }}"{{ end }} />
|
||||
<figure {{ with .Get "class" }}class="{{ . }}"{{ end }}>
|
||||
{{ with .Get "link" }}<a href="{{ . }}">{{ end }}
|
||||
<img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt" }}{{ . }}{{ else }}{{ .Get "caption" }}{{ end }}"{{ end }} />
|
||||
{{ if .Get "link" }}</a>{{ end }}
|
||||
{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr") }}
|
||||
<figcaption>{{ if isset .Params "title" }}
|
||||
<figcaption>{{ if isset .Params "title" }}
|
||||
<h4>{{ .Get "title" }}</h4>{{ end }}
|
||||
{{ if or (.Get "caption") (.Get "attr") }}<p>
|
||||
{{ .Get "caption" }}
|
||||
{{ with .Get "attrlink" }}<a href="{{ . }}"> {{ end }}
|
||||
{{ .Get "attr" }}
|
||||
{{ .Get "attr" }}
|
||||
{{ if .Get "attrlink" }}</a> {{ end }}
|
||||
</p> {{ end }}
|
||||
</figcaption>
|
||||
{{ end }}
|
||||
</figcaption>
|
||||
{{ end }}
|
||||
</figure>
|
||||
<!-- image -->
|
||||
{{< /code >}}
|
||||
|
||||
Would be rendered as:
|
||||
|
||||
{{< code file="img-output.html" copy="false" >}}
|
||||
{{< code file="img-output.html" copy=false >}}
|
||||
<figure>
|
||||
<img src="/media/spf13.jpg" />
|
||||
<figcaption>
|
||||
<h4>Steve Francia</h4>
|
||||
</figcaption>
|
||||
<img src="/media/spf13.jpg" />
|
||||
<figcaption>
|
||||
<h4>Steve Francia</h4>
|
||||
</figcaption>
|
||||
</figure>
|
||||
{{< /code >}}
|
||||
|
||||
@@ -268,7 +262,7 @@ Would load the template found at `/layouts/shortcodes/vimeo.html`:
|
||||
|
||||
Would be rendered as:
|
||||
|
||||
{{< code file="vimeo-iframes.html" copy="false" >}}
|
||||
{{< code file="vimeo-iframes.html" copy=false >}}
|
||||
<div class="vimeo-container">
|
||||
<iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
|
||||
</div>
|
||||
@@ -297,7 +291,7 @@ The template for the `highlight` shortcode uses the following code, which is alr
|
||||
|
||||
The rendered output of the HTML example code block will be as follows:
|
||||
|
||||
{{< code file="syntax-highlighted.html" copy="false" >}}
|
||||
{{< code file="syntax-highlighted.html" copy=false >}}
|
||||
<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672"><html></span>
|
||||
<span style="color: #f92672"><body></span> This HTML <span style="color: #f92672"></body></span>
|
||||
<span style="color: #f92672"></html></span>
|
||||
@@ -321,9 +315,9 @@ You also have an `img` shortcode with a single named `src` parameter that you wa
|
||||
{{< code file="layouts/shortcodes/img.html" >}}
|
||||
{{- $src := .Get "src" -}}
|
||||
{{- with .Parent -}}
|
||||
<img src="{{$src}}" class="{{ .Get "class" }}-image">
|
||||
<img src="{{ $src }}" class="{{ .Get "class" }}-image">
|
||||
{{- else -}}
|
||||
<img src="{{$src}}">
|
||||
<img src="{{ $src }}">
|
||||
{{- end -}}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
@@ -1,19 +1,13 @@
|
||||
---
|
||||
title: Single Page Templates
|
||||
linktitle:
|
||||
description: The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-04-06
|
||||
categories: [templates]
|
||||
keywords: [page, templates]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 60
|
||||
weight: 60
|
||||
sections_weight: 60
|
||||
draft: false
|
||||
aliases: [/layout/content/]
|
||||
toc: true
|
||||
---
|
||||
@@ -30,46 +24,46 @@ Content pages are of the type `page` and will therefore have all the [page varia
|
||||
|
||||
This single page template makes use of Hugo [base templates], the [`.Format` function] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`] is also used to check whether the taxonomies are set in the front matter.
|
||||
|
||||
{{< code file="layouts/posts/single.html" download="single.html" >}}
|
||||
{{< code file="layouts/posts/single.html" >}}
|
||||
{{ define "main" }}
|
||||
|
||||
<section id="main">
|
||||
<h1 id="title">{{ .Title }}</h1>
|
||||
<div>
|
||||
<article id="content">
|
||||
{{ .Content }}
|
||||
</article>
|
||||
<article id="content">
|
||||
{{ .Content }}
|
||||
</article>
|
||||
</div>
|
||||
</section>
|
||||
<aside id="meta">
|
||||
<div>
|
||||
<section>
|
||||
<h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
|
||||
<h5 id="wordcount"> {{ .WordCount }} Words </h5>
|
||||
</section>
|
||||
{{ with .GetTerms "topics" }}
|
||||
<ul id="topics">
|
||||
{{ range . }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
{{ with .GetTerms "tags" }}
|
||||
<ul id="tags">
|
||||
{{ range . }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
</div>
|
||||
<div>
|
||||
{{ with .PrevInSection }}
|
||||
<a class="previous" href="{{.Permalink}}"> {{.Title}}</a>
|
||||
<div>
|
||||
<section>
|
||||
<h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
|
||||
<h5 id="wordcount"> {{ .WordCount }} Words </h5>
|
||||
</section>
|
||||
{{ with .GetTerms "topics" }}
|
||||
<ul id="topics">
|
||||
{{ range . }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
{{ with .NextInSection }}
|
||||
<a class="next" href="{{.Permalink}}"> {{.Title}}</a>
|
||||
</ul>
|
||||
{{ end }}
|
||||
{{ with .GetTerms "tags" }}
|
||||
<ul id="tags">
|
||||
{{ range . }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</div>
|
||||
</ul>
|
||||
{{ end }}
|
||||
</div>
|
||||
<div>
|
||||
{{ with .PrevInSection }}
|
||||
<a class="previous" href="{{ .Permalink }}"> {{ .Title }}</a>
|
||||
{{ end }}
|
||||
{{ with .NextInSection }}
|
||||
<a class="next" href="{{ .Permalink }}"> {{ .Title }}</a>
|
||||
{{ end }}
|
||||
</div>
|
||||
</aside>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: Sitemap Templates
|
||||
description: Hugo provides built-in sitemap templates.
|
||||
date: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [sitemap, xml, templates]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 160
|
||||
weight: 160
|
||||
sections_weight: 160
|
||||
draft: false
|
||||
aliases: [/layout/sitemap/,/templates/sitemap/]
|
||||
toc: true
|
||||
---
|
||||
@@ -79,7 +76,7 @@ You may disable sitemap generation in your site configuration:
|
||||
disableKinds = ['sitemap']
|
||||
{{</ code-toggle >}}
|
||||
|
||||
[`publishDir`]: {{< relref "getting-started/configuration#publishdir" >}}
|
||||
[`publishDir`]: /getting-started/configuration#publishdir
|
||||
[change frequency]: <https://www.sitemaps.org/protocol.html#changefreqdef>
|
||||
[priority]: <https://www.sitemaps.org/protocol.html#priority>
|
||||
[sitemap protocol]: <https://www.sitemaps.org/protocol.html>
|
||||
|
||||
@@ -1,19 +1,13 @@
|
||||
---
|
||||
title: Taxonomy Templates
|
||||
# linktitle:
|
||||
description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [taxonomies,metadata,front matter,terms,templates]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 50
|
||||
weight: 50
|
||||
sections_weight: 50
|
||||
draft: false
|
||||
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/]
|
||||
toc: true
|
||||
---
|
||||
@@ -150,16 +144,14 @@ Weights of zero are thus treated specially: if two pages have unequal weights, a
|
||||
|
||||
Content can be assigned weight for each taxonomy that it's assigned to.
|
||||
|
||||
```txt
|
||||
+++
|
||||
|
||||
{{< code-toggle file="content/example.md" fm=true copy=false >}}
|
||||
tags = [ "a", "b", "c" ]
|
||||
tags_weight = 22
|
||||
categories = ["d"]
|
||||
title = "foo"
|
||||
title = "Example"
|
||||
categories_weight = 44
|
||||
+++
|
||||
Front Matter with weighted tags and categories
|
||||
```
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The convention is `taxonomyname_weight`.
|
||||
|
||||
@@ -177,16 +169,16 @@ There are two different templates that the use of taxonomies will require you to
|
||||
|
||||
Both templates are covered in detail in the templates section.
|
||||
|
||||
A [list template](/templates/list/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages.
|
||||
A [list template](/templates/lists/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages.
|
||||
|
||||
A [taxonomy terms template](/templates/terms/) is a template used to
|
||||
A [taxonomy template](/templates/taxonomy-templates/) is a template used to
|
||||
generate the list of terms for a given template.
|
||||
|
||||
<!-- Begin /taxonomies/displaying/ -->
|
||||
|
||||
There are four common ways you can display the data in your
|
||||
taxonomies in addition to the automatic taxonomy pages created by hugo
|
||||
using the [list templates](/templates/list/):
|
||||
using the [list templates](/templates/lists/):
|
||||
|
||||
1. For a given piece of content, you can list the terms attached
|
||||
2. For a given piece of content, you can list other content with the same
|
||||
@@ -258,7 +250,7 @@ This would be very useful in a sidebar as “featured content”. You could even
|
||||
<li>{{ $key }}</li>
|
||||
<ul>
|
||||
{{ range $taxonomy.Pages }}
|
||||
<li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}">{{ .LinkTitle }}</a></li>
|
||||
<li hugo-nav="{{ .RelPermalink }}"><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
@@ -288,7 +280,7 @@ The following example displays all terms in a site's tags taxonomy:
|
||||
|
||||
This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
|
||||
|
||||
{{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}}
|
||||
{{< code file="layouts/partials/all-taxonomies.html" >}}
|
||||
<section>
|
||||
<ul id="all-taxonomies">
|
||||
{{ range $taxonomy_term, $taxonomy := .Site.Taxonomies }}
|
||||
@@ -299,8 +291,8 @@ This example will list all taxonomies and their terms, as well as all the conten
|
||||
<li>{{ $key }}</li>
|
||||
<ul>
|
||||
{{ range $value.Pages }}
|
||||
<li hugo-nav="{{ .RelPermalink}}">
|
||||
<a href="{{ .Permalink}}">{{ .LinkTitle }}</a>
|
||||
<li hugo-nav="{{ .RelPermalink }}">
|
||||
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
@@ -315,14 +307,14 @@ This example will list all taxonomies and their terms, as well as all the conten
|
||||
|
||||
## `.Site.GetPage` for Taxonomies
|
||||
|
||||
Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above]({{< relref "#example-list-all-site-tags" >}}):
|
||||
Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above](#example-list-all-site-tags):
|
||||
|
||||
{{< code file="links-to-all-tags.html" >}}
|
||||
{{ $taxo := "tags" }}
|
||||
<ul class="{{ $taxo }}">
|
||||
{{ with ($.Site.GetPage (printf "/%s" $taxo)) }}
|
||||
{{ range .Pages }}
|
||||
<li><a href="{{ .Permalink }}">{{ .Title}}</a></li>
|
||||
<li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
</ul>
|
||||
|
||||
@@ -1,18 +1,13 @@
|
||||
---
|
||||
title: Template Debugging
|
||||
description: You can use Go templates' `printf` function to debug your Hugo templates. These snippets provide a quick and easy visualization of the variables available to you in different contexts.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [debugging,troubleshooting]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 180
|
||||
weight: 180
|
||||
sections_weight: 180
|
||||
aliases: []
|
||||
toc: false
|
||||
---
|
||||
|
||||
Here are some snippets you can add to your template to answer some common questions.
|
||||
|
||||
@@ -1,20 +1,13 @@
|
||||
---
|
||||
title: Content View Templates
|
||||
# linktitle: Content Views
|
||||
description: Hugo can render alternative views of your content, which is especially useful in list and summary views.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [views]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
parent: templates
|
||||
weight: 70
|
||||
weight: 70
|
||||
sections_weight: 70
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: true
|
||||
---
|
||||
|
||||
@@ -69,13 +62,13 @@ The following example demonstrates how to use content views inside your [list te
|
||||
|
||||
In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
|
||||
|
||||
{{< code file="layouts/_default/list.html" download="list.html" >}}
|
||||
{{< code file="layouts/_default/list.html" >}}
|
||||
<main id="main">
|
||||
<div>
|
||||
<h1 id="title">{{ .Title }}</h1>
|
||||
{{ range .Pages }}
|
||||
{{ .Render "summary"}}
|
||||
{{ end }}
|
||||
<h1 id="title">{{ .Title }}</h1>
|
||||
{{ range .Pages }}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
</div>
|
||||
</main>
|
||||
{{< /code >}}
|
||||
@@ -84,7 +77,7 @@ In this example, `.Render` is passed into the template to call the [render funct
|
||||
|
||||
Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
|
||||
|
||||
{{< code file="layouts/_default/summary.html" download="summary.html" >}}
|
||||
{{< code file="layouts/_default/summary.html" >}}
|
||||
<article class="post">
|
||||
<header>
|
||||
<h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
|
||||
@@ -101,7 +94,7 @@ Hugo will pass the entire page object to the following `summary.html` view templ
|
||||
|
||||
Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
|
||||
|
||||
{{< code file="layouts/_default/li.html" download="li.html" >}}
|
||||
{{< code file="layouts/_default/li.html" >}}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
|
||||
Reference in New Issue
Block a user