phoenix/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-07-02 13:06:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '87de22d7464e239c775fbd48ebce1665d5b1e80d'

Browse source
This commit is contained in:
Bjørn Erik Pedersen 2023-07-29 11:17:28 +02:00
parent bec9b80d95 87de22d746
commit 8859be1c01
No known key found for this signature in database
GPG key ID: 330E6E2BD4859D8F
177 changed files with 1623 additions and 1556 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/.github/SUPPORT.md vendored
View file

@ -1,3 +1,3 @@
### Asking Support Questions
### Asking support questions
We have an active [discussion forum](https://discourse.gohugo.io) where users and developers can ask questions. Please don't use the GitHub issue tracker to ask questions.

5
docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/bep-consulting.svg generated
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.5 KiB

After

Width:  |  Height:  |  Size: 9.3 KiB

6
docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/cloudcannon-blue.svg generated Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 13 KiB

6
docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/cloudcannon-white.svg generated Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 13 KiB

21
docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml generated
View file

@ -3,19 +3,20 @@
link = "https://www.linode.com/"
logo = "images/sponsors/linode-logo.svg"
utm_campaign = "hugosponsor"
bgcolor = "#ffffff"
[[banners]]
name = "CloudCannon"
link = "https://cloudcannon.com/hugo-cms/"
logo = "/images/sponsors/cloudcannon-white.svg"
utm_campaign = "HugoSponsorship"
utm_source = "sponsor"
utm_content = "gohugo"
bgcolor = "#034AD8"
[[banners]]
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 = "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"
bgcolor = "#4e4f4f"

6
docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html generated
View file

@ -23,7 +23,7 @@
class="{{ $classes_box }} o-100"
style="background-color: {{ .bgcolor }};">
{{ $query_params := .query_params | default "" }}
{{ $url := printf "%s?%s%s" .link $query_params (querify "utm_source" $utmSource "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor")) | safeURL }}
{{ $url := printf "%s?%s%s" .link $query_params (querify "utm_source" (.utm_source | default $utmSource ) "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor") "utm_content" (.utm_content | default "gohugoio")) | safeURL }}
{{ $logo := resources.Get .logo }}
{{ if hugo.IsProduction }}
{{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }}
@ -34,7 +34,7 @@
show-on-hover
{{ end }}"
style="">
{{ $logo.Content | safeHTML }}
{{ with $logo }}{{ .Content | safeHTML }}{{ end }}
</a>
{{ else }}
<a
@ -42,7 +42,7 @@
class="w-100 grow pa3{{ if .show_on_hover }}
show-on-hover
{{ end }}">
{{ $logo.Content | safeHTML }}
{{ with $logo }}{{ .Content | safeHTML }}{{ end }}
</a>
{{ end }}
</div>

2
docs/_vendor/modules.txt
View file

@ -1 +1 @@
# github.com/gohugoio/gohugoioTheme v0.0.0-20230527124826-78bc315d7b8a
# github.com/gohugoio/gohugoioTheme v0.0.0-20230630055807-9874cd863bc5

12
docs/config/_default/menus/menus.en.toml
View file

@ -11,7 +11,7 @@
url = "/installation/"
[[docs]]
name = "Getting Started"
name = "Getting started"
weight = 30
identifier = "getting-started"
url = "/getting-started/"
@ -26,7 +26,7 @@
# Core menus
[[docs]]
name = "Content Management"
name = "Content management"
weight = 50
identifier = "content-management"
post = "expanded"
@ -53,7 +53,7 @@
[[docs]]
name = "Hugo Pipes"
weight = 90
identifier = "pipes"
identifier = "hugo-pipes"
url = "/hugo-pipes/"
[[docs]]
@ -72,13 +72,13 @@
url = "/troubleshooting/"
[[docs]]
name = "Tools"
name = "Developer tools"
weight = 120
identifier = "tools"
identifier = "developer-tools"
url = "/tools/"
[[docs]]
name = "Hosting & Deployment"
name = "Hosting and deployment"
weight = 130
identifier = "hosting-and-deployment"
url = "/hosting-and-deployment/"

2
docs/content/en/_index.md
View file

@ -1,5 +1,5 @@
---
title: "The world’s fastest framework for building websites"
title: The world’s fastest framework for building websites
date: 2017-03-02T12:00:00-05:00
features:
- heading: Blistering Speed

7
docs/content/en/about/_index.md
View file

@ -1,14 +1,15 @@
---
title: About Hugo
linktitle: Overview
linkTitle: Overview
description: Hugo's features, roadmap, license, and motivation.
categories: []
keywords: []
menu:
docs:
identifier: about-hugo-overview
parent: about
weight: 1
weight: 1
weight: 10
weight: 10
aliases: [/about-hugo/,/docs/]
---

10
docs/content/en/about/benefits.md
View file

@ -1,13 +1,13 @@
---
title: The Benefits of Static Site Generators
linktitle: The Benefits of Static
title: Benefits of static site generators
linkTitle: Static site generators
description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing.
keywords: [ssg,static,performance,security]
menu:
docs:
parent: about
weight: 30
weight: 30
weight: 40
weight: 40
---
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.
@ -18,7 +18,7 @@ Hugo takes caching a step further and all HTML files are rendered on your comput
This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site.
## More on Static Site Generators
## More on static site generators
* ["An Introduction to Static Site Generators", David Walsh]
* ["Hugo vs. WordPress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress]

8
docs/content/en/about/features.md
View file

@ -1,11 +1,11 @@
---
title: Hugo Features
title: 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.
menu:
docs:
parent: about
weight: 20
weight: 20
weight: 30
weight: 30
toc: true
---
@ -40,7 +40,7 @@ toc: true
* ["Minutes to Read"][pagevars] functionality
* ["WordCount"][pagevars] functionality
## Additional Features
## Additional features
* Integrated [Disqus] comment support
* Integrated [Google Analytics] support

22
docs/content/en/about/hugo-and-gdpr.md
View file

@ -1,14 +1,14 @@
---
title: Hugo and the General Data Protection Regulation (GDPR)
linktitle: Hugo and GDPR
title: Hugo and the General Data Protection Regulation
linkTitle: Hugo and the GDPR
description: About how to configure your Hugo site to meet the new regulations.
layout: single
keywords: ["GDPR", "Privacy", "Data Protection"]
menu:
docs:
parent: about
weight: 5
weight: 5
weight: 60
weight: 60
aliases: [/privacy/,/gdpr/]
toc: true
---
@ -17,7 +17,7 @@ toc: true
**Hugo is a static site generator. By using Hugo you are already standing on very solid ground. Static HTML files on disk are much easier to reason about compared to server and database driven web sites.**
But even static websites can integrate with external services, so from version `0.41`, Hugo provides a **Privacy Config** that covers the relevant built-in templates.
But even static websites can integrate with external services, so from version `0.41`, Hugo provides a **privacy configuration** that covers the relevant built-in templates.
Note that:
@ -25,9 +25,9 @@ toc: true
* These settings work with the [internal templates](/templates/internal/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect.
* We will continue this work and improve this further in future Hugo versions.
## All Privacy Settings
## All privacy settings
Below are all privacy settings and their default value. These settings need to be put in your site config (e.g. `hugo.toml`).
Below are all privacy settings and their default value. These settings need to be put in your site configuration (e.g. `hugo.toml`).
{{< code-toggle file="hugo" >}}
[privacy]
@ -54,11 +54,11 @@ disable = false
privacyEnhanced = false
{{< /code-toggle >}}
## Disable All Services
## Disable all services
An example Privacy Config that disables all the relevant services in Hugo. With this configuration, the other settings will not matter.
An example privacy configuration that disables all the relevant services in Hugo. With this configuration, the other settings will not matter.
{{< code-toggle file="hugo" >}}
{{< code-toggle file="hugo" >}}
[privacy]
[privacy.disqus]
disable = true
@ -74,7 +74,7 @@ disable = true
disable = true
{{< /code-toggle >}}
## The Privacy Settings Explained
## The privacy settings explained
### GoogleAnalytics

7
docs/content/en/about/license.md
View file

@ -1,14 +1,13 @@
---
title: Apache License
linktitle: License
title: License
description: Hugo v0.15 and later are released under the Apache 2.0 license.
categories: ["about hugo"]
keywords: ["License","apache"]
menu:
docs:
parent: about
weight: 60
weight: 60
weight: 70
weight: 70
aliases: [/meta/license]
toc: true
---

16
docs/content/en/about/security-model/index.md
View file

@ -1,18 +1,18 @@
---
title: Hugo's Security Model
title: Hugo's security model
description: A summary of Hugo's security model.
layout: single
keywords: ["Security", "Privacy"]
menu:
docs:
parent: about
weight: 4
weight: 5
weight: 50
weight: 50
aliases: [/security/]
toc: true
---
## Runtime Security
## Runtime security
Hugo produces static output, so once built, the runtime is the browser (assuming the output is HTML) and any server (API) that you integrate with.
@ -25,7 +25,7 @@ But when developing and building your site, the runtime is the `hugo` executable
* User-defined components have read-only access to the filesystem.
* We shell out to some external binaries to support [Asciidoctor](/content-management/formats/#list-of-content-formats) and similar, but those binaries and their flags are predefined and disabled by default (see [Security Policy](#security-policy)). General functions to run arbitrary external OS commands have been [discussed](https://github.com/gohugoio/hugo/issues/796), but not implemented because of security concerns.
## Security Policy
## Security policy
Hugo has a built-in security policy that restricts access to [os/exec](https://pkg.go.dev/os/exec), remote communication and similar.
@ -33,19 +33,19 @@ The default configuration is listed below. Any build using features not in the a
{{< code-toggle config="security" />}}
Note that these and other config settings in Hugo can be overridden by the OS environment. If you want to block all remote HTTP fetching of data:
Note that these and other configuration settings in Hugo can be overridden by the OS environment. If you want to block all remote HTTP fetching of data:
```txt
HUGO_SECURITY_HTTP_URLS=none hugo
```
## Dependency Security
## Dependency security
Hugo is built as a static binary using [Go Modules](https://github.com/golang/go/wiki/Modules) to manage its dependencies. Go Modules have several safeguards, one of them being the `go.sum` file. This is a database of the expected cryptographic checksums of all of your dependencies, including transitive dependencies.
[Hugo Modules](/hugo-modules/) is a feature built on top of the functionality of Go Modules. Like Go Modules, a Hugo project using Hugo Modules will have a `go.sum` file. We recommend that you commit this file to your version control system. The Hugo build will fail if there is a checksum mismatch, which would be an indication of [dependency tampering](https://julienrenaux.fr/2019/12/20/github-actions-security-risk/).
## Web Application Security
## Web application security
These are the security threats as defined by [OWASP](https://en.wikipedia.org/wiki/OWASP).

10
docs/content/en/about/what-is-hugo.md
View file

@ -5,8 +5,8 @@ layout: single
menu:
docs:
parent: about
weight: 10
weight: 10
weight: 20
weight: 20
aliases: [/overview/introduction/,/about/why-i-built-hugo/]
toc: true
---
@ -17,15 +17,15 @@ Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted
We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made.
## How Fast is Hugo?
## How fast is Hugo?
{{< youtube "CdiDYZ51a2o" >}}
## What Does Hugo Do?
## What does Hugo do?
In technical terms, Hugo takes a source directory of files and templates and uses these as input to create a complete website.
## Who Should Use Hugo?
## Who should use Hugo?
Hugo is for people that prefer writing in a text editor over a browser.

1
docs/content/en/commands/hugo_completion_bash.md
View file

@ -62,4 +62,3 @@ hugo completion bash
### SEE ALSO
* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell

4
docs/content/en/commands/hugo_convert.md
View file

@ -13,10 +13,6 @@ Convert your content (e.g. front matter) to different formats.
See convert's subcommands toJSON, toTOML and toYAML for more information.
```
hugo convert [command] [flags]
```
### Options
```

4
docs/content/en/commands/hugo_gen.md
View file

@ -7,10 +7,6 @@ url: /commands/hugo_gen/
A collection of several useful generators.
```
hugo gen [command] [flags]
```
### Options
```

4
docs/content/en/commands/hugo_import.md
View file

@ -13,10 +13,6 @@ Import your site from other web site generators like Jekyll.
Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`.
```
hugo import [command] [flags]
```
### Options
```

4
docs/content/en/commands/hugo_list.md
View file

@ -13,10 +13,6 @@ Listing out various types of content.
List requires a subcommand, e.g. hugo list drafts
```
hugo list [command] [flags]
```
### Options
```

6
docs/content/en/commands/hugo_new.md
View file

@ -18,10 +18,6 @@ If archetypes are provided in your theme or site, they will be used.
Ensure you run this within the root directory of your site.
```
hugo new [command] [flags]
```
### Options
```
@ -50,5 +46,5 @@ hugo new [command] [flags]
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo new content](/commands/hugo_new_content/) - Create new content for your site
* [hugo new site](/commands/hugo_new_site/) - Create a new site (skeleton)
* [hugo new theme](/commands/hugo_new_theme/) - Create a new site (skeleton)
* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme (skeleton)

14
docs/content/en/commands/hugo_new_content.md
View file

@ -10,13 +10,13 @@ Create new content for your site
### Synopsis
Create a new content file and automatically set the date and title.
It will guess which kind of file to create based on the path provided.
You can also specify the kind with `-k KIND`.
If archetypes are provided in your theme or site, they will be used.
Ensure you run this within the root directory of your site.
It will guess which kind of file to create based on the path provided.
You can also specify the kind with `-k KIND`.
If archetypes are provided in your theme or site, they will be used.
Ensure you run this within the root directory of your site.
```
hugo new content [path] [flags]

5
docs/content/en/commands/hugo_new_site.md
View file

@ -20,8 +20,9 @@ hugo new site [path] [flags]
### Options
```
-f, --force init inside non-empty directory
-h, --help help for site
-f, --force init inside non-empty directory
--format string preferred file format (toml, yaml or json) (default "toml")
-h, --help help for site
```
### Options inherited from parent commands

11
docs/content/en/commands/hugo_new_theme.md
View file

@ -5,16 +5,17 @@ url: /commands/hugo_new_theme/
---
## hugo new theme
Create a new site (skeleton)
Create a new theme (skeleton)
### Synopsis
Create a new site in the provided directory.
The new site will have the correct structure, but no content or theme yet.
Use `hugo new [contentPath]` to create new content.
Create a new theme (skeleton) called [name] in ./themes.
New theme is a skeleton. Please add content to the touched files. Add your
name to the copyright line in the license and adjust the theme.toml file
according to your needs.
```
hugo new theme [path] [flags]
hugo new theme [name] [flags]
```
### Options

5
docs/content/en/content-management/_index.md
View file

@ -1,9 +1,10 @@
---
title: Content Management
linkTitle: Content Management Overview
title: Content management
linkTitle: Overview
description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more.
menu:
docs:
identifier: content-management-overview
parent: content-management
weight: 10
keywords: [source, organization]

6
docs/content/en/content-management/archetypes.md
View file

@ -13,7 +13,7 @@ weight: 140
aliases: [/content/archetypes/]
---
## What are Archetypes?
## What are archetypes?
**Archetypes** are content template files in the [archetypes directory] of your project that contain preconfigured [front matter] and possibly also a content disposition for your website's [content types]. These will be used when you run `hugo new`.
@ -33,7 +33,7 @@ The above will create a new content file in `content/posts/my-first-post.md` usi
The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example.
## Create a New Archetype Template
## Create a new archetype template
A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`. Create a new file in `archetypes/newsletter.md` and open it in a text editor.
@ -46,7 +46,7 @@ draft: true
**Insert Lead paragraph here.**
## New Cool Posts
## New cool posts
{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }}
* {{ .Title }}

49
docs/content/en/content-management/build-options.md
View file

@ -1,9 +1,8 @@
---
title: Build Options
linkTitle: Build Options
title: Build options
description: Build options help define how Hugo must treat a given page when building the site.
keywords: [build,content,front matter, page resources]
categories: [content management]
categories: [fundamentals,content management]
menu:
docs:
parent: content-management
@ -13,7 +12,7 @@ weight: 70
aliases: [/content/build-options/]
---
They are stored in a reserved Front Matter object named `_build` with the following defaults:
They are stored in a reserved front matter object named `_build` with the following defaults:
{{< code-toggle >}}
_build:
@ -26,38 +25,30 @@ _build:
If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink.
We extended this property from a boolean to an enum in Hugo 0.76.0. Valid values are:
Valid values are:
never
: The page will not be included in any page collection.
always (default)
: The page will be rendered to disk and get a `RelPermalink` etc.
link
: The page will be not be rendered to disk, but will get a `RelPermalink`.
- `never`
: The page will not be included in any page collection.
- `always (default)`
: The page will be rendered to disk and get a `RelPermalink` etc.
- `link`
: The page will be not be rendered to disk, but will get a `RelPermalink`.
#### list
Note that we extended this property from a boolean to an enum in Hugo 0.68.0.
Valid values are:
never
: The page will not be included in any page collection.
always (default)
: The page will be included in all page collections, e.g. `site.RegularPages`, `$page.Pages`.
local
: The page will be included in any _local_ page collection, e.g. `$page.RegularPages`, `$page.Pages`. One use case for this would be to create fully navigable, but headless content sections.
If true, the page will be treated as part of the project's collections and, when appropriate, returned by Hugo's listing methods (`.Pages`, `.RegularPages` etc...).
- `never`
: The page will not be included in any page collection.
- `always (default)`
: The page will be included in all page collections, e.g. `site.RegularPages`, `.Pages`.
- `local`
: The page will be included in any _local_ page collection, e.g. `.RegularPages`, `.Pages`. One use case for this would be to create fully navigable, but headless content sections.
#### publishResources
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.
If set to `true` (default) 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`](/functions/getpage) methods.
@ -67,7 +58,7 @@ Any page, regardless of their build options, will always be available using the
#### 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.
Project needs a "Who We Are" content file for front matter and body to be used by the homepage but nowhere else.
{{< code-toggle file="content/who-we-are.md" fm=true copy=false >}}
title: Who we are

6
docs/content/en/content-management/comments.md
View file

@ -2,7 +2,7 @@
title: 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]
categories: [project organization]
menu:
docs:
parent: content-management
@ -34,9 +34,9 @@ For many websites, this is enough configuration. However, you also have the opti
* `disqus_title`
* `disqus_url`
### Render Hugo's Built-in Disqus Partial Template
### Render Hugo's built-in Disqus partial template
Disqus has its own [internal template](https://gohugo.io/templates/internal/#disqus) available, to render it add the following code where you want comments to appear:
Disqus has its own [internal template](/templates/internal/#disqus) available, to render it add the following code where you want comments to appear:
```go-html-template
{{ template "_internal/disqus.html" . }}

7
docs/content/en/content-management/cross-references.md
View file

@ -1,6 +1,5 @@
---
title: Links and Cross References
linkTitle: Links and Cross References
title: Links and cross references
description: Shortcodes for creating links to documents.
categories: [content management]
keywords: ["cross references","references", "anchors", "urls"]
@ -19,7 +18,7 @@ The `ref` and `relref` shortcodes display the absolute and relative permalinks t
The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
```
```text
.
└── content
├── about
@ -78,7 +77,7 @@ To link to another language version of a document, use this syntax:
{{</* relref path="document.md" lang="ja" */>}}
```
### Get another Output Format
### Get another output format
To link to another Output Format of a document, use this syntax:

14
docs/content/en/content-management/diagrams.md
View file

@ -12,7 +12,7 @@ weight: 50
---
{{< new-in "0.93.0" >}}
## GoAT Diagrams (Ascii)
## GoAT diagrams (Ascii)
Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block:
@ -42,14 +42,14 @@ Will be rendered as:
1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4
```
## Mermaid Diagrams
## Mermaid diagrams
Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create `layouts/_default/_markup/render-codeblock-mermaid.html`:
```go-html-template
<div class="mermaid">
<pre class="mermaid">
{{- .Inner | safeHTML }}
</div>
</pre>
{{ .Page.Store.Set "hasMermaid" true }}
```
@ -66,7 +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:
````
````text
```mermaid
sequenceDiagram
participant Alice
@ -82,7 +82,7 @@ sequenceDiagram
```
````
## Goat Ascii Diagram Examples
## Goat ASCII diagram examples
### Graphics
@ -166,7 +166,7 @@ Created from <https://arthursonzogni.com/Diagon/#Tree>
```
### Sequence Diagram
### Sequence diagram
<https://arthursonzogni.com/Diagon/#Sequence>

15
docs/content/en/content-management/formats.md
View file

@ -1,6 +1,5 @@
---
title: Content Formats
linkTitle: Content Formats
title: Content formats
description: Both HTML and Markdown are supported content formats.
categories: [content management]
keywords: [markdown,asciidoc,pandoc,content format]
@ -34,7 +33,7 @@ The current list of content formats in Hugo:
The `markup identifier` is fetched from either the `markup` variable in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/).
## External Helpers
## External helpers
Some of the formats in the table above need external helpers installed on your PC. For example, for AsciiDoc files,
Hugo will try to call the `asciidoctor` command. This means that you will have to install the associated
@ -50,13 +49,7 @@ Hugo passes reasonable default arguments to these external helpers by default:
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.
{{% /note %}}
### External Helper AsciiDoc
[AsciiDoc](https://github.com/asciidoc/asciidoc) implementation EOLs in Jan 2020 and is no longer supported.
AsciiDoc development is being continued under [Asciidoctor](https://github.com/asciidoctor). The format AsciiDoc
remains of course. Please continue with the implementation Asciidoctor.
### External Helper Asciidoctor
### External helper Asciidoctor
The Asciidoctor community offers a wide set of tools for the AsciiDoc format that can be installed additionally to Hugo.
[See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/). Make sure that also all
@ -113,7 +106,7 @@ parameters. Run Hugo with `-v`. You will get an output like
INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...
```
## Learn Markdown
## Learn markdown
Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running:

40
docs/content/en/content-management/front-matter.md
View file

@ -1,5 +1,5 @@
---
title: Front Matter
title: Front matter
description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
categories: [content management]
keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
@ -16,7 +16,7 @@ aliases: [/content/front-matter/]
{{< youtube Yh2xKRJGff4 >}}
## Front Matter Formats
## Front matter formats
Hugo supports four formats for front matter, each with their own identifying tokens.
@ -47,7 +47,7 @@ categories = [
slug = "spf13-vim-3-0-release-and-new-website"
{{< /code-toggle >}}
## Front Matter Variables
## Front matter variables
### Predefined
@ -93,7 +93,7 @@ lastmod
: 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.
@ -135,10 +135,10 @@ weight
: 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 %}}
If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site configuration 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.
If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site configuration file](/content-management/urls/#permalinks), Hugo will use the file name 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 %}}
### User-Defined
### User-defined
You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates.
@ -149,11 +149,11 @@ include_toc: true
show_comments: false
{{</ code-toggle >}}
## Front Matter Cascade
## Front matter cascade
Any node or section can pass down to descendants a set of Front Matter values as long as defined underneath the reserved `cascade` Front Matter key.
Any node or section can pass down to descendants a set of front matter values as long as defined underneath the reserved `cascade` front matter key.
### Target Specific Pages
### Target specific pages
The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
@ -202,15 +202,15 @@ With the above example the Blog section page and its descendants will return `im
- Said descendant has its own `banner` value set
- Or a closer ancestor node has its own `cascade.banner` value set.
## Order Content Through Front Matter
## Order content through front matter
You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views.
## Override Global Markdown Configuration
## Override global markdown configuration
It's possible to set some options for Markdown rendering in a content's front matter as an override to the [Rendering options set in your project configuration][config].
It's possible to set some options for Markdown rendering in a content's front matter as an override to the [rendering options set in your project configuration][config].
## Front Matter Format Specs
## Front matter format specs
- [TOML Spec][toml]
- [YAML Spec][yaml]
@ -220,15 +220,15 @@ It's possible to set some options for Markdown rendering in a content's front ma
[aliases]: /content-management/urls/#aliases
[archetype]: /content-management/archetypes/
[bylinktitle]: /templates/lists/#by-link-title
[config]: /getting-started/configuration/ "Hugo documentation for site configuration"
[config]: /getting-started/configuration/
[content type]: /content-management/types/
[contentorg]: /content-management/organization/
[headless-bundle]: /content-management/page-bundles/#headless-bundle
[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
[lists]: /templates/lists/#order-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter."
[lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating."
[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates"
[outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating"
[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
[lists]: /templates/lists/#order-content
[lookup]: /templates/lookup-order/
[ordering]: /templates/lists/
[outputs]: /templates/output-formats/
[page-resources]: /content-management/page-resources/
[pagevars]: /variables/page/
[section]: /content-management/sections/
@ -236,4 +236,4 @@ It's possible to set some options for Markdown rendering in a content's front ma
[toml]: https://toml.io/
[urls]: /content-management/urls/
[variables]: /variables/
[yaml]: https://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language"
[yaml]: https://yaml.org/spec/

56
docs/content/en/content-management/image-processing/index.md
View file

@ -1,7 +1,7 @@
---
title: Image Processing
title: Image processing
description: Resize, crop, rotate, filter, and convert images.
categories: [content management]
categories: [fundamentals,content management]
keywords: [resources, images]
menu:
docs:
@ -10,11 +10,11 @@ menu:
toc: true
weight: 90
---
## Image Resources
## Image resources
To process an image, you must access the image as either a page resource or a global resource.
### Page Resources
### Page resources
A page resource is a file within a [page bundle]. A page bundle is a directory with an `index.md` or `_index.md` file at its root.
@ -26,7 +26,7 @@ content/
└── sunset.jpg <-- page resource
```
### Global Resources
### Global resources
A global resource is a file:
@ -52,7 +52,7 @@ To access a remote image as a global resource:
{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}
```
## Image Rendering
## Image rendering
Once you have accessed an image as either a page resource or a global resource, render it in your templates using the `Permalink`, `RelPermalink`, `Width`, and `Height` properties.
@ -80,12 +80,12 @@ Example 3: A more concise way to skip image rendering if the resource is not fou
{{ end }}
```
## Image Processing Methods
## Image processing methods
The `image` resource implements the [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods.
{{% note %}}
Metadata (Exif, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`] method with the _original_ image to extract Exif metadata from JPEG or TIFF images.
Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`] method with the _original_ image to extract EXIF metadata from JPEG or TIFF images.
{{% /note %}}
### Resize
@ -164,11 +164,11 @@ Sometimes it can be useful to create the filter chain once and then reuse it.
This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled down image.
### Exif
### EXIF
Provides an [Exif] object containing image metadata.
Provides an [EXIF] object containing image metadata.
You may access Exif data in JPEG and TIFF images. To prevent errors when processing images without Exif data, wrap the access in a [`with`] statement.
You may access EXIF data in JPEG and TIFF images. To prevent errors when processing images without EXIF data, wrap the access in a [`with`] statement.
```go-html-template
{{ with $image.Exif }}
@ -181,7 +181,7 @@ You may access Exif data in JPEG and TIFF images. To prevent errors when process
{{ end }}
```
You may also access Exif fields individually, using the [`lang.FormatNumber`] function to format the fields as needed.
You may also access EXIF fields individually, using the [`lang.FormatNumber`] function to format the fields as needed.
```go-html-template
{{ with $image.Exif }}
@ -198,7 +198,7 @@ You may also access Exif fields individually, using the [`lang.FormatNumber`] fu
{{ end }}
```
#### Exif Variables
#### EXIF variables
.Date
: Image creation date/time. Format with the [time.Format] function.
@ -210,9 +210,9 @@ You may also access Exif fields individually, using the [`lang.FormatNumber`] fu
: GPS longitude in degrees.
.Tags
: A collection of the available Exif tags for this image. You may include or exclude specific tags from this collection in the [site configuration](#exif-data).
: A collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration](#exif-data).
## Image Processing Options
## Image processing options
The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-separated, case-insensitive list of options. The order of the options within the list is irrelevant.
@ -265,7 +265,7 @@ For example, if you have a 400x200 image with a bird in the upper left quadrant,
If you apply [rotation](#rotation) when using the [`Crop`] or [`Fill`] method, specify the anchor relative to the rotated image.
### Target Format
### Target format
By default, Hugo encodes the image in the source format. You may convert the image to another format by specifying `bmp`, `gif`, `jpeg`, `jpg`, `png`, `tif`, `tiff`, or `webp`.
@ -313,7 +313,7 @@ The default value is `photo`. You may override the default value in the [site co
{{ $image.Resize "600x webp picture" }}
```
### Background Color
### Background color
When converting an image from a format that supports transparency (e.g., PNG) to a format that does _not_ support transparency (e.g., JPEG), you may specify the background color of the resulting image.
@ -325,7 +325,7 @@ The default value is `#ffffff` (white). You may override the default value in th
{{ $image.Resize "600x jpg #b31280" }}
```
### Resampling Filter
### Resampling filter
You may specify the resampling filter used when resizing an image. Commonly used resampling filters include:
@ -346,7 +346,7 @@ The default value is `Box`. You may override the default value in the [site conf
See [github.com/disintegration/imaging] for the complete list of resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.
## Image Processing Examples
## Image processing examples
_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_
@ -378,9 +378,9 @@ Call the shortcode from your Markdown like this:
Note the self-closing shortcode syntax above. You may call the `imgproc` shortcode with or without **inner content**.
{{% /note %}}
## Imaging Configuration
## Imaging configuration
### Processing Options
### Processing options
Define an `imaging` section in your site configuration to set the default [image processing options](#image-processing-options).
@ -408,9 +408,9 @@ quality
resampleFilter
: See image processing options: [resampling filter](#resampling-filter).
### Exif Data
### EXIF data
Define an `imaging.exif` section in your site configuration to control the availability of Exif data.
Define an `imaging.exif` section in your site configuration to control the availability of EXIF data.
{{< code-toggle file="hugo" copy=true >}}
[imaging.exif]
@ -427,16 +427,16 @@ disableLatLong
: Hugo extracts the GPS latitude and longitude into `.Lat` and `.Long`. Set this to `true` to disable. Default is `false`.
excludeFields
: Regular expression matching the Exif tags to exclude from the `.Tags` collection. Default is&nbsp;`""`.
: Regular expression matching the EXIF tags to exclude from the `.Tags` collection. Default is&nbsp;`""`.
includeFields
: Regular expression matching the Exif tags to include in the `.Tags` collection. Default is&nbsp;`""`. To include all available tags, set this value to&nbsp;`".*"`.
: Regular expression matching the EXIF tags to include in the `.Tags` collection. Default is&nbsp;`""`. To include all available tags, set this value to&nbsp;`".*"`.
{{% note %}}
To improve performance and decrease cache size, if you set neither `excludeFields` nor `includeFields`, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
{{% /note %}}
## Smart Cropping of Images
## Smart cropping of images
By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or`Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice.
@ -446,7 +446,7 @@ Examples using the sunset image from above:
{{< imgproc sunset Crop "200x200 smart" />}}
## Image Processing Performance Consideration
## Image processing performance consideration
Hugo caches processed images in the `resources` directory. If you include this directory in source control, Hugo will not have to regenerate the images in a CI/CD workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds.
@ -458,7 +458,7 @@ hugo --gc
[time.Format]: /functions/dateformat
[`anchor`]: /content-management/image-processing#anchor
[mounted]: /hugo-modules/configuration#module-config-mounts
[mounted]: /hugo-modules/configuration#module-configuration-mounts
[page bundle]: /content-management/page-bundles
[`lang.FormatNumber`]: /functions/lang
[filters]: /functions/images

166
docs/content/en/content-management/multilingual.md
View file

@ -1,5 +1,5 @@
---
title: Multilingual Mode
title: Multilingual mode
linkTitle: Multilingual
description: Hugo supports the creation of websites with multiple languages side by side.
categories: [content management]
@ -17,57 +17,79 @@ You should define the available languages in a `languages` section in your site
Also See [Hugo Multilingual Part 1: Content translation].
## Configure Languages
## Configure languages
The following is an example of a site configuration for a multilingual Hugo project:
This is an example of a site configuration for a multilingual project. Any key not defined in a `languages` object will fall back to the global value in the root of your site configuration.
{{< code-toggle file="hugo" >}}
defaultContentLanguage = "en"
copyright = "Everything is mine"
defaultContentLanguage = 'de'
defaultContentLanguageInSubdir = true
[params]
[params.navigation]
help = "Help"
[languages]
[languages.en]
title = "My blog"
[languages.de]
contentDir = 'content/de'
disabled = false
languageCode = 'de-DE'
languageDirection = 'ltr'
languageName = 'Deutsch'
title = 'Projekt Dokumentation'
weight = 1
[languages.de.params]
subtitle = 'Referenz, Tutorials und Erklärungen'
[languages.en]
contentDir = 'content/en'
disabled = false
languageCode = 'en-US'
languageDirection = 'ltr'
languageName = 'English'
title = 'Project Documentation'
weight = 2
[languages.en.params]
linkedin = "https://linkedin.com/whoever"
[languages.fr]
title = "Mon blogue"
weight = 2
[languages.fr.params]
linkedin = "https://linkedin.com/fr/whoever"
[languages.fr.params.navigation]
help = "Aide"
[languages.ar]
title = "مدونتي"
weight = 2
languagedirection = "rtl"
[languages.pt-pt]
title = "O meu blog"
weight = 3
subtitle = 'Reference, Tutorials, and Explanations'
{{< /code-toggle >}}
Anything not defined in a `languages` block will fall back to the global value for that key (e.g., `copyright` for the English `en` language). This also works for `params`, as demonstrated with `help` above: You will get the value `Aide` in French and `Help` in all the languages without this parameter set.
`defaultContentLanguage`
: (`string`) The project's default language tag as defined by [RFC 5646]. Must be lower case, and must match one of the defined language keys. Default is `en`. Examples:
With the configuration above, all content, sitemap, RSS feeds, pagination,
and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French.
- `en`
- `en-gb`
- `pt-br`
When working with front matter `Params` in [single page templates], omit the `params` in the key for the translation.
`defaultContentLanguageInSubdir`
: (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`.
`defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`.
`contentDir`
: (`string`) The content directory for this language. Omit if [translating by file name].
If the default language needs to be rendered below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`.
`disabled`
: (`bool`) If `true`, Hugo will not render content for this language. Default is `false`.
Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc.
`languageCode`
: (`string`) The language tag as defined by [RFC 5646]. This value may include upper and lower case characters, hyphens or underscores, and does not affect localization or URLs. Hugo uses this value to populate the `language` element in the [built-in RSS template], and the `lang` attribute of the `html` element in the [built-in alias template]. Examples:
**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)
- `en`
- `en-GB`
- `pt-BR`
`languageDirection`
: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`] HTML attribute.
`languageName`
: (`string`) The language name, typically used when rendering a language switcher.
`title`
: (`string`) The language title. When set, this overrides the site title for this language.
`weight`
: (`int`) The language weight. When set to a non-zero value, this is the primary sort criteria for this language.
[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
[built-in RSS template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml
[built-in alias template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
[translating by file name]: #translation-by-file-name
### Changes in Hugo 0.112.0
@ -76,7 +98,7 @@ Only the obvious non-global options can be overridden per language. Examples of
In Hugo `v0.112.0` we consolidated all configuration options, and improved how the languages and their parameters are merged with the main configuration. But while testing this on Hugo sites out there, we received some error reports and reverted some of the changes in favor of deprecation warnings:
1. `site.Language.Params` is deprecated. Use `site.Params` directly.
1. Adding custom params to the top level language config is deprecated, add all of these below `[params]`, see `color` in the example below.
1. Adding custom parameters to the top level language configuration is deprecated, add all of these below `[params]`, see `color` in the example below.
```toml
title = "My blog"
@ -92,35 +114,36 @@ color = "blue"
In the example above, all settings except `color` below `params` map to predefined configuration options in Hugo for the site and its language, and should be accessed via the documented accessors:
```
```go-html-template
{{ site.Title }}
{{ site.LanguageCode }}
{{ site.Params.color }}
```
### Disable a Language
### Disable a language
You can disable one or more languages. This can be useful when working on a new translation.
To disable a language within a `languages` object in your site configuration:
{{< code-toggle file="hugo" >}}
disableLanguages = ["fr", "ja"]
{{< code-toggle file="hugo" copy=false >}}
[languages.es]
disabled = true
{{< /code-toggle >}}
To disable one or more languages in the root of your site configuration:
{{< code-toggle file="hugo" copy=false >}}
disableLanguages = ["es", "fr"]
{{< /code-toggle >}}
To disable one or more languages using an environment variable:
```bash
HUGO_DISABLELANGUAGES="es fr" hugo
```
Note that you cannot disable the default content language.
We kept this as a standalone setting to make it easier to set via [OS environment]:
```bash
HUGO_DISABLELANGUAGES="fr ja" hugo
```
If you have already a list of disabled languages in `hugo.toml`, you can enable them in development like this:
```bash
HUGO_DISABLELANGUAGES=" " hugo server
```
### Configure Multilingual Multihost
### Configure multilingual multihost
From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details.
@ -167,12 +190,11 @@ Press Ctrl+C to stop
Live reload and `--navigateToChanged` between the servers work as expected.
## Translate Your Content
## Translate your content
There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations.
### Translation by filename
### Translation by file name
Considering the following example:
@ -182,9 +204,9 @@ Considering the following example:
The first file is assigned the English language and is linked to the second.
The second file is assigned the French language and is linked to the first.
Their language is __assigned__ according to the language code added as a __suffix to the filename__.
Their language is __assigned__ according to the language code added as a __suffix to the file name__.
By having the same **path and base filename**, the content pieces are __linked__ together as translated pages.
By having the same **path and base file name**, the content pieces are __linked__ together as translated pages.
{{% note %}}
If a file has no language code, it will be assigned the default language.
@ -192,7 +214,7 @@ If a file has no language code, it will be assigned the default language.
### Translation by content directory
This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` param.
This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` parameter.
{{< code-toggle file="hugo" >}}
languages:
@ -234,11 +256,11 @@ Considering the following example:
translationKey: "about"
{{< /code-toggle >}}
By setting the `translationKey` front matter param to `about` in all three pages, they will be __linked__ as translated pages.
By setting the `translationKey` front matter parameter to `about` in all three pages, they will be __linked__ as translated pages.
### Localizing permalinks
Because paths and filenames are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory).
Because paths and file names are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory).
To localize URLs:
@ -257,7 +279,7 @@ slug: "a-propos"
At render, Hugo will build both `/about/` and `/fr/a-propos/` without affecting the translation link.
### Page Bundles
### Page bundles
To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (Markdown files, HTML files etc...).
@ -269,10 +291,10 @@ If, across the linked bundles, two or more files share the same basename, only o
* First file found across bundles by order of language `Weight`.
{{% note %}}
Page Bundle resources follow the same language assignment logic as content files, both by filename (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`).
Page Bundle resources follow the same language assignment logic as content files, both by file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`).
{{%/ note %}}
## Reference the Translated Content
## Reference translated content
To create a list of links to translated content, use a template similar to the following:
@ -293,7 +315,7 @@ The above can be put in a `partial` (i.e., inside `layouts/partials/`) and inclu
The above also uses the [`i18n` function][i18func] described in the next section.
### List All Available Languages
### List all available languages
`.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator:
@ -305,7 +327,7 @@ The above also uses the [`i18n` function][i18func] described in the next section
</ul>
{{< /code >}}
## Translation of Strings
## Translation of strings
Hugo uses [go-i18n] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows.
@ -585,7 +607,7 @@ weight = 20
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
## Missing translations
If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
@ -604,7 +626,7 @@ hugo --printI18nWarnings | grep i18n
i18n|MISSING_TRANSLATION|en|wordCount
```
## Multilingual Themes support
## Multilingual themes support
To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria:

16
docs/content/en/content-management/organization/index.md
View file

@ -1,8 +1,8 @@
---
title: Content Organization
title: Content organization
linkTitle: Organization
description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site.
categories: [content management,fundamentals]
categories: [fundamentals,content management]
keywords: [sections,content,organization,bundle,resources]
menu:
docs:
@ -13,7 +13,7 @@ weight: 20
aliases: [/content/sections/]
---
## Page Bundles
## Page bundles
Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`.
@ -29,7 +29,7 @@ The bundle documentation is a **work in progress**. We will publish more compreh
{{% /note %}}
## Organization of Content Source
## Organization of content source
In Hugo, your content should be organized in a manner that reflects the rendered website.
@ -52,12 +52,12 @@ Without any additional configuration, the following will automatically work:
└── second.md // <- https://example.com/quote/second/
```
## Path Breakdown in Hugo
## Path breakdown in Hugo
The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.com"` in your [site's configuration file][config].
### Index Pages: `_index.md`
### Index pages: `_index.md`
`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates], [taxonomy templates], [taxonomy terms templates], and your [homepage template].
@ -94,7 +94,7 @@ https://example.com/posts/index.html
The [sections] can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. `_index.md`).
### Single Pages in Sections
### Single pages in sections
Single content files in each of your sections will be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`:
@ -121,7 +121,7 @@ https://example.com/posts/my-first-hugo-post/index.html
```
## Paths Explained
## Paths explained
The following concepts provide more insight into the relationship between your project's organization and the default Hugo behavior when building output for the website.

23
docs/content/en/content-management/page-bundles.md
View file

@ -1,5 +1,5 @@
---
title: Page Bundles
title: Page bundles
description: Content organization using Page Bundles
keywords: [page, bundle, leaf, branch]
categories: [content management]
@ -19,23 +19,22 @@ A Page Bundle can be one of:
- Branch Bundle (home page, section, taxonomy terms, taxonomy list)
| | Leaf Bundle | Branch Bundle |
|-------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|-------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Usage | Collection of content and attachments for single pages | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list) |
| Index filename | `index.md` [^fn:1] | `_index.md` [^fn:1] |
| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] |
| Allowed Resources | Page and non-page (like images, PDF, etc.) types | Only non-page (like images, PDF, etc.) types |
| Where can the Resources live? | At any directory level within the leaf bundle directory. | Only in the directory level **of** the branch bundle directory i.e. the directory containing the `_index.md` ([ref](https://discourse.gohugo.io/t/question-about-content-folder-structure/11822/4?u=kaushalmodi)). |
| Layout type | `single` | `list` |
| Layout type | [`single`](/templates/single-page-templates/) | [`list`](/templates/lists) |
| Nesting | Does not allow nesting of more bundles under it | Allows nesting of leaf or branch bundles under it |
| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` |
| Content from non-index page files... | Accessed only as page resources | Accessed only as regular pages |
| Content from non-index page files...| Accessed only as page resources | Accessed only as regular pages |
## Leaf Bundles {#leaf-bundles}
## Leaf bundles
A _Leaf Bundle_ is a directory at any hierarchy within the `content/`
directory, that contains an **`index.md`** file.
### Examples of Leaf Bundle organization {#examples-of-leaf-bundle-organization}
### Examples of leaf bundle organization {#examples-of-leaf-bundle-organization}
```text
content/
@ -92,7 +91,7 @@ as long as it is not inside another **leaf** bundle.
{{% /note %}}
### Headless Bundle {#headless-bundle}
### Headless bundle
A headless bundle is a bundle that is configured to not get published
anywhere:
@ -126,7 +125,7 @@ Explanation of the above example:
---
A leaf bundle can be made headless by adding below in the Front Matter
A leaf bundle can be made headless by adding below in the front matter
(in the `index.md`):
{{< code-toggle file="content/headless/index.md" fm=true copy=false >}}
@ -138,7 +137,7 @@ There are many use cases of such headless page bundles:
- Shared media galleries
- Reusable page content "snippets"
## Branch Bundles {#branch-bundles}
## Branch bundles
A _Branch Bundle_ is any directory at any hierarchy within the
`content/` directory, that contains at least an **`_index.md`** file.
@ -151,7 +150,7 @@ type as a content resource as long as it is a content type recognized by Hugo.
{{% /note %}}
### Examples of Branch Bundle organization {#examples-of-branch-bundle-organization}
### Examples of branch bundle organization
```text
content/

20
docs/content/en/content-management/page-resources.md
View file

@ -1,5 +1,5 @@
---
title: Page Resources
title: 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]
@ -42,7 +42,7 @@ ResourceType
: The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`.
Name
: Default value is the filename (relative to the owning page). Can be set in front matter.
: Default value is the file name (relative to the owning page). Can be set in front matter.
Title
: Default value is the same as `.Name`. Can be set in front matter.
@ -67,21 +67,21 @@ with the contents of the file. Use this to create inline resources.
{{ end }}
{{ with .Resources.GetMatch "img.png" }}
<img src="data:{{ .MediaType }};base64,{{ .Content | base64Encode }}">
<img src="data:{{ .MediaType.Type }};base64,{{ .Content | base64Encode }}">
{{ end }}
```
MediaType
: The MIME type of the resource, such as `image/jpeg`.
MediaType.Type
: The media type (formerly known as a MIME type) of the resource (e.g., `image/jpeg`).
MediaType.MainType
: The main type of the resource's MIME type. For example, a file of MIME type `application/pdf` has for MainType `application`.
: The main type of the resource's media type (e.g., `image`).
MediaType.SubType
: The subtype of the resource's MIME type. For example, a file of MIME type `application/pdf` has for SubType `pdf`. Note that this is not the same as the file extension. For example, Microsoft PowerPoint files (`.ppt`) have a subtype of `vnd.ms-powerpoint`.
: The subtype of the resource's type (e.g., `jpeg`). This may or may not correspond to the file suffix.
MediaType.Suffixes
: A slice of possible suffixes for the resource's MIME type.
: A slice of possible file suffixes for the resource's media type (e.g., `[jpg jpeg jpe jif jfif]`).
## Methods
@ -101,7 +101,7 @@ Match
GetMatch
: Same as `Match` but will return the first match.
### Pattern Matching
### Pattern matching
```go
// Using Match/GetMatch to find this images/sunset.jpg ?
@ -115,7 +115,7 @@ GetMatch
```
## Page Resources Metadata
## Page resources metadata
The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm).

20
docs/content/en/content-management/related.md
View file

@ -1,5 +1,5 @@
---
title: Related Content
title: Related content
description: List related content in "See Also" sections.
categories: [content management]
keywords: [content]
@ -12,9 +12,9 @@ weight: 110
aliases: [/content/related/,/related/]
---
Hugo uses a set of factors to identify a page's related content based on Front Matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content).
Hugo uses a set of factors to identify a page's related content based on front matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content).
## List Related Content
## List related content
To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template:
@ -60,7 +60,7 @@ A fictional example using all of the above options:
We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndicies`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
{{% /note %}}
## Index Content Headings in Related Content
## Index content headings in related content
{{< new-in "0.111.0" >}}
@ -105,7 +105,7 @@ weight = 80
{{ end }}
```
## Configure Related Content
## Configure related content
Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed.
@ -130,10 +130,10 @@ Note that if you have configured `tags` as a taxonomy, `tags` will also be added
Custom configuration should be set using the same syntax.
{{% note %}}
If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults.
If you add a `related` configuration section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults.
{{% /note %}}
### Top Level Config Options
### Top level configuration options
threshold
: A value between 0-100. Lower value will give more, but maybe not so relevant, matches.
@ -144,10 +144,10 @@ includeNewer
toLower
: Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index.
### Config Options per Index
### Configuration options per index
name
: The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
: The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
type
: {{< new-in "0.111.0" >}}. One of `basic`(default) or `fragments`.
@ -168,7 +168,7 @@ pattern
toLower
: See above.
## Performance Considerations
## Performance considerations
**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast.

13
docs/content/en/content-management/sections.md
View file

@ -1,6 +1,5 @@
---
title: Content Sections
linkTitle: Sections
title: Sections
description: Hugo generates a **section tree** that matches your content.
categories: [content management]
keywords: [lists,sections,content types,organization]
@ -31,7 +30,7 @@ A **section** cannot be defined or overridden by a front matter parameter -- it
is strictly derived from the content organization structure.
{{% /note %}}
## Nested Sections
## Nested sections
The sections can be nested as deeply as you need.
@ -55,7 +54,7 @@ currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`).
If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter.
{{% /note %}}
## Example: Breadcrumb Navigation
## Example: breadcrumb navigation
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:
@ -74,17 +73,17 @@ With the available [section variables and methods](#section-page-variables-and-m
</nav>
{{< /code >}}
## Section Page Variables and Methods
## Section page variables and methods
Also see [Page Variables](/variables/page/).
{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}}
## Content Section Lists
## Content section lists
Hugo will automatically create a page for each *root section* that lists all the content in that section. See the documentation on [section templates] for details on customizing the way these pages are rendered.
## Content *Section* vs Content *Type*
## Content *section* vs. content *type*
By default, everything created within a section will use the [content `type`][content type] that matches the *root section* name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content `type`. If you are using an [archetype] for your `posts` section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`.

38
docs/content/en/content-management/shortcodes.md
View file

@ -13,7 +13,7 @@ aliases: [/extras/shortcodes/]
testparam: "Hugo Rocks!"
---
## What a Shortcode is
## What a shortcode is
Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframe>`'s) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax.
@ -23,7 +23,7 @@ A shortcode is a simple snippet inside a content file that Hugo will render usin
In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.
## Use Shortcodes
## Use shortcodes
{{< youtube 2xkNJL4gJ9E >}}
@ -54,7 +54,7 @@ You can pass multiple lines as parameters to a shortcode by using raw string lit
and a new line with a "quoted string".` */>}}
```
### Shortcodes with Markdown
### Shortcodes with markdown
In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%` as the outer-most delimiter will now be fully rendered when sent to the content renderer. They can be part of the generated table of contents, footnotes, etc.
@ -64,7 +64,7 @@ If you want the old behavior, you can put the following line in the start of you
{{ $_hugo_config := `{ "version": 1 }` }}
```
### Shortcodes Without Markdown
### Shortcodes without markdown
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML:
@ -72,11 +72,11 @@ The `<` character indicates that the shortcode's inner content does *not* need f
{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
```
### Nested Shortcodes
### Nested shortcodes
You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
## Use Hugo's Built-in Shortcodes
## Use Hugo's built-in shortcodes
Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your Markdown content clean.
@ -125,13 +125,13 @@ attr
attrlink
: If the attribution text needs to be hyperlinked, URL of the destination.
#### Example `figure` Input
#### Example `figure` input
{{< code file="figure-input-example.md" >}}
{{</* figure src="elephant.jpg" title=">An elephant at sunset" */>}}
{{</* figure src="elephant.jpg" title="An elephant at sunset" */>}}
{{< /code >}}
#### Example `figure` Output
#### Example `figure` output
```html
<figure>
@ -254,17 +254,17 @@ Include this in your markdown:
### `param`
Gets a value from the current `Page's` params set in front matter, with a fallback to the site param value. It will log an `ERROR` if the param with the given key could not be found in either.
Gets a value from the current `Page's` parameters set in front matter, with a fallback to the site parameter value. It will log an `ERROR` if the parameter with the given key could not be found in either.
```bash
{{</* param testparam */>}}
```
Since `testparam` is a param defined in front matter of this page with the value `Hugo Rocks!`, the above will print:
Since `testparam` is a parameter defined in front matter of this page with the value `Hugo Rocks!`, the above will print:
{{< param testparam >}}
To access deeply nested params, use "dot syntax", e.g:
To access deeply nested parameters, use "dot syntax", e.g:
```bash
{{</* param "my.nested.param" */>}}
@ -282,14 +282,14 @@ Read a more extensive description of `ref` and `relref` in the [cross references
`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
#### Example `ref` and `relref` Input
#### Example `ref` and `relref` input
```go-html-template
[Neat]({{</* ref "blog/neat.md" */>}})
[Who]({{</* relref "about.md#who" */>}})
```
#### Example `ref` and `relref` Output
#### Example `ref` and `relref` output
Assuming that standard Hugo pretty URLs are turned on.
@ -350,7 +350,7 @@ The `youtube` shortcode embeds a responsive video player for [YouTube videos]. O
https://www.youtube.com/watch?v=w7Ft2ymGmfc
```
#### Example `youtube` Input
#### Example `youtube` input
Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
@ -371,7 +371,7 @@ For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titl
{{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}}
{{< /code >}}
#### Example `youtube` Output
#### Example `youtube` output
Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
@ -379,17 +379,17 @@ Using the preceding `youtube` example, the following HTML will be added to your
{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
{{< /code >}}
#### Example `youtube` Display
#### Example `youtube` display
Using the preceding `youtube` example (without `autoplay="true"`), 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. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
{{< youtube w7Ft2ymGmfc >}}
## Privacy Config
## Privacy configuration
To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR].
## Create Custom Shortcodes
## Create custom shortcodes
To learn more about creating custom shortcodes, see the [shortcode template documentation].

7
docs/content/en/content-management/static-files.md
View file

@ -1,6 +1,5 @@
---
title: Static Files
linkTitle: Static Files
title: Static files
description: Files that get served **statically** (as-is, no modification) on the site root.
categories: [content management]
keywords: [source, directories]
@ -18,7 +17,7 @@ all **static files** (e.g. stylesheets, JavaScript, images). The static files ar
Hugo can be configured to look into a different directory, or even
**multiple directories** for such static files by configuring the
`staticDir` parameter in the [site config]. All the files in all the
`staticDir` parameter in the [site configuration]. All the files in all the
static directories will form a union filesystem.
This union filesystem will be served from your site root. So a file
@ -65,5 +64,5 @@ Note 2
: The example above is a [multihost setup]. In a regular setup, all
the static directories will be available to all sites.
[site config]: /getting-started/configuration/#all-configuration-settings
[site configuration]: /getting-started/configuration/#all-configuration-settings
[multihost setup]: /content-management/multilingual/#configure-multilingual-multihost

14
docs/content/en/content-management/summaries.md
View file

@ -1,5 +1,5 @@
---
title: Content Summaries
title: Content summaries
linkTitle: Summaries
description: Hugo generates summaries of your content.
categories: [content management]
@ -15,7 +15,7 @@ aliases: [/content/summaries/,/content-management/content-summaries/]
With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views.
## Summary Splitting Options
## Summary splitting options
* Automatic Summary Split
* Manual Summary Split
@ -23,7 +23,7 @@ With the use of the `.Summary` [page variable][pagevariables], Hugo generates su
It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables].
### Automatic Summary Splitting
### Automatic summary splitting
By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/).
@ -35,7 +35,7 @@ You can customize how HTML tags in the summary are loaded using functions such a
The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](/getting-started/configuration/).
{{% /note %}}
### Manual Summary Splitting
### Manual summary splitting
Alternatively, you may add the <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider where you want to split the article.
@ -57,7 +57,7 @@ Cons
Be careful to enter <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> exactly; i.e., all lowercase and with no whitespace.
{{% /note %}}
### Front Matter Summary
### Front matter summary
You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter.
@ -67,7 +67,7 @@ Pros
Cons
: Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article.
## Summary Selection Order
## Summary selection order
Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`. It is as follows:
@ -79,7 +79,7 @@ Because there are multiple ways in which a summary can be specified it is useful
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>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider Hugo will use the manual summary split method.
{{% /note %}}
## Example: First 10 Articles with Summaries
## Example: first 10 articles with summaries
You can show content summaries with the following code. You could use the following snippet, for example, in a [section template].

26
docs/content/en/content-management/syntax-highlighting.md
View file

@ -1,5 +1,5 @@
---
title: Syntax Highlighting
title: Syntax highlighting
description: Hugo comes with really fast syntax highlighting from Chroma.
keywords: [highlighting,chroma,code blocks,syntax]
categories: [content management]
@ -14,13 +14,13 @@ aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
Hugo uses [Chroma](https://github.com/alecthomas/chroma) as its code highlighter; it is built in Go and is really, really fast.
## Configure Syntax Highlighter
## Configure syntax highlighter
See [Configure Highlight](/getting-started/configuration-markup#highlight).
## Generate Syntax Highlighter CSS
## Generate syntax highlighter CSS
If you run with `markup.highlight.noClasses=false` in your site config, you need a style sheet.
If you run with `markup.highlight.noClasses=false` in your site configuration, you need a style sheet.
You can generate one with Hugo:
@ -30,20 +30,20 @@ hugo gen chromastyles --style=monokai > syntax.css
Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles.
## Highlight Shortcode
## Highlight shortcode
Highlighting is carried out via the built-in [`highlight` shortcode](https://gohugo.io/content-management/shortcodes/#highlight). It takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode.
Highlighting is carried out via the built-in [`highlight` shortcode](/content-management/shortcodes/#highlight). It takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode.
Options:
* `linenos`: configure line numbers. Valid values are `true`, `false`, `table`, or `inline`. `false` will turn off line numbers if it's configured to be on in site config. `table` will give copy-and-paste friendly code blocks.
* `linenos`: configure line numbers. Valid values are `true`, `false`, `table`, or `inline`. `false` will turn off line numbers if it's configured to be on in site configuration. `table` will give copy-and-paste friendly code blocks.
* `hl_lines`: lists a set of line numbers or line number ranges to be highlighted.
* `linenostart=199`: starts the line number count from 199.
* `anchorlinenos`: Configure anchors on line numbers. Valid values are `true` or `false`;
* `lineanchors`: Configure a prefix for the anchors on line numbers. Will be suffixed with `-`, so linking to the line number 1 with the option `lineanchors=prefix` adds the anchor `prefix-1` to the page.
* `hl_inline` Highlight inside a `<code>` (inline HTML element) tag. Valid values are `true` or `false`. The `code` tag will get a class with name `code-inline`. {{< new-in "0.101.0" >}}
### Example: Highlight Shortcode
### Example: highlight shortcode
```go-html-template
{{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}}
@ -76,9 +76,9 @@ func GetTitleFunc(style string) func(s string) string {
}
{{< / highlight >}}
## Highlight Hugo/GO Template Code
## Highlight Hugo/Go template code
For highlighting Hugo/GO template code on your page, add `/*` after the opening double curly braces and `*/` before closing curly braces.
For highlighting Hugo/Go template code on your page, add `/*` after the opening double curly braces and `*/` before closing curly braces.
``` go
{{</*/* myshortcode */*/>}}
@ -90,11 +90,11 @@ Gives this:
{{</* myshortcode */>}}
```
## Highlight Template Func
## Highlight template function
See [Highlight](/functions/highlight/).
## Highlighting in Code Fences
## Highlighting in code fences
Highlighting in code fences is enabled by default.
@ -132,7 +132,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.
## List of Chroma Highlighting Languages
## List of Chroma highlighting languages
The full list of Chroma lexers and their aliases (which is the identifier used in the `highlight` template func or when doing highlighting in code fences):

36
docs/content/en/content-management/taxonomies.md
View file

@ -12,7 +12,7 @@ weight: 150
aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes]
---
## What is a Taxonomy?
## What is a taxonomy?
Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications of logical relationships between content.
@ -28,7 +28,7 @@ Value
: a piece of content assigned to a term
## Example Taxonomy: Movie Website
## Example taxonomy: movie website
Let's assume you are making a website about movies. You may want to include the following taxonomies:
@ -41,7 +41,7 @@ Let's assume you are making a website about movies. You may want to include the
Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
### Movie Taxonomy Organization
### Movie taxonomy organization
To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:
@ -76,11 +76,11 @@ Moonrise Kingdom <- Value
...
```
## Hugo Taxonomy Defaults {#default-taxonomies}
## Default taxonomies
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:
Without adding a single line to your [site configuration] 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 file="hugo" copy=false >}}
[taxonomies]
@ -88,7 +88,7 @@ Without adding a single line to your [site config][config] file, Hugo will autom
category = "categories"
{{</ code-toggle >}}
If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site config][config] to the following:
If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site configuration] to the following:
{{< code-toggle file="hugo" copy=false >}}
disableKinds = ["taxonomy","term"]
@ -96,18 +96,18 @@ disableKinds = ["taxonomy","term"]
{{% page-kinds %}}
### Default Destinations
### Default destinations
When taxonomies are used---and [taxonomy templates] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
* A single page at `example.com/categories/` that lists all the [terms within the taxonomy]
* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter]
## Configure Taxonomies
## Configure taxonomies
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.
Custom taxonomies other than the [defaults](#default-taxonomies) must be defined in your [site configuration] 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"
### Example: adding a custom taxonomy named "series"
{{% note %}}
While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_.
@ -120,9 +120,9 @@ While adding custom taxonomies, you need to put in the default taxonomies too, _
series = "series"
{{</ code-toggle >}}
### Example: Removing default taxonomies
### Example: removing default taxonomies
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].
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 configuration].
{{< code-toggle file="hugo" copy=false >}}
[taxonomies]
@ -143,7 +143,7 @@ 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.
{{% /note %}}
## Add Taxonomies to Content
## Add taxonomies to content
Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type] or [content section].
@ -153,7 +153,7 @@ Assigning content to a taxonomy is done in the [front matter]. Simply create a v
If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
{{% /note %}}
### Example: Front Matter with Taxonomies
### Example: front matter with taxonomies
{{< code-toggle file="content/example.md" fm=true copy=false >}}
title = "Hugo: A fast and flexible static site generator"
@ -164,13 +164,13 @@ slug = "hugo"
project_url = "https://github.com/gohugoio/hugo"
{{</ code-toggle >}}
## Order Taxonomies
## Order taxonomies
A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy list templates] and is declared in a content file's [front matter]. The convention for declaring taxonomic weight is `taxonomyname_weight`.
The following show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page.
### Example: Taxonomic `weight`
### Example: taxonomic `weight`
{{< code-toggle copy=false >}}
title = "foo"
@ -186,7 +186,7 @@ By using taxonomic weight, the same piece of content can appear in different pos
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 %}}
## Add custom metadata to a Taxonomy or Term
## Add custom metadata to a taxonomy or term
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:
@ -203,4 +203,4 @@ wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-list-templates
[taxonomy templates]: /templates/taxonomy-templates/
[terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates "See how to order terms associated with a taxonomy"
[config]: /getting-started/configuration/
[configuration]: /getting-started/configuration/

8
docs/content/en/content-management/toc.md
View file

@ -1,5 +1,5 @@
---
title: Table of Contents
title: 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]
@ -44,7 +44,7 @@ Hugo will take this Markdown and create a table of contents from `## Introductio
The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with appropriate HTML headings. See [the available settings](/getting-started/configuration-markup/#table-of-contents) to configure what heading levels you want to include in TOC.
## Template Example: Basic TOC
## Template example: basic TOC
The following is an example of a very basic [single page template]:
@ -64,7 +64,7 @@ The following is an example of a very basic [single page template]:
{{ end }}
{{< /code >}}
## Template Example: TOC Partial
## Template example: TOC partial
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:
@ -92,7 +92,7 @@ In the header of your content file, specify the AsciiDoc TOC directives necessar
```asciidoc
// <!-- Your front matter up here -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] configuration key
:toclevels: 4
== Introduction

4
docs/content/en/content-management/types.md
View file

@ -1,5 +1,5 @@
---
title: Content Types
title: Content types
description: Hugo is built around content organized in sections.
categories: [content management]
keywords: [lists, sections, content types, types, organization]
@ -16,5 +16,5 @@ A **content type** is a way to organize your content. Hugo resolves the content
A content type is used to
- Determine how the content is rendered. See [Template Lookup Order](/templates/lookup-order/) and [Content Views](https://gohugo.io/templates/views) for more.
- Determine how the content is rendered. See [Template Lookup Order](/templates/lookup-order/) and [Content Views](/templates/views) for more.
- Determine which [archetype](/content-management/archetypes/) template to use for new content.

10
docs/content/en/content-management/urls.md
View file

@ -1,5 +1,5 @@
---
title: URL Management
title: URL management
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]
@ -93,7 +93,7 @@ In your site configuration, define a URL pattern for each top-level section. Eac
Front matter `url` values override the URL patterns defined in the `permalinks` section of your site configuration.
[page kind]: https://gohugo.io/templates/section-templates/#page-kinds
[page kind]: /templates/section-templates/#page-kinds
#### Monolingual examples {#permalinks-monolingual-examples}
@ -271,10 +271,10 @@ Use these tokens when defining the URL pattern. The `date` field in front matter
: the content's slug (or title if no slug is provided in the front matter)
`:slugorfilename`
: the content's slug (or filename if no slug is provided in the front matter)
: the content's slug (or file name if no slug is provided in the front matter)
`:filename`
: the content's filename (without extension)
: the content's file name (without extension)
For time-related values, you can also use the layout string components defined in Go's [time package]. For example:
@ -383,7 +383,7 @@ In a multilingual site, use a directory-relative alias, or include the language
aliases = ['/de/posts/previous-file-name']
{{< /code-toggle >}}
### How Aliases Work
### How aliases work
Using the first example above, Hugo generates the following site structure:

9
docs/content/en/contribute/_index.md
View file

@ -1,14 +1,15 @@
---
title: Contribute to the Hugo Project
linktitle: Contribute to Hugo
title: Contribute to the Hugo project
linkTitle: Overview
description: Contribute to Hugo development and documentation.
categories: [contribute]
keywords: []
menu:
docs:
identifier: contribute-overview
parent: contribute
weight: 01
weight: 01
weight: 10
weight: 10
aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/]
---

24
docs/content/en/contribute/development.md
View file

@ -1,14 +1,14 @@
---
title: Contribute to Hugo Development
linktitle: Development
title: Contribute to development
linkTitle: Development
description: Hugo relies heavily on contributions from the open source community.
categories: [contribute]
keywords: [dev,open source]
menu:
docs:
parent: contribute
weight: 10
weight: 10
weight: 20
weight: 20
toc: true
---
@ -33,7 +33,7 @@ The installation of Go should take only a few minutes. You have more than one op
If you are having trouble following the installation guides for Go, check out [Go Bootcamp, which contains setups for every platform][gobootcamp] or reach out to the Hugo community in the [Hugo Discussion Forums][forums].
### Install Go From Source
### Install Go from source
[Download the latest stable version of Go][godl] and follow the official [Go installation guide][goinstall].
@ -71,11 +71,11 @@ More experienced users can use the [Go Version Manager][gvm] (GVM). GVM allows y
GVM comes in especially handy if you follow the development of Hugo over a longer period of time. Future versions of Hugo will usually be compiled with the latest version of Go. Sooner or later, you will have to upgrade if you want to keep up.
## Create a GitHub Account
## Create a GitHub account
If you're going to contribute code, you'll need to have an account on GitHub. Go to [www.github.com/join](https://github.com/join) and set up a personal account.
## Install Git on Your System
## Install Git on your system
You will need to have Git installed on your computer to contribute to Hugo development. Teaching Git is outside the scope of the Hugo docs, but if you're looking for an excellent reference to learn the basics of Git, we recommend the [Git book][gitbook] if you are not sure where to begin. We will include short explanations of the Git commands in this document.
@ -87,11 +87,11 @@ Move back to the terminal and check if Git is already installed. Type in `git ve
Finally, check again with `git version` if Git was installed successfully.
### Git Graphical Front Ends
### Git graphical front ends
There are several [GUI clients](https://git-scm.com/downloads/guis) that help you to operate Git. Not all are available for all operating systems and maybe differ in their usage. Because of this we will document how to use the command-line, since the commands are the same everywhere.
### Install Hub on Your System (Optional)
### Install Hub on your system (optional)
Hub is a great tool for working with GitHub. The main site for it is [hub.github.com](https://hub.github.com/). Feel free to install this little Git wrapper.
@ -208,7 +208,7 @@ origin https://github.com/gohugoio/hugo (fetch)
origin https://github.com/gohugoio/hugo (push)
```
## The Hugo Git Contribution Workflow
## The Hugo Git contribution workflow
### Create a new branch
@ -229,7 +229,7 @@ git checkout -b <BRANCH-NAME>
You can check on which branch you are with `git branch`. You should see a list of all local branches. The current branch is indicated with a little asterisk.
### Contribute to Documentation
### Contribute to documentation
Perhaps you want to start contributing to the Hugo docs. If so, you can ignore most of the following steps and focus on the `/docs` directory within your newly cloned repository. You can change directories into the Hugo docs using `cd docs`.
@ -408,7 +408,7 @@ Thank you for reading through this contribution guide. Hopefully, we will see yo
Feel free to [open an issue][newissue] if you think you found a bug or you have a new idea to improve Hugo. We are happy to hear from you.
## Additional References for Learning Git and Go
## Additional references for learning Git and Go
* [Codecademy's Free "Learn Git" Course][codecademy] (Free)
* [Code School and GitHub's "Try Git" Tutorial][trygit] (Free)

8
docs/content/en/contribute/documentation.md
View file

@ -1,15 +1,15 @@
---
title: Contribute to the Hugo Docs
linktitle: Documentation
title: Contribute to documentation
linkTitle: Documentation
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
weight: 20
weight: 30
toc: true
weight: 20
weight: 30
aliases: [/contribute/docs/]
---

10
docs/content/en/contribute/themes.md
View file

@ -1,14 +1,14 @@
---
title: Add Your Hugo Theme to the Showcase
linktitle: Themes
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.
categories: [contribute]
keywords: [contribute,themes,design]
menu:
docs:
parent: contribute
weight: 30
weight: 30
weight: 40
weight: 40
aliases: [/contribute/theme/]
toc: true
---
@ -17,7 +17,7 @@ A collection of all themes created by the Hugo community, including screenshots
Another great site for Hugo themes is [jamstackthemes.dev/](https://jamstackthemes.dev/ssg/hugo/).
### Add Your Theme to the Repo
### Add your theme to the repository
In order to add your Hugo theme to [themes.gohugo.io] please [open a pull request in the theme repository](https://github.com/gohugoio/hugoThemesSiteBuilder). **Please make sure that you've read the theme submission guidelines in the [README](https://github.com/gohugoio/hugoThemesSiteBuilder/blob/main/README.md#hugo-themes) of the hugoThemesSiteBuilder repository.**

6
docs/content/en/documentation.md
View file

@ -1,11 +1,11 @@
---
title: Hugo Documentation
linktitle: Hugo
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.
menu:
main:
weight: 01
weight: 01
weight: 1
weight: 1
layout: documentation-home
---

8
docs/content/en/functions/GetPage.md
View file

@ -37,15 +37,15 @@ And since `Page` also provides a `.GetPage` method, the above is the same as:
{{ end }}
```
## .GetPage and Multilingual Sites
## .GetPage and multilingual sites
The previous examples have used the full content filename to look up the post. Depending on how you have organized your content (whether you have the language code in the file name or not, e.g. `my-post.en.md`), you may want to do the lookup without extension. This will get you the current language's version of the page:
The previous examples have used the full content file name to look up the post. Depending on how you have organized your content (whether you have the language code in the file name or not, e.g. `my-post.en.md`), you may want to do the lookup without extension. This will get you the current language's version of the page:
```go-html-template
{{ with .Site.GetPage "/blog/my-post" }}{{ .Title }}{{ end }}
```
## .GetPage Example
## .GetPage example
This code snippet---in the form of a [partial template][partials]---allows you to do the following:
@ -63,7 +63,7 @@ This code snippet---in the form of a [partial template][partials]---allows you t
</ul>
{{< /code >}}
## `.GetPage` on Page Bundles
## `.GetPage` on page bundles
If the page retrieved by `.GetPage` is a [Leaf Bundle][leaf_bundle], and you
need to get the nested _**page** resources_ in that, you will need to use the

7
docs/content/en/functions/_index.md
View file

@ -1,11 +1,14 @@
---
title: Functions Quick Reference
title: Functions
linkTitle: Overview
description: Comprehensive list of Hugo templating functions, including basic and advanced usage examples.
keywords: []
menu:
docs:
identifier: functions-overview
parent: functions
weight: 01
weight: 10
weight: 10
aliases: [/layout/functions/,/templates/functions]
---

2
docs/content/en/functions/after.md
View file

@ -20,7 +20,7 @@ The following shows `after` being used in conjunction with the [`slice` function
→ ["three", "four"]
```
## Example of `after` with `first`: 2nd&ndash;4th Most Recent Articles
## Example of `after` with `first`: 2nd&ndash;4th most recent articles
You can use `after` in combination with the [`first` function] and Hugo's [powerful sorting methods][lists]. Let's assume you have a list page at `example.com/articles`. You have 10 articles, but you want your templating for the [list/section page] to show only two rows:

4
docs/content/en/functions/anchorize.md
View file

@ -1,6 +1,6 @@
---
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.
description: Takes a string and sanitizes it the same way as the [`defaultMarkdownHandler`](/getting-started/configuration-markup#configure-markup) does for markdown headers.
categories: [functions]
menu:
docs:
@ -10,7 +10,7 @@ signature: ["anchorize INPUT"]
relatedfuncs: [humanize]
---
If [Goldmark](https://gohugo.io/getting-started/configuration-markup#goldmark) is set as `defaultMarkdownHandler`, the sanitizing logic adheres to the setting [`markup.goldmark.parser.autoHeadingIDType`](https://gohugo.io/getting-started/configuration-markup#goldmark).
If [Goldmark](/getting-started/configuration-markup#goldmark) is set as `defaultMarkdownHandler`, the sanitizing logic adheres to the setting [`markup.goldmark.parser.autoHeadingIDType`](/getting-started/configuration-markup#goldmark).
Since the `defaultMarkdownHandler` and this template function use the same sanitizing logic, you can use the latter to determine the ID of a header for linking with anchor tags.

2
docs/content/en/functions/apply.md
View file

@ -1,6 +1,6 @@
---
title: apply
description: Given a map, array, or slice, `apply` returns a new slice with a function applied over it.
description: Given an array or slice, `apply` returns a new slice with a function applied over it.
categories: [functions]
menu:
docs:

2
docs/content/en/functions/dict.md
View file

@ -18,7 +18,7 @@ Note that the `key` can be either a `string` or a `string slice`. The latter is
{{ $m := dict (slice "a" "b" "c") "value" }}
```
## Example: Using `dict` to pass multiple values to a `partial`
## Example: using `dict` to pass multiple values to a `partial`
The partial below creates an SVG and expects `fill`, `height` and `width` from the caller:

4
docs/content/en/functions/emojify.md
View file

@ -14,12 +14,12 @@ relatedfuncs: []
See the [Emoji cheat sheet][emojis] for available emoticons.
The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set `enableEmoji` to `true` in your site's [configuration][config]. Then you can write emoji shorthand directly into your content files; e.g. <code>I :</code><code>heart</code><code>: Hugo!</code>:
The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set `enableEmoji` to `true` in your site's [configuration]. Then you can write emoji shorthand directly into your content files; e.g. <code>I :</code><code>heart</code><code>: Hugo!</code>:
I :heart: Hugo!
[config]: /getting-started/configuration/
[configuration]: /getting-started/configuration/
[emojis]: https://www.webfx.com/tools/emoji-cheat-sheet/
[sc]: /templates/shortcode-templates/
[scsource]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes

2
docs/content/en/functions/errorf.md
View file

@ -40,6 +40,6 @@ This will produce:
```
ERROR 2021/06/07 17:47:38 You should consider fixing this.
If you feel that this should not be logged as an ERROR, you can ignore it by adding this to your site config:
If you feel that this should not be logged as an ERROR, you can ignore it by adding this to your site configuration:
ignoreErrors = ["my-custom-error"]
```

6
docs/content/en/functions/format.md
View file

@ -25,7 +25,7 @@ Assuming a key-value of `date: 2017-03-03` in a content file's front matter, you
For formatting *any* string representations of dates defined in your front matter, see the [`dateFormat` function][dateFormat], which will still leverage the Go layout string explained below but uses a slightly different syntax.
## Go's Layout String
## Go's layout string
Hugo templates [format your dates][time] via layout strings that point to a specific reference time:
@ -42,7 +42,7 @@ Here is a visual explanation [taken directly from the Go docs][gdex]:
=> 1 2 3 4 5 6 -7
```
### Hugo Date and Time Templating Reference
### Hugo date and time templating reference
The following examples show the layout string followed by the rendered output.
@ -84,7 +84,7 @@ date: 2017-03-03T14:15:59-06:00
More examples can be found in Go's [documentation for the time package][timeconst].
### Cardinal Numbers and Ordinal Abbreviations
### Cardinal s
Spelled-out cardinal numbers (e.g. "one", "two", and "three") are not currently supported.

1
docs/content/en/functions/hasPrefix.md
View file

@ -1,6 +1,5 @@
---
title: hasprefix
linktitle: hasPrefix
description: Tests whether a string begins with prefix.
date: 2017-02-01
publishdate: 2017-02-01

4
docs/content/en/functions/hasSuffix.md
View file

@ -1,6 +1,6 @@
---
title: hassuffix
linktitle: hasSuffix
linkTitle: hasSuffix
description: Tests whether a string ends with suffix.
date: 2023-03-01
publishdate: 2023-03-01
@ -18,4 +18,4 @@ deprecated: false
aliases: []
---
* `{{ hasSuffix "Hugo" "go" }}` → true
* `{{ hasSuffix "Hugo" "go" }}` → true

4
docs/content/en/functions/highlight.md
View file

@ -91,8 +91,8 @@ Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the f
{{ $input := `echo "Hello World!"` }}
{{ $lang := "bash" }}
{{ $options := slice "lineNos=table" "style=dracula" }}
{{ transform.Highlight $input $lang (delimit $options ",") }}
{{ $options := dict "lineNos" "table" "style" "dracula" }}
{{ transform.Highlight $input $lang $options }}
```
[Chroma]: https://github.com/alecthomas/chroma

2
docs/content/en/functions/images/index.md
View file

@ -1,5 +1,5 @@
---
title: Image Filters
title: Image filters
description: The images namespace provides a list of filters and other image related functions.
categories: [functions]
aliases: [/functions/imageconfig/]

2
docs/content/en/functions/index-function.md
View file

@ -37,7 +37,7 @@ You may write multiple indices as a slice:
{{ index $map $slice }} => 20
```
## Example: Load Data from a Path Based on Front Matter Params
## Example: load data from a path based on front matter parameters
Assume you want to add a `location = ""` field to your front matter for every article written in `content/vacations/`. You want to use this field to populate information about the location at the bottom of the article in your `single.html` template. You also have a directory in `data/locations/` that looks like the following:

2
docs/content/en/functions/intersect.md
View file

@ -19,7 +19,7 @@ A useful example is to use it as `AND` filters when combined with where:
{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
```
The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page params.
The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page parameters.
See [union](/functions/union) for `OR`.

2
docs/content/en/functions/isset.md
View file

@ -17,6 +17,6 @@ Takes either a slice, array, or channel and an index or a map and a key as input
```
{{% 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).
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 configuration 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/).
{{% /note %}}

44
docs/content/en/functions/math.md
View file

@ -11,24 +11,26 @@ signature: []
relatedfuncs: []
---
| Function | Description | Example |
|--------------|-----------------------------------------------------------------------------|-------------------------------------|
| `add` | Adds two or more numbers. | `{{ add 12 3 2 }}` &rarr; `17` |
| | *If one of the numbers is a float, the result is a float.* | `{{ add 1.1 2 }}` &rarr; `3.1` |
| `sub` | Subtracts one or more numbers from the first number. | `{{ sub 12 3 2 }}` &rarr; `7` |
| | *If one of the numbers is a float, the result is a float.* | `{{ sub 3 2.5 }}` &rarr; `0.5` |
| `mul` | Multiplies two or more numbers. | `{{ mul 12 3 2 }}` &rarr; `72` |
| | *If one of the numbers is a float, the result is a float.* | `{{ mul 2 3.1 }}` &rarr; `6.2` |
| `div` | Divides the first number by one or more numbers. | `{{ div 12 3 2 }}` &rarr; `2` |
| | *If one of the numbers is a float, the result is a float.* | `{{ div 6 4.0 }}` &rarr; `1.5` |
| `mod` | Modulus of two integers. | `{{ mod 15 3 }}` &rarr; `0` |
| `modBool` | Boolean of modulus of two integers. Evaluates to `true` if result equals 0. | `{{ modBool 15 3 }}` &rarr; `true` |
| `math.Abs` | Returns the absolute value of the given number. | `{{ math.Abs -2.1 }}` &rarr; `2.1` |
| `math.Ceil` | Returns the least integer value greater than or equal to the given number. | `{{ math.Ceil 2.1 }}` &rarr; `3` |
| `math.Floor` | Returns the greatest integer value less than or equal to the given number. | `{{ math.Floor 1.9 }}` &rarr; `1` |
| `math.Log` | Returns the natural logarithm of the given number. | `{{ math.Log 42 }}` &rarr; `3.737` |
| `math.Max` | Returns the greater of two or more numbers. | `{{ math.Max 12 3 2 }}` &rarr; `12` |
| `math.Min` | Returns the smaller of two or more numbers. | `{{ math.Min 12 3 2 }}` &rarr; `2` |
| `math.Pow` | Returns the first number raised to the power of the second number. | `{{ math.Pow 2 3 }}` &rarr; `8` |
| `math.Round` | Returns the nearest integer, rounding half away from zero. | `{{ math.Round 1.5 }}` &rarr; `2` |
| `math.Sqrt` | Returns the square root of the given number. | `{{ math.Sqrt 81 }}` &rarr; `9` |
| Function | Description | Example |
|-----------------|-----------------------------------------------------------------------------|---------------------------------------------------|
| `add` | Adds two or more numbers. | `{{ add 12 3 2 }}` &rarr; `17` |
| | *If one of the numbers is a float, the result is a float.* | `{{ add 1.1 2 }}` &rarr; `3.1` |
| `sub` | Subtracts one or more numbers from the first number. | `{{ sub 12 3 2 }}` &rarr; `7` |
| | *If one of the numbers is a float, the result is a float.* | `{{ sub 3 2.5 }}` &rarr; `0.5` |
| `mul` | Multiplies two or more numbers. | `{{ mul 12 3 2 }}` &rarr; `72` |
| | *If one of the numbers is a float, the result is a float.* | `{{ mul 2 3.1 }}` &rarr; `6.2` |
| `div` | Divides the first number by one or more numbers. | `{{ div 12 3 2 }}` &rarr; `2` |
| | *If one of the numbers is a float, the result is a float.* | `{{ div 6 4.0 }}` &rarr; `1.5` |
| `mod` | Modulus of two integers. | `{{ mod 15 3 }}` &rarr; `0` |
| `modBool` | Boolean of modulus of two integers. Evaluates to `true` if result equals 0. | `{{ modBool 15 3 }}` &rarr; `true` |
| `math.Abs` | Returns the absolute value of the given number. | `{{ math.Abs -2.1 }}` &rarr; `2.1` |
| `math.Ceil` | Returns the least integer value greater than or equal to the given number. | `{{ math.Ceil 2.1 }}` &rarr; `3` |
| `math.Floor` | Returns the greatest integer value less than or equal to the given number. | `{{ math.Floor 1.9 }}` &rarr; `1` |
| `math.Log` | Returns the natural logarithm of the given number. | `{{ math.Log 42 }}` &rarr; `3.737` |
| `math.Max` | Returns the greater of all numbers. Accepts scalars, slices, or both. | `{{ math.Max 1 (slice 2 3) 4 }}` &rarr; `4` |
| `math.Min` | Returns the smaller of all numbers. Accepts scalars, slices, or both. | `{{ math.Min 1 (slice 2 3) 4 }}` &rarr; `1` |
| `math.Product` | Returns the product of all numbers. Accepts scalars, slices, or both. | `{{ math.Product 1 (slice 2 3) 4 }}` &rarr; `24` |
| `math.Pow` | Returns the first number raised to the power of the second number. | `{{ math.Pow 2 3 }}` &rarr; `8` |
| `math.Round` | Returns the nearest integer, rounding half away from zero. | `{{ math.Round 1.5 }}` &rarr; `2` |
| `math.Sqrt` | Returns the square root of the given number. | `{{ math.Sqrt 81 }}` &rarr; `9` |
| `math.Sum` | Returns the sum of all numbers. Accepts scalars, slices, or both. | `{{ math.Sum 1 (slice 2 3) 4 }}` &rarr; `10` |

2
docs/content/en/functions/readdir.md
View file

@ -1,6 +1,6 @@
---
title: readDir
description: Returns an array of FileInfo structures sorted by filename, one element for each directory entry.
description: Returns an array of FileInfo structures sorted by file name, one element for each directory entry.
categories: [functions]
menu:
docs:

8
docs/content/en/functions/safeHTMLAttr.md
View file

@ -34,12 +34,16 @@ Will produce:
`ZgotmplZ` is a special value, inserted by Go's [template/html] package, that indicates that unsafe content reached a CSS or URL context.
To override the safety check, use the `safeHTMLAttr` function:
To indicate that the HTML attribute is safe:
```go-html-template
{{ range site.Menus.main }}
<a {{ printf "href=%q" .URL | safeHTMLAttr }}>{{ .Name }}</a>
{{ end }}
```
```
{{% note %}}
As demonstrated above, you must pass the HTML attribute name _and_ value through the function. Applying `safeHTMLAttr` to the attribute value has no effect.
{{% /note %}}
[template/html]: https://pkg.go.dev/html/template

4
docs/content/en/functions/time.md
View file

@ -19,7 +19,7 @@ relatedfuncs: []
{{ mul 1000 (time "2016-05-28T10:30:00.00+10:00").Unix }} → 1464395400000, or Unix time in milliseconds
```
## Using Locations
## Using locations
The optional `TIMEZONE` parameter is a string that sets a default time zone (or more specific, the location, which represents the collection of time offsets in a geographical area) that is associated with the specified time value. If the time value has an explicit timezone or offset specified, it will take precedence over the `TIMEZONE` parameter.
@ -33,7 +33,7 @@ If no `TIMEZONE` is set, the `timeZone` from site configuration will be used.
{{ time "2020-01-20" "America/Los_Angeles" }} → 2020-01-20 00:00:00 -0800 PST
```
## Example: Using `time` to get Month Index
## Example: Using `time` to get month index
The following example takes a UNIX timestamp---set as `utimestamp: "1489276800"` in a content's front matter---converts the timestamp (string) to an integer using the [`int` function][int], and then uses [`printf`] to convert the `Month` property of `time` into an index.

4
docs/content/en/functions/transform.Unmarshal.md
View file

@ -27,7 +27,7 @@ In both the above examples, you get a map you can work with:
The above prints `Hello Hugo`.
## CSV Options
## CSV options
Unmarshal with CSV as input has some options you can set:
@ -61,7 +61,7 @@ To get the contents of `<title>` in the document below, you use `{{ .message.tit
The following example lists the items of an RSS feed:
```go-html-template
{{ with resources.Get "https://example.com/rss.xml" | transform.Unmarshal }}
{{ with resources.GetRemote "https://example.com/rss.xml" | transform.Unmarshal }}
{{ range .channel.item }}
<strong>{{ .title | plainify | htmlUnescape }}</strong><br />
<p>{{ .description | plainify | htmlUnescape }}</p>

2
docs/content/en/functions/union.md
View file

@ -36,6 +36,6 @@ This is also very useful to use as `OR` filters when combined with where:
{{ $pages = $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
```
The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page params.
The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page parameters.
See [intersect](/functions/intersect) for `AND`.

9
docs/content/en/functions/where.md
View file

@ -73,7 +73,7 @@ The following logical operators are available with `where`:
`intersect`
: `true` if a given field value that is a slice/array of strings or integers contains elements in common with the matching value; it follows the same rules as the [`intersect` function][intersect].
## Use `where` with `Booleans`
## Use `where` with boolean values
When using booleans you should not put quotation marks.
```go-html-template
{{ range where .Pages "Draft" true }}
@ -116,7 +116,7 @@ then ranges through only the first 5 posts in that list:
{{ end }}
{{< /code >}}
## Nest `where` Clauses
## Nest `where` clauses
You can also nest `where` clauses to drill down on lists of content by more than one parameter. The following first grabs all pages in the "blog" section and then ranges through the result of the first `where` clause and finds all pages that are *not* featured:
@ -124,7 +124,7 @@ You can also nest `where` clauses to drill down on lists of content by more than
{{ range where (where .Pages "Section" "blog" ) "Params.featured" "!=" true }}
```
## Unset Fields
## Unset fields
Filtering only works for set fields. To check whether a field is set or exists, you can use the operand `nil`.
@ -153,8 +153,7 @@ section names to hard-coded values like `"posts"` or `"post"`.
{{ $pages := where site.RegularPages "Type" "in" site.Params.mainSections }}
```
If the user has not set this config parameter in their site config, it
will default to the *section with the most pages*.
If the user has not set this configuration parameter in their site configuration, it will default to the *section with the most pages*.
The user can override the default:

9
docs/content/en/getting-started/_index.md
View file

@ -1,14 +1,15 @@
---
title: Get Started
linktitle: Get Started Overview
title: Getting started
linkTitle: Overview
description: Quick start and guides for installing Hugo on your preferred operating system.
categories: [getting started]
keywords: [usage,docs]
menu:
docs:
identifier: getting-started-overview
parent: getting-started
weight: 1
weight: 0001
weight: 10
weight: 10
aliases: [/overview/introduction/]
---

16
docs/content/en/getting-started/configuration-markup.md
View file

@ -1,14 +1,18 @@
---
title: Configure Markup
title: Configure markup
description: How to handle Markdown and other markup related configuration.
categories: [getting started,fundamentals]
categories: [fundamentals, getting started]
keywords: [configuration,highlighting]
weight: 65
menu:
docs:
parent: getting-started
weight: 50
weight: 50
slug: configuration-markup
toc: true
---
## Configure Markup
## Configure markup
See [Goldmark](#goldmark) for settings related to the default Markdown handler in Hugo.
@ -91,7 +95,7 @@ For `style`, see these galleries:
For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#generate-syntax-highlighter-css).
### Table Of Contents
### Table of contents
{{< code-toggle config="markup.tableOfContents" />}}
@ -106,6 +110,6 @@ endLevel
ordered
: Whether or not to generate an ordered list instead of an unordered list.
## Markdown Render Hooks
## Markdown render hooks
See [Markdown Render Hooks](/templates/render-hooks/).

213
docs/content/en/getting-started/configuration.md
View file

@ -1,25 +1,24 @@
---
title: Configure Hugo
linktitle: Configuration
linkTitle: Configuration
description: How to configure your Hugo site.
categories: [getting started,fundamentals]
categories: [fundamentals,getting started]
keywords: [configuration,toml,yaml,json]
menu:
docs:
parent: getting-started
weight: 60
weight: 60
weight: 40
weight: 40
aliases: [/overview/source-directory/,/overview/configuration/]
toc: true
---
## Configuration File
## Configuration file
Hugo uses the `hugo.toml`, `hugo.yaml`, or `hugo.json` (if found in the
site root) as the default site configuration file.
The user can choose to override that default with one or more site config files
using the command-line `--config` switch.
The user can choose to override that default with one or more site configuration files using the command-line `--config` switch.
Examples:
@ -29,18 +28,18 @@ hugo --config a.toml,b.toml,c.toml
```
{{% note %}}
Multiple site config files can be specified as a comma-separated string to the `--config` switch.
Multiple site configuration files can be specified as a comma-separated string to the `--config` switch.
{{% /note %}}
## hugo.toml vs config.toml
In Hugo 0.110.0 we changed the default config base filename to `hugo`, e.g. `hugo.toml`. We will still look for `config.toml` etc., but we recommend you eventually rename it (but you need to wait if you want to support older Hugo versions). The main reason we're doing this is to make it easier for code editors and build tools to identify this as a Hugo configuration file and project.
In Hugo 0.110.0 we changed the default configuration base file name to `hugo`, e.g. `hugo.toml`. We will still look for `config.toml` etc., but we recommend you eventually rename it (but you need to wait if you want to support older Hugo versions). The main reason we're doing this is to make it easier for code editors and build tools to identify this as a Hugo configuration file and project.
{{< new-in "0.110.0" >}}
## Configuration Directory
## Configuration directory
In addition to using a single site config file, one can use the `configDir` directory (default to `config/`) to maintain easier organization and environment specific settings.
In addition to using a single site configuration file, one can use the `configDir` directory (default to `config/`) to maintain easier organization and environment specific settings.
- Each file represents a configuration root object, such as `params.toml` for `[Params]`, `menu(s).toml` for `[Menu]`, `languages.toml` for `[Languages]` etc...
- Each file's content must be top-level, for example:
@ -57,7 +56,6 @@ foo = "bar"
- Each directory holds a group of files containing settings unique to an environment.
- Files can be localized to become language specific.
```txt
├── config
│ ├── _default
@ -83,23 +81,23 @@ Let's take an example to understand this better. Let's say you are using Google
- `G-SSSSSSSS` for staging
This is how you need to configure your `hugo.toml` files considering the above scenario:
1. In `_default/hugo.toml` you don't need to mention `googleAnalytics` parameter at all. This ensures that no Google Analytics code is loaded in your development server i.e. when you run `hugo server`. This works since, by default Hugo sets `Environment=development` when you run `hugo server` which uses the config files from `_default` folder
1. In `_default/hugo.toml` you don't need to mention `googleAnalytics` parameter at all. This ensures that no Google Analytics code is loaded in your development server i.e. when you run `hugo server`. This works since, by default Hugo sets `Environment=development` when you run `hugo server` which uses the configuration files from `_default` folder
2. In `production/hugo.toml` you just need to have one line:
```googleAnalytics = "G-PPPPPPPP"```
```googleAnalytics = "G-PPPPPPPP"```
You don't need to mention all other parameters like `title`, `baseURL`, `theme` etc. again in this config file. You need to mention only those parameters which are different or new for the production environment. This is due to the fact that Hugo is going to __merge__ this on top of `_default/hugo.toml`. Now when you run `hugo` (build command), by default hugo sets `Environment=production`, so the `G-PPPPPPPP` analytics code will be there in your production website
You don't need to mention all other parameters like `title`, `baseURL`, `theme` etc. again in this configuration file. You need to mention only those parameters which are different or new for the production environment. This is due to the fact that Hugo is going to __merge__ this on top of `_default/hugo.toml`. Now when you run `hugo` (build command), by default hugo sets `Environment=production`, so the `G-PPPPPPPP` analytics code will be there in your production website
3. Similarly in `staging/hugo.toml` you just need to have one line:
```googleAnalytics = "G-SSSSSSSS"```
```googleAnalytics = "G-SSSSSSSS"```
Now you need to tell Hugo that you are using the staging environment. So your build command should be `hugo --environment staging` which will load the `G-SSSSSSSS` analytics code in your staging website
Now you need to tell Hugo that you are using the staging environment. So your build command should be `hugo --environment staging` which will load the `G-SSSSSSSS` analytics code in your staging website
{{% note %}}
Default environments are __development__ with `hugo server` and __production__ with `hugo`.
{{%/ note %}}
## Merge Configuration from Themes
## Merge configuration from themes
The configuration value for `_merge` can be one of:
@ -116,10 +114,9 @@ Note that you don't need to be so verbose as in the default setup below; a `_mer
{{< code-toggle config="mergeStrategy" skipHeader=true />}}
## All Configuration Settings
## All configuration settings
The following is the full list of Hugo-defined variables. Users may choose to override those values in their site
config file(s).
The following is the full list of Hugo-defined variables. Users may choose to override those values in their site configuration file(s).
### archetypeDir
@ -165,7 +162,7 @@ See [Configure File Caches](#configure-file-caches)
### cascade
Pass down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade).
Pass down default configuration values (front matter) to pages in the content tree. The options in site configuration is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade).
### canonifyURLs
@ -205,25 +202,25 @@ Content without language indicator will default to this language.
### defaultContentLanguageInSubdir
**Default value:** false
**Default value:** false
Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`.
### disableAliases
**Default value:** false
**Default value:** false
Will disable generation of alias redirects. Note that even if `disableAliases` is set, the aliases themselves are preserved on the page. The motivation with this is to be able to generate 301 redirects in an `.htaccess`, a Netlify `_redirects` file or similar using a custom output format.
### disableHugoGeneratorInject
**Default value:** false
**Default value:** false
Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise.
### disableKinds
**Default value:** []
**Default value:** []
Enable disabling of all pages of the specified *Kinds*. Allowed values in this list: `"page"`, `"home"`, `"section"`, `"taxonomy"`, `"term"`, `"RSS"`, `"sitemap"`, `"robotsTXT"`, `"404"`.
@ -235,37 +232,37 @@ Disable automatic live reloading of browser window.
### disablePathToLower
**Default value:** false
**Default value:** false
Do not convert the url/path to lowercase.
### enableEmoji
**Default value:** false
**Default value:** false
Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/).
### enableGitInfo
**Default value:** false
**Default value:** false
Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file.
### enableInlineShortcodes
**Default value:** false
**Default value:** false
Enable inline shortcode support. See [Inline Shortcodes](/templates/shortcode-templates/#inline-shortcodes).
### enableMissingTranslationPlaceholders
**Default value:** false
**Default value:** false
Show a placeholder instead of the default value or an empty string if a translation is missing.
### enableRobotsTXT
**Default value:** false
**Default value:** false
Enable generation of `robots.txt` file.
@ -275,7 +272,7 @@ See [Front matter Configuration](#configure-front-matter).
### googleAnalytics
**Default value:** ""
**Default value:** ""
Google Analytics tracking ID.
@ -287,11 +284,11 @@ If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will
### imaging
See [Image Processing Config](/content-management/image-processing/#imaging-configuration).
See [image processing configuration](/content-management/image-processing/#imaging-configuration).
### languageCode
**Default value:** ""
**Default value:** ""
A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). This value is used to populate:
@ -324,7 +321,7 @@ See [Configure Minify](#configure-minify)
### module
Module config see [Module Config](/hugo-modules/configuration/).
Module configuration see [module configuration](/hugo-modules/configuration/).
### newContentEditor
@ -436,11 +433,11 @@ See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies).
### theme
: See [Module Config](/hugo-modules/configuration/#module-config-imports) for how to import a theme.
: See [module configuration](/hugo-modules/configuration/#module-configuration-imports) for how to import a theme.
### themesDir
**Default value:** "themes"
**Default value:** "themes"
The directory where Hugo reads the themes from.
@ -448,11 +445,11 @@ The directory where Hugo reads the themes from.
**Default value:** "30s"
Timeout for generating page contents, specified as a [duration](https://pkg.go.dev/time#Duration) or in milliseconds. *Note:*&nbsp;this is used to bail out of recursive content generation. You might need to raise this limit if your pages are slow to generate (e.g., because they require large image processing or depend on remote contents).
Timeout for generating page contents, specified as a [duration](https://pkg.go.dev/time#Duration) or in seconds. *Note:*&nbsp;this is used to bail out of recursive content generation. You might need to raise this limit if your pages are slow to generate (e.g., because they require large image processing or depend on remote contents).
### timeZone
The time zone (or location), e.g. `Europe/Oslo`, used to parse front matter dates without such information and in the [`time` function](/functions/time/). The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
The time zone (or location), e.g. `Europe/Oslo`, used to parse front matter dates without such information and in the [`time` function](/functions/time/). The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
### title
@ -460,7 +457,7 @@ Site title.
### titleCaseStyle
**Default value:** "AP"
**Default value:** "ap"
See [Configure Title Case](#configure-title-case)
@ -490,53 +487,73 @@ enableemoji: true
```
{{% /note %}}
## Configure Build
## Configure build
The `build` configuration section contains global build-related configuration options.
{{< code-toggle file="hugo" >}}
[build]
useResourceCacheWhen="fallback"
writeStats = false
noJSConfigInAssets = false
[[build.cachebusters]]
source = "assets/watching/hugo_stats\\.json"
target = "styles\\.css"
[[build.cachebusters]]
source = "(postcss|tailwind)\\.config\\.js"
target = "css"
[[build.cachebusters]]
source = "assets/.*\\.(js|ts|jsx|tsx)"
target = "js"
[[build.cachebusters]]
source = "assets/.*\\.(.*)$"
target = "$1"
noJSConfigInAssets = false
useResourceCacheWhen = 'fallback'
[build.buildStats]
disableClasses = false
disableIDs = false
disableTags = false
enable = false
[[build.cachebusters]]
source = 'assets/.*\.(js|ts|jsx|tsx)'
target = '(js|scripts|javascript)'
[[build.cachebusters]]
source = 'assets/.*\.(css|sass|scss)$'
target = '(css|styles|scss|sass)'
[[build.cachebusters]]
source = '(postcss|tailwind)\.config\.js'
target = '(css|styles|scss|sass)'
[[build.cachebusters]]
source = 'assets/.*\.(.*)$'
target = '$1'
{{< /code-toggle >}}
buildStats {{< new-in "0.115.1" >}}
: When enabled, creates a `hugo_stats.json` file in the root of your project. This file contains arrays of the `class` attributes, `id` attributes, and tags of every HTML element within your published site. Use this file as data source when [removing unused CSS] from your site. This process is also known as pruning, purging, or tree shaking.
useResourceCacheWhen
: When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available.
[removing unused CSS]: http://localhost:1313/hugo-pipes/postprocess/#css-purging-with-postcss
writeStats
: When enabled, a file named `hugo_stats.json` will be written to your project root with some aggregated data about the build, e.g. list of HTML entities published to be used to do [CSS pruning](/hugo-pipes/postprocess/#css-purging-with-postcss). If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory). It's also worth mentioning that, due to the nature of the partial server builds, new HTML entities will be added when you add or change them while the server is running, but the old values will not be removed until you restart the server or run a regular `hugo` build.
Exclude `class` attributes, `id` attributes, or tags from `hugo_stats.json` with the `disableClasses`, `disableIDs`, and `disableTags` keys.
**Note** that the prime use case for this is purging of unused CSS; it is built for speed and there may be false positives (e.g., detection of HTML elements that are not HTML elements).
{{% note %}}
With v0.115.0 and earlier this feature was enabled by setting `writeStats` to `true`. Although still functional, the `writeStats` key will be deprecated in a future release.
noJSConfigInAssets
: Turn off writing a `jsconfig.json` into your `/assets` folder with mapping of imports from running [js.Build](https://gohugo.io/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written.
Given that CSS purging is typically limited to production builds, place the `buildStats` object below [config/production].
[config/production]: /getting-started/configuration/#configuration-directory
Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential.
{{% /note %}}
Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build.
cachebusters
: See [Configure Cache Busters](#configure-cache-busters)
## Configure Cache Busters
noJSConfigInAssets
: Turn off writing a `jsconfig.json` into your `/assets` folder with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written.
useResourceCacheWhen
: When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available.
## Configure cache busters
{{< new-in "0.112.0" >}}
The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` config may look like this:
The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this:
<!-- TODO (jmm) writeStats => build.buildStats -->
{{< code-toggle file="hugo" >}}
[build]
writeStats = true
[build.buildStats]
enable = true
[[build.cachebusters]]
source = "assets/watching/hugo_stats\\.json"
target = "styles\\.css"
@ -559,7 +576,7 @@ source
target
: A regexp matching the keys in the resource cache that should be expired when `source` changes. You can use the matching regexp groups from `source` in the expression, e.g. `$1`.
## Configure Server
## Configure server
This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slightly more powerful [Glob matching](https://github.com/gobwas/glob):
@ -579,7 +596,6 @@ Content-Security-Policy = "script-src localhost:1313"
Since this is "development only", it may make sense to put it below the `development` environment:
{{< code-toggle file="config/development/server">}}
[[headers]]
for = "/**"
@ -604,13 +620,13 @@ status = 200
force = false
{{< /code-toggle >}}
Setting `force=true` will make a redirect even if there is existing content in the path. Note that before Hugo 0.76 `force` was the default behavior, but this is inline with how Netlify does it.
Setting `force=true` will make a redirect even if there is existing content in the path. Note that before Hugo 0.76 `force` was the default behavior, but this is inline with how Netlify does it.
## 404 Server Error Page {#_404-server-error-page}
## 404 server error page {#_404-server-error-page}
{{< new-in "0.103.0" >}}
Hugo will, by default, render all 404 errors when running `hugo server` with the `404.html` template. Note that if you have already added one or more redirects to your [Server Config](#configure-server), you need to add the 404 redirect explicitly, e.g:
Hugo will, by default, render all 404 errors when running `hugo server` with the `404.html` template. Note that if you have already added one or more redirects to your [server configuration](#configure-server), you need to add the 404 redirect explicitly, e.g:
{{< code-toggle file="config/development/server" copy=false >}}
[[redirects]]
@ -619,13 +635,13 @@ to = "/404.html"
status = 404
{{< /code-toggle >}}
## Configure Title Case
## Configure title case
Set `titleCaseStyle` to specify the title style used by the [title](/functions/title/) template function and the automatic section titles in Hugo.
Set `titleCaseStyle` to specify the title style used by the [title](/functions/title/) template function and the automatic section titles in Hugo.
Can be one of:
* `ap` (default), the capitalization rules in the [Associated Press (AP) Stylebook]
* `ap` (default), the capitalization rules in the [Associated Press (AP) Stylebook]
* `chicago`, the [Chicago Manual of Style]
* `go`, Go's convention of capitalizing every word.
* `firstupper`, capitalize the first letter of the first word.
@ -635,12 +651,12 @@ Can be one of:
[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
[site configuration]: /getting-started/configuration/#configure-title-case
## Configuration Environment Variables
## Configuration environment variables
HUGO_NUMWORKERMULTIPLIER
: Can be set to increase or reduce the number of workers used in parallel processing in Hugo. If not set, the number of logical CPUs will be used.
## Configuration Lookup Order
## Configuration lookup order
Similar to the template [lookup order], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior:
@ -650,8 +666,7 @@ Similar to the template [lookup order], Hugo has a default set of rules for sear
In your configuration file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project.
## Example Configuration
## Example configuration
The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`] variable for use in [templates]:
@ -670,9 +685,9 @@ params:
SidebarRecentLimit: 5
{{< /code-toggle >}}
## Configure with Environment Variables
## Configure with environment variables
In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables.
In addition to the 3 configuration options already mentioned, configuration key-values can be defined through operating system environment variables.
For example, the following command will effectively set a website's title on Unix-like systems:
@ -685,18 +700,18 @@ This is really useful if you use a service such as Netlify to deploy your site.
{{% note %}}
Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables.
To set config params, prefix the name with `HUGO_PARAMS_`
To set configuration parameters, prefix the name with `HUGO_PARAMS_`
{{% /note %}}
If you are using snake_cased variable names, the above will not work. Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter.
{{< todo >}}
Test and document setting params via JSON env var.
Test and document setting parameters via JSON env var.
{{< /todo >}}
## Ignore Content and Data Files when Rendering
## Ignore content and data files when rendering
**Note:** This works, but we recommend you use the newer and more powerful [includeFiles and excludeFiles](https://gohugo.io/hugo-modules/configuration/#module-config-mounts) mount options.
**Note:** This works, but we recommend you use the newer and more powerful [includeFiles and excludeFiles](/hugo-modules/configuration/#module-configuration-mounts) mount options.
To exclude specific files from the `content`, `data`, and `i18n` directories when rendering your site, set `ignoreFiles` to one or more regular expressions to match against the absolute file path.
@ -712,9 +727,9 @@ To ignore a file using the absolute file path:
ignoreFiles = ['^/home/user/project/content/test\.md$']
{{< /code-toggle >}}
## Configure Front Matter
## Configure front matter
### Configure Dates
### Configure dates
Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `hugo.toml`.
@ -737,11 +752,10 @@ date = ["myDate", ":default"]
The `:default` is a shortcut to the default settings. The above will set `.Date` to the date value in `myDate` if present, if not we will look in `date`,`publishDate`, `lastmod` and pick the first valid date.
In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`.
In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`.
The special date handlers are:
`:fileModTime`
: Fetches the date from the content file's last modification timestamp.
@ -752,12 +766,10 @@ An example:
lastmod = ["lastmod", ":fileModTime", ":default"]
{{< /code-toggle >}}
The above will try first to extract the value for `.Lastmod` starting with the `lastmod` front matter parameter, then the content file's modification timestamp. The last, `:default` should not be needed here, but Hugo will finally look for a valid date in `:git`, `date` and then `publishDate`.
`:filename`
: Fetches the date from the content file's filename. For example, `2018-02-22-mypage.md` will extract the date `2018-02-22`. Also, if `slug` is not set, `mypage` will be used as the value for `.Slug`.
: Fetches the date from the content file's file name. For example, `2018-02-22-mypage.md` will extract the date `2018-02-22`. Also, if `slug` is not set, `mypage` will be used as the value for `.Slug`.
An example:
@ -766,23 +778,22 @@ An example:
date = [":filename", ":default"]
{{< /code-toggle >}}
The above will try first to extract the value for `.Date` from the filename, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`.
The above will try first to extract the value for `.Date` from the file name, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`.
`:git`
: This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site config.
: This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site configuration.
## Configure Additional Output Formats
## Configure additional output formats
Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats] for information on how to add these values to your Hugo project's configuration file.
## Configure Minify
## Configure minify
Default configuration:
{{< code-toggle config="minify" />}}
## Configure File Caches
## Configure file caches
Since Hugo 0.52 you can configure more than just the `cacheDir`. This is the default configuration:
@ -813,13 +824,13 @@ You can override any of these cache settings in your own `hugo.toml`.
### The keywords explained
`:cacheDir`
: This is the value of the `cacheDir` config option if set (can also be set via OS env variable `HUGO_CACHEDIR`). It will fall back to `/opt/build/cache/hugo_cache/` on Netlify, or a `hugo_cache_$USER` directory below the OS temp dir for the others. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml).
: This is the value of the `cacheDir` configuration option if set (can also be set via OS env variable `HUGO_CACHEDIR`). It will fall back to `/opt/build/cache/hugo_cache/` on Netlify, or a `hugo_cache_$USER` directory below the OS temp dir for the others. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml).
`:project`
: The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC.
`:resourceDir`
: This is the value of the `resourceDir` config option.
: This is the value of the `resourceDir` configuration option.
maxAge
: This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours).
@ -827,7 +838,7 @@ maxAge
dir
: The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above).
## Configuration Format Specs
## Configuration format specs
- [TOML Spec][toml]
- [YAML Spec][yaml]

19
docs/content/en/getting-started/directory-structure.md
View file

@ -1,18 +1,18 @@
---
title: Directory Structure
title: Directory structure
description: Hugo's CLI scaffolds a project directory structure and then takes that single directory and uses it as the input to create a complete website.
categories: [getting started,fundamentals]
categories: [fundamentals,getting started]
keywords: [source, organization, directories]
menu:
docs:
parent: getting-started
weight: 50
weight: 50
weight: 30
weight: 30
aliases: [/overview/source-directory/]
toc: true
---
## New Site Scaffolding
## New site scaffolding
{{< youtube sB0HLHjgQ7E >}}
@ -32,23 +32,23 @@ example/
└── hugo.toml
```
## Directory Structure Explained
## Directory structure explained
The following is a high-level overview of each of the directories with links to each of their respective sections within the Hugo docs.
[`archetypes`](/content-management/archetypes/)
: You can create new content files in Hugo using the `hugo new` command.
By default, Hugo will create new content files with at least `date`, `title` (inferred from the filename), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes] with custom preconfigured front matter fields as well.
By default, Hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes] with custom preconfigured front matter fields as well.
[`assets`]
: Stores all the files which need be processed by [Hugo Pipes](/hugo-pipes/). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory.
[`config`](/getting-started/configuration/)
: Hugo ships with a large number of [configuration directives].
The [config directory](/getting-started/configuration/#configuration-directory) is where those directives are stored as JSON, YAML, or TOML files. Every root setting object can stand as its own file and structured by environments.
The [configuration directory](/getting-started/configuration/#configuration-directory) is where those directives are stored as JSON, YAML, or TOML files. Every root setting object can stand as its own file and structured by environments.
Projects with minimal settings and no need for environment awareness can use a single `hugo.toml` file at its root.
Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives] for more granular directions on how you want Hugo to build your website. Note: config directory is not created by default.
Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives] for more granular directions on how you want Hugo to build your website. Note: the `config` directory is not created by default.
[`content`]
: All content for your website will live inside this directory. Each top-level folder in Hugo is considered a [content section]. For example, if your site has three main sections---`blog`, `articles`, and `tutorials`---you will have three directories at `content/blog`, `content/articles`, and `content/tutorials`. Hugo uses sections to assign default [content types].
@ -86,7 +86,6 @@ From **Hugo 0.31** you can have multiple static directories.
[partials]: /templates/partials/
[searchconsole]: https://support.google.com/webmasters/answer/9008080#zippy=%2Chtml-file-upload
[singles]: /templates/single-page-templates/
[starters]: /tools/starter-kits/
[taxonomies]: /content-management/taxonomies/
[taxonomy templates]: /templates/taxonomy-templates/
[types]: /content-management/types/

6
docs/content/en/getting-started/external-learning-resources/index.md
View file

@ -1,12 +1,12 @@
---
title: External Learning Resources
title: External learning resources
description: A list of tutorials and books on Hugo.
keywords: [books, tutorials, learning, usage]
menu:
docs:
parent: getting-started
weight: 70
weight: 70
weight: 60
weight: 60
---
## Books

13
docs/content/en/getting-started/quick-start.md
View file

@ -1,13 +1,13 @@
---
title: Quick Start
title: Quick start
description: Learn to create a Hugo site in minutes.
categories: [getting started]
keywords: [quick start,usage]
menu:
docs:
parent: getting-started
weight: 10
weight: 10
weight: 20
weight: 20
toc: true
aliases: [/quickstart/,/overview/quickstart/]
---
@ -39,9 +39,10 @@ You must also be comfortable working from the command line.
- Do not use Windows PowerShell
- Run these commands from [PowerShell] or a Linux terminal such as WSL or Git Bash
PowerShell and Windows PowerShell are different applications.
PowerShell and Windows PowerShell [are different applications].
[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
[are different applications]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3
{{% /note %}}
Run these commands to create a Hugo site with the [Ananke] theme. The next section provides an explanation of each command.
@ -50,7 +51,7 @@ Run these commands to create a Hugo site with the [Ananke] theme. The next secti
hugo new site quickstart
cd quickstart
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo "theme = 'ananke'" >> hugo.toml
hugo server
```
@ -80,7 +81,7 @@ git init
Clone the [Ananke] theme into the `themes` directory, adding it to your project as a [Git submodule].
```text
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
```
Append a line to the site configuration file, indicating the current theme.

4
docs/content/en/getting-started/usage.md
View file

@ -6,8 +6,8 @@ keywords: [usage,livereload,command,flags]
menu:
docs:
parent: getting-started
weight: 40
weight: 40
weight: 30
weight: 30
aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
toc: true
---

9
docs/content/en/hosting-and-deployment/_index.md
View file

@ -1,14 +1,15 @@
---
title: Hosting & Deployment
linktitle: Hosting & Deployment Overview
title: Hosting and deployment
linkTitle: Overview
description: Site builds, automated deployments, and popular hosting solutions.
categories: [hosting and deployment]
keywords: []
menu:
docs:
identifier: hosting-and-deployment-overview
parent: hosting-and-deployment
weight: 01
weight: 01
weight: 1
weight: 1
---
Because Hugo renders *static* websites, you can host your new Hugo website virtually anywhere. The following represent only a few of the more popular hosting and automated deployment solutions used by the Hugo community.

10
docs/content/en/hosting-and-deployment/deployment-with-rclone.md
View file

@ -1,13 +1,11 @@
---
title: Deployment with Rclone
title: Deploy with Rclone
description: If you have access to your web host with SFTP/FTP/SSH/HTTP(DAV), you can use rclone to incrementally deploy your entire Hugo website.
categories: [hosting and deployment]
keywords: [rclone,sftp,deployment]
menu:
docs:
parent: hosting-and-deployment
weight: 80
weight: 80
aliases: [/tutorials/deployment-with-rclone/]
toc: true
---
@ -22,7 +20,7 @@ toc: true
**NB**: You can remove ``--interactive`` in the commands below once you are comfortable with rclone, if you wish. Also, ``--gc`` and ``--minify`` are optional in the ``hugo`` commands below.
## Getting Started
## Getting started
The spoiler is that you can even deploy your entire website from any compatible OS with no configuration. Using SFTP for example:
@ -31,9 +29,9 @@ hugo --gc --minify
rclone sync --interactive --sftp-host sftp.example.com --sftp-user www-data --sftp-ask-password public/ :sftp:www/
```
## Configure Rclone for Even Easier Usage
## Configure Rclone for even easier usage
The easiest way is simply to run ``rclone config``.
The easiest way is simply to run `rclone config`.
The [Rclone docs](https://rclone.org/docs/) provide [an example of configuring Rclone to use SFTP](https://rclone.org/sftp/).

8
docs/content/en/hosting-and-deployment/deployment-with-rsync.md
View file

@ -1,13 +1,11 @@
---
title: Deployment with Rsync
title: Deploy with Rsync
description: If you have access to your web host with SSH, you can use a simple rsync one-liner to incrementally deploy your entire Hugo website.
categories: [hosting and deployment]
keywords: [rsync,deployment]
menu:
docs:
parent: hosting-and-deployment
weight: 70
weight: 70
aliases: [/tutorials/deployment-with-rsync/]
toc: true
---
@ -26,7 +24,7 @@ hugo && rsync -avz --delete public/ www-data@ftp.topologix.fr:~/www/
As you will see, we'll put this command in a shell script file, which makes building and deployment as easy as executing `./deploy`.
## Copy Your SSH Key to your Host
## Copy Your SSH Key to your host
To make logging in to your server more secure and less interactive, you can upload your SSH key. If you have already installed your SSH key to your server, you can move on to the next section.
@ -77,7 +75,7 @@ Enter passphrase for key '/home/mylogin/.ssh/rsa_id':
Now that you can log in with your SSH key, let's create a script to automate deployment of your Hugo site.
## Shell Script
## Shell script
Create a new script called `deploy` the root of your Hugo tree:

2
docs/content/en/hosting-and-deployment/hosting-on-21yunbox.md
View file

@ -6,8 +6,6 @@ keywords: [21yunbox,hosting,deployment]
menu:
docs:
parent: hosting-and-deployment
weight: 10
weight: 10
toc: true
---

2
docs/content/en/hosting-and-deployment/hosting-on-aws-amplify.md
View file

@ -6,8 +6,6 @@ keywords: [amplify,hosting,deployment]
menu:
docs:
parent: hosting-and-deployment
weight: 10
weight: 10
toc: true
---

6
docs/content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md
View file

@ -1,13 +1,11 @@
---
title: Hosting on Azure Static Web Apps
description: Learn how to deploy a Hugo application to Azure Static Web Apps.
title: Host on Azure Static Web Apps
description: Publish a Hugo site to Azure Static Web Apps.
categories: [hosting and deployment]
keywords: [hosting,Azure Static Web Apps]
menu:
docs:
parent: hosting-and-deployment
weight: 200
weight: 200
toc: true
---

96
docs/content/en/hosting-and-deployment/hosting-on-azure.md
View file

@ -1,96 +0,0 @@
---
title: Host on Azure Static Web Apps
description: Deploy Hugo to Azure Static Web Apps and automate the whole process with GitHub Action Workflow
categories: [hosting and deployment]
keywords: [azure,git,deployment,hosting]
menu:
docs:
parent: hosting-and-deployment
weight: 10
weight: 10
toc: true
---
[Azure Static Web Apps] is a service that automatically builds and deploys full stack web apps to Azure from a Git repository, using [GitHub Actions] or [Azure DevOps].
_The following documentation covers how to use GitHub Actions for the deployment. If you are using Azure DevOps, follow the Microsoft documentation._
## Assumptions
1. You have Git 2.8 or greater [installed on your machine][installgit].
2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free.
3. You have an Azure account. You can sign up for a [Free Trial][azuretrial].
4. You have a ready-to-publish Hugo website or have at least completed the [Quick Start].
## Deploy Hugo to Azure Static Web Apps
1. Navigate to the [Azure Portal][azureportal]
2. Click **Create a Resource**
3. Search for **Static Web Apps**
4. Click **Static Web Apps**
5. Click **Create**
![Create in Azure Portal](/images/hosting-and-deployment/hosting-on-azure/create-in-portal.png)
6. For **Subscription**, accept the subscription that is listed or select a new one from the drop-down list.
7. In _Resource group_, select **New**. In _New resource group name_, enter **hugo-static-app** and select **OK**.
8. Next, a name for your app in the **Name** box. Valid characters include `a-z`, `A-Z`, `0-9` and `-`.
9. For _Region_, select an available region close to you.
10. For _SKU_, select **Free**.
![Basic app details](/images/hosting-and-deployment/hosting-on-azure/basic-app-details.png)
11. Click the **Sign in with GitHub** button.
12. Select the **Organization** under which your repo exists.
13. Select the Hugo app you wish to deploy as the _Repository_ .
14. For the _Branch_ select the branch you want to deploy (eg: **main**).
15. Select **Hugo** under the _Build Presets_, which will populate the configuration files with the standard Hugo build options
* **App Location** is the path in the Git repo where Hugo's config file is
* **Api Location** is the path where the Serverless API is (or left blank if there is no API)
* **Artifact Location** is the path where Hugo publishes to
16. Click **Review + Create** to review the details and then **Create** to start the creation of the Azure Static Web Apps and create the GitHub Action workflow for deployment.
A GitHub Action workflow will immediately start a build using Hugo and deployment to Azure. The website can be accessed via the URL shown on the _Overview_ page of the Azure Static Web Apps resource in Azure.
## Using A Custom Hugo Version
When you create a Static Web App, a [workflow file][swaconfig] is generated which contains the deployment settings for the site. You can configure a specific Hugo version in the workflow file by providing a value for `HUGO_VERSION` in the `env` section of the `Azure/static-web-apps-deploy` GitHub Action.
```yaml
jobs:
build_and_deploy_job:
if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
runs-on: ubuntu-latest
name: Build and Deploy Job
steps:
- uses: actions/checkout@v3
with:
submodules: true
- name: Build And Deploy
id: builddeploy
uses: Azure/static-web-apps-deploy@v1
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
repo_token: ${{ secrets.GITHUB_TOKEN }}
action: "upload"
app_location: "/" # App source code path
api_location: "api" # Api source code path - optional
output_location: "public" # Built app content directory - optional
env:
HUGO_VERSION: 0.100.2
```
## Use a Custom Domain
Azure Static Web Apps supports custom domains as a CNAME or APEX domain mapping. You can configure the custom domains via the Azure Portal. Refer to the [official documentation for custom domains][domains] for more information.
[Azure Static Web Apps]: https://docs.microsoft.com/azure/static-web-apps/?WT.mc_id=javascript-26008-aapowell
[GitHub Actions]: https://docs.github.com/en/actions
[Azure DevOps]: https://docs.microsoft.com/azure/static-web-apps/publish-devops?WT.mc_id=javascript-26008-aapowell
[ghsignup]: https://github.com/join
[installgit]: https://git-scm.com/downloads
[azuretrial]: https://azure.microsoft.com/free/?WT.mc_id=javascript-26008-aapowell
[azureportal]: https://portal.azure.com/
[swaconfig]: https://docs.microsoft.com/azure/static-web-apps/github-actions-workflow?WT.mc_id=javascript-26008-aapowell
[domains]: https://docs.microsoft.com/azure/static-web-apps/custom-domain?WT.mc_id=javascript-26008-aapowell
[Quick Start]: /getting-started/quick-start/

2
docs/content/en/hosting-and-deployment/hosting-on-cloudflare-pages.md
View file

@ -5,8 +5,6 @@ categories: [hosting and deployment]
menu:
docs:
parent: hosting-and-deployment
weight: 50
weight: 50
toc: true
---

6
docs/content/en/hosting-and-deployment/hosting-on-firebase.md
View file

@ -6,8 +6,6 @@ keywords: [hosting,firebase]
menu:
docs:
parent: hosting-and-deployment
weight: 20
weight: 20
toc: true
---
@ -76,7 +74,7 @@ With this you will have the app initialized manually. After that you can manage
Don't forget to update your static pages before push!
## Manual Deploy
## Manual deploy
To deploy your Hugo site, execute the `firebase deploy` command, and your site will be up in no time:
@ -84,7 +82,7 @@ To deploy your Hugo site, execute the `firebase deploy` command, and your site w
hugo && firebase deploy
```
## CI Setup (Other tools)
## CI setup (other tools)
You can generate a deploy token using

10
docs/content/en/hosting-and-deployment/hosting-on-github/index.md
View file

@ -1,13 +1,11 @@
---
title: Host on GitHub
title: Host on GitHub Pages
description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with Github Actions
categories: [hosting and deployment]
keywords: [github,git,deployment,hosting]
menu:
docs:
parent: hosting-and-deployment
weight: 30
weight: 30
toc: true
aliases: [/tutorials/github-pages-blog/]
---
@ -102,14 +100,14 @@ jobs:
build:
runs-on: ubuntu-latest
env:
HUGO_VERSION: 0.111.3
HUGO_VERSION: 0.115.1
steps:
- name: Install Hugo CLI
run: |
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
- name: Install Dart Sass Embedded
run: sudo snap install dart-sass-embedded
- name: Install Dart Sass
run: sudo snap install dart-sass
- name: Checkout
uses: actions/checkout@v3
with:

48
docs/content/en/hosting-and-deployment/hosting-on-gitlab.md
View file

@ -1,13 +1,11 @@
---
title: Host on GitLab
title: Host on GitLab Pages
description: GitLab makes it easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides native support for Hugo.
categories: [hosting and deployment]
keywords: [hosting,deployment,git,gitlab]
menu:
docs:
parent: hosting-and-deployment
weight: 40
weight: 40
toc: true
aliases: [/tutorials/hosting-on-gitlab/]
---
@ -28,24 +26,48 @@ The `baseURL` in your [site configuration](/getting-started/configuration/) must
Define your [CI/CD](https://docs.gitlab.com/ee/ci/quick_start/) jobs by creating a `.gitlab-ci.yml` file in the root of your project.
{{< code file=".gitlab-ci.yml" >}}
image: registry.gitlab.com/pages/hugo/hugo_extended:latest
variables:
DART_SASS_VERSION: 1.63.6
HUGO_VERSION: 0.115.3
NODE_VERSION: 20.x
GIT_DEPTH: 0
GIT_STRATEGY: clone
GIT_SUBMODULE_STRATEGY: recursive
TZ: America/Los_Angeles
image:
name: golang:1.20.6-bookworm
pages:
script:
- hugo
# Install brotli
- apt-get update
- apt-get install -y brotli
# Install Dart Sass
- curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- cp -r dart-sass/* /usr/local/bin
- rm -rf dart-sass*
# Install Hugo
- curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- apt-get install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
# Install Node.js
- curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION} | bash -
- apt-get install -y nodejs
# Install Node.js dependencies
- "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
# Build
- hugo --gc --minify
# Compress
- find public -type f -regex '.*\.\(css\|html\|js\|txt\|xml\)$' -exec gzip -f -k {} \;
- find public -type f -regex '.*\.\(css\|html\|js\|txt\|xml\)$' -exec brotli -f -k {} \;
artifacts:
paths:
- public
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
{{< /code >}}
{{% note %}}
See [this list](https://gitlab.com/pages/hugo/container_registry) if you wish to use a particular Hugo version to build your site.
{{% /note %}}
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
{{% /code %}}
## Push your Hugo website to GitLab

5
docs/content/en/hosting-and-deployment/hosting-on-keycdn.md
View file

@ -1,12 +1,11 @@
---
title: "Host on KeyCDN"
title: Host on KeyCDN
description: "Accelerate your Hugo site globally with a KeyCDN integration. This tutorial shows you how to set up your static site as a GitLab page behind a KeyCDN pull zone."
categories: [hosting and deployment]
keywords: [keycdn,hosting,deployment,cdn]
menu:
docs:
parent: hosting-and-deployment
weight: 40
---
[KeyCDN](https://www.keycdn.com/) provides a multitude of features to help accelerate and secure your Hugo site globally including Brotli compression, Let's Encrypt support, Origin Shield, and more.
@ -73,7 +72,7 @@ While the Secret Variable for your API Key will look similar to:
The Zone ID and API key are used to purge your zone – it’s not strictly needed but otherwise, the CDN might deliver older versions of your assets for quite a while.
## Push Your Changes to GitLab
## Push your changes to GitLab
Now it’s time to push the newly created repository to GitLab:

12
docs/content/en/hosting-and-deployment/hosting-on-netlify.md
View file

@ -6,8 +6,6 @@ keywords: [netlify,hosting,deployment]
menu:
docs:
parent: hosting-and-deployment
weight: 10
weight: 10
toc: true
---
@ -49,7 +47,7 @@ Select the repo you want to use for continuous deployment. If you have a large n
![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-2.jpg)
Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you want to publish, your [build command], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration][config], the default of which is `public`. The following steps assume you are publishing from the `master` branch.
Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you want to publish, your [build command], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration], the default of which is `public`. The following steps assume you are publishing from the `master` branch.
## Configure Hugo version in Netlify
@ -73,7 +71,7 @@ The Netlify configuration file can be a little hard to understand and get right
{{< readfile file="netlify.toml" highlight="toml" >}}
## Build and Deploy Site
## Build and deploy site
In the Netlify console, selecting "Deploy site" will immediately take you to a terminal for your build:.
@ -91,7 +89,7 @@ Now every time you push changes to your hosted git repository, Netlify will rebu
See [this blog post](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for more details about how Netlify handles Hugo versions.
## Use Hugo Themes with Netlify
## Use Hugo themes with Netlify
The `git clone` method for installing themes is not supported by Netlify. If you were to use `git clone`, it would require you to recursively remove the `.git` subdirectory from the theme folder and would therefore prevent compatibility with future versions of the theme.
@ -124,7 +122,7 @@ You can update a theme to the latest version by executing the following command
git submodule update --rebase --remote
```
## Next Steps
## Next steps
You now have a live website served over HTTPS, distributed through CDN, and configured for continuous deployment. Dig deeper into the Netlify documentation:
@ -134,7 +132,7 @@ You now have a live website served over HTTPS, distributed through CDN, and conf
[app.netlify.com]: https://app.netlify.com
[build command]: /getting-started/usage/#build-your-site
[config]: /getting-started/configuration/
[site configuration]: /getting-started/configuration/
[ghsm]: https://github.com/blog/2104-working-with-submodules
[gitsm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
[httpscustom]: https://www.netlify.com/docs/ssl/

12
docs/content/en/hosting-and-deployment/hosting-on-render.md
View file

@ -6,8 +6,6 @@ keywords: [hosting,deployment]
menu:
docs:
parent: hosting-and-deployment
weight: 10
weight: 10
toc: true
---
@ -48,23 +46,23 @@ You can set up a Hugo site on Render in two quick steps:
That's it! Your site will be live on your Render URL (which looks like `yoursite.onrender.com`) as soon as the build is done.
## Continuous Deploys
## Continuous deploys
Now that Render is connected to your repo, it will **automatically build and publish your site** any time you push to your GitHub/GitLab.
You can choose to disable auto deploys under the **Settings** section for your site and deploy it manually from the Render dashboard.
## CDN and Cache Invalidation
## CDN and cache invalidation
Render hosts your site on a global, lightning fast CDN which ensures the fastest possible download times for all your users across the globe.
Every deploy automatically and instantly invalidates the CDN cache, so your users can always access the latest content on your site.
## Custom Domains
## Custom domains
Add your own domains to your site easily using Render's [custom domains](https://render.com/docs/custom-domains) guide.
## Pull Request Previews
## Pull Request previews
With Pull Request (PR) previews, you can visualize changes introduced in a pull request instead of simply relying on code reviews.
@ -72,7 +70,7 @@ Once enabled, every PR for your site will automatically generate a new static si
Read more about [Pull Request Previews](https://render.com/docs/pull-request-previews) on Render.
## Hugo Themes
## Hugo themes
Render automatically downloads all Git submodules defined in your Git repo on every build. This way Hugo themes added as submodules work as expected.

4
docs/content/en/hosting-and-deployment/hugo-deploy.md
View file

@ -6,8 +6,8 @@ keywords: [s3,gcs,azure,hosting,deployment]
menu:
docs:
parent: hosting-and-deployment
weight: 2
weight: 2
weight: 20
weight: 20
toc: true
---

9
docs/content/en/hugo-modules/_index.md
View file

@ -1,12 +1,13 @@
---
title: Hugo Modules
linktitle: Hugo Modules Overview
linkTitle: Overview
description: How to use Hugo Modules.
menu:
docs:
identifier: hugo-modules-overview
parent: modules
weight: 01
weight: 01
weight: 10
weight: 10
categories: [hugo modules]
keywords: [themes,modules]
aliases: [/themes/overview/,/themes/]
@ -22,7 +23,7 @@ Hugo Modules are powered by Go Modules. For more information about Go Modules, s
- [https://github.com/golang/go/wiki/Modules](https://github.com/golang/go/wiki/Modules)
- [https://go.dev/blog/using-go-modules](https://go.dev/blog/using-go-modules)
This is all very much brand new and there are only a few example projects around:
Some example projects:
- [https://github.com/bep/docuapi](https://github.com/bep/docuapi) is a theme that has been ported to Hugo Modules while testing this feature. It is a good example of a non-Hugo-project mounted into Hugo’s folder structure. It even shows a JS Bundler implementation in regular Go templates.
- [https://github.com/bep/my-modular-site](https://github.com/bep/my-modular-site) is a very simple site used for testing.

22
docs/content/en/hugo-modules/configuration.md
View file

@ -1,17 +1,17 @@
---
title: Configure Modules
title: Configure Hugo modules
description: This page describes the configuration options for a module.
categories: [hugo modules]
keywords: [themes, source, organization, directories]
menu:
docs:
parent: modules
weight: 10
weight: 10
weight: 20
weight: 20
toc: true
---
## Module Config: Top level
## Module configuration: top level
{{< code-toggle file="hugo" >}}
[module]
@ -39,10 +39,10 @@ private
: Comma separated glob list matching paths that should be treated as private.
workspace
: The workspace file to use. This enables Go workspace mode. Note that this can also be set via OS env, e.g. `export HUGO_MODULE_WORKSPACE=/my/hugo.work` This only works with Go 1.18+. In Hugo `v0.109.0` we changed the default to `off` and we now resolve any relative work filenames relative to the working directory.
: The workspace file to use. This enables Go workspace mode. Note that this can also be set via OS env, e.g. `export HUGO_MODULE_WORKSPACE=/my/hugo.work` This only works with Go 1.18+. In Hugo `v0.109.0` we changed the default to `off` and we now resolve any relative work file names relative to the working directory.
replacements
: A comma-separated list of mappings from module paths to directories, e.g. `github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path`. This is mostly useful for temporary local development of a module, in which case you might want to save it as an environment variable, e.g: `env HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."`. Relative paths are relative to [themesDir](https://gohugo.io/getting-started/configuration/#all-configuration-settings). Absolute paths are allowed.
: A comma-separated list of mappings from module paths to directories, e.g. `github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path`. This is mostly useful for temporary local development of a module, in which case you might want to save it as an environment variable, e.g: `env HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."`. Relative paths are relative to [themesDir](/getting-started/configuration/#all-configuration-settings). Absolute paths are allowed.
Note that the above terms maps directly to their counterparts in Go Modules. Some of these setting may be natural to set as OS environment variables. To set the proxy server to use, as an example:
@ -52,7 +52,7 @@ env HUGO_MODULE_PROXY=https://proxy.example.org hugo
{{< gomodules-info >}}
## Module Config: hugoVersion
## Module configuration: hugoVersion
If your module requires a particular version of Hugo to work, you can indicate that in the `module` section and the user will be warned if using a too old/new version.
@ -76,7 +76,7 @@ max
extended
: Whether the extended version of Hugo is required.
## Module Config: imports
## Module configuration: imports
{{< code-toggle file="hugo" >}}
[module]
@ -109,10 +109,10 @@ noVendor
{{< gomodules-info >}}
## Module Config: mounts
## Module configuration: mounts
{{% note %}}
When the `mounts` config was introduced in Hugo 0.56.0, we were careful to preserve the existing `contentDir`, `staticDir`, and similar configuration to make sure all existing sites just continued to work. But you should not have both: if you add a `mounts` section you should remove the old `contentDir`, `staticDir`, etc. settings.
When the `mounts` configuration was introduced in Hugo 0.56.0, we were careful to preserve the existing `contentDir`, `staticDir`, and similar configuration to make sure all existing sites just continued to work. But you should not have both: if you add a `mounts` section you should remove the old `contentDir`, `staticDir`, etc. settings.
{{% /note %}}
{{% note %}}
@ -157,7 +157,7 @@ lang
includeFiles (string or slice)
: One or more [glob](https://github.com/gobwas/glob) patterns matching files or directories to include. If `excludeFiles` is not set, the files matching `includeFiles` will be the files mounted.
The glob patterns are matched to the filenames starting from the `source` root, they should have Unix styled slashes even on Windows, `/` matches the mount root and `**` can be used as a super-asterisk to match recursively down all directories, e.g `/posts/**.jpg`.
The glob patterns are matched to the file names starting from the `source` root, they should have Unix styled slashes even on Windows, `/` matches the mount root and `**` can be used as a super-asterisk to match recursively down all directories, e.g `/posts/**.jpg`.
The search is case-insensitive.

Some files were not shown because too many files have changed in this diff Show more