mirror of
https://github.com/gohugoio/hugo.git
synced 2024-09-13 01:12:31 -04:00
Merge commit 'f96384a3b596f9bc0a3a035970b09b2c601f0ccb'
This commit is contained in:
Bjørn Erik Pedersen
commit
b95e156940
341 changed files with 3107 additions and 4238 deletions
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 8 KiB After Width: | Height: | Size: 8 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 8 KiB After Width: | Height: | Size: 8 KiB |
|
|
@ -5,20 +5,17 @@
|
|||
utm_campaign = "hugosponsor"
|
||||
|
||||
[[banners]]
|
||||
name = "ButterCMS"
|
||||
link = "https://buttercms.com/hugo-cms/"
|
||||
logo = "images/sponsors/butter-light.svg"
|
||||
utm_campaign = "sponsorship"
|
||||
bgcolor = "#131A3E"
|
||||
name = "Your Company?"
|
||||
link = "https://bep.is/en/hugo-sponsor-2023-01/"
|
||||
logo = "/images/sponsors/your-company.svg"
|
||||
utm_campaign = "hugosponsor"
|
||||
show_on_hover = true
|
||||
bgcolor = "#004887"
|
||||
|
||||
[[banners]]
|
||||
name = "Gravity Kit"
|
||||
link = "https://www.gravitykit.com/"
|
||||
logo = "images/sponsors/graitykit-dark.svg"
|
||||
query_params = "ref=532&campaign=hugo&"
|
||||
utm_campaign = "hugosponsor"
|
||||
bgcolor = "#e0ecf3"
|
||||
|
||||
#hugohome
|
||||
#hugofooter
|
||||
#hugogithub
|
||||
name = "Your Company?"
|
||||
link = "https://bep.is/en/hugo-sponsor-2023-01/"
|
||||
logo = "/images/sponsors/your-company.svg"
|
||||
utm_campaign = "hugosponsor"
|
||||
show_on_hover = true
|
||||
bgcolor = "#004887"
|
||||
|
|
|
|||
|
|
@ -5,6 +5,14 @@
|
|||
{{ $isFooter := (eq $gtag "footer") }}
|
||||
{{ $utmSource := cond $isFooter "hugofooter" "hugohome" }}
|
||||
{{ with .cx.Site.Data.sponsors }}
|
||||
<style>
|
||||
a.show-on-hover {
|
||||
opacity: 0;
|
||||
}
|
||||
a.show-on-hover:hover {
|
||||
opacity: 1;
|
||||
}
|
||||
</style>
|
||||
<section
|
||||
class="{{ $.classes_section | default "bg-primary-color-dark b--dark-gray bb bt ph5 pv4 w-100" }}">
|
||||
<div class="center mw9">
|
||||
|
|
@ -22,11 +30,18 @@
|
|||
<a
|
||||
href="{{ $url }}"
|
||||
onclick="trackOutboundLink({{ printf "'%s', '%s'" $gtagID $url | safeJS }});"
|
||||
class="w-100 grow pa3">
|
||||
class="w-100 grow pa3{{ if .show_on_hover }}
|
||||
show-on-hover
|
||||
{{ end }}"
|
||||
style="">
|
||||
{{ $logo.Content | safeHTML }}
|
||||
</a>
|
||||
{{ else }}
|
||||
<a href="{{ $url }}" class="w-100 grow pa3" style="">
|
||||
<a
|
||||
href="{{ $url }}"
|
||||
class="w-100 grow pa3{{ if .show_on_hover }}
|
||||
show-on-hover
|
||||
{{ end }}">
|
||||
{{ $logo.Content | safeHTML }}
|
||||
</a>
|
||||
{{ end }}
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
# github.com/gohugoio/gohugoioTheme v0.0.0-20230124135550-462d5fe4a87f
|
||||
# github.com/gohugoio/gohugoioTheme v0.0.0-20230418063032-99f9185b8e11
|
||||
|
|
|
|||
|
|
@ -1,12 +1,11 @@
|
|||
---
|
||||
linktitle: ""
|
||||
title: {{ replace .Name "-" " " | title }}
|
||||
description: ""
|
||||
categories: [functions]
|
||||
tags: []
|
||||
ns: ""
|
||||
signature: []
|
||||
hugoversion: ""
|
||||
aliases: []
|
||||
categories: [functions]
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
relatedfuncs: []
|
||||
toc: false
|
||||
---
|
||||
|
|
|
|||
|
|
@ -2,19 +2,14 @@
|
|||
title: About Hugo
|
||||
linktitle: Overview
|
||||
description: Hugo's features, roadmap, license, and motivation.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: "about"
|
||||
parent: about
|
||||
weight: 1
|
||||
weight: 1
|
||||
draft: false
|
||||
aliases: [/about-hugo/,/docs/]
|
||||
toc: false
|
||||
---
|
||||
|
||||
Hugo is not your average static site generator.
|
||||
|
|
|
|||
|
|
@ -2,19 +2,12 @@
|
|||
title: The Benefits of Static Site Generators
|
||||
linktitle: The Benefits of Static
|
||||
description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
keywords: [ssg,static,performance,security]
|
||||
menu:
|
||||
docs:
|
||||
parent: "about"
|
||||
parent: about
|
||||
weight: 30
|
||||
weight: 30
|
||||
sections_weight: 30
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: false
|
||||
---
|
||||
|
||||
The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.
|
||||
|
|
|
|||
|
|
@ -1,17 +1,11 @@
|
|||
---
|
||||
title: Hugo Features
|
||||
linktitle: Hugo Features
|
||||
description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
menu:
|
||||
docs:
|
||||
parent: "about"
|
||||
parent: about
|
||||
weight: 20
|
||||
weight: 20
|
||||
sections_weight: 20
|
||||
draft: false
|
||||
toc: true
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -2,16 +2,13 @@
|
|||
title: Hugo and the General Data Protection Regulation (GDPR)
|
||||
linktitle: Hugo and GDPR
|
||||
description: About how to configure your Hugo site to meet the new regulations.
|
||||
date: 2018-05-25
|
||||
layout: single
|
||||
keywords: ["GDPR", "Privacy", "Data Protection"]
|
||||
menu:
|
||||
docs:
|
||||
parent: "about"
|
||||
parent: about
|
||||
weight: 5
|
||||
weight: 5
|
||||
sections_weight: 5
|
||||
draft: false
|
||||
aliases: [/privacy/,/gdpr/]
|
||||
toc: true
|
||||
---
|
||||
|
|
@ -57,7 +54,6 @@ disable = false
|
|||
privacyEnhanced = false
|
||||
{{< /code-toggle >}}
|
||||
|
||||
|
||||
## Disable All Services
|
||||
|
||||
An example Privacy Config that disables all the relevant services in Hugo. With this configuration, the other settings will not matter.
|
||||
|
|
@ -91,9 +87,9 @@ respectDoNotTrack
|
|||
useSessionStorage
|
||||
: Enabling this will disable the use of Cookies and use Session Storage to Store the GA Client ID.
|
||||
|
||||
{{% warning %}}
|
||||
{{% note %}}
|
||||
`useSessionStorage` is not supported when using Google Analytics v4 (gtag.js).
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
### Instagram
|
||||
|
||||
|
|
|
|||
|
|
@ -2,24 +2,20 @@
|
|||
title: Apache License
|
||||
linktitle: License
|
||||
description: Hugo v0.15 and later are released under the Apache 2.0 license.
|
||||
date: 2016-02-01
|
||||
publishdate: 2016-02-01
|
||||
lastmod: 2016-03-02
|
||||
categories: ["about hugo"]
|
||||
keywords: ["License","apache"]
|
||||
menu:
|
||||
docs:
|
||||
parent: "about"
|
||||
parent: about
|
||||
weight: 60
|
||||
weight: 60
|
||||
sections_weight: 60
|
||||
aliases: [/meta/license]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{% note %}}
|
||||
Hugo v0.15 and later are released under the Apache 2.0 license.
|
||||
Earlier versions of Hugo were released under the [Simple Public License](https://opensource.org/licenses/Simple-2.0).
|
||||
Earlier versions of Hugo were released under the [Simple Public License](https://opensource.org/license/simpl-2-0-html/).
|
||||
{{% /note %}}
|
||||
|
||||
_Version 2.0, January 2004_ <br>
|
||||
|
|
@ -148,7 +144,7 @@ _END OF TERMS AND CONDITIONS_
|
|||
|
||||
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets `[]` replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same “printed page” as the copyright notice for easier identification within third-party archives.
|
||||
|
||||
{{< code file="apache-notice.txt" download="apache-notice.txt" >}}
|
||||
{{< code file="apache-notice.txt" >}}
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
|
|
|
|||
|
|
@ -1,15 +1,13 @@
|
|||
---
|
||||
title: Hugo's Security Model
|
||||
description: A summary of Hugo's security model.
|
||||
date: 2019-10-01
|
||||
layout: single
|
||||
keywords: ["Security", "Privacy"]
|
||||
menu:
|
||||
docs:
|
||||
parent: "about"
|
||||
parent: about
|
||||
weight: 4
|
||||
weight: 5
|
||||
sections_weight: 5
|
||||
aliases: [/security/]
|
||||
toc: true
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,18 +1,12 @@
|
|||
---
|
||||
title: What is Hugo
|
||||
linktitle: What is Hugo
|
||||
description: Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
layout: single
|
||||
menu:
|
||||
docs:
|
||||
parent: "about"
|
||||
parent: about
|
||||
weight: 10
|
||||
weight: 10
|
||||
sections_weight: 10
|
||||
draft: false
|
||||
aliases: [/overview/introduction/,/about/why-i-built-hugo/]
|
||||
toc: true
|
||||
---
|
||||
|
|
|
|||
|
|
@ -8,7 +8,6 @@ menu:
|
|||
weight: 10
|
||||
keywords: [source, organization]
|
||||
categories: [content management]
|
||||
toc: false
|
||||
weight: 10
|
||||
aliases: [/content/,/content/organization]
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: Archetypes
|
||||
linkTitle: Archetypes
|
||||
description: Archetypes are templates used when creating new content.
|
||||
keywords: [archetypes,generators,metadata,front matter]
|
||||
categories: [content management]
|
||||
|
|
|
|||
|
|
@ -56,43 +56,39 @@ If true, the page will be treated as part of the project's collections and, when
|
|||
|
||||
#### publishResources
|
||||
|
||||
If set to true the [Bundle's Resources]({{< relref "content-management/page-bundles" >}}) will be published.
|
||||
If set to true the [Bundle's Resources](/content-management/page-bundles) will be published.
|
||||
Setting this to false will still publish Resources on demand (when a resource's `.Permalink` or `.RelPermalink` is invoked from the templates) but will skip the others.
|
||||
|
||||
{{% note %}}
|
||||
Any page, regardless of their build options, will always be available using the [`.GetPage`]({{< relref "functions/GetPage" >}}) methods.
|
||||
Any page, regardless of their build options, will always be available using the [`.GetPage`](/functions/getpage) methods.
|
||||
{{% /note %}}
|
||||
|
||||
------
|
||||
|
||||
### Illustrative use cases
|
||||
|
||||
#### Not publishing a page
|
||||
|
||||
Project needs a "Who We Are" content file for Front Matter and body to be used by the homepage but nowhere else.
|
||||
|
||||
```yaml
|
||||
# content/who-we-are.md`
|
||||
{{< code-toggle file="content/who-we-are.md" fm=true copy=false >}}
|
||||
title: Who we are
|
||||
_build:
|
||||
list: false
|
||||
render: false
|
||||
```
|
||||
{{< /code-toggle >}}
|
||||
|
||||
```go-html-template
|
||||
{{/* layouts/index.html */}}
|
||||
{{< code file="layouts/index.html" copy=false >}}
|
||||
<section id="who-we-are">
|
||||
{{ with site.GetPage "who-we-are" }}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
{{ with site.GetPage "who-we-are" }}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
</section>
|
||||
```
|
||||
{{< /code >}}
|
||||
|
||||
#### Listing pages without publishing them
|
||||
|
||||
Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them.
|
||||
|
||||
To avoid setting the build options on every testimonials, one can use [`cascade`]({{< relref "/content-management/front-matter#front-matter-cascade" >}}) on the testimonial section's content file.
|
||||
To avoid setting the build options on every testimonials, one can use [`cascade`](/content-management/front-matter#front-matter-cascade) on the testimonial section's content file.
|
||||
|
||||
{{< code-toggle >}}
|
||||
title: Testimonials
|
||||
|
|
@ -104,12 +100,12 @@ cascade:
|
|||
list: true # default
|
||||
{{< /code-toggle >}}
|
||||
|
||||
```go-html-template
|
||||
{{/* layouts/_defaults/testimonials.html */}}
|
||||
{{< code file="layouts/_defaults/testimonials.html" copy=false >}}
|
||||
<section id="testimonials">
|
||||
{{ range first 5 .Pages }}
|
||||
<blockquote cite="{{ .Params.cite }}">
|
||||
{{ .Content }}
|
||||
</blockquote>
|
||||
{{ end }}
|
||||
{{ range first 5 .Pages }}
|
||||
<blockquote cite="{{ .Params.cite }}">
|
||||
{{ .Content }}
|
||||
</blockquote>
|
||||
{{ end }}
|
||||
</section>
|
||||
{{< /code >}}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: Comments
|
||||
linkTitle: Comments
|
||||
description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
|
||||
keywords: [sections,content,organization]
|
||||
categories: [project organization, fundamentals]
|
||||
|
|
@ -25,7 +24,7 @@ Hugo comes with all the code you need to load Disqus into your templates. Before
|
|||
|
||||
Disqus comments require you set a single value in your [site's configuration file][configuration] like so:
|
||||
|
||||
{{< code-toggle copy="false" >}}
|
||||
{{< code-toggle copy=false >}}
|
||||
disqusShortname = "yourDisqusShortname"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: Diagrams
|
||||
LinkTitle: Diagrams
|
||||
description: Use fenced code blocks and markdown render hooks to display diagrams.
|
||||
categories: [content management]
|
||||
keywords: [diagrams,drawing]
|
||||
|
|
@ -58,8 +57,8 @@ And then include this snippet at the bottom of the content template (**Note**: b
|
|||
|
||||
```go-html-template
|
||||
{{ if .Page.Store.Get "hasMermaid" }}
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
|
||||
<script>
|
||||
<script type="module">
|
||||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
|
||||
mermaid.initialize({ startOnLoad: true });
|
||||
</script>
|
||||
{{ end }}
|
||||
|
|
@ -67,6 +66,7 @@ And then include this snippet at the bottom of the content template (**Note**: b
|
|||
|
||||
With that you can use the `mermaid` language in Markdown code blocks:
|
||||
|
||||
````
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Alice
|
||||
|
|
@ -80,6 +80,7 @@ sequenceDiagram
|
|||
John->>Bob: How about you?
|
||||
Bob-->>John: Jolly good!
|
||||
```
|
||||
````
|
||||
|
||||
## Goat Ascii Diagram Examples
|
||||
|
||||
|
|
|
|||
|
|
@ -46,9 +46,9 @@ Hugo passes reasonable default arguments to these external helpers by default:
|
|||
- `rst2html`: `--leave-comments --initial-header-level=2`
|
||||
- `pandoc`: `--mathjax`
|
||||
|
||||
{{% warning "Performance of External Helpers" %}}
|
||||
{{% note %}}
|
||||
Because additional formats are external commands, generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
### External Helper AsciiDoc
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,6 @@
|
|||
---
|
||||
title: Front Matter
|
||||
linkTitle: Front Matter
|
||||
description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
|
||||
lastmod: 2017-02-24
|
||||
categories: [content management]
|
||||
keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
|
||||
menu:
|
||||
|
|
@ -56,87 +54,87 @@ slug = "spf13-vim-3-0-release-and-new-website"
|
|||
There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates.
|
||||
|
||||
aliases
|
||||
: an array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
|
||||
: An array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
|
||||
|
||||
audio
|
||||
: an array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
|
||||
: An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
|
||||
|
||||
cascade
|
||||
: a map of Front Matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
|
||||
: A map of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
|
||||
|
||||
date
|
||||
: the datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
|
||||
: The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
|
||||
|
||||
description
|
||||
: the description for the content.
|
||||
: The description for the content.
|
||||
|
||||
draft
|
||||
: if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
|
||||
: If `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
|
||||
|
||||
expiryDate
|
||||
: the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
|
||||
: The datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
|
||||
|
||||
headless
|
||||
: if `true`, sets a leaf bundle to be [headless][headless-bundle].
|
||||
: If `true`, sets a leaf bundle to be [headless][headless-bundle].
|
||||
|
||||
images
|
||||
: an array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
|
||||
: An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
|
||||
|
||||
isCJKLanguage
|
||||
: if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
|
||||
: If `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
|
||||
|
||||
keywords
|
||||
: the meta keywords for the content.
|
||||
: The meta keywords for the content.
|
||||
|
||||
layout
|
||||
: the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type].
|
||||
: The layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type].
|
||||
|
||||
lastmod
|
||||
: the datetime at which the content was last modified.
|
||||
: The datetime at which the content was last modified.
|
||||
|
||||
linkTitle
|
||||
: used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle].
|
||||
: Used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle].
|
||||
|
||||
markup
|
||||
: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
|
||||
|
||||
outputs
|
||||
: allows you to specify output formats specific to the content. See [output formats][outputs].
|
||||
: Allows you to specify output formats specific to the content. See [output formats][outputs].
|
||||
|
||||
publishDate
|
||||
: if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
|
||||
: If in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
|
||||
|
||||
resources
|
||||
: used for configuring page bundle resources. See [Page Resources][page-resources].
|
||||
: Used for configuring page bundle resources. See [Page Resources][page-resources].
|
||||
|
||||
series
|
||||
: an array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
|
||||
: An array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
|
||||
|
||||
slug
|
||||
: appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename.
|
||||
: Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details.
|
||||
|
||||
summary
|
||||
: text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
|
||||
: Text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
|
||||
|
||||
title
|
||||
: the title for the content.
|
||||
: The title for the content.
|
||||
|
||||
type
|
||||
: the type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter.
|
||||
: The type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter.
|
||||
|
||||
url
|
||||
: the full path to the content from the web root. It makes no assumptions about the path of the content file. See [URL Management](/content-management/urls/#set-url-in-front-matter).
|
||||
: Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details.
|
||||
|
||||
videos
|
||||
: an array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
|
||||
: An array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
|
||||
|
||||
weight
|
||||
: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight.
|
||||
|
||||
\<taxonomies\>
|
||||
: field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.*
|
||||
: Field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.*
|
||||
|
||||
{{% note "Hugo's Default URL Destinations" %}}
|
||||
{{% note %}}
|
||||
If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors.
|
||||
{{% /note %}}
|
||||
|
||||
|
|
@ -146,7 +144,7 @@ You can add fields to your front matter arbitrarily to meet your needs. These us
|
|||
|
||||
The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables] section provides more information on using Hugo's page- and site-level variables in your templates.
|
||||
|
||||
{{< code-toggle copy="false" >}}
|
||||
{{< code-toggle copy=false >}}
|
||||
include_toc: true
|
||||
show_comments: false
|
||||
{{</ code-toggle >}}
|
||||
|
|
@ -159,7 +157,7 @@ Any node or section can pass down to descendants a set of Front Matter values as
|
|||
|
||||
The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
|
||||
|
||||
{{< code-toggle copy="false" >}}
|
||||
{{< code-toggle copy=false >}}
|
||||
title ="Blog"
|
||||
[[cascade]]
|
||||
background = "yosemite.jpg"
|
||||
|
|
@ -193,7 +191,7 @@ Any of the above can be omitted.
|
|||
|
||||
In `content/blog/_index.md`
|
||||
|
||||
{{< code-toggle copy="false" >}}
|
||||
{{< code-toggle copy=false >}}
|
||||
title: Blog
|
||||
cascade:
|
||||
banner: images/typewriter.jpg
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: Image Processing
|
||||
linkTitle: Image Processing
|
||||
description: Resize, crop, rotate, filter, and convert images.
|
||||
categories: [content management]
|
||||
keywords: [resources, images]
|
||||
|
|
@ -457,15 +456,15 @@ If you change image processing methods or options, or if you rename or remove im
|
|||
hugo --gc
|
||||
```
|
||||
|
||||
[`anchor`]: {{< relref "content-management/image-processing#anchor" >}}
|
||||
[`lang.FormatNumber`]: {{< relref "functions/lang#langformatnumber" >}}
|
||||
[Exif]: <https://en.wikipedia.org/wiki/Exif>
|
||||
[filters]: {{< relref "functions/images" >}}
|
||||
[time.Format]: /functions/dateformat
|
||||
[`anchor`]: /content-management/image-processing#anchor
|
||||
[mounted]: /hugo-modules/configuration#module-config-mounts
|
||||
[page bundle]: /content-management/page-bundles
|
||||
[`lang.FormatNumber`]: /functions/lang
|
||||
[filters]: /functions/images
|
||||
[github.com/disintegration/imaging]: <https://github.com/disintegration/imaging#image-resizing>
|
||||
[mounted]: {{< relref "hugo-modules/configuration#module-config-mounts">}}
|
||||
[page bundle]: {{< relref "content-management/page-bundles" >}}
|
||||
[Smartcrop]: <https://github.com/muesli/smartcrop#smartcrop>
|
||||
[time.Format]: {{< relref "functions/dateformat" >}}
|
||||
[Exif]: <https://en.wikipedia.org/wiki/Exif>
|
||||
[`Colors`]: #colors
|
||||
[`Crop`]: #crop
|
||||
[`Exif`]: #exif
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
---
|
||||
title: Menus
|
||||
linkTitle: Menus
|
||||
description: Hugo has a simple yet powerful menu system.
|
||||
description: Create menus by defining entries, localizing each entry, and rendering the resulting data structure.
|
||||
categories: [content management]
|
||||
keywords: [menus]
|
||||
menu:
|
||||
|
|
@ -13,117 +12,214 @@ weight: 190
|
|||
aliases: [/extras/menus/]
|
||||
---
|
||||
|
||||
{{% note "Lazy Blogger"%}}
|
||||
If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-bloggers).
|
||||
{{% /note %}}
|
||||
## Overview
|
||||
|
||||
You can do this:
|
||||
To create a menu for your site:
|
||||
|
||||
* Place content in one or many menus
|
||||
* Handle nested menus with unlimited depth
|
||||
* Create menu entries without being attached to any content
|
||||
* Distinguish active element (and active branch)
|
||||
1. Define the menu entries
|
||||
2. [Localize] each entry
|
||||
3. Render the menu with a [template]
|
||||
|
||||
## What is a Menu in Hugo?
|
||||
Create multiple menus, either flat or nested. For example, create a main menu for the header, and a separate menu for the footer.
|
||||
|
||||
A **menu** is a named array of menu entries accessible by name via the [`.Site.Menus` site variable][sitevars]. For example, you can access your site's `main` menu via `.Site.Menus.main`.
|
||||
There are three ways to define menu entries:
|
||||
|
||||
{{% note "Menus on Multilingual Sites" %}}
|
||||
If you make use of the [multilingual feature](/content-management/multilingual/), you can define language-independent menus.
|
||||
{{% /note %}}
|
||||
|
||||
See the [Menu Entry Properties][me-props] for all the variables and functions related to a menu entry.
|
||||
|
||||
## Add content to menus
|
||||
|
||||
Hugo allows you to add content to a menu via the content's [front matter](/content-management/front-matter/).
|
||||
|
||||
### Simple
|
||||
|
||||
If all you need to do is add an entry to a menu, the simple form works well.
|
||||
|
||||
#### A Single Menu
|
||||
|
||||
{{< code-toggle >}}
|
||||
menu: "main"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Multiple Menus
|
||||
|
||||
{{< code-toggle >}}
|
||||
menu: ["main", "footer"]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Advanced
|
||||
|
||||
{{< code-toggle >}}
|
||||
menu:
|
||||
docs:
|
||||
parent: 'extras'
|
||||
weight: 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Add Non-content Entries to a Menu
|
||||
|
||||
You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config] (see [Menu Entry Properties][me-props] for full details of available variables).
|
||||
|
||||
Here’s an example snippet pulled from a configuration file:
|
||||
|
||||
{{< code-toggle file="config" >}}
|
||||
[[menu.main]]
|
||||
name = "about hugo"
|
||||
pre = "<i class='fa fa-heart'></i>"
|
||||
weight = -110
|
||||
identifier = "about"
|
||||
url = "/about/"
|
||||
[[menu.main]]
|
||||
name = "getting started"
|
||||
pre = "<i class='fa fa-road'></i>"
|
||||
post = "<span class='alert'>New!</span>"
|
||||
weight = -100
|
||||
url = "/getting-started/"
|
||||
{{< /code-toggle >}}
|
||||
1. Automatically
|
||||
1. In front matter
|
||||
1. In site configuration
|
||||
|
||||
{{% note %}}
|
||||
The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`.
|
||||
Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site.
|
||||
{{% /note %}}
|
||||
|
||||
## Nesting
|
||||
## Define automatically
|
||||
|
||||
All nesting of content is done via the `parent` field.
|
||||
To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration.
|
||||
|
||||
The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu).
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
sectionPagesMenu = "main"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The following order is used to determine an Identifier:
|
||||
This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
`.Name > .LinkTitle > .Title`
|
||||
## Define in front matter
|
||||
|
||||
This means that `.Title` will be used unless `.LinkTitle` is present, etc. In practice, `.Name` and `.Identifier` are only used to structure relationships and therefore never displayed.
|
||||
To add a page to the "main" menu:
|
||||
|
||||
In this example, the top level of the menu is defined in your [site `config` file][config]. All content entries are attached to one of these entries via the `.Parent` field.
|
||||
{{< code-toggle file="content/about.md" copy=false fm=true >}}
|
||||
title = 'About'
|
||||
menu = 'main'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Params
|
||||
Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
You can also add user-defined content to menu items via the `params` field.
|
||||
To add a page to the "main" and "footer" menus:
|
||||
|
||||
A common use case is to define a custom param to add a css class to a specific menu item.
|
||||
{{< code-toggle file="content/contact.md" copy=false fm=true >}}
|
||||
title = 'Contact'
|
||||
menu = ['main','footer']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{< code-toggle file="config" >}}
|
||||
Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details.
|
||||
|
||||
### Properties {#properties-front-matter}
|
||||
|
||||
Use these properties when defining menu entries in front matter:
|
||||
|
||||
identifier
|
||||
: (`string`) Required when two or more menu entries have the same `name`, or when localizing the `name` using translation tables. Must start with a letter, followed by letters, digits, or underscores.
|
||||
|
||||
name
|
||||
: (`string`) The text to display when rendering the menu entry.
|
||||
|
||||
params
|
||||
: (`map`) User-defined properties for the menu entry.
|
||||
|
||||
parent
|
||||
: (`string`) The `identifier` of the parent menu entry. If `identifier` is not defined, use `name`. Required for child entries in a nested menu.
|
||||
|
||||
post
|
||||
: (`string`) The HTML to append when rendering the menu entry.
|
||||
|
||||
pre
|
||||
: (`string`) The HTML to prepend when rendering the menu entry.
|
||||
|
||||
title
|
||||
: (`string`) The HTML `title` attribute of the rendered menu entry.
|
||||
|
||||
weight
|
||||
: (`int`) A non-zero integer indicating the entry's position relative the root of the menu, or to its parent for a child entry. Lighter entries float to the top, while heavier entries sink to the bottom.
|
||||
|
||||
### Example {#example-front-matter}
|
||||
|
||||
This front matter menu entry demonstrates some of the available properties:
|
||||
|
||||
{{< code-toggle file="content/products/software.md" copy=false fm=true >}}
|
||||
title = 'Software'
|
||||
[menu.main]
|
||||
parent = 'Products'
|
||||
weight = 20
|
||||
pre = '<i class="fa-solid fa-code"></i>'
|
||||
[menu.main.params]
|
||||
class = 'center'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
|
||||
## Define in site configuration
|
||||
|
||||
To define entries for the "main" menu:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[[menu.main]]
|
||||
name = "about hugo"
|
||||
pre = "<i class='fa fa-heart'></i>"
|
||||
weight = -110
|
||||
identifier = "about"
|
||||
url = "/about/"
|
||||
[menu.main.params]
|
||||
class = "highlight-menu-item"
|
||||
{{</ code-toggle >}}
|
||||
name = 'Home'
|
||||
pageRef = '/'
|
||||
weight = 10
|
||||
|
||||
## Render Menus
|
||||
[[menu.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 20
|
||||
|
||||
See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates.
|
||||
[[menu.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 30
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[config]: /getting-started/configuration/
|
||||
[multilingual]: /content-management/multilingual/
|
||||
[sitevars]: /variables/
|
||||
[me-props]: /variables/menus/
|
||||
This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
To define entries for the "footer" menu:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[[menu.footer]]
|
||||
name = 'Terms'
|
||||
pageRef = '/terms'
|
||||
weight = 10
|
||||
|
||||
[[menu.footer]]
|
||||
name = 'Privacy'
|
||||
pageRef = '/privacy'
|
||||
weight = 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This creates a menu structure that you can access with `site.Menus.footer` in your templates. See [menu templates] for details.
|
||||
|
||||
### Properties {#properties-site-configuration}
|
||||
|
||||
{{% note %}}
|
||||
The [properties available to entries defined in front matter] are also available to entries defined in site configuration.
|
||||
|
||||
[properties available to entries defined in front matter]: /content-management/menus/#properties-front-matter
|
||||
{{% /note %}}
|
||||
|
||||
Each menu entry defined in site configuration requires two or more properties:
|
||||
|
||||
- Specify `name` and `pageRef` for internal links
|
||||
- Specify `name` and `url` for external links
|
||||
|
||||
pageRef
|
||||
: (`string`) The file path of the target page, relative to the `content` directory. Omit language code and file extension. Required for *internal* links.
|
||||
|
||||
Kind|pageRef
|
||||
:--|:--
|
||||
home|`/`
|
||||
page|`/books/book-1`
|
||||
section|`/books`
|
||||
taxonomy|`/tags`
|
||||
term|`/tags/foo`
|
||||
|
||||
url
|
||||
: (`string`) Required for *external* links.
|
||||
|
||||
### Example {#example-site-configuration}
|
||||
|
||||
This nested menu demonstrates some of the available properties:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[[menu.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
|
||||
[[menu.main]]
|
||||
name = 'Hardware'
|
||||
pageRef = '/products/hardware'
|
||||
parent = 'Products'
|
||||
weight = 1
|
||||
|
||||
[[menu.main]]
|
||||
name = 'Software'
|
||||
pageRef = '/products/software'
|
||||
parent = 'Products'
|
||||
weight = 2
|
||||
|
||||
[[menu.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
|
||||
[[menu.main]]
|
||||
name = 'Hugo'
|
||||
pre = '<i class="fa fa-heart"></i>'
|
||||
url = 'https://gohugo.io/'
|
||||
weight = 30
|
||||
[menu.main.params]
|
||||
rel = 'external'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
## Localize
|
||||
|
||||
Hugo provides two methods to localize your menu entries. See [multilingual].
|
||||
|
||||
## Render
|
||||
|
||||
See [menu templates].
|
||||
|
||||
[localize]: /content-management/multilingual/#menus
|
||||
[menu templates]: /templates/menu-templates/
|
||||
[multilingual]: /content-management/multilingual/#menus
|
||||
[template]: /templates/menu-templates/
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/]
|
|||
|
||||
You should define the available languages in a `languages` section in your site configuration.
|
||||
|
||||
> Also See [Hugo Multilingual Part 1: Content translation]
|
||||
Also See [Hugo Multilingual Part 1: Content translation].
|
||||
|
||||
## Configure Languages
|
||||
|
||||
|
|
@ -69,6 +69,35 @@ Only the obvious non-global options can be overridden per language. Examples of
|
|||
|
||||
**Please note:** use lowercase language codes, even when using regional languages (ie. use pt-pt instead of pt-PT). Currently Hugo language internals lowercase language codes, which can cause conflicts with settings like `defaultContentLanguage` which are not lowercased. Please track the evolution of this issue in [Hugo repository issue tracker](https://github.com/gohugoio/hugo/issues/7344)
|
||||
|
||||
### Changes in Hugo 0.112.0
|
||||
|
||||
{{< new-in "0.112.0" >}}
|
||||
|
||||
In version `0.112.0` of Hugo we did a major we consolidated all configuration options, but also improved how the languages and their params gets merged with the main configuration. But while testing this on Hugo sites out there, we got some error reports.
|
||||
|
||||
1. `site.Language.Params` is deprecated. Use `site.Params` directly.
|
||||
1. The `params` sections on site and language is the only place to put custom user parameters, and `site.Params` will only contain these user defined parameters (see example below).
|
||||
|
||||
```toml
|
||||
title = "My blog"
|
||||
languageCode = "en-us"
|
||||
|
||||
[languages]
|
||||
[languages.sv]
|
||||
title = "Min blogg"
|
||||
languageCode = "sv"
|
||||
[languages.en.params]
|
||||
color = "blue"
|
||||
```
|
||||
|
||||
In the example above, all the settings exept the `color` below `params` maps to predefined configuration options in Hguo for the site and its language, and should be accessed via the documented accessors:
|
||||
|
||||
```
|
||||
{{ site.Title }}
|
||||
{{ site.LanguageCode }}
|
||||
{{ site.Params.color }}
|
||||
```
|
||||
|
||||
### Disable a Language
|
||||
|
||||
You can disable one or more languages. This can be useful when working on a new translation.
|
||||
|
|
@ -97,7 +126,9 @@ From **Hugo 0.31** we support multiple languages in a multihost configuration. S
|
|||
|
||||
This means that you can now configure a `baseURL` per `language`:
|
||||
|
||||
> If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different.
|
||||
{{% note %}}
|
||||
If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different.
|
||||
{{% /note %}}
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -155,9 +186,9 @@ Their language is __assigned__ according to the language code added as a __suffi
|
|||
|
||||
By having the same **path and base filename**, the content pieces are __linked__ together as translated pages.
|
||||
|
||||
{{< note >}}
|
||||
{{% note %}}
|
||||
If a file has no language code, it will be assigned the default language.
|
||||
{{</ note >}}
|
||||
{{% /note %}}
|
||||
|
||||
### Translation by content directory
|
||||
|
||||
|
|
@ -209,16 +240,22 @@ By setting the `translationKey` front matter param to `about` in all three pages
|
|||
|
||||
Because paths and filenames are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory).
|
||||
|
||||
To localize the URLs, the [`slug`]({{< ref "/content-management/organization/index.md#slug" >}}) or [`url`]({{< ref "/content-management/organization/index.md#url" >}}) front matter param can be set in any of the non-default language file.
|
||||
To localize URLs:
|
||||
|
||||
For example, a French translation (`content/about.fr.md`) can have its own localized slug.
|
||||
- For a regular page, set either [`slug`] or [`url`] in front matter
|
||||
- For a section page, set [`url`] in front matter
|
||||
|
||||
{{< code-toggle >}}
|
||||
Title: A Propos
|
||||
[`slug`]: /content-management/urls/#slug
|
||||
[`url`]: /content-management/urls/#url
|
||||
|
||||
For example, a French translation can have its own localized slug.
|
||||
|
||||
{{< code-toggle file="content/about.fr.md" fm=true copy=false >}}
|
||||
title: A Propos
|
||||
slug: "a-propos"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
At render, Hugo will build both `/about/` and `/fr/a-propos/` while maintaining their translation linking.
|
||||
At render, Hugo will build both `/about/` and `/fr/a-propos/` without affecting the translation link.
|
||||
|
||||
### Page Bundles
|
||||
|
||||
|
|
@ -338,7 +375,7 @@ The function will read `.Count` from `.ReadingTime` and evaluate whether the num
|
|||
{{< code-toggle file="i18n/en-US" >}}
|
||||
[readingTime]
|
||||
one = "One minute to read"
|
||||
other = "{{.Count}} minutes to read"
|
||||
other = "{{ .Count }} minutes to read"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Assuming `.ReadingTime.Count` in the context has value is 525600. The result will be:
|
||||
|
|
@ -462,76 +499,91 @@ See [lang.FormatPercent] for details.
|
|||
|
||||
## Menus
|
||||
|
||||
You can define your menus for each language independently. Creating multilingual menus works just like [creating regular menus][menus], except they're defined in language-specific blocks in the configuration file:
|
||||
Localization of menu entries depends on the how you define them:
|
||||
|
||||
{{< code-toggle file="config" >}}
|
||||
defaultContentLanguage = "en"
|
||||
- When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry.
|
||||
- When you define menu entries [in front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry.
|
||||
- When you define menu entries [in site configuration], you can (a) use translation tables, or (b) create language-specific menu entries under each language key.
|
||||
|
||||
[languages.en]
|
||||
weight = 0
|
||||
languageName = "English"
|
||||
### Use translation tables
|
||||
|
||||
[[languages.en.menu.main]]
|
||||
url = "/"
|
||||
name = "Home"
|
||||
weight = 0
|
||||
|
||||
[languages.de]
|
||||
weight = 10
|
||||
languageName = "Deutsch"
|
||||
|
||||
[[languages.de.menu.main]]
|
||||
url = "/"
|
||||
name = "Startseite"
|
||||
weight = 0
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu in the current language. Note that `absLangURL` below will link to the correct locale of your website. Without it, menu entries in all languages would link to the English version, since it's the default content language that resides in the root directory.
|
||||
When rendering the text that appears in menu each entry, the [example menu template] does this:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{- $currentPage := . -}}
|
||||
{{ range .Site.Menus.main -}}
|
||||
<li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
|
||||
<a href="{{ .URL | absLangURL }}">{{ .Name }}</a>
|
||||
</li>
|
||||
{{- end }}
|
||||
</ul>
|
||||
{{ or (T .Identifier) .Name | safeHTML }}
|
||||
```
|
||||
|
||||
### Dynamically localizing menus with i18n
|
||||
It queries the translation table for the current language using the menu entry's `identifier` and returns the translated string. If the translation table does not exist, or if the `identifier` key is not present in the translation table, it falls back to `name`.
|
||||
|
||||
While customizing menus per language is useful, your config file can become hard to maintain if you have a lot of languages
|
||||
The `identifier` depends on how you define menu entries:
|
||||
|
||||
If your menus are the same in all languages (ie. if the only thing that changes is the translated name) you can use the `.Identifier` as a translation key for the menu name:
|
||||
- If you define the menu entry [automatically] using the section pages menu, the `identifier` is the page's `.Section`.
|
||||
- If you define the menu entry [in site configuration] or [in front matter], set the `identifier` property to the desired value.
|
||||
|
||||
{{< code-toggle file="config" >}}
|
||||
For example, if you define menu entries in site configuration:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[[menu.main]]
|
||||
name = "About me"
|
||||
url = "about"
|
||||
identifier = 'products'
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
[[menu.main]]
|
||||
identifier = 'services'
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
{{< / code-toggle >}}
|
||||
|
||||
Create corresponding entries in the translation tables:
|
||||
|
||||
{{< code-toggle file="i18n/de" copy=false >}}
|
||||
products = 'Produkte'
|
||||
services = 'Leistungen'
|
||||
{{< / code-toggle >}}
|
||||
|
||||
[example menu template]: /templates/menu-templates/#example
|
||||
[automatically]: /content-management/menus/#define-automatically
|
||||
[in front matter]: /content-management/menus/#define-in-front-matter
|
||||
[in site configuration]: /content-management/menus/#define-in-site-configuration
|
||||
|
||||
### Create language-specific menu entries
|
||||
|
||||
For example:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[languages.de]
|
||||
languageCode = 'de-DE'
|
||||
languageName = 'Deutsch'
|
||||
weight = 1
|
||||
identifier = "about"
|
||||
|
||||
[[languages.de.menu.main]]
|
||||
name = 'Produkte'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
|
||||
[[languages.de.menu.main]]
|
||||
name = 'Leistungen'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
|
||||
[languages.en]
|
||||
languageCode = 'en-US'
|
||||
languageName = 'English'
|
||||
weight = 2
|
||||
|
||||
[[languages.en.menu.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
|
||||
[[languages.en.menu.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
You now need to specify the translations for the menu keys in the i18n files:
|
||||
|
||||
{{< code file="i18n/pt.toml" >}}
|
||||
[about]
|
||||
other="Sobre mim"
|
||||
{{< /code >}}
|
||||
|
||||
And do the appropriate changes in the menu code to use the `i18n` tag with the `.Identifier` as a key. You will also note that here we are using a `default` to fall back to `.Name`, in case the `.Identifier` key is also not present in the language specified in the `defaultContentLanguage` configuration.
|
||||
|
||||
{{< code file="layouts/partials/menu.html" >}}
|
||||
<ul>
|
||||
{{- $currentPage := . -}}
|
||||
{{ range .Site.Menus.main -}}
|
||||
<li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
|
||||
<a href="{{ .URL | absLangURL }}">{{ i18n .Identifier | default .Name}}</a>
|
||||
</li>
|
||||
{{- end }}
|
||||
</ul>
|
||||
{{< /code >}}
|
||||
For a simple menu with two languages, these menu entries are easy to create and maintain. For a larger menu, or with more than two languages, using translation tables as described above is preferable.
|
||||
|
||||
## Missing Translations
|
||||
|
||||
|
|
@ -586,11 +638,11 @@ hugo new content/de/post/test.md
|
|||
[homepage]: /templates/homepage/
|
||||
[Hugo Multilingual Part 1: Content translation]: https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/
|
||||
[i18func]: /functions/i18n/
|
||||
[lang.FormatAccounting]: /functions/lang/#langformataccounting
|
||||
[lang.FormatCurrency]: /functions/lang/#langformatcurrency
|
||||
[lang.FormatNumber]: /functions/lang/#langformatnumber
|
||||
[lang.FormatNumberCustom]: /functions/lang/#langformatnumbercustom
|
||||
[lang.FormatPercent]: /functions/lang/#langformatpercent
|
||||
[lang.FormatAccounting]: /functions/lang
|
||||
[lang.FormatCurrency]: /functions/lang
|
||||
[lang.FormatNumber]: /functions/lang
|
||||
[lang.FormatNumberCustom]: /functions/lang
|
||||
[lang.FormatPercent]: /functions/lang
|
||||
[lang.Merge]: /functions/lang.merge/
|
||||
[menus]: /content-management/menus/
|
||||
[OS environment]: /getting-started/configuration/#configure-with-environment-variables
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ aliases: [/content/sections/]
|
|||
|
||||
Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`.
|
||||
|
||||
These terms are connected, and you also need to read about [Page Resources]({{< relref "/content-management/page-resources" >}}) and [Image Processing]({{< relref "/content-management/image-processing" >}}) to get the full picture.
|
||||
These terms are connected, and you also need to read about [Page Resources](/content-management/page-resources) and [Image Processing](/content-management/image-processing) to get the full picture.
|
||||
|
||||
{{< imgproc 1-featured Resize "300x" >}}
|
||||
The illustration shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed.
|
||||
|
|
@ -131,10 +131,7 @@ A default content type is determined by the section in which a content item is s
|
|||
|
||||
### `slug`
|
||||
|
||||
A content's `slug` is either `name.extension` or `name/`. The value for `slug` is determined by
|
||||
|
||||
* the name of the content file (e.g., `lollapalooza.md`) OR
|
||||
* front matter overrides
|
||||
The `slug` is the last segment of the URL path, defined by the file name and optionally overridden by a `slug` value in front matter. See [URL Management](/content-management/urls/#slug) for details.
|
||||
|
||||
### `path`
|
||||
|
||||
|
|
@ -145,78 +142,7 @@ A content's `path` is determined by the section's path to the file. The file `pa
|
|||
|
||||
### `url`
|
||||
|
||||
The `url` is the relative URL for the piece of content. The `url`
|
||||
|
||||
* is based on the content item's location within the directory structure OR
|
||||
* is defined in front matter, in which case it *overrides all the above*
|
||||
|
||||
## Override Destination Paths via Front Matter
|
||||
|
||||
Hugo assumes that your content is organized with a purpose. The same structure that you use to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored at the destination.
|
||||
|
||||
There are times when you may need more fine-grained control over the content organization. In such cases, the front matter field can be used to determine the destination of a specific piece of content.
|
||||
|
||||
The following items are defined in a specific order for a reason: items explained lower down in the list override higher items. Note that not all items can be defined in front matter.
|
||||
|
||||
### `filename`
|
||||
|
||||
`filename` is not a front matter field. It is the actual file name, minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `example.com/posts/my-post/`).
|
||||
|
||||
### `slug`
|
||||
|
||||
When defined in the front matter, the `slug` can take the place of the filename in the destination.
|
||||
|
||||
{{< code file="content/posts/old-post.md" >}}
|
||||
---
|
||||
title: A new post with the filename old-post.md
|
||||
slug: "new-post"
|
||||
---
|
||||
{{< /code >}}
|
||||
|
||||
This will render to the following destination according to Hugo's default behavior:
|
||||
|
||||
```txt
|
||||
example.com/posts/new-post/
|
||||
```
|
||||
|
||||
### `section`
|
||||
|
||||
`section` is determined by a content item's location on disk and *cannot* be specified in the front matter. See [sections] for more information.
|
||||
|
||||
### `type`
|
||||
|
||||
A content item's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types]. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at `layouts/new/mylayout.html` that Hugo will use to render this piece of content, even in the midst of many other posts.
|
||||
|
||||
{{< code file="content/posts/my-post.md" >}}
|
||||
---
|
||||
title: My Post
|
||||
type: new
|
||||
layout: mylayout
|
||||
---
|
||||
{{< /code >}}
|
||||
<!-- See https://discourse.gohugo.io/t/path-not-works/6387 -->
|
||||
<!-- ### `path`-->
|
||||
|
||||
<!--`path` can be provided in the front matter. This will replace the actual path to the file on disk. Destination will create the destination with the same path, including the section. -->
|
||||
|
||||
### `url`
|
||||
|
||||
A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a `/`). `url` will be used exactly as it is defined in the front matter, and will ignore the `--uglyURLs` setting in your site configuration:
|
||||
|
||||
{{< code file="content/posts/old-url.md" >}}
|
||||
---
|
||||
title: Old URL
|
||||
url: /blog/new-url/
|
||||
---
|
||||
{{< /code >}}
|
||||
|
||||
Assuming your `baseURL` is [configured][config] to `https://example.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination:
|
||||
|
||||
```txt
|
||||
https://example.com/blog/new-url/
|
||||
```
|
||||
|
||||
You can see more information on how to control output paths in [URL Management][urls].
|
||||
The `url` is the entire URL path, defined by the file path and optionally overridden by a `url` value in front matter. See [URL Management](/content-management/urls/#slug) for details.
|
||||
|
||||
[config]: /getting-started/configuration/
|
||||
[formats]: /content-management/formats/
|
||||
|
|
@ -225,7 +151,7 @@ You can see more information on how to control output paths in [URL Management][
|
|||
[homepage template]: /templates/homepage/
|
||||
[homepage]: /templates/homepage/
|
||||
[lists]: /templates/lists/
|
||||
[pretty]: /content-management/urls/#pretty-urls
|
||||
[pretty]: /content-management/urls/#appearance
|
||||
[section templates]: /templates/section-templates/
|
||||
[sections]: /content-management/sections/
|
||||
[singles]: /templates/single-page-templates/
|
||||
|
|
|
|||
|
|
@ -1,14 +1,11 @@
|
|||
---
|
||||
title: Page Bundles
|
||||
linkTitle: Page Bundles
|
||||
description: Content organization using Page Bundles
|
||||
linkTitle: Page Bundles
|
||||
keywords: [page, bundle, leaf, branch]
|
||||
categories: [content management]
|
||||
menu :
|
||||
docs:
|
||||
identifier: "page-bundles"
|
||||
parent: "content-management"
|
||||
parent: content-management
|
||||
weight: 30
|
||||
toc: true
|
||||
weight: 30
|
||||
|
|
@ -132,9 +129,9 @@ Explanation of the above example:
|
|||
A leaf bundle can be made headless by adding below in the Front Matter
|
||||
(in the `index.md`):
|
||||
|
||||
```toml
|
||||
{{< code-toggle file="content/headless/index.md" fm=true copy=false >}}
|
||||
headless = true
|
||||
```
|
||||
{{< /code-toggle >}}
|
||||
|
||||
There are many use cases of such headless page bundles:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: Page Resources
|
||||
linkTitle: Page Resources
|
||||
description: Page resources -- images, other pages, documents, etc. -- have page-relative URLs and their own metadata.
|
||||
categories: [content management]
|
||||
keywords: [bundle,content,resources]
|
||||
|
|
@ -11,8 +10,7 @@ menu:
|
|||
toc: true
|
||||
weight: 80
|
||||
---
|
||||
Page resources are only accessible from [page bundles]({{< relref
|
||||
"/content-management/page-bundles" >}}), those directories with `index.md` or
|
||||
Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or
|
||||
`_index.md` files at their root. Page resources are only available to the
|
||||
page with which they are bundled.
|
||||
|
||||
|
|
@ -128,9 +126,9 @@ Resources of type `page` get `Title` etc. from their own front matter.
|
|||
name
|
||||
: Sets the value returned in `Name`.
|
||||
|
||||
{{% warning %}}
|
||||
{{% note %}}
|
||||
The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources.
|
||||
{{%/ warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
title
|
||||
: Sets the value returned in `Title`
|
||||
|
|
@ -140,7 +138,7 @@ params
|
|||
|
||||
### Resources metadata example
|
||||
|
||||
{{< code-toggle copy="false">}}
|
||||
{{< code-toggle copy=false >}}
|
||||
title: Application
|
||||
date : 2018-01-25
|
||||
resources :
|
||||
|
|
@ -174,9 +172,9 @@ From the example above:
|
|||
- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`.
|
||||
- Every docx in the bundle will receive the `word` icon.
|
||||
|
||||
{{% warning %}}
|
||||
{{% note %}}
|
||||
The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
|
||||
{{%/ warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
### The `:counter` placeholder in `name` and `title`
|
||||
|
||||
|
|
@ -186,7 +184,7 @@ The counter starts at 1 the first time they are used in either `name` or `title`
|
|||
|
||||
For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as:
|
||||
|
||||
{{< code-toggle copy="false">}}
|
||||
{{< code-toggle copy=false >}}
|
||||
[[resources]]
|
||||
src = "*specs.pdf"
|
||||
title = "Specification #:counter"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: Related Content
|
||||
linkTitle: Related Content
|
||||
description: List related content in "See Also" sections.
|
||||
categories: [content management]
|
||||
keywords: [content]
|
||||
|
|
@ -67,8 +66,7 @@ We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 di
|
|||
|
||||
Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration:
|
||||
|
||||
|
||||
```toml
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[related]
|
||||
threshold = 20
|
||||
includeNewer = true
|
||||
|
|
@ -78,7 +76,7 @@ name = "fragmentrefs"
|
|||
type = "fragments"
|
||||
applyFilter = false
|
||||
weight = 80
|
||||
```
|
||||
{{< /code-toggle >}}
|
||||
|
||||
* The `name` maps to a optional front matter slice attribute that can be used to link from the page level down to the fragment/heading level.
|
||||
* If `applyFilter`is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing:
|
||||
|
|
|
|||
|
|
@ -2,9 +2,6 @@
|
|||
title: Content Sections
|
||||
linkTitle: Sections
|
||||
description: Hugo generates a **section tree** that matches your content.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [content management]
|
||||
keywords: [lists,sections,content types,organization]
|
||||
menu:
|
||||
|
|
@ -62,17 +59,19 @@ If you need a specific template for a sub-section, you need to adjust either the
|
|||
|
||||
With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation:
|
||||
|
||||
{{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}}
|
||||
<ol class="nav navbar-nav">
|
||||
<ul>
|
||||
{{- range .Ancestors.Reverse }}
|
||||
<li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
|
||||
{{- end }}
|
||||
<li class="active" aria-current="page">
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
</li>
|
||||
</ul>
|
||||
</ol>
|
||||
{{< code file="layouts/partials/breadcrumb.html" >}}
|
||||
<nav aria-label="breadcrumb">
|
||||
<ol>
|
||||
{{ range .Ancestors.Reverse }}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
<li class="active">
|
||||
<a aria-current="page" href="{{ .Permalink }}">{{ .LinkTitle }}</a>
|
||||
</li>
|
||||
</ol>
|
||||
</nav>
|
||||
{{< /code >}}
|
||||
|
||||
## Section Page Variables and Methods
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: Shortcodes
|
||||
linkTitle: Shortcodes
|
||||
description: Shortcodes are simple snippets inside your content files calling built-in or custom templates.
|
||||
categories: [content management]
|
||||
keywords: [markdown,content,shortcodes]
|
||||
|
|
@ -129,130 +128,129 @@ attrlink
|
|||
#### Example `figure` Input
|
||||
|
||||
{{< code file="figure-input-example.md" >}}
|
||||
{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
|
||||
{{</* figure src="elephant.jpg" title=">An elephant at sunset" */>}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `figure` Output
|
||||
|
||||
{{< output file="figure-output-example.html" >}}
|
||||
```html
|
||||
<figure>
|
||||
<img src="/media/spf13.jpg" />
|
||||
<figcaption>
|
||||
<h4>Steve Francia</h4>
|
||||
</figcaption>
|
||||
<img src="elephant.jpg">
|
||||
<figcaption>An elephant at sunset</figcaption>
|
||||
</figure>
|
||||
{{< /output >}}
|
||||
```
|
||||
|
||||
### `gist`
|
||||
|
||||
Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]:
|
||||
To display a GitHub [gist] with this URL:
|
||||
|
||||
```txt
|
||||
https://gist.github.com/spf13/7896402
|
||||
[gist]: https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists
|
||||
|
||||
```text
|
||||
https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
|
||||
```
|
||||
|
||||
We can embed the gist in our content via username and gist ID pulled from the URL:
|
||||
Include this in your markdown:
|
||||
|
||||
```go-html-template
|
||||
{{</* gist spf13 7896402 */>}}
|
||||
```text
|
||||
{{</* gist user 50a7482715eac222e230d1e64dd9a89b */>}}
|
||||
```
|
||||
|
||||
#### Example `gist` Input
|
||||
This will display all files in the gist alphabetically by file name.
|
||||
|
||||
If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument:
|
||||
{{< gist jmooring 50a7482715eac222e230d1e64dd9a89b >}}
|
||||
|
||||
{{< code file="gist-input.md" >}}
|
||||
{{</* gist spf13 7896402 "img.html" */>}}
|
||||
{{< /code >}}
|
||||
To display a specific file within the gist:
|
||||
|
||||
#### Example `gist` Output
|
||||
```text
|
||||
{{</* gist user 50a7482715eac222e230d1e64dd9a89b 1-template.html */>}}
|
||||
```
|
||||
|
||||
{{< output file="gist-output.html" >}}
|
||||
{{< gist spf13 7896402 >}}
|
||||
{{< /output >}}
|
||||
Rendered:
|
||||
|
||||
#### Example `gist` Display
|
||||
|
||||
To demonstrate the remarkable efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will depend on your stylesheets and surrounding markup.
|
||||
|
||||
{{< gist spf13 7896402 >}}
|
||||
{{< gist jmooring 50a7482715eac222e230d1e64dd9a89b 1-template.html >}}
|
||||
|
||||
### `highlight`
|
||||
|
||||
This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/content-management/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode.
|
||||
To display a highlighted code sample:
|
||||
|
||||
#### Example `highlight` Input
|
||||
|
||||
{{< code file="content/tutorials/learn-html.md" >}}
|
||||
{{</* highlight html */>}}
|
||||
<section id="main">
|
||||
<div>
|
||||
<h1 id="title">{{ .Title }}</h1>
|
||||
{{ range .Pages }}
|
||||
{{ .Render "summary"}}
|
||||
{{ end }}
|
||||
</div>
|
||||
</section>
|
||||
```text
|
||||
{{</* highlight go-html-template */>}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{</* /highlight */>}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
#### Example `highlight` Output
|
||||
Rendered:
|
||||
|
||||
The `highlight` shortcode example above would produce the following HTML when the site is rendered:
|
||||
{{< highlight go-html-template >}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{< /highlight >}}
|
||||
|
||||
{{< output file="tutorials/learn-html/index.html" >}}
|
||||
<span style="color: #f92672"><section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"main"</span><span style="color: #f92672">></span>
|
||||
<span style="color: #f92672"><div></span>
|
||||
<span style="color: #f92672"><h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"title"</span><span style="color: #f92672">></span>{{ .Title }}<span style="color: #f92672"></h1></span>
|
||||
{{ range .Pages }}
|
||||
{{ .Render "summary"}}
|
||||
{{ end }}
|
||||
<span style="color: #f92672"></div></span>
|
||||
<span style="color: #f92672"></section></span>
|
||||
{{< /output >}}
|
||||
To specify one or more [highlighting options], include a quotation-encapsulated, comma-separated list:
|
||||
|
||||
{{% note "More on Syntax Highlighting" %}}
|
||||
To see even more options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting in Developer Tools](/tools/syntax-highlighting/).
|
||||
{{% /note %}}
|
||||
[highlighting options]: /functions/highlight/
|
||||
|
||||
```text
|
||||
{{</* highlight go-html-template "lineNos=inline, lineNoStart=42" */>}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{</* /highlight */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{< /highlight >}}
|
||||
|
||||
### `instagram`
|
||||
|
||||
If you'd like to embed a photo from [Instagram], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
|
||||
The `instagram` shortcode uses Facebook's **oEmbed Read** feature. The Facebook [developer documentation] states:
|
||||
|
||||
```txt
|
||||
- This permission or feature requires successful completion of the App Review process before your app can access live data. [Learn More]
|
||||
- This permission or feature is only available with business verification. You may also need to sign additional contracts before your app can access data. [Learn More Here]
|
||||
|
||||
[developer documentation]: https://developers.facebook.com/docs/features-reference/oembed-read
|
||||
[Learn More]: https://developers.facebook.com/docs/app-review
|
||||
[Learn More Here]: https://developers.facebook.com/docs/development/release/business-verification
|
||||
|
||||
You must obtain an Access Token to use the `instagram` shortcode.
|
||||
|
||||
If your site configuration is private:
|
||||
|
||||
{{< code-toggle file=config copy=false >}}
|
||||
[services.instagram]
|
||||
accessToken = 'xxx'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
If your site configuration is _not_ private, set the Access Token with an environment variable:
|
||||
|
||||
```text
|
||||
HUGO_SERVICES_INSTAGRAM_ACCESSTOKEN=xxx hugo --gc --minify
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
If you are using a Client Access Token, you must combine the Access Token with your App ID using a pipe symbol (`APPID|ACCESSTOKEN`).
|
||||
{{% /note %}}
|
||||
|
||||
To display an Instagram post with this URL:
|
||||
|
||||
```text
|
||||
https://www.instagram.com/p/BWNjjyYFxVx/
|
||||
```
|
||||
|
||||
#### Example `instagram` Input
|
||||
Include this in your markdown:
|
||||
|
||||
{{< code file="instagram-input.md" >}}
|
||||
```text
|
||||
{{</* instagram BWNjjyYFxVx */>}}
|
||||
{{< /code >}}
|
||||
|
||||
You also have the option to hide the caption:
|
||||
|
||||
{{< code file="instagram-input-hide-caption.md" >}}
|
||||
{{</* instagram BWNjjyYFxVx hidecaption */>}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `instagram` Output
|
||||
|
||||
By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup:
|
||||
|
||||
{{< output file="instagram-hide-caption-output.html" >}}
|
||||
{{< instagram BWNjjyYFxVx hidecaption >}}
|
||||
{{< /output >}}
|
||||
|
||||
#### Example `instagram` Display
|
||||
|
||||
Using the preceding `instagram` with `hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your style sheets and surrounding markup.
|
||||
|
||||
{{< instagram BWNjjyYFxVx hidecaption >}}
|
||||
|
||||
|
||||
{{% note %}}
|
||||
The `instagram`-shortcode refers an endpoint of Instagram's API, that's deprecated since October 24th, 2020. Thus, no images can be fetched from this API endpoint, resulting in an error when the `instagram`-shortcode is used. For more information please have a look at GitHub issue [#7879](https://github.com/gohugoio/hugo/issues/7879).
|
||||
{{% /note %}}
|
||||
```
|
||||
|
||||
### `param`
|
||||
|
||||
|
|
@ -278,7 +276,7 @@ These shortcodes will look up the pages by their relative path (e.g., `blog/post
|
|||
|
||||
`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
|
||||
|
||||
{{% note "More on Cross References" %}}
|
||||
{{% note %}}
|
||||
Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
|
||||
{{% /note %}}
|
||||
|
||||
|
|
@ -302,71 +300,47 @@ Assuming that standard Hugo pretty URLs are turned on.
|
|||
|
||||
### `tweet`
|
||||
|
||||
You want to include a single tweet into your blog post? Everything you need is the URL of the tweet:
|
||||
To display a Twitter post with this URL:
|
||||
|
||||
```txt
|
||||
https://twitter.com/SanDiegoZoo/status/1453110110599868418
|
||||
```
|
||||
|
||||
#### Example `tweet` Input
|
||||
Include this in your markdown:
|
||||
|
||||
Pass the tweet's user (case-insensitive) and ID from the URL as parameters to the `tweet` shortcode.
|
||||
|
||||
{{< code file="example-tweet-input.md" >}}
|
||||
```text
|
||||
{{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
#### Example `tweet` Output
|
||||
|
||||
Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup:
|
||||
|
||||
{{< output file="example-tweet-output.html" >}}
|
||||
{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}
|
||||
{{< /output >}}
|
||||
|
||||
#### Example `tweet` Display
|
||||
|
||||
Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
|
||||
Rendered:
|
||||
|
||||
{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}
|
||||
|
||||
### `vimeo`
|
||||
|
||||
Adding a video from [Vimeo] is equivalent to the [YouTube Input shortcode].
|
||||
To display a Vimeo video with this URL:
|
||||
|
||||
```txt
|
||||
https://vimeo.com/channels/staffpicks/146022717
|
||||
```text
|
||||
https://vimeo.com/channels/staffpicks/55073825
|
||||
```
|
||||
|
||||
#### Example `vimeo` Input
|
||||
Include this in your markdown:
|
||||
|
||||
Extract the ID from the video's URL and pass it to the `vimeo` shortcode:
|
||||
```text
|
||||
{{</* vimeo 55073825 */>}}
|
||||
```
|
||||
|
||||
{{< code file="example-vimeo-input.md" >}}
|
||||
{{</* vimeo 146022717 */>}}
|
||||
{{< /code >}}
|
||||
Rendered:
|
||||
|
||||
#### Example `vimeo` Output
|
||||
{{< vimeo 55073825 >}}
|
||||
|
||||
Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup:
|
||||
|
||||
{{< output file="example-vimeo-output.html" >}}
|
||||
{{< vimeo 146022717 >}}
|
||||
{{< /output >}}
|
||||
|
||||
{{% tip %}}
|
||||
{{% note %}}
|
||||
If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
|
||||
|
||||
```go
|
||||
{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
|
||||
```
|
||||
{{% /tip %}}
|
||||
|
||||
#### Example `vimeo` Display
|
||||
|
||||
Using the preceding `vimeo` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
|
||||
|
||||
{{< vimeo 146022717 >}}
|
||||
{{% /note %}}
|
||||
|
||||
### `youtube`
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ This union filesystem will be served from your site root. So a file
|
|||
Here's an example of setting `staticDir` and `staticDir2` for a
|
||||
multi-language site:
|
||||
|
||||
{{< code-toggle copy="false" file="config" >}}
|
||||
{{< code-toggle copy=false file="config" >}}
|
||||
staticDir = ["static1", "static2"]
|
||||
|
||||
[languages]
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ For [Org mode content][org], use `# more` where you want to split the article.
|
|||
|
||||
Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact.
|
||||
|
||||
{{% note "Summary Divider"%}}
|
||||
{{% note %}}
|
||||
The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature.
|
||||
{{% /note %}}
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ Cons
|
|||
|
||||
{{% warning "Be Precise with the Summary Divider" %}}
|
||||
Be careful to enter <code><!--more--></code> exactly; i.e., all lowercase and with no whitespace.
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
### Front Matter Summary
|
||||
|
||||
|
|
@ -77,7 +77,7 @@ Because there are multiple ways in which a summary can be specified it is useful
|
|||
|
||||
{{% warning "Competing selections" %}}
|
||||
Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a <code><!--more--></code> summary divider Hugo will use the manual summary split method.
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
## Example: First 10 Articles with Summaries
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: Syntax Highlighting
|
||||
linkTitle: Syntax Highlighting
|
||||
description: Hugo comes with really fast syntax highlighting from Chroma.
|
||||
keywords: [highlighting,chroma,code blocks,syntax]
|
||||
categories: [content management]
|
||||
|
|
@ -131,7 +130,7 @@ func GetTitleFunc(style string) func(s string) string {
|
|||
}
|
||||
```
|
||||
|
||||
The options are the same as in the [highlighting shortcode](/content-management/syntax-highlighting/#highlight-shortcode),including `linenos=false`, but note the slightly different Markdown attribute syntax.
|
||||
The options are the same as in the [highlighting shortcode](/content-management/syntax-highlighting/#highlight-shortcode), including `linenos=false`, but note the slightly different Markdown attribute syntax.
|
||||
|
||||
## List of Chroma Highlighting Languages
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: Taxonomies
|
||||
linkTitle: Taxonomies
|
||||
description: Hugo includes support for user-defined taxonomies.
|
||||
keywords: [taxonomies,metadata,front matter,terms]
|
||||
categories: [content management]
|
||||
|
|
@ -83,7 +82,7 @@ Hugo natively supports taxonomies.
|
|||
|
||||
Without adding a single line to your [site config][config] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be the same as manually [configuring your taxonomies](#configure-taxonomies) as below:
|
||||
|
||||
{{< code-toggle copy="false" >}}
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[taxonomies]
|
||||
tag = "tags"
|
||||
category = "categories"
|
||||
|
|
@ -91,7 +90,7 @@ Without adding a single line to your [site config][config] file, Hugo will autom
|
|||
|
||||
If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site config][config] to the following:
|
||||
|
||||
{{< code-toggle copy="false" >}}
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
disableKinds = ["taxonomy","term"]
|
||||
{{</ code-toggle >}}
|
||||
|
||||
|
|
@ -106,7 +105,7 @@ When taxonomies are used---and [taxonomy templates] are provided---Hugo will aut
|
|||
|
||||
## Configure Taxonomies
|
||||
|
||||
Custom taxonomies other than the [defaults]({{< relref "taxonomies.md#default-taxonomies" >}}) must be defined in your [site config][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
|
||||
Custom taxonomies other than the [defaults](#default-taxonomies) must be defined in your [site config][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
|
||||
|
||||
### Example: Adding a custom taxonomy named "series"
|
||||
|
||||
|
|
@ -114,7 +113,7 @@ Custom taxonomies other than the [defaults]({{< relref "taxonomies.md#default-ta
|
|||
While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_.
|
||||
{{% /note %}}
|
||||
|
||||
{{< code-toggle copy="false" >}}
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[taxonomies]
|
||||
tag = "tags"
|
||||
category = "categories"
|
||||
|
|
@ -125,12 +124,12 @@ While adding custom taxonomies, you need to put in the default taxonomies too, _
|
|||
|
||||
If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so by modifying the `taxonomies` value in your [site config][config].
|
||||
|
||||
{{< code-toggle copy="false" >}}
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[taxonomies]
|
||||
tag = "tags"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults]({{< relref "taxonomies.md#default-taxonomies" >}}).
|
||||
If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies).
|
||||
|
||||
{{% note %}}
|
||||
You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
|
||||
|
|
@ -138,11 +137,11 @@ You can add content and front matter to your taxonomy list and taxonomy terms pa
|
|||
Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not.
|
||||
{{% /note %}}
|
||||
|
||||
{{% warning %}}
|
||||
{{% note %}}
|
||||
The configuration option `preserveTaxonomyNames` was removed in Hugo 0.55.
|
||||
|
||||
You can now use `.Page.Title` on the relevant taxonomy node to get the original value.
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
## Add Taxonomies to Content
|
||||
|
||||
|
|
@ -156,7 +155,7 @@ If you would like the ability to quickly generate content files with preconfigur
|
|||
|
||||
### Example: Front Matter with Taxonomies
|
||||
|
||||
{{< code-toggle copy="false">}}
|
||||
{{< code-toggle file="content/example.md" fm=true copy=false >}}
|
||||
title = "Hugo: A fast and flexible static site generator"
|
||||
tags = [ "Development", "Go", "fast", "Blogging" ]
|
||||
categories = [ "Development" ]
|
||||
|
|
@ -173,7 +172,7 @@ The following show a piece of content that has a weight of 22, which can be used
|
|||
|
||||
### Example: Taxonomic `weight`
|
||||
|
||||
{{< code-toggle copy="false" >}}
|
||||
{{< code-toggle copy=false >}}
|
||||
title = "foo"
|
||||
tags = [ "a", "b", "c" ]
|
||||
tags_weight = 22
|
||||
|
|
@ -183,7 +182,7 @@ categories_weight = 44
|
|||
|
||||
By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies.
|
||||
|
||||
{{% note "Limits to Ordering Taxonomies" %}}
|
||||
{{% note %}}
|
||||
Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight--date--linktitle--filepath). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/).
|
||||
{{% /note %}}
|
||||
|
||||
|
|
@ -191,13 +190,10 @@ Currently taxonomies only support the [default `weight => date` ordering of list
|
|||
|
||||
If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter. Continuing with our 'Actors' example, let's say you want to add a Wikipedia page link to each actor. Your terms pages would be something like this:
|
||||
|
||||
{{< code file="/content/actors/bruce-willis/_index.md" >}}
|
||||
---
|
||||
{{< code-toggle file="content/actors/bruce-willis/_index.md" fm=true copy=false >}}
|
||||
title: "Bruce Willis"
|
||||
wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
|
||||
---
|
||||
{{< /code >}}
|
||||
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[`urlize` template function]: /functions/urlize/
|
||||
[content section]: /content-management/sections/
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: Table of Contents
|
||||
linkTitle: Table of Contents
|
||||
description: Hugo can automatically parse Markdown content and create a Table of Contents you can use in your templates.
|
||||
categories: [content management]
|
||||
keywords: [table of contents, toc]
|
||||
|
|
@ -13,9 +12,9 @@ weight: 210
|
|||
aliases: [/extras/toc/]
|
||||
---
|
||||
|
||||
{{% note "TOC Heading Levels are Fixed" %}}
|
||||
{{% note %}}
|
||||
|
||||
Previously, there was no out-of-the-box way to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `<nav id="TableOfContents"><ul></ul></nav>` was going to start at `<h1>` when pulling from `{{.Content}}`.
|
||||
Previously, there was no out-of-the-box way to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `<nav id="TableOfContents"><ul></ul></nav>` was going to start at `<h1>` when pulling from `{{ .Content }}`.
|
||||
|
||||
Hugo [v0.60.0](https://github.com/gohugoio/hugo/releases/tag/v0.60.0) made a switch to [Goldmark](https://github.com/yuin/goldmark/) as the default library for Markdown which has improved and configurable implementation of TOC. Take a look at [how to configure TOC](/getting-started/configuration-markup/#table-of-contents) for Goldmark renderer.
|
||||
|
||||
|
|
@ -49,7 +48,7 @@ The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">`
|
|||
|
||||
The following is an example of a very basic [single page template]:
|
||||
|
||||
{{< code file="layout/_default/single.html" download="single.html" >}}
|
||||
{{< code file="layout/_default/single.html" >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
<article>
|
||||
|
|
@ -69,19 +68,19 @@ The following is an example of a very basic [single page template]:
|
|||
|
||||
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals] in your templating:
|
||||
|
||||
{{< code file="layouts/partials/toc.html" download="toc.html" >}}
|
||||
{{< code file="layouts/partials/toc.html" >}}
|
||||
{{ if and (gt .WordCount 400 ) (.Params.toc) }}
|
||||
<aside>
|
||||
<header>
|
||||
<h2>{{.Title}}</h2>
|
||||
<h2>{{ .Title }}</h2>
|
||||
</header>
|
||||
{{.TableOfContents}}
|
||||
{{ .TableOfContents }}
|
||||
</aside>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{.TableOfContents}}` variable to pull from.
|
||||
With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{ .TableOfContents }}` variable to pull from.
|
||||
{{% /note %}}
|
||||
|
||||
## Usage with AsciiDoc
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: Content Types
|
||||
linkTitle: Content Types
|
||||
description: Hugo is built around content organized in sections.
|
||||
categories: [content management]
|
||||
keywords: [lists, sections, content types, types, organization]
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
---
|
||||
title: URL Management
|
||||
linkTitle: URL Management
|
||||
description: Hugo supports permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs.
|
||||
description: Control the structure and appearance of URLs through front matter entries and settings in your site configuration.
|
||||
categories: [content management]
|
||||
keywords: [aliases,redirects,permalinks,urls]
|
||||
menu:
|
||||
|
|
@ -13,46 +12,148 @@ weight: 180
|
|||
aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
|
||||
---
|
||||
|
||||
## Permalinks
|
||||
## Overview
|
||||
|
||||
The default Hugo target directory for your built website is `public/`. However, you can change this value by specifying a different `publishDir` in your [site configuration][config]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder and namespace matching its layout within the `contentdir` hierarchy.
|
||||
By default, when Hugo renders a page, the resulting URL matches the file path within the `content` directory. For example:
|
||||
|
||||
The `permalinks` option in your [site configuration][config] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option.
|
||||
```text
|
||||
content/posts/post-1.md → https://example.org/posts/post-1/
|
||||
```
|
||||
|
||||
{{% note "Default Publish and Content Folders" %}}
|
||||
These examples use the default values for `publishDir` and `contentDir`; i.e., `public` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/).
|
||||
You can change the structure and appearance of URLs with front matter values and site configuration options.
|
||||
|
||||
## Front matter
|
||||
|
||||
### `slug`
|
||||
|
||||
Set the `slug` in front matter to override the last segment of the path. The `slug` value does not affect section pages.
|
||||
|
||||
{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}}
|
||||
title = 'My First Post'
|
||||
slug = 'my-first-post'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The resulting URL will be:
|
||||
|
||||
```text
|
||||
https://example.org/posts/my-first-post/
|
||||
```
|
||||
|
||||
### `url`
|
||||
|
||||
Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages.
|
||||
|
||||
With this front matter:
|
||||
|
||||
{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}}
|
||||
title = 'My First Article'
|
||||
url = '/articles/my-first-article'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The resulting URL will be:
|
||||
|
||||
```text
|
||||
https://example.org/articles/my-first-article/
|
||||
```
|
||||
|
||||
If you include a file extension:
|
||||
|
||||
{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}}
|
||||
title = 'My First Article'
|
||||
url = '/articles/my-first-article.html'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The resulting URL will be:
|
||||
|
||||
```text
|
||||
https://example.org/articles/my-first-article.html
|
||||
```
|
||||
|
||||
In a monolingual site, a `url` value with or without a leading slash is relative to the `baseURL`.
|
||||
|
||||
In a multilingual site:
|
||||
|
||||
- A `url` value with a leading slash is relative to the `baseURL`.
|
||||
- A `url` value without a leading slash is relative to the `baseURL` plus the language prefix.
|
||||
|
||||
Site type|Front matter `url`|Resulting URL
|
||||
:--|:--|:--
|
||||
monolingual|`/about`|`https://example.org/about/`
|
||||
monolingual|`about`|`https://example.org/about/`
|
||||
multilingual|`/about`|`https://example.org/about/`
|
||||
multilingual|`about`|`https://example.org/de/about/`
|
||||
|
||||
If you set both `slug` and `url` in front matter, the `url` value takes precedence.
|
||||
|
||||
## Site configuration
|
||||
|
||||
### Permalinks
|
||||
|
||||
In your site configuration, set a URL pattern for regular pages within a top-level section. This is recursive, affecting descendant regular pages.
|
||||
|
||||
{{% note %}}
|
||||
The `permalinks` defined in your site configuration do not apply to section pages. To adjust the URL for section pages, set `url` in front matter.
|
||||
{{% /note %}}
|
||||
|
||||
For example, if one of your [sections] is called `posts` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively.
|
||||
#### Examples {#permalinks-examples}
|
||||
|
||||
### Permalinks Configuration Example
|
||||
With this content structure:
|
||||
|
||||
{{< code-toggle file="config" copy="false" >}}
|
||||
permalinks:
|
||||
posts: /:year/:month/:title/
|
||||
```text
|
||||
content/
|
||||
├── posts/
|
||||
│ ├── _index.md
|
||||
│ ├── post-1.md
|
||||
│ └── post-2.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
Create a date-based hierarchy, recursively, for regular pages within the `posts` section:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[permalinks]
|
||||
posts = '/posts/:year/:month/:title/'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Only the content under `posts/` will have the new URL structure. For example, the file `content/posts/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`.
|
||||
The structure of the published site will be:
|
||||
|
||||
To configure the `permalinks` option for pages in the "root" section, use **/** as the key:
|
||||
```text
|
||||
public/
|
||||
├── posts/
|
||||
│ ├── 2023/
|
||||
│ │ └── 03/
|
||||
│ │ ├── post-1/
|
||||
│ │ │ └── index.html
|
||||
│ │ └── post-2/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
├── favicon.ico
|
||||
└── index.html
|
||||
```
|
||||
|
||||
{{< code-toggle file="config" copy="false" >}}
|
||||
permalinks:
|
||||
/: /:year/:month/:filename/
|
||||
To create a date-based hierarchy for regular pages in the content root:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[permalinks]
|
||||
'/' = '/:year/:month/:title/'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
If the standard date-based permalink configuration does not meet your needs, you can also format URL segments using [Go time formatting directives](https://pkg.go.dev/time#Time.Format). For example, a URL structure with two digit years and month and day digits without zero padding can be accomplished with:
|
||||
{{% note %}}
|
||||
A URL pattern defined for the content root is not recursive.
|
||||
{{% /note %}}
|
||||
|
||||
{{< code-toggle file="config" copy="false" >}}
|
||||
permalinks:
|
||||
posts: /:06/:1/:2/:title/
|
||||
Use the same approach with taxonomies. For example, to omit the taxonomy segment of the URL:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[permalinks]
|
||||
'tags' = '/:title/'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
You can also configure permalinks of taxonomies with the same syntax, by using the plural form of the taxonomy instead of the section. You will probably only want to use the configuration values `:slug` or `:title`.
|
||||
Front matter `url` values take precedence over URL patterns defined in `permalinks`.
|
||||
|
||||
### Permalink Configuration Values
|
||||
#### Tokens
|
||||
|
||||
The following is a list of values that can be used in a `permalink` definition in your site `config` file. All references to time are dependent on the content's date.
|
||||
Use these tokens when defining the URL pattern. The `date` field in front matter determines the value of time-related tokens.
|
||||
|
||||
`:year`
|
||||
: the 4-digit year
|
||||
|
|
@ -93,219 +194,157 @@ The following is a list of values that can be used in a `permalink` definition i
|
|||
`:filename`
|
||||
: the content's filename (without extension)
|
||||
|
||||
Additionally, a Go time format string prefixed with `:` may be used.
|
||||
For time-related values, you can also use the layout string components defined in Go's [time package]. For example:
|
||||
|
||||
[time package]: https://pkg.go.dev/time#pkg-constants
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
permalinks:
|
||||
posts: /:06/:1/:2/:title/
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Appearance
|
||||
|
||||
The appearance of a URL is either ugly or pretty.
|
||||
|
||||
Type|Path|URL
|
||||
:--|:--|:--
|
||||
ugly|content/about.md|`https://example.org/about.html`
|
||||
pretty|content/about.md|`https://example.org/about/`
|
||||
|
||||
By default, Hugo produces pretty URLs. To generate ugly URLs, change your site configuration:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
uglyURLs = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Post-processing
|
||||
|
||||
Hugo provides two mutually exclusive configuration options to alter URLs _after_ it renders a page.
|
||||
|
||||
#### Canonical URLs
|
||||
|
||||
{{% note %}}
|
||||
This is a legacy configuration option, superseded by template functions and markdown render hooks, and will likely be [removed in a future release].
|
||||
|
||||
[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733
|
||||
{{% /note %}}
|
||||
|
||||
If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then prepends the `baseURL` to create absolute URLs.
|
||||
|
||||
```text
|
||||
<a href="/about"> → <a href="https://example.org/about/">
|
||||
<img src="/a.gif"> → <img src="https://example.org/a.gif">
|
||||
```
|
||||
|
||||
This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, this is a legacy configuration option that will likely be removed in a future release.
|
||||
|
||||
To enable:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
canonifyURLs = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Relative URLs
|
||||
|
||||
{{% note %}}
|
||||
Do not enable this option unless you are creating a serverless site, navigable via the file system.
|
||||
{{% /note %}}
|
||||
|
||||
If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then transforms the URL to be relative to the current page.
|
||||
|
||||
For example, when rendering `content/posts/post-1`:
|
||||
|
||||
```text
|
||||
<a href="/about"> → <a href="../../about">
|
||||
<img src="/a.gif"> → <img src="../../a.gif">
|
||||
```
|
||||
|
||||
This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, do not enable this option unless you are creating a serverless site.
|
||||
|
||||
To enable:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
relativeURLs = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Aliases
|
||||
|
||||
Aliases can be used to create redirects to your page from other URLs.
|
||||
Create redirects from old URLs to new URLs with aliases:
|
||||
|
||||
Aliases comes in two forms:
|
||||
- An alias with a leading slash is relative to the `baseURL`
|
||||
- An alias without a leading slash is relative to the current directory
|
||||
|
||||
1. Starting with a `/` meaning they are relative to the `BaseURL`, e.g. `/posts/my-blogpost/`
|
||||
2. They are relative to the `Page` they're defined in, e.g. `my-blogpost` or even something like `../blog/my-blogpost` (new in Hugo 0.55).
|
||||
### Examples {#alias-examples}
|
||||
|
||||
### Example: Aliases
|
||||
Change the file name of an existing page, and create an alias from the previous URL to the new URL:
|
||||
|
||||
Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following examples show how to create this field in TOML and YAML front matter, respectively.
|
||||
{{< code-toggle file="content/posts/new-file-name.md" copy=false >}}
|
||||
aliases = ['/posts/previous-file-name']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### TOML Front Matter
|
||||
Each of these directory-relative aliases is equivalent to the site-relative alias above:
|
||||
|
||||
{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
|
||||
+++
|
||||
aliases = [
|
||||
"/posts/my-original-url/",
|
||||
"/2010/01/01/even-earlier-url.html"
|
||||
]
|
||||
+++
|
||||
{{< /code >}}
|
||||
- `previous-file-name`
|
||||
- `./previous-file-name`
|
||||
- `../posts/previous-file-name`
|
||||
|
||||
#### YAML Front Matter
|
||||
You can create more than one alias to the current page:
|
||||
|
||||
{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
|
||||
---
|
||||
aliases:
|
||||
- /posts/my-original-url/
|
||||
- /2010/01/01/even-earlier-url.html
|
||||
---
|
||||
{{< /code >}}
|
||||
{{< code-toggle file="content/posts/new-file-name.md" copy=false >}}
|
||||
aliases = ['previous-file-name','original-file-name']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Now when you visit any of the locations specified in aliases---i.e., _assuming the same site domain_---you'll be redirected to the page they are specified on. For example, a visitor to `example.com/posts/my-original-url/` will be immediately redirected to `example.com/posts/my-awesome-post/`.
|
||||
In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias:
|
||||
|
||||
### Example: Aliases in Multilingual
|
||||
{{< code-toggle file="content/posts/new-file-name.de.md" copy=false >}}
|
||||
aliases = ['/de/posts/previous-file-name']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
On [multilingual sites][multilingual], each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code.
|
||||
### How Aliases Work
|
||||
|
||||
In `/posts/my-new-post.es.md`:
|
||||
Using the first example above, Hugo generates the following site structure:
|
||||
|
||||
```md
|
||||
---
|
||||
aliases:
|
||||
- /es/posts/my-original-post/
|
||||
---
|
||||
```text
|
||||
public/
|
||||
├── posts/
|
||||
│ ├── new-file-name/
|
||||
│ │ └── index.html
|
||||
│ ├── previous-file-name/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
From Hugo 0.55 you can also have page-relative aliases, so `/es/posts/my-original-post/` can be simplified to the more portable `my-original-post/`
|
||||
The alias from the previous URL to the new URL is a client-side redirect:
|
||||
|
||||
### How Hugo Aliases Work
|
||||
|
||||
When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target.
|
||||
|
||||
For example, a content file at `posts/my-intended-url.md` with the following in the front matter:
|
||||
|
||||
```yml
|
||||
---
|
||||
title: My New post
|
||||
aliases: [/posts/my-old-url/]
|
||||
---
|
||||
```
|
||||
|
||||
Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias `.html` found at `https://example.com/posts/my-old-url/` will contain the following:
|
||||
|
||||
```html
|
||||
{{< code file="posts/previous-file-name/index.html" copy=false >}}
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<html lang="en-us">
|
||||
<head>
|
||||
<title>https://example.com/posts/my-intended-url</title>
|
||||
<link rel="canonical" href="https://example.com/posts/my-intended-url"/>
|
||||
<title>https://example.org/posts/new-file-name/</title>
|
||||
<link rel="canonical" href="https://example.org/posts/new-file-name/">
|
||||
<meta name="robots" content="noindex">
|
||||
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
|
||||
<meta http-equiv="refresh" content="0; url=https://example.com/posts/my-intended-url"/>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="refresh" content="0; url=https://example.org/posts/new-file-name/">
|
||||
</head>
|
||||
</html>
|
||||
```
|
||||
{{< /code >}}
|
||||
|
||||
The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `<meta name="robots" content="noindex">` lets search engine bots know that they should not index your alias page (`https://example.com/posts/my-old-url/`).
|
||||
Collectively, the elements in the `head` section:
|
||||
|
||||
- Tell search engines that the new URL is canonical
|
||||
- Tell search engines not to index the previous URL
|
||||
- Tell the browser to redirect to the new URL
|
||||
|
||||
Hugo renders alias files before rendering pages. A new page with the previous file name will overwrite the alias, as expected.
|
||||
|
||||
### Customize
|
||||
|
||||
You may customize this alias page by creating an `alias.html` template in the
|
||||
layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is
|
||||
Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context:
|
||||
|
||||
`Permalink`
|
||||
: the link to the page being aliased
|
||||
|
||||
`Page`
|
||||
: the Page data for the page being aliased
|
||||
|
||||
### Important Behaviors of Aliases
|
||||
|
||||
1. Hugo makes no assumptions about aliases. They also do not change based
|
||||
on your UglyURLs setting. You need to provide absolute paths to your web root
|
||||
and the complete filename or directory.
|
||||
2. Aliases are rendered *before* any content are rendered and therefore will be overwritten by any content with the same location.
|
||||
|
||||
## Pretty URLs
|
||||
|
||||
Hugo's default behavior is to render your content with "pretty" URLs. No non-standard server-side configuration is required for these pretty URLs to work.
|
||||
|
||||
The following demonstrates the concept:
|
||||
|
||||
```txt
|
||||
content/posts/_index.md
|
||||
=> example.com/posts/
|
||||
content/posts/post-1.md
|
||||
=> example.com/posts/post-1/
|
||||
```
|
||||
|
||||
## Ugly URLs
|
||||
|
||||
If you would like to have what are often referred to as "ugly URLs" (e.g., example.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also set the `HUGO_UGLYURLS` environment variable to `true` when running `hugo` or `hugo server`.
|
||||
|
||||
If you want a specific piece of content to have an exact URL, you can specify this in the [front matter] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be when Hugo runs with its default behavior.
|
||||
|
||||
See [Content Organization][contentorg] for more details on paths.
|
||||
|
||||
```txt
|
||||
.
|
||||
└── content
|
||||
└── about
|
||||
| └── _index.md // <- https://example.com/about/
|
||||
├── posts
|
||||
| ├── firstpost.md // <- https://example.com/posts/firstpost/
|
||||
| ├── happy
|
||||
| | └── ness.md // <- https://example.com/posts/happy/ness/
|
||||
| └── secondpost.md // <- https://example.com/posts/secondpost/
|
||||
└── quote
|
||||
├── first.md // <- https://example.com/quote/first/
|
||||
└── second.md // <- https://example.com/quote/second/
|
||||
```
|
||||
|
||||
Here's the same organization run with `hugo --uglyURLs`:
|
||||
|
||||
```txt
|
||||
.
|
||||
└── content
|
||||
└── about
|
||||
| └── _index.md // <- https://example.com/about.html
|
||||
├── posts
|
||||
| ├── firstpost.md // <- https://example.com/posts/firstpost.html
|
||||
| ├── happy
|
||||
| | └── ness.md // <- https://example.com/posts/happy/ness.html
|
||||
| └── secondpost.md // <- https://example.com/posts/secondpost.html
|
||||
└── quote
|
||||
├── first.md // <- https://example.com/quote/first.html
|
||||
└── second.md // <- https://example.com/quote/second.html
|
||||
```
|
||||
|
||||
## Canonicalization
|
||||
|
||||
By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`. The `canonifyURLs` field in your site `config` has a default value of `false`.
|
||||
|
||||
By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = https://example.com/`, the relative URL `/css/foo.css` would be turned into the absolute URL `https://example.com/css/foo.css`.
|
||||
|
||||
Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issue.
|
||||
|
||||
Benefits of non-canonicalization include being able to have scheme-relative resource inclusion; e.g., so that `http` vs `https` can be decided according to how the page was retrieved.
|
||||
|
||||
{{% note "`canonifyURLs` default change" %}}
|
||||
In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. Please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions.
|
||||
{{% /note %}}
|
||||
|
||||
To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13.
|
||||
|
||||
```txt
|
||||
hugo config | grep -i canon
|
||||
```
|
||||
|
||||
Or, if you are on Windows and do not have `grep` installed:
|
||||
|
||||
```txt
|
||||
hugo config | FINDSTR /I canon
|
||||
```
|
||||
|
||||
## Set URL in Front Matter
|
||||
|
||||
In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content.
|
||||
|
||||
Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg].
|
||||
|
||||
From Hugo 0.55, you can use URLs relative to the current site context (the language), which makes it simpler to maintain. For a Japanese translation, both of the following examples would get the same URL:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Custom URL!"
|
||||
url: "/jp/custom/foo"
|
||||
---
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Custom URL!"
|
||||
url: "custom/foo"
|
||||
---
|
||||
```
|
||||
|
||||
## Relative URLs
|
||||
|
||||
By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system.
|
||||
|
||||
Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content.
|
||||
|
||||
For example, if your `/posts/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`.
|
||||
|
||||
[config]: /getting-started/configuration/
|
||||
[contentorg]: /content-management/organization/
|
||||
[front matter]: /content-management/front-matter/
|
||||
[multilingual]: /content-management/multilingual/
|
||||
[sections]: /content-management/sections/
|
||||
[usage]: /getting-started/usage/
|
||||
|
|
|
|||
|
|
@ -2,20 +2,14 @@
|
|||
title: Contribute to the Hugo Project
|
||||
linktitle: Contribute to Hugo
|
||||
description: Contribute to Hugo development and documentation.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [contribute]
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: "contribute"
|
||||
parent: contribute
|
||||
weight: 01
|
||||
weight: 01 #rem
|
||||
draft: false
|
||||
slug:
|
||||
weight: 01
|
||||
aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/]
|
||||
toc: false
|
||||
---
|
||||
|
||||
Hugo relies heavily on the enthusiasm and participation of the open-source community. We need your support in both its development and documentation.
|
||||
|
|
|
|||
|
|
@ -2,17 +2,13 @@
|
|||
title: Contribute to Hugo Development
|
||||
linktitle: Development
|
||||
description: Hugo relies heavily on contributions from the open source community.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
categories: [contribute]
|
||||
keywords: [dev,open source]
|
||||
authors: [digitalcraftsman]
|
||||
menu:
|
||||
docs:
|
||||
parent: "contribute"
|
||||
parent: contribute
|
||||
weight: 10
|
||||
weight: 10
|
||||
sections_weight: 10
|
||||
toc: true
|
||||
---
|
||||
|
||||
|
|
@ -27,7 +23,7 @@ This contribution guide takes a step-by-step approach in hopes of helping newcom
|
|||
* You are new to Git or open-source projects in general
|
||||
* You are a fan of Hugo and enthusiastic about contributing to the project
|
||||
|
||||
{{% note "Additional Questions?" %}}
|
||||
{{% note %}}
|
||||
If you're struggling at any point in this contribution guide, reach out to the Hugo community in [Hugo's Discussion forum](https://discourse.gohugo.io).
|
||||
{{% /note %}}
|
||||
|
||||
|
|
@ -126,7 +122,9 @@ You set up the working copy of the repository locally on your computer. Your loc
|
|||
|
||||
We assume that you've set up your `GOPATH` (see the section above if you're unsure about this). You should now copy the Hugo repository down to your computer. You'll hear this called "clone the repo". GitHub's [help pages](https://help.github.com/articles/cloning-a-repository/) give us a short explanation:
|
||||
|
||||
> When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations.
|
||||
{{% note %}}
|
||||
When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations.
|
||||
{{% /note %}}
|
||||
|
||||
We're going to clone the [master Hugo repository](https://github.com/gohugoio/hugo). That seems counter-intuitive, since you won't have commit rights on it. But it's required for the Go workflow. You'll work on a copy of the master and push your changes to your own repository on GitHub.
|
||||
|
||||
|
|
@ -138,8 +136,7 @@ cd $HOME/src
|
|||
git clone https://github.com/gohugoio/hugo.git
|
||||
```
|
||||
|
||||
> Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build.
|
||||
> The easiest is to clone Hugo in a directory outside of GOPATH
|
||||
Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. The easiest is to clone Hugo in a directory outside of GOPATH
|
||||
|
||||
And then, install dependencies of Hugo by running the following in the cloned directory:
|
||||
|
||||
|
|
@ -158,7 +155,9 @@ go install github.com/magefile/mage@latest
|
|||
|
||||
If you're not familiar with this term, GitHub's [help pages](https://help.github.com/articles/fork-a-repo/) provide again a simple explanation:
|
||||
|
||||
> A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
|
||||
{{% note %}}
|
||||
A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
|
||||
{{% /note %}}
|
||||
|
||||
#### Fork by hand
|
||||
|
||||
|
|
@ -316,7 +315,7 @@ git commit --amend
|
|||
|
||||
{{% warning "Be Careful Modifying Multiple Commits"%}}
|
||||
Modifications such as those described in this section can have serious unintended consequences. Skip this section if you're not sure!
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
||||
This is a bit more advanced. Git allows you to [rebase](https://git-scm.com/docs/git-rebase) commits interactively. In other words: it allows you to rewrite the commit history.
|
||||
|
||||
|
|
@ -421,7 +420,7 @@ Feel free to [open an issue][newissue] if you think you found a bug or you have
|
|||
[docscontrib]: /contribute/documentation/
|
||||
[forums]: https://discourse.gohugo.io
|
||||
[gitbook]: https://git-scm.com/
|
||||
[gobootcamp]: https://www.golangbootcamp.com/book/get_setup
|
||||
[gobootcamp]: https://www.golang-book.com/guides/machine_setup
|
||||
[godl]: https://go.dev/dl/
|
||||
[goinstall]: https://go.dev/doc/install
|
||||
[gvm]: https://github.com/moovweb/gvm
|
||||
|
|
|
|||
|
|
@ -1,331 +1,176 @@
|
|||
---
|
||||
title: Contribute to the Hugo Docs
|
||||
linktitle: Documentation
|
||||
description: Documentation is an integral part of any open source project. The Hugo docs are as much a work in progress as the source it attempts to cover.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
description: Documentation is an integral part of any open source project. The Hugo documentation is as much a work in progress as the source it attempts to cover.
|
||||
categories: [contribute]
|
||||
keywords: [docs,documentation,community, contribute]
|
||||
menu:
|
||||
docs:
|
||||
parent: "contribute"
|
||||
parent: contribute
|
||||
weight: 20
|
||||
weight: 20
|
||||
sections_weight: 20
|
||||
aliases: [/contribute/docs/]
|
||||
toc: true
|
||||
weight: 20
|
||||
aliases: [/contribute/docs/]
|
||||
---
|
||||
|
||||
## Create Your Fork
|
||||
## GitHub workflow
|
||||
|
||||
It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of [hugoDocs](https://github.com/gohugoio/hugoDocs) on GitHub and cloned the repository locally on your machine. For more information, you can see [GitHub's documentation on "forking"][ghforking] or follow along with [Hugo's development contribution guide][hugodev].
|
||||
Step 1
|
||||
: Fork the [documentation repository].
|
||||
|
||||
You can then create a separate branch for your additions. Be sure to choose a descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:
|
||||
Step 2
|
||||
: Clone your fork.
|
||||
|
||||
```txt
|
||||
git checkout -b jon-doe-showcase-addition
|
||||
Step 3
|
||||
: Create a new branch with a descriptive name.
|
||||
|
||||
```bash
|
||||
git checkout -b fix/typos-site-variables
|
||||
```
|
||||
|
||||
## Add New Content
|
||||
Step 4
|
||||
: Make changes.
|
||||
|
||||
The Hugo docs make heavy use of Hugo's [archetypes] feature. All content sections in Hugo documentation have an assigned archetype.
|
||||
Step 5
|
||||
: Commit your changes with a descriptive commit message, typically 50 characters or less. Included the "Closes" keyword if your change addresses one or more open [issues].
|
||||
|
||||
Adding new content to the Hugo docs follows the same pattern, regardless of the content section:
|
||||
```bash
|
||||
git commit -m "Fix typos on site variables page
|
||||
|
||||
```txt
|
||||
hugo new <DOCS-SECTION>/<new-content-lowercase>.md
|
||||
Closes #1234
|
||||
Closes #5678"
|
||||
```
|
||||
|
||||
### Add a New Function
|
||||
Step 5
|
||||
: Push the new branch to your fork of the documentation repository.
|
||||
|
||||
Once you have cloned the Hugo repository, you can create a new function via the following command. Keep the filename lowercase.
|
||||
Step 6
|
||||
: Visit the [documentation repository] and create a pull request (PR).
|
||||
|
||||
```txt
|
||||
hugo new functions/newfunction.md
|
||||
```
|
||||
[documentation repository]: https://github.com/gohugoio/hugoDocs/
|
||||
[issues]: https://github.com/gohugoio/hugoDocs/issues
|
||||
|
||||
The archetype for `functions` according to the Hugo docs is as follows:
|
||||
Step 7
|
||||
: A project maintainer will review your PR, and may request changes. You may delete your branch after the maintainer merges your PR.
|
||||
|
||||
{{< code file="archetypes/functions.md" >}}
|
||||
{{< readfile file="/archetypes/functions.md">}}
|
||||
{{< /code >}}
|
||||
## Including sample code
|
||||
|
||||
#### New Function Required Fields
|
||||
{{% note %}}
|
||||
Use this syntax to include shortcodes calls within your code samples:
|
||||
|
||||
Here is a review of the front matter fields automatically generated for you using `hugo new functions/*`:
|
||||
`{{</*/* foo */*/>}}`\
|
||||
`{{%/*/* foo */*/%}}`
|
||||
{{% /note %}}
|
||||
|
||||
***`title`***
|
||||
: this will be auto-populated in all lowercase when you use `hugo new` generator.
|
||||
### Fenced code blocks
|
||||
|
||||
***`linktitle`***
|
||||
: the function's actual casing (e.g., `replaceRE` rather than `replacere`).
|
||||
Include the language when using a fenced code block.
|
||||
|
||||
***`description`***
|
||||
: a brief description used to populate the [Functions Quick Reference](/functions/).
|
||||
|
||||
`categories`
|
||||
: currently auto-populated with 'functions` for future-proofing and portability reasons only; ignore this field.
|
||||
|
||||
`tags`
|
||||
: only if you think it will help end users find other related functions
|
||||
|
||||
`signature`
|
||||
: this is a signature/syntax definition for calling the function (e.g., `apply SEQUENCE FUNCTION [PARAM...]`).
|
||||
|
||||
`workson`
|
||||
: acceptable values include `lists`,`taxonomies`, `terms`, `groups`, and `files`.
|
||||
|
||||
`hugoversion`
|
||||
: the version of Hugo that will ship with this new function.
|
||||
|
||||
`relatedfuncs`
|
||||
: other [templating functions] you feel are related to your new function to help fellow Hugo users.
|
||||
|
||||
`{{.Content}}`
|
||||
: an extended description of the new function; examples are not only welcomed but encouraged.
|
||||
|
||||
In the body of your function, expand the short description used in the front matter. Include as many examples as possible, and leverage the Hugo docs [`code` shortcode](#add-code-blocks). If you are unable to add examples but would like to solicit help from the Hugo community, add `needsexample: true` to your front matter.
|
||||
|
||||
## Add Code Blocks
|
||||
|
||||
Code blocks are crucial for providing examples of Hugo's new features to end users of the Hugo docs. Whenever possible, create examples that you think Hugo users will be able to implement in their own projects.
|
||||
|
||||
### Standard Syntax
|
||||
|
||||
Across many pages on the Hugo docs, the typical triple-back-tick Markdown syntax (```` ``` ````) is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard GitHub-flavored Markdown.
|
||||
|
||||
````txt
|
||||
````text
|
||||
```go-html-template
|
||||
{{ range site.RegularPages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ if eq $foo "bar" }}
|
||||
{{ print "foo is bar" }}
|
||||
{{ end }}
|
||||
```
|
||||
````
|
||||
|
||||
|
||||
### Code Block Shortcode
|
||||
|
||||
The Hugo documentation comes with a very robust shortcode for adding interactive code blocks.
|
||||
|
||||
{{% note %}}
|
||||
With the `code` shortcodes, *you must include triple back ticks and a language declaration*. This was done by design so that the shortcode wrappers were easily added to legacy documentation and will be that much easier to remove if needed in future versions of the Hugo docs.
|
||||
{{% /note %}}
|
||||
|
||||
### `code`
|
||||
|
||||
`code` is the Hugo docs shortcode you'll use most often. `code` requires has only one named parameter: `file`. Here is the pattern:
|
||||
Rendered:
|
||||
|
||||
```go-html-template
|
||||
{{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
|
||||
A whole bunch of coding going on up in here!
|
||||
{{%/* /code */%}}
|
||||
{{ if eq $foo "bar" }}
|
||||
{{ print "foo is bar" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The following are the arguments passed into `code`:
|
||||
### The code shortcode
|
||||
|
||||
***`file`***
|
||||
: the only *required* argument. `file` is needed for styling but also plays an important role in helping users create a mental model around Hugo's directory structure. Visually, this will be displayed as text in the top left of the code block.
|
||||
Use the `code` shortcode to include the file name and a copy-to-clipboard button. This shortcode accepts these optional parameters:
|
||||
|
||||
`download`
|
||||
: if omitted, this will have no effect on the rendered shortcode. When a value is added to `download`, it's used as the filename for a downloadable version of the code block.
|
||||
copy
|
||||
: (`bool`) If `true`, displays a copy-to-clipboard button. Default is `true`.
|
||||
|
||||
`copy`
|
||||
: a copy button is added automatically to all `code` shortcodes. If you want to keep the filename and styling of `code` but don't want to encourage readers to copy the code (e.g., a "Do not do" snippet in a tutorial), use `copy="false"`.
|
||||
file
|
||||
: (`string`) The file name to display. If you do not provide a `lang` parameter, the file extension determines the code language.
|
||||
|
||||
#### Example `code` Input
|
||||
lang
|
||||
: (`string`) The code language. Default is `text`.
|
||||
|
||||
This example HTML code block tells Hugo users the following:
|
||||
|
||||
1. This file *could* live in `layouts/_default`, as demonstrated by `layouts/_default/single.html` as the value for `file`.
|
||||
2. This snippet is complete enough to be downloaded and implemented in a Hugo project, as demonstrated by `download="single.html"`.
|
||||
|
||||
```go-html-template
|
||||
{{</* code file="layouts/_default/single.html" download="single.html" */>}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
<article>
|
||||
<header>
|
||||
<h1>{{.Title}}</h1>
|
||||
{{with .Params.subtitle}}
|
||||
<span>{{.}}</span>
|
||||
</header>
|
||||
<div>
|
||||
{{.Content}}
|
||||
</div>
|
||||
<aside>
|
||||
{{.TableOfContents}}
|
||||
</aside>
|
||||
</article>
|
||||
</main>
|
||||
````text
|
||||
{{</* code file="layouts/_default_/single.html" */>}}
|
||||
{{ if eq $foo "bar" }}
|
||||
{{ print "foo is bar" }}
|
||||
{{ end }}
|
||||
{{</* /code */>}}
|
||||
```
|
||||
|
||||
##### Example 'code' Display
|
||||
````
|
||||
|
||||
The output of this example will render to the Hugo docs as follows:
|
||||
Rendered:
|
||||
|
||||
{{< code file="layouts/_default/single.html" download="single.html" >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
<article>
|
||||
<header>
|
||||
<h1>{{.Title}}</h1>
|
||||
{{with .Params.subtitle}}
|
||||
<span>{{.}}</span>
|
||||
</header>
|
||||
<div>
|
||||
{{.Content}}
|
||||
</div>
|
||||
<aside>
|
||||
{{.TableOfContents}}
|
||||
</aside>
|
||||
</article>
|
||||
</main>
|
||||
{{< code file="layouts/_default_/single.html" >}}
|
||||
{{ if eq $foo "bar" }}
|
||||
{{ print "foo is bar" }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
<!-- #### Output Code Block
|
||||
### The code-toggle shortcode
|
||||
|
||||
The `output` shortcode is almost identical to the `code` shortcode but only takes and requires `file`. The purpose of `output` is to show *rendered* HTML and therefore almost always follows another basic code block *or* and instance of the `code` shortcode:
|
||||
Use the `code-toggle` shortcode to display examples of site configuration, front matter, or data files. This shortcode accepts these optional parameters:
|
||||
|
||||
```
|
||||
{{%/* output file="posts/my-first-post/index.html" */%}}
|
||||
<h1>This is my First Hugo Blog Post</h1>
|
||||
<p>I am excited to be using Hugo.</p>
|
||||
{{%/* /output */%}}
|
||||
copy
|
||||
: (`bool`) If `true`, displays a copy-to-clipboard button. Default is `true`.
|
||||
|
||||
file
|
||||
: (`string`) The file name to display. Omit the file extension for site configuration and data file examples.
|
||||
|
||||
fm
|
||||
: (`bool`) If `true`, displays the code as front matter. Default is `false`.
|
||||
|
||||
#### Site configuration example
|
||||
|
||||
```text
|
||||
{{</* code-toggle file="config" */>}}
|
||||
baseURL = 'https://example.org'
|
||||
languageCode = 'en-US'
|
||||
title = "Example Site"
|
||||
{{</* /code-toggle */>}}
|
||||
```
|
||||
|
||||
The preceding `output` example will render as follows to the Hugo docs:
|
||||
Rendered:
|
||||
|
||||
{{< output file="posts/my-first-post/index.html" >}}
|
||||
<h1>This is my First Hugo Blog Post</h1>
|
||||
<p>I am excited to be using Hugo.</p>
|
||||
{{< /output >}} -->
|
||||
{{< code-toggle file="config" >}}
|
||||
baseURL = 'https://example.org'
|
||||
languageCode = 'en-US'
|
||||
title = "Example Site"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Blockquotes
|
||||
#### Front matter example
|
||||
|
||||
Blockquotes can be added to the Hugo documentation using [typical Markdown blockquote syntax][bqsyntax]:
|
||||
|
||||
```md
|
||||
> Without the threat of punishment, there is no joy in flight.
|
||||
```text
|
||||
{{</* code-toggle file="content/about.md" fm=true */>}}
|
||||
title = "About"
|
||||
date = 2023-04-02T12:47:24-07:00
|
||||
draft = false
|
||||
{{</* /code-toggle */>}}
|
||||
```
|
||||
|
||||
The preceding blockquote will render as follows in the Hugo docs:
|
||||
Rendered:
|
||||
|
||||
> Without the threat of punishment, there is no joy in flight.
|
||||
|
||||
However, you can add a quick and easy `<cite>` element (added on the client via JavaScript) by separating your main blockquote and the citation with a hyphen with a single space on each side:
|
||||
|
||||
```md
|
||||
> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)
|
||||
```
|
||||
|
||||
Which will render as follows in the Hugo docs:
|
||||
|
||||
> Without the threat of punishment, there is no joy in flight. - [Kobo Abe][abe]
|
||||
|
||||
{{% note "Blockquotes `!=` Admonitions" %}}
|
||||
Previous versions of Hugo documentation used blockquotes to draw attention to text. This is *not* the [intended semantic use of `<blockquote>`](https://html5doctor.com/cite-and-blockquote-reloaded/). Use blockquotes when quoting. To note or warn your user of specific information, use the admonition shortcodes that follow.
|
||||
{{% /note %}}
|
||||
{{< code-toggle file="content/about.md" fm=true >}}
|
||||
title = "About"
|
||||
date = 2023-04-02T12:47:24-07:00
|
||||
draft = false
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Admonitions
|
||||
|
||||
**Admonitions** are common in technical documentation. The most popular is that seen in [reStructuredText Directives][sourceforge]. From the SourceForge documentation:
|
||||
Use the `note` shortcode to draw attention to content. Use the `{{%/* */%}}` notation when calling this shortcode.
|
||||
|
||||
> Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. - [SourceForge][sourceforge]
|
||||
|
||||
The Hugo docs contain three admonitions: `note`, `tip`, and `warning`.
|
||||
|
||||
### `note` Admonition
|
||||
|
||||
Use the `note` shortcode when you want to draw attention to information subtly. `note` is intended to be less of an interruption in content than is `warning`.
|
||||
|
||||
#### Example `note` Input
|
||||
|
||||
{{< code file="note-with-heading.md" >}}
|
||||
```text
|
||||
{{%/* note */%}}
|
||||
Here is a piece of information I would like to draw your **attention** to.
|
||||
This is **bold** text.
|
||||
{{%/* /note */%}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `note` Output
|
||||
|
||||
{{< output file="note-with-heading.html" >}}
|
||||
{{% note %}}
|
||||
Here is a piece of information I would like to draw your **attention** to.
|
||||
{{% /note %}}
|
||||
{{< /output >}}
|
||||
|
||||
#### Example `note` Display
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Here is a piece of information I would like to draw your **attention** to.
|
||||
This is **bold** text.
|
||||
{{% /note %}}
|
||||
|
||||
### `tip` Admonition
|
||||
|
||||
Use the `tip` shortcode when you want to give the reader advice. `tip`, like `note`, is intended to be less of an interruption in content than is `warning`.
|
||||
|
||||
#### Example `tip` Input
|
||||
|
||||
{{< code file="using-tip.md" >}}
|
||||
{{%/* tip */%}}
|
||||
Here's a bit of advice to improve your productivity with Hugo.
|
||||
{{%/* /tip */%}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `tip` Output
|
||||
|
||||
{{< output file="tip-output.html" >}}
|
||||
{{% tip %}}
|
||||
Here's a bit of advice to improve your productivity with Hugo.
|
||||
{{% /tip %}}
|
||||
{{< /output >}}
|
||||
|
||||
#### Example `tip` Display
|
||||
|
||||
{{% tip %}}
|
||||
Here's a bit of advice to improve your productivity with Hugo.
|
||||
{{% /tip %}}
|
||||
|
||||
### `warning` Admonition
|
||||
|
||||
Use the `warning` shortcode when you want to draw the user's attention to something important. A good usage example is for articulating breaking changes in Hugo versions, known bugs, or templating "gotchas."
|
||||
|
||||
#### Example `warning` Input
|
||||
|
||||
{{< code file="warning-admonition-input.md" >}}
|
||||
{{%/* warning */%}}
|
||||
This is a warning, which should be reserved for *important* information like breaking changes.
|
||||
{{%/* /warning */%}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `warning` Output
|
||||
|
||||
{{< output file="warning-admonition-output.html" >}}
|
||||
{{% warning %}}
|
||||
This is a warning, which should be reserved for *important* information like breaking changes.
|
||||
{{% /warning %}}
|
||||
{{< /output >}}
|
||||
|
||||
#### Example `warning` Display
|
||||
|
||||
{{% warning %}}
|
||||
This is a warning, which should be reserved for *important* information like breaking changes.
|
||||
{{% /warning %}}
|
||||
|
||||
{{% note "Pull Requests and Branches" %}}
|
||||
Similar to [contributing to Hugo development](/contribute/development/), the Hugo team expects you to create a separate branch/fork when you make your contributions to the Hugo docs.
|
||||
{{% /note %}}
|
||||
|
||||
[abe]: https://en.wikipedia.org/wiki/Kobo_Abe
|
||||
[archetypes]: /content-management/archetypes/
|
||||
[bqsyntax]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes
|
||||
[charcount]: https://www.lettercount.com/
|
||||
[`docs/static/images/showcase/`]: https://github.com/gohugoio/hugo/tree/master/docs/static/images/showcase/
|
||||
[ghforking]: https://help.github.com/articles/fork-a-repo/
|
||||
[hugodev]: /contribute/development/
|
||||
[shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown
|
||||
[sourceforge]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions
|
||||
[templating function]: /functions/
|
||||
|
|
|
|||
|
|
@ -2,19 +2,14 @@
|
|||
title: Add Your Hugo Theme to the Showcase
|
||||
linktitle: Themes
|
||||
description: If you've built a Hugo theme and want to contribute back to the Hugo Community, share it with us.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
categories: [contribute]
|
||||
keywords: [contribute,themes,design]
|
||||
authors: [digitalcraftsman]
|
||||
menu:
|
||||
docs:
|
||||
parent: "contribute"
|
||||
parent: contribute
|
||||
weight: 30
|
||||
weight: 30
|
||||
sections_weight: 30
|
||||
aliases: [/contribute/theme/]
|
||||
wip: true
|
||||
toc: true
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -2,17 +2,10 @@
|
|||
title: Hugo Documentation
|
||||
linktitle: Hugo
|
||||
description: Hugo is the world's fastest static website engine. It's written in Go (aka Golang) and developed by bep, spf13 and friends.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
menu:
|
||||
main:
|
||||
parent: "section name"
|
||||
weight: 01
|
||||
weight: 01 #rem
|
||||
draft: false
|
||||
slug:
|
||||
aliases: []
|
||||
toc: false
|
||||
weight: 01
|
||||
layout: documentation-home
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,20 +1,13 @@
|
|||
---
|
||||
title: .GetPage
|
||||
description: "Gets a `Page` of a given `path`."
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [sections,lists,indexes]
|
||||
signature: [".GetPage PATH"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`.GetPage` returns a page of a given `path`. Both `Site` and `Page` implements this method. The `Page` variant will, if given a relative path -- i.e. a path without a leading `/` -- try look for the page relative to the current page.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,10 @@
|
|||
---
|
||||
title: .RenderString
|
||||
description: "Renders markup to HTML."
|
||||
date: 2019-12-18
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [markdown,goldmark,render]
|
||||
signature: [".RenderString MARKUP"]
|
||||
---
|
||||
|
|
@ -26,8 +25,8 @@ Some examples:
|
|||
{{ $optBlock := dict "display" "block" }}
|
||||
{{ $optOrg := dict "markup" "org" }}
|
||||
{{ "**Bold Markdown**" | $p.RenderString }}
|
||||
{{ "**Bold Block Markdown**" | $p.RenderString $optBlock }}
|
||||
{{ "/italic org mode/" | $p.RenderString $optOrg }}
|
||||
{{ "**Bold Block Markdown**" | $p.RenderString $optBlock }}
|
||||
{{ "/italic org mode/" | $p.RenderString $optOrg }}
|
||||
```
|
||||
|
||||
{{< new-in "0.93.0" >}} **Note**: [markdownify](/functions/markdownify/) uses this function in order to support [Render Hooks](/getting-started/configuration-markup/#markdown-render-hooks).
|
||||
|
|
|
|||
|
|
@ -1,16 +1,11 @@
|
|||
---
|
||||
title: Functions Quick Reference
|
||||
linktitle: Functions Quick Reference
|
||||
description: Comprehensive list of Hugo templating functions, including basic and advanced usage examples.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
weight: 01 #rem
|
||||
draft: false
|
||||
parent: functions
|
||||
weight: 01
|
||||
aliases: [/layout/functions/,/templates/functions]
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,20 +1,13 @@
|
|||
---
|
||||
title: .AddDate
|
||||
description: Returns the time corresponding to adding the given number of years, months, and days to the given time.Time value.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [dates,time]
|
||||
signature: [".AddDate YEARS MONTHS DAYS"]
|
||||
workson: [times]
|
||||
hugoversion:
|
||||
relatedfuncs: [now]
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
|
|
|
|||
|
|
@ -1,25 +1,18 @@
|
|||
---
|
||||
title: after
|
||||
description: "`after` slices an array to only the items after the <em>N</em>th item."
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [iteration]
|
||||
signature: ["after INDEX COLLECTION"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: [last,first,seq]
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
The following shows `after` being used in conjunction with the [`slice` function][slice]:
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ $data := slice "one" "two" "three" "four" }}
|
||||
{{ range after 2 $data }}
|
||||
{{ . }}
|
||||
|
|
@ -34,27 +27,27 @@ You can use `after` in combination with the [`first` function] and Hugo's [power
|
|||
1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
|
||||
2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
|
||||
|
||||
{{< code file="layouts/section/articles.html" download="articles.html" >}}
|
||||
{{< code file="layouts/section/articles.html" >}}
|
||||
{{ define "main" }}
|
||||
<section class="row featured-article">
|
||||
<h2>Featured Article</h2>
|
||||
{{ range first 1 .Pages.ByPublishDate.Reverse }}
|
||||
<header>
|
||||
<h3><a href="{{.Permalink}}">{{.Title}}</a></h3>
|
||||
</header>
|
||||
<p>{{.Description}}</p>
|
||||
{{ end }}
|
||||
<h2>Featured Article</h2>
|
||||
{{ range first 1 .Pages.ByPublishDate.Reverse }}
|
||||
<header>
|
||||
<h3><a href="{{ . Permalink }}">{{ .Title }}</a></h3>
|
||||
</header>
|
||||
<p>{{ .Description }}</p>
|
||||
{{ end }}
|
||||
</section>
|
||||
<div class="row recent-articles">
|
||||
<h2>Recent Articles</h2>
|
||||
{{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
|
||||
<section class="recent-article">
|
||||
<header>
|
||||
<h3><a href="{{.Permalink}}">{{.Title}}</a></h3>
|
||||
</header>
|
||||
<p>{{.Description}}</p>
|
||||
</section>
|
||||
{{ end }}
|
||||
<h2>Recent Articles</h2>
|
||||
{{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
|
||||
<section class="recent-article">
|
||||
<header>
|
||||
<h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3>
|
||||
</header>
|
||||
<p>{{ .Description }}</p>
|
||||
</section>
|
||||
{{ end }}
|
||||
</div>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
|
|
|||
|
|
@ -1,15 +1,12 @@
|
|||
---
|
||||
title: anchorize
|
||||
description: Takes a string and sanitizes it the same way as the [`defaultMarkdownHandler`](https://gohugo.io/getting-started/configuration-markup#configure-markup) does for markdown headers.
|
||||
date: 2018-10-13
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [markdown,strings]
|
||||
signature: ["anchorize INPUT"]
|
||||
hugoversion: "0.39"
|
||||
workson: []
|
||||
relatedfuncs: [humanize]
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,17 +1,13 @@
|
|||
---
|
||||
title: append
|
||||
description: "`append` appends one or more values to a slice and returns the resulting slice."
|
||||
date: 2018-09-14
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [collections]
|
||||
signature: ["COLLECTION | append VALUE [VALUE]...", "COLLECTION | append COLLECTION"]
|
||||
workson: []
|
||||
hugoversion: "0.49"
|
||||
relatedfuncs: [last,first,where,slice]
|
||||
aliases: []
|
||||
---
|
||||
|
||||
An example appending single values:
|
||||
|
|
|
|||
|
|
@ -1,27 +1,15 @@
|
|||
---
|
||||
title: apply
|
||||
description: Given a map, array, or slice, `apply` returns a new slice with a function applied over it.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [advanced]
|
||||
signature: ["apply COLLECTION FUNCTION [PARAM...]"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
{{< todo >}}
|
||||
POTENTIAL NEW CONTENT: see apply/sequence discussion: https://discourse.gohugo.io/t/apply-printf-on-a-sequence/5722;
|
||||
{{< /todo >}}
|
||||
|
||||
`apply` expects at least three parameters, depending on the function being applied.
|
||||
|
||||
1. The first parameter is the sequence to operate on.
|
||||
|
|
@ -30,15 +18,14 @@ POTENTIAL NEW CONTENT: see apply/sequence discussion: https://discourse.gohugo.i
|
|||
|
||||
Here is an example of a content file with `names:` as a front matter field:
|
||||
|
||||
```
|
||||
+++
|
||||
{{< code-toggle file="content/example.md" fm=true copy=false >}}
|
||||
title: Example
|
||||
names: [ "Derek Perkins", "Joe Bergevin", "Tanner Linsley" ]
|
||||
+++
|
||||
```
|
||||
{{< /code-toggle >}}
|
||||
|
||||
You can then use `apply` as follows:
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ apply .Params.names "urlize" "." }}
|
||||
```
|
||||
|
||||
|
|
@ -50,7 +37,7 @@ Which will result in the following:
|
|||
|
||||
This is *roughly* equivalent to using the following with [range]:
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ range .Params.names }}{{ . | urlize }}{{ end }}
|
||||
```
|
||||
|
||||
|
|
@ -58,25 +45,25 @@ However, it is not possible to provide the output of a range to the [`delimit` f
|
|||
|
||||
If you have `post-tag-list.html` and `post-tag-link.html` as [partials], you *could* use the following snippets, respectively:
|
||||
|
||||
{{< code file="layouts/partials/post-tag-list.html" copy="false" >}}
|
||||
{{< code file="layouts/partials/post-tag-list.html" copy=false >}}
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ $len := len . }}
|
||||
{{ if eq $len 1 }}
|
||||
{{ partial "post-tag-link.html" (index . 0) }}
|
||||
{{ else }}
|
||||
{{ $last := sub $len 1 }}
|
||||
{{ range first $last . }}
|
||||
{{ partial "post-tag-link.html" . }},
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ $len := len . }}
|
||||
{{ if eq $len 1 }}
|
||||
{{ partial "post-tag-link.html" (index . 0) }}
|
||||
{{ else }}
|
||||
{{ $last := sub $len 1 }}
|
||||
{{ range first $last . }}
|
||||
{{ partial "post-tag-link.html" . }},
|
||||
{{ end }}
|
||||
{{ partial "post-tag-link.html" (index . $last) }}
|
||||
{{ end }}
|
||||
{{ partial "post-tag-link.html" (index . $last) }}
|
||||
{{ end }}
|
||||
</div>
|
||||
</div>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file="layouts/partials/post-tag-link.html" copy="false" >}}
|
||||
{{< code file="layouts/partials/post-tag-link.html" copy=false >}}
|
||||
<a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a>
|
||||
{{< /code >}}
|
||||
|
||||
|
|
@ -84,27 +71,27 @@ This works, but the complexity of `post-tag-list.html` is fairly high. The Hugo
|
|||
|
||||
This first version of `layouts/partials/post-tag-list.html` separates all of the operations for ease of reading. The combined and DRYer version is shown next:
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ $sort := sort . }}
|
||||
{{ $links := apply $sort "partial" "post-tag-link.html" "." }}
|
||||
{{ $clean := apply $links "chomp" "." }}
|
||||
{{ delimit $clean ", " }}
|
||||
</div>
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ $sort := sort . }}
|
||||
{{ $links := apply $sort "partial" "post-tag-link.html" "." }}
|
||||
{{ $clean := apply $links "chomp" "." }}
|
||||
{{ delimit $clean ", " }}
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Now in the completed version, you can sort the tags, convert the tags to links with `layouts/partials/post-tag-link.html`, [chomp] off stray newlines, and join the tags together in a delimited list for presentation. Here is an even DRYer version of the preceding example:
|
||||
|
||||
{{< code file="layouts/partials/post-tag-list.html" download="post-tag-list.html" >}}
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ delimit (apply (apply (sort .) "partial" "post-tag-link.html" ".") "chomp" ".") ", " }}
|
||||
</div>
|
||||
{{ end }}
|
||||
{{< code file="layouts/partials/post-tag-list.html" >}}
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ delimit (apply (apply (sort .) "partial" "post-tag-link.html" ".") "chomp" ".") ", " }}
|
||||
</div>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
|
|
|
|||
|
|
@ -1,40 +1,18 @@
|
|||
---
|
||||
title: base64
|
||||
description: "`base64Encode` and `base64Decode` let you easily decode content with a base64 encoding and vice versa through pipes."
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: []
|
||||
relatedfuncs: []
|
||||
signature: ["base64Decode INPUT", "base64Encode INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
An example:
|
||||
|
||||
{{< code file="base64-input.html" >}}
|
||||
<p>Hello world = {{ "Hello world" | base64Encode }}</p>
|
||||
<p>SGVsbG8gd29ybGQ = {{ "SGVsbG8gd29ybGQ=" | base64Decode }}</p>
|
||||
{{< /code >}}
|
||||
|
||||
{{< output file="base-64-output.html" >}}
|
||||
<p>Hello world = SGVsbG8gd29ybGQ=</p>
|
||||
<p>SGVsbG8gd29ybGQ = Hello world</p>
|
||||
{{< /output >}}
|
||||
|
||||
You can also pass other data types as arguments to the template function which tries to convert them. The following will convert *42* from an integer to a string because both `base64Encode` and `base64Decode` always return a string.
|
||||
|
||||
```
|
||||
{{ 42 | base64Encode | base64Decode }}
|
||||
=> "42" rather than 42
|
||||
```go-html-template
|
||||
{{ "Hugo" | base64Encode }} → "SHVnbw=="
|
||||
{{ "SHVnbw==" | base64Decode }} → "Hugo"
|
||||
```
|
||||
|
||||
## `base64` with APIs
|
||||
|
|
@ -42,8 +20,8 @@ You can also pass other data types as arguments to the template function which t
|
|||
Using base64 to decode and encode becomes really powerful if we have to handle
|
||||
responses from APIs.
|
||||
|
||||
```
|
||||
{{ $resp := getJSON "https://api.github.com/repos/gohugoio/hugo/readme" }}
|
||||
```go-html-template
|
||||
{{ $resp := getJSON "https://api.github.com/repos/gohugoio/hugo/readme" }}
|
||||
{{ $resp.content | base64Decode | markdownify }}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -2,25 +2,19 @@
|
|||
title: chomp
|
||||
toc: true
|
||||
description: Removes any trailing newline characters.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [trim]
|
||||
signature:
|
||||
- "chomp INPUT"
|
||||
- "strings.Chomp INPUT"
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: [truncate]
|
||||
deprecated: false
|
||||
---
|
||||
|
||||
Useful in a pipeline to remove newlines added by other processing (e.g., [`markdownify`](/functions/markdownify/)).
|
||||
|
||||
```
|
||||
{{chomp "<p>Blockhead</p>\n"}} → "<p>Blockhead</p>"
|
||||
```go-html-template
|
||||
{{ chomp "<p>Blockhead</p>\n" }} → "<p>Blockhead</p>"
|
||||
```
|
||||
|
|
|
|||
|
|
@ -10,14 +10,13 @@ signature:
|
|||
- "complement COLLECTION [COLLECTION]..."
|
||||
- "collections.Complement COLLECTION [COLLECTION]..."
|
||||
relatedfuncs: [intersect,symdiff,union]
|
||||
aliases: []
|
||||
---
|
||||
|
||||
To find the elements within `$c3` that do not exist in `$c1` or `$c2`:
|
||||
|
||||
```go-html-template
|
||||
{{ $c1 := slice 3 }}
|
||||
{{ $c2 := slice 4 5 }}
|
||||
{{ $c2 := slice 4 5 }}
|
||||
{{ $c3 := slice 1 2 3 4 5 }}
|
||||
|
||||
{{ complement $c1 $c2 $c3 }} → [1 2]
|
||||
|
|
|
|||
|
|
@ -1,30 +1,26 @@
|
|||
---
|
||||
title: "cond"
|
||||
date: 2017-09-08
|
||||
title: cond
|
||||
description: "Return one of two arguments, depending on the value of a third argument."
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
signature: ["cond CONTROL VAR1 VAR2"]
|
||||
hugoversion: 0.27
|
||||
relatedfuncs: [default]
|
||||
toc: false
|
||||
draft: false
|
||||
---
|
||||
|
||||
`cond` returns *VAR1* if *CONTROL* is true, or *VAR2* if it is not.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ cond (eq (len $geese) 1) "goose" "geese" }}
|
||||
```
|
||||
|
||||
Would emit "goose" if the `$geese` array has exactly 1 item, or "geese" otherwise.
|
||||
|
||||
{{% warning %}}
|
||||
{{% note %}}
|
||||
Whenever you use a `cond` function, *both* variable expressions are *always* evaluated. This means that a usage like `cond false (div 1 0) 27` will throw an error because `div 1 0` will be evaluated *even though the condition is false*.
|
||||
|
||||
In other words, the `cond` function does *not* provide [short-circuit evaluation](https://en.wikipedia.org/wiki/Short-circuit_evaluation) and does *not* work like a normal [ternary operator](https://en.wikipedia.org/wiki/%3F:) that will pass over the first expression if the condition returns `false`.
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
|
|
|||
|
|
@ -1,26 +1,20 @@
|
|||
---
|
||||
title: countrunes
|
||||
description: Determines the number of runes in a string excluding any whitespace.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [counting, word count]
|
||||
signature:
|
||||
- "countrunes INPUT"
|
||||
- "strings.CountRunes INPUT"
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
---
|
||||
|
||||
In contrast with `countwords` function, which counts every word in a string, the `countrunes` function determines the number of runes in the content and excludes any whitespace. This has specific utility if you are dealing with CJK-like languages.
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ "Hello, 世界" | countrunes }}
|
||||
<!-- outputs a content length of 8 runes. -->
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,24 +1,18 @@
|
|||
---
|
||||
title: countwords
|
||||
description: Counts the number of words in a string.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [counting, word count]
|
||||
signature: ["countwords INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: [countrunes]
|
||||
deprecated: false
|
||||
---
|
||||
|
||||
The template function works similar to the [.WordCount page variable][pagevars].
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ "Hugo is a static site generator." | countwords }}
|
||||
<!-- outputs a content length of 6 words. -->
|
||||
```
|
||||
|
|
|
|||
|
|
@ -4,10 +4,9 @@ description: Returns the FNV (Fowler–Noll–Vo) 32 bit hash of a given string.
|
|||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [crypto hash FNV32 Fowler-Noll-Vo]
|
||||
signature: ["crypto.FNV32a STRING"]
|
||||
aliases: []
|
||||
---
|
||||
|
||||
This function calculates the 32 bit [FNV1a hash](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function#FNV-1a_hash) of a given string according to the [specification](https://datatracker.ietf.org/doc/html/draft-eastlake-fnv-12):
|
||||
|
|
|
|||
|
|
@ -1,21 +1,15 @@
|
|||
---
|
||||
title: time.Format
|
||||
description: Converts a date/time to a localized string.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [dates,time,strings]
|
||||
signature:
|
||||
- "time.Format LAYOUT INPUT"
|
||||
- "dateFormat LAYOUT INPUT"
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: [Format,now,Unix,time]
|
||||
deprecated: false
|
||||
---
|
||||
|
||||
`time.Format` (alias `dateFormat`) converts either a `time.Time` object (e.g. `.Date`) or a timestamp string `INPUT` into the format specified by the `LAYOUT` string.
|
||||
|
|
|
|||
|
|
@ -2,22 +2,14 @@
|
|||
title: default
|
||||
description: Allows setting a default value that can be returned if a first value is not set.
|
||||
qref: "Returns a default value if a value is not set when checked."
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
keywords: [defaults]
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
toc:
|
||||
signature: ["default DEFAULT INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`default` checks whether a given value is set and returns a default value if it is not. *Set* in this context means different things depending on the data type:
|
||||
|
|
@ -42,50 +34,50 @@ newparam:
|
|||
|
||||
`default` can be written in more than one way:
|
||||
|
||||
```
|
||||
{{ index .Params "font" | default "Roboto" }}
|
||||
{{ default "Roboto" (index .Params "font") }}
|
||||
```go-html-template
|
||||
{{ .Params.font | default "Roboto" }}
|
||||
{{ default "Roboto" .Params.font }}
|
||||
```
|
||||
|
||||
Both of the above `default` function calls return `Roboto`.
|
||||
|
||||
A `default` value, however, does not need to be hard coded like the previous example. The `default` value can be a variable or pulled directly from the front matter using dot notation:
|
||||
|
||||
{{< code file="variable-as-default-value.html" nocopy="true" >}}
|
||||
{{$old := .Params.oldparam }}
|
||||
```go-html-template
|
||||
{{ $old := .Params.oldparam }}
|
||||
<p>{{ .Params.newparam | default $old }}</p>
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
Which would return:
|
||||
|
||||
```
|
||||
```html
|
||||
<p>The default function helps make your templating DRYer.</p>
|
||||
```
|
||||
|
||||
And then using dot notation
|
||||
|
||||
{{< code file="dot-notation-default-value.html" >}}
|
||||
```go-html-template
|
||||
<title>{{ .Params.seo_title | default .Title }}</title>
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
Which would return
|
||||
|
||||
{{< output file="dot-notation-default-return-value.html" >}}
|
||||
```html
|
||||
<title>Sane Defaults</title>
|
||||
{{< /output >}}
|
||||
```
|
||||
|
||||
The following have equivalent return values but are far less terse. This demonstrates the utility of `default`:
|
||||
|
||||
Using `if`:
|
||||
|
||||
{{< code file="if-instead-of-default.html" nocopy="true" >}}
|
||||
<title>{{if .Params.seo_title}}{{.Params.seo_title}}{{else}}{{.Title}}{{end}}</title>
|
||||
```go-html-template
|
||||
<title>{{ if .Params.seo_title }}{{ .Params.seo_title }}{{ else }}{{ .Title }}{{ end }}</title>
|
||||
=> Sane Defaults
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
Using `with`:
|
||||
|
||||
{{< code file="with-instead-of-default.html" nocopy="true" >}}
|
||||
<title>{{with .Params.seo_title}}{{.}}{{else}}{{.Title}}{{end}}</title>
|
||||
```go-html-template
|
||||
<title>{{ with .Params.seo_title }}{{ . }}{{ else }}{{ .Title }}{{ end }}</title>
|
||||
=> Sane Defaults
|
||||
{{< /code >}}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,62 +1,31 @@
|
|||
---
|
||||
title: delimit
|
||||
description: Loops through any array, slice, or map and returns a string of all the values separated by a delimiter.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [iteration]
|
||||
toc: false
|
||||
signature: ["delimit COLLECTION DELIMIT LAST"]
|
||||
workson: [lists,taxonomies,terms]
|
||||
hugoversion:
|
||||
signature: ["delimit COLLECTION DELIMITER [LAST]"]
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`delimit` called in your template takes the form of
|
||||
Delimit a slice:
|
||||
|
||||
```
|
||||
{{ delimit array/slice/map delimiter optionallastdelimiter}}
|
||||
```go-html-template
|
||||
{{ $s := slice "b" "a" "c" }}
|
||||
{{ delimit $s ", " }} → "b, a, c"
|
||||
{{ delimit $s ", " " and "}} → "b, a and c"
|
||||
```
|
||||
|
||||
`delimit` loops through any array, slice, or map and returns a string of all the values separated by a delimiter, the second argument in the function call. There is an optional third parameter that lets you choose a different delimiter to go between the last two values in the loop.
|
||||
Delimit a map:
|
||||
|
||||
To maintain a consistent output order, maps will be sorted by keys and only a slice of the values will be returned.
|
||||
{{% note %}}
|
||||
The `delimit` function sorts maps by key, returning the values.
|
||||
{{% /note %}}
|
||||
|
||||
The examples of `delimit` that follow all use the same front matter:
|
||||
|
||||
{{< code file="delimit-example-front-matter.toml" nocopy="true" >}}
|
||||
+++
|
||||
title: I love Delimit
|
||||
tags: [ "tag1", "tag2", "tag3" ]
|
||||
+++
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file="delimit-page-tags-input.html" >}}
|
||||
<p>Tags: {{ delimit .Params.tags ", " }}</p>
|
||||
{{< /code >}}
|
||||
|
||||
{{< output file="delimit-page-tags-output.html" >}}
|
||||
<p>Tags: tag1, tag2, tag3</p>
|
||||
{{< /output >}}
|
||||
|
||||
Here is the same example but with the optional "last" delimiter:
|
||||
|
||||
{{< code file="delimit-page-tags-final-and-input.html" >}}
|
||||
Tags: {{ delimit .Params.tags ", " ", and " }}
|
||||
{{< /code >}}
|
||||
|
||||
{{< output file="delimit-page-tags-final-and-output.html" >}}
|
||||
<p>Tags: tag1, tag2, and tag3</p>
|
||||
{{< /output >}}
|
||||
|
||||
|
||||
[lists]: /templates/lists/
|
||||
[taxonomies]: /templates/taxonomy-templates/#taxonomy-list-templates
|
||||
[terms]: /templates/taxonomy-templates/#terms-list-templates
|
||||
```go-html-template
|
||||
{{ $m := dict "b" 2 "a" 1 "c" 3 }}
|
||||
{{ delimit $m ", " }} → "1, 2, 3"
|
||||
{{ delimit $m ", " " and "}} → "1, 2 and 3"
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,19 +1,13 @@
|
|||
---
|
||||
title: dict
|
||||
description: Creates a dictionary from a list of key and value pairs.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [dictionary]
|
||||
signature: ["dict KEY VALUE [KEY VALUE]..."]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`dict` is especially useful for passing more than one value to a partial template.
|
||||
|
|
@ -30,7 +24,7 @@ The partial below creates an SVG and expects `fill`, `height` and `width` from t
|
|||
|
||||
### Partial definition
|
||||
|
||||
{{< code file="layouts/partials/svgs/external-links.svg" download="external-links.svg" >}}
|
||||
{{< code file="layouts/partials/svgs/external-links.svg" >}}
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 32" aria-label="External Link">
|
||||
<path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path>
|
||||
|
|
|
|||
|
|
@ -4,10 +4,9 @@ description: Returns a `time.Duration` structure, using the given time unit and
|
|||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [time duration]
|
||||
signature: ["duration TIME_UNIT DURATION_NUMBER"]
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`time.Duration` converts a given number into a [`time.Duration`](https://pkg.go.dev/time#Duration) structure so you can access its fields. E.g. you can perform [time operations](https://pkg.go.dev/time#Duration) on the returned `time.Duration` value:
|
||||
|
|
|
|||
|
|
@ -1,24 +1,16 @@
|
|||
---
|
||||
title: echoParam
|
||||
description: Prints a parameter if it is set.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: []
|
||||
signature: ["echoParam DICTIONARY KEY"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ echoParam .Params "project_url" }}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,19 +1,13 @@
|
|||
---
|
||||
title: emojify
|
||||
description: Runs a string through the Emoji emoticons processor.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [strings,emojis]
|
||||
signature: ["emojify INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
---
|
||||
|
||||
`emojify` runs a passed string through the Emoji emoticons processor.
|
||||
|
|
|
|||
|
|
@ -1,24 +1,16 @@
|
|||
---
|
||||
title: eq
|
||||
linktitle: eq
|
||||
description: Returns the boolean truth of arg1 == arg2.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [operators,logic]
|
||||
signature: ["eq ARG1 ARG2"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ if eq .Section "blog" }}current{{ end }}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,19 +1,13 @@
|
|||
---
|
||||
title: errorf and warnf
|
||||
description: Log ERROR or WARNING from the templates.
|
||||
date: 2017-09-30
|
||||
publishdate: 2017-09-30
|
||||
lastmod: 2017-09-30
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [strings, log, error]
|
||||
signature: ["errorf FORMAT INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: [printf]
|
||||
deprecated: false
|
||||
---
|
||||
|
||||
`errorf` or `warnf` will evaluate a format string, then output the result to the ERROR or WARNING log (and only once per error message to avoid flooding the log).
|
||||
|
|
@ -22,11 +16,11 @@ Any ERROR will also cause the build to fail (the `hugo` command will `exit -1`).
|
|||
|
||||
Both functions return an empty string, so the messages are only printed to the console.
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ errorf "Failed to handle page %q" .Path }}
|
||||
```
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ warnf "You should update the shortcodes in %q" .Path }}
|
||||
```
|
||||
|
||||
|
|
@ -38,7 +32,7 @@ Sometimes it may make sense to let the user suppress an ERROR and make the build
|
|||
|
||||
You can do this by using the `erroridf` function. This functions takes an error ID as the first argument.
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ erroridf "my-custom-error" "You should consider fixing this." }}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,22 +1,14 @@
|
|||
---
|
||||
title: "fileExists"
|
||||
linktitle: "fileExists"
|
||||
date: 2017-08-31T22:38:22+02:00
|
||||
title: fileExists
|
||||
description: Checks for file or directory existence.
|
||||
publishdate: 2017-08-31T22:38:22+02:00
|
||||
lastmod: 2021-11-26
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
signature: ["os.FileExists PATH","fileExists PATH"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: ['os.ReadDir','os.ReadFile','os.Stat']
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
The `os.FileExists` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`]({{< relref "getting-started/configuration#contentdir">}}). A leading path separator (`/`) is optional.
|
||||
The `os.FileExists` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/getting-started/configuration#contentdir). A leading path separator (`/`) is optional.
|
||||
|
||||
With this directory structure:
|
||||
|
||||
|
|
|
|||
|
|
@ -9,14 +9,25 @@ keywords: [regex]
|
|||
signature:
|
||||
- "findRE PATTERN INPUT [LIMIT]"
|
||||
- "strings.FindRE PATTERN INPUT [LIMIT]"
|
||||
relatedfuncs: [replaceRE]
|
||||
aliases: []
|
||||
relatedfuncs: [findRESubmatch, replaceRE]
|
||||
---
|
||||
By default, the `findRE` function finds all matches. You can limit the number of matches with an optional LIMIT parameter.
|
||||
By default, `findRE` finds all matches. You can limit the number of matches with an optional LIMIT parameter.
|
||||
|
||||
When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes.
|
||||
|
||||
The syntax of the regular expression is the same general syntax used by Perl, Python, and other languages. More precisely, it is the syntax accepted by [RE2] except for `\C`.
|
||||
[string literal]: https://go.dev/ref/spec#String_literals
|
||||
|
||||
This function uses the [RE2] regular expression library. See the [RE2 syntax documentation] for details. Note that the RE2 `\C` escape sequence is not supported.
|
||||
|
||||
[RE2]: https://github.com/google/re2/
|
||||
[RE2 syntax documentation]: https://github.com/google/re2/wiki/Syntax/
|
||||
|
||||
{{% note %}}
|
||||
The RE2 syntax is a subset of that accepted by [PCRE], roughly speaking, and with various [caveats].
|
||||
|
||||
[caveats]: https://swtch.com/~rsc/regexp/regexp3.html#caveats
|
||||
[PCRE]: https://www.pcre.org/
|
||||
{{% /note %}}
|
||||
|
||||
This example returns a slice of all second level headings (`h2` elements) within the rendered `.Content`:
|
||||
|
||||
|
|
@ -35,25 +46,3 @@ To limit the number of matches to one:
|
|||
{{% note %}}
|
||||
You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin.
|
||||
{{% /note %}}
|
||||
|
||||
## findRESubmatch
|
||||
|
||||
In Hugo 0.110.0 we added a variant of `findRe` that returns a slice of strings holding the text of the leftmost match of the regular expression in s and the matches, if any, of its subexpressions.
|
||||
|
||||
This:
|
||||
|
||||
```go-html-template
|
||||
{{ findRESubmatch §§<a\s*href="(.+?)">(.+?)</a>§§ §§<li><a href="#foo">Foo</a></li> <li><a href="#bar">Bar</a></li>§§ | print | safeHTML }}
|
||||
```
|
||||
|
||||
Will print:
|
||||
|
||||
```
|
||||
[[<a href=\"#foo\">Foo</a> #foo Foo] [<a href=\"#bar\">Bar</a> #bar Bar]]
|
||||
```
|
||||
|
||||
{{< new-in "0.110.0" >}}
|
||||
|
||||
|
||||
[RE2]: https://github.com/google/re2/wiki/Syntax
|
||||
[string literal]: https://go.dev/ref/spec#String_literals
|
||||
|
|
|
|||
102
docs/content/en/functions/findresubmatch.md
Normal file
102
docs/content/en/functions/findresubmatch.md
Normal file
|
|
@ -0,0 +1,102 @@
|
|||
---
|
||||
title: findRESubmatch
|
||||
description: Returns a slice of all successive matches of the regular expression. Each element is a slice of strings holding the text of the leftmost match of the regular expression and the matches, if any, of its subexpressions.
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
keywords: [regex]
|
||||
signature:
|
||||
- "findRESubmatch PATTERN INPUT [LIMIT]"
|
||||
- "strings.FindRESubmatch PATTERN INPUT [LIMIT]"
|
||||
relatedfuncs: [findRE, replaceRE]
|
||||
---
|
||||
|
||||
By default, `findRESubmatch` finds all matches. You can limit the number of matches with an optional LIMIT parameter. A return value of nil indicates no match.
|
||||
|
||||
When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes.
|
||||
|
||||
[string literal]: https://go.dev/ref/spec#String_literals
|
||||
|
||||
This function uses the [RE2] regular expression library. See the [RE2 syntax documentation] for details. Note that the RE2 `\C` escape sequence is not supported.
|
||||
|
||||
[RE2]: https://github.com/google/re2/
|
||||
[RE2 syntax documentation]: https://github.com/google/re2/wiki/Syntax/
|
||||
|
||||
{{% note %}}
|
||||
The RE2 syntax is a subset of that accepted by [PCRE], roughly speaking, and with various [caveats].
|
||||
|
||||
[caveats]: https://swtch.com/~rsc/regexp/regexp3.html#caveats
|
||||
[PCRE]: https://www.pcre.org/
|
||||
{{% /note %}}
|
||||
|
||||
## Demonstrative examples
|
||||
|
||||
```go-html-template
|
||||
{{ findRESubmatch `a(x*)b` "-ab-" }} → [["ab" ""]]
|
||||
{{ findRESubmatch `a(x*)b` "-axxb-" }} → [["axxb" "xx"]]
|
||||
{{ findRESubmatch `a(x*)b` "-ab-axb-" }} → [["ab" ""] ["axb" "x"]]
|
||||
{{ findRESubmatch `a(x*)b` "-axxb-ab-" }} → [["axxb" "xx"] ["ab" ""]]
|
||||
{{ findRESubmatch `a(x*)b` "-axxb-ab-" 1 }} → [["axxb" "xx"]]
|
||||
```
|
||||
|
||||
## Practical example
|
||||
|
||||
This markdown:
|
||||
|
||||
```text
|
||||
- [Example](https://example.org)
|
||||
- [Hugo](https://gohugo.io)
|
||||
```
|
||||
|
||||
Produces this HTML:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="https://example.org">Example</a></li>
|
||||
<li><a href="https://gohugo.io">Hugo</a></li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
To match the anchor elements, capturing the link destination and text:
|
||||
|
||||
```go-html-template
|
||||
{{ $regex := `<a\s*href="(.+?)">(.+?)</a>` }}
|
||||
{{ $matches := findRESubmatch $regex .Content }}
|
||||
```
|
||||
|
||||
Viewed as JSON, the data structure of `$matches` in the code above is:
|
||||
|
||||
```json
|
||||
[
|
||||
[
|
||||
"<a href=\"https://example.org\"></a>Example</a>",
|
||||
"https://example.org",
|
||||
"Example"
|
||||
],
|
||||
[
|
||||
"<a href=\"https://gohugo.io\">Hugo</a>",
|
||||
"https://gohugo.io",
|
||||
"Hugo"
|
||||
]
|
||||
]
|
||||
```
|
||||
|
||||
To render the `href` attributes:
|
||||
|
||||
```go-html-template
|
||||
{{ range $matches }}
|
||||
{{ index . 1 }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
```text
|
||||
https://example.org
|
||||
https://gohugo.io
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin.
|
||||
{{% /note %}}
|
||||
|
|
@ -1,21 +1,13 @@
|
|||
---
|
||||
title: first
|
||||
linktitle: first
|
||||
description: "Slices an array to only the first _N_ elements."
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [iteration]
|
||||
signature: ["first LIMIT COLLECTION"]
|
||||
workson: [lists,taxonomies,terms,groups]
|
||||
hugoversion:
|
||||
relatedfuncs: [after,last]
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`first` works in a similar manner to the [`limit` keyword in
|
||||
|
|
|
|||
|
|
@ -1,25 +1,45 @@
|
|||
---
|
||||
title: float
|
||||
linktitle: float
|
||||
description: Creates a `float` from the argument passed into the function.
|
||||
date: 2017-09-28
|
||||
publishdate: 2017-09-28
|
||||
lastmod: 2017-09-28
|
||||
description: Casts a value to a decimal (base 10) floating point value.
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
keywords: [strings,floats]
|
||||
parent: functions
|
||||
keywords: [cast,strings,floats]
|
||||
signature: ["float INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
Useful for turning strings into floating point numbers.
|
||||
With a decimal (base 10) input:
|
||||
|
||||
```go-html-template
|
||||
{{ float 11 }} → 11 (float64)
|
||||
{{ float "11" }} → 11 (float64)
|
||||
|
||||
{{ float 11.1 }} → 11.1 (float64)
|
||||
{{ float "11.1" }} → 11.1 (float64)
|
||||
|
||||
{{ float 11.9 }} → 11.9 (float64)
|
||||
{{ float "11.9" }} → 11.9 (float64)
|
||||
```
|
||||
{{ float "1.23" }} → 1.23
|
||||
|
||||
With a binary (base 2) input:
|
||||
|
||||
```go-html-template
|
||||
{{ float 0b11 }} → 3 (float64)
|
||||
```
|
||||
|
||||
With an octal (base 8) input (use either notation):
|
||||
|
||||
```go-html-template
|
||||
{{ float 011 }} → 9 (float64)
|
||||
{{ float "011" }} → 11 (float64)
|
||||
|
||||
{{ float 0o11 }} → 9 (float64)
|
||||
```
|
||||
|
||||
With a hexadecimal (base 16) input:
|
||||
|
||||
```go-html-template
|
||||
{{ float 0x11 }} → 17 (float64)
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,20 +1,13 @@
|
|||
---
|
||||
title: .Format
|
||||
description: Formats built-in Hugo dates---`.Date`, `.PublishDate`, and `.Lastmod`---according to Go's layout string.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [dates,time]
|
||||
signature: [".Format FORMAT"]
|
||||
workson: [times]
|
||||
hugoversion:
|
||||
relatedfuncs: [dateFormat,now,Unix,time]
|
||||
deprecated: false
|
||||
aliases: []
|
||||
toc: true
|
||||
---
|
||||
|
||||
|
|
@ -26,7 +19,7 @@ toc: true
|
|||
|
||||
Assuming a key-value of `date: 2017-03-03` in a content file's front matter, your can run the date through `.Format` followed by a layout string for your desired output at build time:
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ .PublishDate.Format "January 2, 2006" }} => March 3, 2017
|
||||
```
|
||||
|
||||
|
|
@ -97,7 +90,7 @@ Spelled-out cardinal numbers (e.g. "one", "two", and "three") are not currently
|
|||
|
||||
Use the [`humanize`](/functions/humanize) function to render the day of the month as an ordinal number:
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ humanize .Date.Day }} of {{ .Date.Format "January 2006" }}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,24 +1,16 @@
|
|||
---
|
||||
title: ge
|
||||
linktitle: ge
|
||||
description: Returns the boolean truth of arg1 >= arg2.
|
||||
date: 2017-07-26
|
||||
publishdate: 2017-07-26
|
||||
lastmod: 2017-07-26
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [operators,logic]
|
||||
signature: ["ge ARG1 ARG2"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ if ge 10 5 }}true{{ end }}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,21 +1,13 @@
|
|||
---
|
||||
title: .Get
|
||||
description: Accesses positional and ordered parameters in shortcode declaration.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [shortcodes]
|
||||
signature: [".Get INDEX", ".Get KEY"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
needsexample: true
|
||||
---
|
||||
|
||||
`.Get` is specifically used when creating your own [shortcode template][sc], to access the [positional and named](/templates/shortcode-templates/#positional-vs-named-parameters) parameters passed to it. When used with a numeric INDEX, it queries positional parameters (starting with 0). With a string KEY, it queries named parameters.
|
||||
|
|
|
|||
|
|
@ -1,20 +1,13 @@
|
|||
---
|
||||
title: getenv
|
||||
description: Returns the value of an environment variable, or an empty string if the environment variable is not set.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2021-11-26
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: []
|
||||
signature: ["os.Getenv VARIABLE", "getenv VARIABLE"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
Examples:
|
||||
|
||||
|
|
@ -43,4 +36,3 @@ And then retrieve the values within a template:
|
|||
```
|
||||
|
||||
With Hugo v0.91.0 and later, you must explicitly allow access to environment variables. For details, review [Hugo's Security Policy](/about/security-model/#security-policy). By default, environment variables beginning with `HUGO_` are allowed when using the `os.Getenv` function.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,14 +1,12 @@
|
|||
---
|
||||
title: group
|
||||
description: "`group` groups a list of pages."
|
||||
date: 2018-09-14
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [collections]
|
||||
signature: ["PAGES | group KEY"]
|
||||
hugoversion: "0.49"
|
||||
---
|
||||
|
||||
{{< code file="layouts/partials/groups.html" >}}
|
||||
|
|
|
|||
|
|
@ -1,24 +1,16 @@
|
|||
---
|
||||
title: gt
|
||||
linktitle: gt
|
||||
description: Returns the boolean truth of arg1 > arg2.
|
||||
date: 2017-07-26
|
||||
publishdate: 2017-07-26
|
||||
lastmod: 2017-07-26
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [operators,logic]
|
||||
signature: ["gt ARG1 ARG2"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ if gt 10 5 }}true{{ end }}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,22 +1,13 @@
|
|||
---
|
||||
title: .HasMenuCurrent
|
||||
description:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [menus]
|
||||
signature: ["PAGE.HasMenuCurrent MENU MENUENTRY"]
|
||||
workson: [menus]
|
||||
hugoversion:
|
||||
relatedfuncs: ["IsMenuCurrent"]
|
||||
deprecated: false
|
||||
toc: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`.HasMenuCurrent` is a method in `Page` object returning a _boolean_ value. It
|
||||
|
|
|
|||
|
|
@ -1,18 +1,13 @@
|
|||
---
|
||||
title: highlight
|
||||
linktitle: highlight
|
||||
description: Renders code with a syntax highlighter.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2021-12-06
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [highlighting,code blocks,syntax]
|
||||
signature: ["transform.Highlight INPUT LANG [OPTIONS]","highlight INPUT LANG [OPTIONS]"]
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
toc: true
|
||||
---
|
||||
The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 available styles.
|
||||
|
|
@ -101,8 +96,8 @@ Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the f
|
|||
```
|
||||
|
||||
[Chroma]: https://github.com/alecthomas/chroma
|
||||
[hugo client]: {{< relref "commands/hugo_gen_chromastyles" >}}
|
||||
[options]: {{< relref "#options" >}}
|
||||
[site configuration]: {{< relref "getting-started/configuration-markup#highlight">}}
|
||||
[hugo client]: /commands/hugo_gen_chromastyles
|
||||
[options]: #options
|
||||
[site configuration]: /getting-started/configuration-markup#highlight
|
||||
[style gallery]: https://xyproto.github.io/splash/docs/
|
||||
[supported languages]: {{< relref "content-management/syntax-highlighting#list-of-chroma-highlighting-languages" >}}
|
||||
[supported languages]: /content-management/syntax-highlighting#list-of-chroma-highlighting-languages
|
||||
|
|
|
|||
|
|
@ -1,21 +1,13 @@
|
|||
---
|
||||
title: hmac
|
||||
linktitle: hmac
|
||||
description: Returns a cryptographic hash that uses a key to sign a message.
|
||||
date: 2020-05-29
|
||||
publishdate: 2020-05-29
|
||||
lastmod: 2020-05-29
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [hmac,checksum]
|
||||
signature: ["crypto.HMAC HASH_TYPE KEY MESSAGE [ENCODING]","hmac HASH_TYPE KEY MESSAGE [ENCODING]" ]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: [hmac]
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
Set the `HASH_TYPE` argument to `md5`, `sha1`, `sha256`, or `sha512`.
|
||||
|
|
|
|||
|
|
@ -1,25 +1,17 @@
|
|||
---
|
||||
title: htmlEscape
|
||||
linktitle:
|
||||
description: Returns the given string with the reserved HTML codes escaped.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [strings, html]
|
||||
signature: ["htmlEscape INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: [htmlUnescape]
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
In the result `&` becomes `&` and so on. It escapes only: `<`, `>`, `&`, `'` and `"`.
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ htmlEscape "Hugo & Caddy > WordPress & Apache" }} → "Hugo & Caddy > WordPress & Apache"
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,27 +1,19 @@
|
|||
---
|
||||
title: htmlUnescape
|
||||
linktitle: htmlUnescape
|
||||
description: Returns the given string with HTML escape codes un-escaped.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: []
|
||||
signature: ["htmlUnescape INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: [htmlEscape]
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`htmlUnescape` returns the given string with HTML escape codes un-escaped.
|
||||
|
||||
Remember to pass the output of this to `safeHTML` if fully un-escaped characters are desired. Otherwise, the output will be escaped again as normal.
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ htmlUnescape "Hugo & Caddy > WordPress & Apache" }} → "Hugo & Caddy > WordPress & Apache"
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,22 +1,14 @@
|
|||
---
|
||||
title: hugo
|
||||
linktitle: hugo
|
||||
description: The `hugo` function provides easy access to Hugo-related data.
|
||||
date: 2019-01-31
|
||||
publishdate: 2019-01-31
|
||||
keywords: []
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
toc:
|
||||
signature: ["hugo"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`hugo` returns an instance that contains the following functions:
|
||||
|
|
@ -45,10 +37,6 @@ hugo.IsExtended
|
|||
hugo.IsProduction
|
||||
: returns true if `hugo.Environment` is set to the production environment
|
||||
|
||||
{{% note "Use the Hugo Generator Tag" %}}
|
||||
We highly recommend using `hugo.Generator` in your website's `<head>`. `hugo.Generator` is included by default in all themes hosted on [themes.gohugo.io](https://themes.gohugo.io). The generator tag allows the Hugo team to track the usage and popularity of Hugo.
|
||||
{{% /note %}}
|
||||
|
||||
hugo.Deps
|
||||
: See [hugo.Deps](#hugodeps)
|
||||
|
||||
|
|
@ -97,10 +85,10 @@ An example table listing the dependencies:
|
|||
{{ range $index, $element := hugo.Deps }}
|
||||
<tr>
|
||||
<th scope="row">{{ add $index 1 }}</th>
|
||||
<td>{{ with $element.Owner }}{{.Path }}{{ end }}</td>
|
||||
<td>{{ with $element.Owner }}{{ .Path }}{{ end }}</td>
|
||||
<td>
|
||||
{{ $element.Path }}
|
||||
{{ with $element.Replace}}
|
||||
{{ with $element.Replace }}
|
||||
=> {{ .Path }}
|
||||
{{ end }}
|
||||
</td>
|
||||
|
|
|
|||
|
|
@ -1,29 +1,21 @@
|
|||
---
|
||||
title: humanize
|
||||
linktitle:
|
||||
description: Returns the humanized version of an argument with the first letter capitalized.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [strings,casing]
|
||||
signature: ["humanize INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: [anchorize]
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
If the input is either an int64 value or the string representation of an integer, humanize returns the number with the proper ordinal appended.
|
||||
|
||||
|
||||
```
|
||||
{{humanize "my-first-post"}} → "My first post"
|
||||
{{humanize "myCamelPost"}} → "My camel post"
|
||||
{{humanize "52"}} → "52nd"
|
||||
{{humanize 103}} → "103rd"
|
||||
```go-html-template
|
||||
{{ humanize "my-first-post" }} → "My first post"
|
||||
{{ humanize "myCamelPost" }} → "My camel post"
|
||||
{{ humanize "52" }} → "52nd"
|
||||
{{ humanize 103 }} → "103rd"
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,33 +1,25 @@
|
|||
---
|
||||
title: i18n
|
||||
linktitle: i18n
|
||||
description: Translates a piece of content based on your i18n configuration files.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [internationalization,i18n,multilingual]
|
||||
signature:
|
||||
- "i18n KEY"
|
||||
- "T KEY"
|
||||
- "lang.Translate KEY"
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
This translates a piece of content based on your `i18n/en-US.toml` files. You can use the [go-i18n](https://github.com/nicksnyder/go-i18n) tools to manage your translations. The translations can exist in both the theme and at the root of your repository.
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ i18n "translation_id" }}
|
||||
```
|
||||
|
||||
{{% note "Alias `T`" %}}
|
||||
{{% note %}}
|
||||
`T` is an alias to `i18n`. E.g. `{{ T "translation_id" }}`.
|
||||
{{% /note %}}
|
||||
|
||||
|
|
@ -35,7 +27,7 @@ This translates a piece of content based on your `i18n/en-US.toml` files. You ca
|
|||
|
||||
Often you will want to use the page variables in the translation strings. To do so, pass the `.` context when calling `i18n`:
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ i18n "wordCount" . }}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,11 @@
|
|||
---
|
||||
title: Image Filters
|
||||
description: The images namespace provides a list of filters and other image related functions.
|
||||
date: 2017-02-01
|
||||
categories: [functions]
|
||||
aliases: [/functions/imageconfig/]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [images]
|
||||
toc: true
|
||||
---
|
||||
|
|
@ -46,7 +45,7 @@ images.Text TEXT DICT)
|
|||
The following example will add the text `Hugo rocks!` to the image with the specified color, size and position.
|
||||
|
||||
```go-html-template
|
||||
{{ $img := resources.Get "/images/background.png"}}
|
||||
{{ $img := resources.Get "/images/background.png" }}
|
||||
{{ $img = $img.Filter (images.Text "Hugo rocks!" (dict
|
||||
"color" "#ffffff"
|
||||
"size" 60
|
||||
|
|
@ -61,7 +60,7 @@ You can load a custom font if needed. Load the font as a Hugo `Resource` and set
|
|||
```go-html-template
|
||||
|
||||
{{ $font := resources.GetRemote "https://github.com/google/fonts/raw/main/apache/roboto/static/Roboto-Black.ttf" }}
|
||||
{{ $img := resources.Get "/images/background.png"}}
|
||||
{{ $img := resources.Get "/images/background.png" }}
|
||||
{{ $img = $img.Filter (images.Text "Hugo rocks!" (dict
|
||||
"font" $font
|
||||
))}}
|
||||
|
|
@ -222,6 +221,6 @@ images.ImageConfig PATH
|
|||
|
||||
```go-html-template
|
||||
{{ with (imageConfig "favicon.ico") }}
|
||||
favicon.ico: {{.Width}} x {{.Height}}
|
||||
favicon.ico: {{ .Width }} x {{ .Height }}
|
||||
{{ end }}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,32 +1,24 @@
|
|||
---
|
||||
title: in
|
||||
linktitle:
|
||||
description: Checks if an element is in an array or slice--or a substring in a string---and returns a boolean.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [strings]
|
||||
signature: ["in SET ITEM"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
The elements supported are strings, integers and floats, although only float64 will match as expected.
|
||||
|
||||
In addition, `in` can also check if a substring exists in a string.
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ if in .Params.tags "Git" }}Follow me on GitHub!{{ end }}
|
||||
```
|
||||
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ if in "this string contains a substring" "substring" }}Substring found!{{ end }}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,22 +1,14 @@
|
|||
---
|
||||
title: index
|
||||
linktitle: index
|
||||
description: Looks up the index(es) or key(s) of the data structure passed into it.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: []
|
||||
signature: ["index COLLECTION INDEXES", "index COLLECTION KEYS"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: [/functions/index/]
|
||||
needsexample: true
|
||||
---
|
||||
|
||||
The `index` functions returns the result of indexing its first argument by the following arguments. Each indexed item must be a map or a slice, e.g.:
|
||||
|
|
@ -61,7 +53,7 @@ Assume you want to add a `location = ""` field to your front matter for every ar
|
|||
|
||||
Here is an example:
|
||||
|
||||
{{< code-toggle file="data/locations/oslo" >}}
|
||||
{{< code-toggle file="data/locations/oslo" copy=false >}}
|
||||
website = "https://www.oslo.kommune.no"
|
||||
pop_city = 658390
|
||||
pop_metro = 1717900
|
||||
|
|
@ -69,10 +61,10 @@ pop_metro = 1717900
|
|||
|
||||
The example we will use will be an article on Oslo, whose front matter should be set to exactly the same name as the corresponding file name in `data/locations/`:
|
||||
|
||||
```
|
||||
{{< code-toggle file="content/articles/oslo.md" fm=true copy=false >}}
|
||||
title = "My Norwegian Vacation"
|
||||
location = "oslo"
|
||||
```
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The content of `oslo.toml` can be accessed from your template using the following node path: `.Site.Data.locations.oslo`. However, the specific file you need is going to change according to the front matter.
|
||||
|
||||
|
|
@ -81,20 +73,20 @@ This is where the `index` function is needed. `index` takes 2 parameters in this
|
|||
1. The node path
|
||||
2. A string corresponding to the desired data; e.g.—
|
||||
|
||||
```
|
||||
{{ index .Site.Data.locations “oslo” }}
|
||||
```go-html-template
|
||||
{{ index .Site.Data.locations "oslo" }}
|
||||
```
|
||||
|
||||
The variable for `.Params.location` is a string and can therefore replace `oslo` in the example above:
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ index .Site.Data.locations .Params.location }}
|
||||
=> map[website:https://www.oslo.kommune.no pop_city:658390 pop_metro:1717900]
|
||||
```
|
||||
|
||||
Now the call will return the specific file according to the location specified in the content's front matter, but you will likely want to write specific properties to the template. You can do this by continuing down the node path via dot notation (`.`):
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ (index .Site.Data.locations .Params.location).pop_city }}
|
||||
=> 658390
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,50 +1,51 @@
|
|||
---
|
||||
title: int
|
||||
linktitle: int
|
||||
description: Creates an `int` from the argument passed into the function.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
description: Casts a value to a decimal (base 10) integer.
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
keywords: [strings,integers]
|
||||
parent: functions
|
||||
keywords: [cast,strings,integers]
|
||||
signature: ["int INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
Useful for turning strings into numbers.
|
||||
With a decimal (base 10) input:
|
||||
|
||||
```
|
||||
{{ int "123" }} → 123
|
||||
```go-html-template
|
||||
{{ int 11 }} → 11 (int)
|
||||
{{ int "11" }} → 11 (int)
|
||||
|
||||
{{ int 11.1 }} → 11 (int)
|
||||
{{ int 11.9 }} → 11 (int)
|
||||
```
|
||||
|
||||
{{% note "Usage Note" %}}
|
||||
If the input string is supposed to represent a decimal number, and if it has
|
||||
leading 0's, then those 0's will have to be removed before passing the string
|
||||
to the `int` function, else that string will be tried to be parsed as an octal
|
||||
number representation.
|
||||
With a binary (base 2) input:
|
||||
|
||||
The [`strings.TrimLeft` function](/functions/strings.trimleft/) can be used for
|
||||
this purpose.
|
||||
|
||||
```
|
||||
{{ int ("0987" | strings.TrimLeft "0") }}
|
||||
{{ int ("00987" | strings.TrimLeft "0") }}
|
||||
```go-html-template
|
||||
{{ int 0b11 }} → 3 (int)
|
||||
{{ int "0b11" }} → 3 (int)
|
||||
```
|
||||
|
||||
### Explanation
|
||||
With an octal (base 8) input (use either notation):
|
||||
|
||||
The `int` function eventually calls the `ParseInt` function from the Go library
|
||||
`strconv`.
|
||||
```go-html-template
|
||||
{{ int 011 }} → 9 (int)
|
||||
{{ int "011" }} → 9 (int)
|
||||
|
||||
From its [documentation](https://golang.org/pkg/strconv/#ParseInt):
|
||||
{{ int 0o11 }} → 9 (int)
|
||||
{{ int "0o11" }} → 9 (int)
|
||||
```
|
||||
|
||||
> the base is implied by the string's prefix: base 16 for "0x", base 8 for "0",
|
||||
> and base 10 otherwise.
|
||||
With a hexadecimal (base 16) input:
|
||||
|
||||
```go-html-template
|
||||
{{ int 0x11 }} → 17 (int)
|
||||
{{ int "0x11" }} → 17 (int)
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros:
|
||||
|
||||
`{{ strings.TrimLeft "0" "0011" | int }} → 11`
|
||||
{{% /note %}}
|
||||
|
|
|
|||
|
|
@ -1,27 +1,19 @@
|
|||
---
|
||||
title: intersect
|
||||
linktitle: intersect
|
||||
description: Returns the common elements of two arrays or slices, in the same order as the first array.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [collections,intersect,union,complement,symdiff]
|
||||
signature: ["intersect SET1 SET2"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
A useful example is to use it as `AND` filters when combined with where:
|
||||
|
||||
## AND filter in where query
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
|
||||
{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
|
||||
{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
|
||||
|
|
|
|||
|
|
@ -1,22 +1,13 @@
|
|||
---
|
||||
title: .IsMenuCurrent
|
||||
description:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [menus]
|
||||
signature: ["PAGE.IsMenuCurrent MENU MENUENTRY"]
|
||||
workson: [menus]
|
||||
hugoversion:
|
||||
relatedfuncs: ["HasMenuCurrent"]
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
needsexample: true
|
||||
---
|
||||
|
||||
`.IsMenuCurrent` is a method in `Page` object returning a _boolean_ value. It
|
||||
|
|
|
|||
|
|
@ -1,30 +1,22 @@
|
|||
---
|
||||
title: isset
|
||||
linktitle: isset
|
||||
description: Returns true if the parameter is set.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: []
|
||||
signature: ["isset COLLECTION INDEX", "isset COLLECTION KEY"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
Takes either a slice, array, or channel and an index or a map and a key as input.
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }}
|
||||
```
|
||||
|
||||
{{% warning %}}
|
||||
All site-level configuration keys are stored as lower case. Therefore, a `myParam` key-value set in your [site configuration file](/getting-started/configuration/) needs to be accessed with `{{if isset .Site.Params "myparam"}}` and *not* with `{{if isset .Site.Params "myParam"}}`. Note that you can still access the same config key with `.Site.Params.myParam` *or* `.Site.Params.myparam`, for example, when using [`with`](/functions/with).
|
||||
{{% note %}}
|
||||
All site-level configuration keys are stored as lower case. Therefore, a `myParam` key-value set in your [site configuration file](/getting-started/configuration/) needs to be accessed with `{{ if isset .Site.Params "myparam" }}` and *not* with `{{ if isset .Site.Params "myParam" }}`. Note that you can still access the same config key with `.Site.Params.myParam` *or* `.Site.Params.myparam`, for example, when using [`with`](/functions/with).
|
||||
This restriction also applies when accessing page-level front matter keys from within [shortcodes](/content-management/shortcodes/).
|
||||
{{% /warning %}}
|
||||
{{% /note %}}
|
||||
|
|
|
|||
|
|
@ -1,21 +1,13 @@
|
|||
---
|
||||
title: jsonify
|
||||
linktitle: jsonify
|
||||
description: Encodes a given object to JSON.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2020-04-13
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [strings,json]
|
||||
signature: ["jsonify INPUT", "jsonify OPTIONS INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: [plainify]
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
Jsonify encodes a given object to JSON.
|
||||
|
|
@ -26,7 +18,7 @@ the output will begin on a new line beginning with *prefix* followed by one or
|
|||
more copies of *indent* according to the indentation nesting.
|
||||
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ dict "title" .Title "content" .Plain | jsonify }}
|
||||
{{ dict "title" .Title "content" .Plain | jsonify (dict "indent" " ") }}
|
||||
{{ dict "title" .Title "content" .Plain | jsonify (dict "prefix" " " "indent" " ") }}
|
||||
|
|
|
|||
|
|
@ -1,20 +1,13 @@
|
|||
---
|
||||
title: lang.Merge
|
||||
description: "Merge missing translations from other languages."
|
||||
date: 2018-03-16
|
||||
categories: [functions]
|
||||
keywords: [multilingual]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
toc: false
|
||||
parent: functions
|
||||
signature: ["lang.Merge FROM TO"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
comments:
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -2,15 +2,12 @@
|
|||
title: lang
|
||||
package: lang
|
||||
description: "TODO.."
|
||||
date: 2021-07-28
|
||||
categories: [functions]
|
||||
keywords: [numbers]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
signature: ["lang.NumFmt PRECISION NUMBER [OPTIONS [DELIMITER]]"]
|
||||
aliases: ['/functions/numfmt/']
|
||||
type: 'template-func'
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,27 +1,18 @@
|
|||
---
|
||||
title: last
|
||||
linktitle: last
|
||||
description: "slices an array to only the last <em>N</em>th elements."
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
keywords: []
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
toc:
|
||||
signature: ["last INDEX COLLECTION"]
|
||||
workson: [lists, taxonomies, terms, groups]
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ range last 10 .Pages }}
|
||||
{{ .Render "summary" }}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,24 +1,16 @@
|
|||
---
|
||||
title: le
|
||||
linktitle: le
|
||||
description: Returns the boolean truth of arg1 <= arg2.
|
||||
date: 2017-07-26
|
||||
publishdate: 2017-07-26
|
||||
lastmod: 2017-07-26
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [operators,logic]
|
||||
signature: ["le ARG1 ARG2"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ if le 5 10 }}true{{ end }}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,63 +1,44 @@
|
|||
---
|
||||
title: len
|
||||
linktitle: len
|
||||
description: Returns the length of a variable according to its type.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-04-18
|
||||
description: Returns the length of a string, slice, map, or collection.
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
keywords: []
|
||||
parent: functions
|
||||
keywords: [length]
|
||||
signature: ["len INPUT"]
|
||||
workson: [lists,taxonomies,terms]
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
toc: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`len` is a built-in function in Go that returns the length of a variable according to its type. From the Go documentation:
|
||||
With a string:
|
||||
|
||||
> Array: the number of elements in v.
|
||||
>
|
||||
> Pointer to array: the number of elements in *v (even if v is nil).
|
||||
>
|
||||
> Slice, or map: the number of elements in v; if v is nil, len(v) is zero.
|
||||
>
|
||||
> String: the number of bytes in v.
|
||||
>
|
||||
> Channel: the number of elements queued (unread) in the channel buffer; if v is nil, len(v) is zero.
|
||||
```go-html-template
|
||||
{{ "ab" | len }} → 2
|
||||
{{ "" | len }} → 0
|
||||
```
|
||||
|
||||
`len` is also considered a [fundamental function for Hugo templating].
|
||||
With a slice:
|
||||
|
||||
## `len` Example 1: Longer Headings
|
||||
```go-html-template
|
||||
{{ slice "a" "b" | len }} → 2
|
||||
{{ slice | len }} → 0
|
||||
```
|
||||
|
||||
You may want to append a class to a heading according to the length of the string therein. The following templating checks to see if the title's length is greater than 80 characters and, if so, adds a `long-title` class to the `<h1>`:
|
||||
With a map:
|
||||
|
||||
{{< code file="check-title-length.html" >}}
|
||||
<header>
|
||||
<h1{{if gt (len .Title) 80}} class="long-title"{{end}}>{{.Title}}</h1>
|
||||
</header>
|
||||
{{< /code >}}
|
||||
```go-html-template
|
||||
{{ dict "a" 1 "b" 2 | len }} → 2
|
||||
{{ dict | len }} → 0
|
||||
```
|
||||
|
||||
## `len` Example 2: Counting Pages with `where`
|
||||
With a collection:
|
||||
|
||||
The following templating uses [`where`] in conjunction with `len` to
|
||||
figure out the total number of content pages in a `posts` [section]:
|
||||
```go-html-template
|
||||
{{ site.RegularPages | len }} → 42
|
||||
```
|
||||
|
||||
{{< code file="how-many-posts.html" >}}
|
||||
{{ $posts := (where .Site.RegularPages "Section" "==" "posts") }}
|
||||
{{ $postCount := len $posts }}
|
||||
{{< /code >}}
|
||||
You may also determine the number of pages in a collection with:
|
||||
|
||||
Note the use of `.RegularPages`, a [site variable] that counts all regular content pages but not the `_index.md` pages used to add front matter and content to [list templates].
|
||||
|
||||
|
||||
[fundamental function for Hugo templating]: /templates/introduction/
|
||||
[list templates]: /templates/lists/
|
||||
[section]: /content-management/sections/
|
||||
[site variable]: /variables/site/
|
||||
[`where`]: /functions/where/
|
||||
```go-html-template
|
||||
{{ site.RegularPages.Len }} → 42
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,23 +1,15 @@
|
|||
---
|
||||
title: lower
|
||||
linktitle: lower
|
||||
description: Converts all characters in the provided string to lowercase.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [strings,casing]
|
||||
signature:
|
||||
- "lower INPUT"
|
||||
- "strings.ToLower INPUT"
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,24 +1,16 @@
|
|||
---
|
||||
title: lt
|
||||
linktitle: lt
|
||||
description: Returns the boolean truth of arg1 < arg2.
|
||||
date: 2017-07-26
|
||||
publishdate: 2017-07-26
|
||||
lastmod: 2017-07-26
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
keywords: [operators,logic]
|
||||
signature: ["lt ARG1 ARG2"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ if lt 5 10 }}true{{ end }}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,29 +1,30 @@
|
|||
---
|
||||
title: markdownify
|
||||
linktitle: markdownify
|
||||
description: Runs the provided string through the Markdown processor.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2023-02-09
|
||||
description: Renders markdown to HTML.
|
||||
keywords: [markdown,content]
|
||||
categories: [functions]
|
||||
menu:
|
||||
docs:
|
||||
parent: "functions"
|
||||
parent: functions
|
||||
signature: ["markdownify INPUT"]
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
|
||||
```
|
||||
```go-html-template
|
||||
{{ .Title | markdownify }}
|
||||
```
|
||||
|
||||
{{< new-in "0.93.0" >}} **Note**: `markdownify` now supports [Render Hooks] just like [`.Page.RenderString`]. However, if you use more complicated [Render Hooks] relying on page context, use [`.Page.RenderString`] instead. See [GitHub issue #9692](https://github.com/gohugoio/hugo/issues/9692) for more details.
|
||||
If the resulting HTML is a single paragraph, Hugo removes the wrapping `p` tags to produce inline HTML as required per the example above.
|
||||
|
||||
To keep the wrapping `p` tags for a single paragraph, use the [`.Page.RenderString`] method, setting the `display` option to `block`.
|
||||
|
||||
If the resulting HTML is two or more paragraphs, Hugo leaves the wrapping `p` tags in place.
|
||||
|
||||
[Render Hooks]: /templates/render-hooks/
|
||||
[`.Page.RenderString`]: /functions/renderstring/
|
||||
|
||||
{{% note %}}
|
||||
Although the `markdownify` function honors [markdown render hooks] when rendering markdown to HTML, use the `.Page.RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details.
|
||||
|
||||
[markdown render hooks]: /templates/render-hooks/
|
||||
[#9692]: https://github.com/gohugoio/hugo/issues/9692
|
||||
{{% /note %}}
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue