summaryrefslogtreecommitdiffstats
path: root/docs/content/en/content-management
diff options
context:
space:
mode:
authorBjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>2023-12-04 15:24:01 +0100
committerBjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>2023-12-04 15:24:01 +0100
commitd19ed4d4e69f51873135f05a51831d25ecc2071e (patch)
tree74dfd9af2b0f4a6c0933266c50ceaa569d388c71 /docs/content/en/content-management
parent9f978d387f8b7cb6bc03fe6b4dd52bb16862a784 (diff)
parent35dec7c96f7ee3eb17dd444f7067f0c776fb56ae (diff)
downloadhugo-d19ed4d4e69f51873135f05a51831d25ecc2071e.tar.gz
hugo-d19ed4d4e69f51873135f05a51831d25ecc2071e.zip
Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'
Diffstat (limited to 'docs/content/en/content-management')
-rw-r--r--docs/content/en/content-management/_common/_index.md13
-rw-r--r--docs/content/en/content-management/_common/page-kinds.md17
-rw-r--r--docs/content/en/content-management/_index.md4
-rw-r--r--docs/content/en/content-management/archetypes.md31
-rw-r--r--docs/content/en/content-management/build-options.md337
-rw-r--r--docs/content/en/content-management/comments.md4
-rw-r--r--docs/content/en/content-management/cross-references.md8
-rw-r--r--docs/content/en/content-management/diagrams.md9
-rw-r--r--docs/content/en/content-management/formats.md17
-rw-r--r--docs/content/en/content-management/front-matter.md23
-rw-r--r--docs/content/en/content-management/image-processing/index.md59
-rw-r--r--docs/content/en/content-management/menus.md17
-rw-r--r--docs/content/en/content-management/multilingual.md89
-rw-r--r--docs/content/en/content-management/organization/index.md35
-rw-r--r--docs/content/en/content-management/page-bundles.md38
-rw-r--r--docs/content/en/content-management/page-resources.md8
-rw-r--r--docs/content/en/content-management/related.md58
-rw-r--r--docs/content/en/content-management/sections.md70
-rw-r--r--docs/content/en/content-management/shortcodes.md38
-rw-r--r--docs/content/en/content-management/static-files.md6
-rw-r--r--docs/content/en/content-management/summaries.md28
-rw-r--r--docs/content/en/content-management/syntax-highlighting.md9
-rw-r--r--docs/content/en/content-management/taxonomies.md33
-rw-r--r--docs/content/en/content-management/toc.md11
-rw-r--r--docs/content/en/content-management/types.md4
-rw-r--r--docs/content/en/content-management/urls.md40
26 files changed, 615 insertions, 391 deletions
diff --git a/docs/content/en/content-management/_common/_index.md b/docs/content/en/content-management/_common/_index.md
new file mode 100644
index 000000000..47d5812fb
--- /dev/null
+++ b/docs/content/en/content-management/_common/_index.md
@@ -0,0 +1,13 @@
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
+Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
diff --git a/docs/content/en/content-management/_common/page-kinds.md b/docs/content/en/content-management/_common/page-kinds.md
new file mode 100644
index 000000000..07a53e8e6
--- /dev/null
+++ b/docs/content/en/content-management/_common/page-kinds.md
@@ -0,0 +1,17 @@
+---
+# Do not remove front matter.
+---
+
+| Kind | Description | Example |
+|----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------|
+| `home` | The landing page for the home page | `/index.html` |
+| `page` | The landing page for a given page | `my-post` page (`/posts/my-post/index.html`) |
+| `section` | The landing page of a given section | `posts` section (`/posts/index.html`) |
+| `taxonomy` | The landing page for a taxonomy | `tags` taxonomy (`/tags/index.html`) |
+| `term` | The landing page for one taxonomy's term | term `awesome` in `tags` taxonomy (`/tags/awesome/index.html`) |
+
+Four other page kinds unrelated to content are `robotsTXT`, `RSS`, `sitemap`, and `404`. Although primarily for internal use, you can specify the name when disabling one or more page kinds on your site. For example:
+
+{{< code-toggle file=hugo >}}
+disableKinds = ['robotsTXT','404']
+{{< /code-toggle >}}
diff --git a/docs/content/en/content-management/_index.md b/docs/content/en/content-management/_index.md
index 35f85a641..66af24681 100644
--- a/docs/content/en/content-management/_index.md
+++ b/docs/content/en/content-management/_index.md
@@ -2,13 +2,13 @@
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.
+categories: []
+keywords: []
menu:
docs:
identifier: content-management-overview
parent: content-management
weight: 10
-keywords: [source, organization]
-categories: [content management]
weight: 10
aliases: [/content/,/content/organization]
---
diff --git a/docs/content/en/content-management/archetypes.md b/docs/content/en/content-management/archetypes.md
index fe460f91f..94f038848 100644
--- a/docs/content/en/content-management/archetypes.md
+++ b/docs/content/en/content-management/archetypes.md
@@ -1,15 +1,15 @@
---
title: Archetypes
description: An archetype is a template for new content.
-keywords: [archetypes,generators,metadata,front matter]
categories: [content management]
+keywords: [archetypes,generators,metadata,front matter]
menu:
docs:
parent: content-management
weight: 140
quicklinks:
-toc: true
weight: 140
+toc: true
aliases: [/content/archetypes/]
---
@@ -19,7 +19,7 @@ A content file consists of [front matter] and markup. The markup is typically ma
The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype:
-{{< code-toggle file="archetypes/default.md" copy=false fm=true >}}
+{{< code-toggle file=archetypes/default.md fm=true >}}
title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
date = '{{ .Date }}'
draft = true
@@ -27,13 +27,13 @@ draft = true
When you create new content, Hugo evaluates the [template actions] within the archetype. For example:
-```text
+```sh
hugo new content posts/my-first-post.md
```
With the default archetype shown above, Hugo creates this content file:
-{{< code-toggle file="content/posts/my-first-post.md" copy=false fm=true >}}
+{{< code-toggle file=content/posts/my-first-post.md fm=true >}}
title = 'My First Post'
date = '2023-08-24T11:49:46-07:00'
draft = true
@@ -53,7 +53,7 @@ Hugo looks for archetypes in the `archetypes` directory in the root of your proj
For example, with this command:
-```text
+```sh
hugo new content posts/my-first-post.md
```
@@ -75,7 +75,7 @@ Archetypes receive the following objects and values in [context]:
- `.Date`
- `.Type`
- `.Site` (see [details](/variables/site/))
-- `.File` (see [details](/variables/files/))
+- `.File` (see [details](/variables/file/))
As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter.
@@ -85,8 +85,7 @@ Although typically used as a front matter template, you can also use an archetyp
For example, in a documentation site you might have a section (content type) for functions. Every page within this section should follow the same format: a brief description, the function signature, examples, and notes. We can pre-populate the page to remind content authors of the standard format.
-
-{{< code file="archetypes/functions.md" copy=false >}}
+{{< code file=archetypes/functions.md >}}
---
date: '{{ .Date }}'
draft: true
@@ -125,17 +124,17 @@ Create an archetype for galleries:
```text
archetypes/
├── galleries/
-│   ├── images/
-│   │   └── .gitkeep
-│   └── index.md <-- same format as default.md
+│ ├── images/
+│ │ └── .gitkeep
+│ └── index.md <-- same format as default.md
└── default.md
```
Subdirectories within an archetype must contain at least one file. Without a file, Hugo will not create the subdirectory when you create new content. The name and size of the file are irrelevant. The example above includes a&nbsp;`.gitkeep` file, an empty file commonly used to preserve otherwise empty directories in a Git repository.
-
To create a new gallery:
-```text
+
+```sh
hugo new galleries/bryce-canyon
```
@@ -166,13 +165,13 @@ archetypes/
To create an article using the articles archetype:
-```text
+```sh
hugo new content articles/something.md
```
To create an article using the tutorials archetype:
-```text
+```sh
hugo new content --kind tutorials articles/something.md
```
diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md
index 378a31144..bc9d7ff49 100644
--- a/docs/content/en/content-management/build-options.md
+++ b/docs/content/en/content-management/build-options.md
@@ -1,102 +1,321 @@
---
title: Build options
description: Build options help define how Hugo must treat a given page when building the site.
+categories: [content management,fundamentals]
keywords: [build,content,front matter, page resources]
-categories: [fundamentals,content management]
menu:
docs:
parent: content-management
weight: 70
-toc: true
weight: 70
+toc: true
aliases: [/content/build-options/]
---
-They are stored in a reserved front matter object named `_build` with the following defaults:
+Build options are stored in a reserved front matter object named `_build` with these defaults:
-{{< code-toggle >}}
-_build:
- render: always
- list: always
- publishResources: true
+{{< code-toggle file=content/example/index.md fm=true >}}
+[_build]
+list = 'always'
+publishResources = true
+render = 'always'
{{< /code-toggle >}}
-#### render
-If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink.
+list
+: When to include the page within page collections. Specify one of:
+
+ - `always`
+ : Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value.
-Valid values are:
+ - `local`
+ : Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections.
- `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`.
+ : Do not include the page in _any_ page collection.
-#### list
+publishResources
+: Applicable to [page bundles], determines whether to publish the associated [page resources]. Specify one of:
-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`, `.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.
+ - `true`
+ : Always publish resources. This is the default value.
-#### publishResources
+ - `false`
+ : Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template.
-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.
+render
+: When to render the page. Specify one of:
+
+ - `always`
+ : Always render the page to disk. This is the default value.
+
+ - `link`
+ : Do not render the page to disk, but include it in all page collections.
+
+ - `never`
+ : Never render the page to disk, and exclude it from all page collections.
+
+[page bundles]: content-management/page-bundles
+[page resources]: /content-management/page-resources
+[`Permalink`]: /methods/resource/permalink
+[`RelPermalink`]: /methods/resource/relpermalink
+[`Publish`]: /methods/resource/publish
{{% note %}}
-Any page, regardless of their build options, will always be available using the [`.GetPage`](/functions/getpage) methods.
+Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method.
+
+[`.Page.GetPage`]: /methods/page/getpage
+[`.Site.GetPage`]: /methods/site/getpage
{{% /note %}}
-### Illustrative use cases
+## Example -- headless page
+
+Create a unpublished page whose content and resources can be included in other pages.
+
+```text
+content/
+├── headless/
+│ ├── a.jpg
+│ ├── b.jpg
+│ └── index.md <-- leaf bundle
+└── _index.md <-- home page
+```
+
+Set the build options in front matter:
+
+{{< code-toggle file=content/headless/index.md fm=true >}}
+title = 'Headless page'
+[_build]
+ list = 'never'
+ publishResources = false
+ render = 'never'
+{{< /code-toggle >}}
+
+To include the content and images on the home page:
+
+{{< code file=layouts/_default/home.html >}}
+{{ with .Site.GetPage "/headless" }}
+ {{ .Content }}
+ {{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+{{< /code >}}
+
+The published site will have this structure:
+
+```text
+public/
+├── headless/
+│ ├── a.jpg
+│ └── b.jpg
+└── index.html
+```
+
+In the example above, note that:
+
+1. Hugo did not publish an HTML file for the page.
+2. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
+
+## Example -- headless section
-#### Not publishing a page
+Create a unpublished section whose content and resources can be included in other pages.
-Project needs a "Who We Are" content file for front matter and body to be used by the homepage but nowhere else.
+[branch bundle]: /content-management/page-bundles
-{{< code-toggle file="content/who-we-are.md" fm=true copy=false >}}
-title: Who we are
-_build:
- list: false
- render: false
+```text
+content/
+├── headless/
+│ ├── note-1/
+│ │ ├── a.jpg
+│ │ ├── b.jpg
+│ │ └── index.md <-- leaf bundle
+│ ├── note-2/
+│ │ ├── c.jpg
+│ │ ├── d.jpg
+│ │ └── index.md <-- leaf bundle
+│ └── _index.md <-- branch bundle
+└── _index.md <-- home page
+```
+
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
+
+{{< code-toggle file=content/headless/_index.md fm=true >}}
+title = 'Headless section'
+[[cascade]]
+[cascade._build]
+ list = 'local'
+ publishResources = false
+ render = 'never'
{{< /code-toggle >}}
-{{< code file="layouts/index.html" copy=false >}}
-<section id="who-we-are">
- {{ with site.GetPage "who-we-are" }}
+In the front matter above, note that we have set `list` to `local` to include the descendant pages in local page collections.
+
+To include the content and images on the home page:
+
+{{< code file=layouts/_default/home.html >}}
+{{ with .Site.GetPage "/headless" }}
+ {{ range .Pages }}
{{ .Content }}
+ {{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
{{ end }}
-</section>
+{{ end }}
{{< /code >}}
-#### Listing pages without publishing them
+The published site will have this structure:
+
+```text
+public/
+├── headless/
+│ ├── note-1/
+│ │ ├── a.jpg
+│ │ └── b.jpg
+│ └── note-2/
+│ ├── c.jpg
+│ └── d.jpg
+└── index.html
+```
+
+In the example above, note that:
+
+1. Hugo did not publish an HTML file for the page.
+2. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
+
+## Example -- list without publishing
-Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them.
+Publish a section page without publishing the descendant pages. For example, to create a glossary:
-To avoid setting the build options on every testimonials, one can use [`cascade`](/content-management/front-matter#front-matter-cascade) on the testimonial section's content file.
+```text
+content/
+├── glossary/
+│ ├── _index.md
+│ ├── bar.md
+│ ├── baz.md
+│ └── foo.md
+└── _index.md
+```
-{{< code-toggle >}}
-title: Testimonials
-_build:
- render: true
-cascade:
- _build:
- render: false
- list: true # default
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
+
+{{< code-toggle file=content/glossary/_index.md fm=true >}}
+title = 'Glossary'
+[_build]
+render = 'always'
+[[cascade]]
+[cascade._build]
+ list = 'local'
+ publishResources = false
+ render = 'never'
{{< /code-toggle >}}
-{{< code file="layouts/_defaults/testimonials.html" copy=false >}}
-<section id="testimonials">
- {{ range first 5 .Pages }}
- <blockquote cite="{{ .Params.cite }}">
- {{ .Content }}
- </blockquote>
+To render the glossary:
+
+{{< code file=layouts/glossary/list.html >}}
+<dl>
+ {{ range .Pages }}
+ <dt>{{ .Title }}</dt>
+ <dd>{{ .Content }}</dd>
{{ end }}
-</section>
+</dl>
{{< /code >}}
+
+The published site will have this structure:
+
+```text
+public/
+├── glossary/
+│ └── index.html
+└── index.html
+```
+
+## Example -- publish without listing
+
+Publish a section's descendant pages without publishing the section page itself.
+
+```text
+content/
+├── books/
+│ ├── _index.md
+│ ├── book-1.md
+│ └── book-2.md
+└── _index.md
+```
+
+Set the build options in front matter:
+
+{{< code-toggle file=content/books/_index.md >}}
+title = 'Books'
+[_build]
+render = 'never'
+list = 'never'
+{{< /code-toggle >}}
+
+The published site will have this structure:
+
+```html
+public/
+├── books/
+│ ├── book-1/
+│ │ └── index.html
+│ └── book-2/
+│ └── index.html
+└── index.html
+```
+
+## Example -- conditionally hide section
+
+Consider this example. A documentation site has a team of contributors with access to 20 custom shortcodes. Each shortcode takes several arguments, and requires documentation for the contributors to reference when using them.
+
+Instead of external documentation for the shortcodes, include an "internal" section that is hidden when building the production site.
+
+```text
+content/
+├── internal/
+│ ├── shortcodes/
+│ │ ├── _index.md
+│ │ ├── shortcode-1.md
+│ │ └── shortcode-2.md
+│ └── _index.md
+├── reference/
+│ ├── _index.md
+│ ├── reference-1.md
+│ └── reference-2.md
+├── tutorials/
+│ ├── _index.md
+│ ├── tutorial-1.md
+│ └── tutorial-2.md
+└── _index.md
+```
+
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages, and use the `target` keyword to target the production environment.
+
+{{< code-toggle file=content/internal/_index.md >}}
+title = 'Internal'
+[[cascade]]
+[cascade._build]
+render = 'never'
+list = 'never'
+[cascade._target]
+environment = 'production'
+{{< /code-toggle >}}
+
+The production site will have this structure:
+
+```html
+public/
+├── reference/
+│ ├── reference-1/
+│ │ └── index.html
+│ ├── reference-2/
+│ │ └── index.html
+│ └── index.html
+├── tutorials/
+│ ├── tutorial-1/
+│ │ └── index.html
+│ ├── tutorial-2/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md
index 39663013b..9985dd1e6 100644
--- a/docs/content/en/content-management/comments.md
+++ b/docs/content/en/content-management/comments.md
@@ -1,14 +1,14 @@
---
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.
+categories: [content management]
keywords: [sections,content,organization]
-categories: [project organization]
menu:
docs:
parent: content-management
weight: 220
-toc: true
weight: 220
+toc: true
aliases: [/extras/comments/]
---
diff --git a/docs/content/en/content-management/cross-references.md b/docs/content/en/content-management/cross-references.md
index c989cc560..500e388a4 100644
--- a/docs/content/en/content-management/cross-references.md
+++ b/docs/content/en/content-management/cross-references.md
@@ -2,13 +2,13 @@
title: Links and cross references
description: Shortcodes for creating links to documents.
categories: [content management]
-keywords: ["cross references","references", "anchors", "urls"]
+keywords: [cross references,references,anchors,urls]
menu:
docs:
parent: content-management
weight: 170
-toc: true
weight: 170
+toc: true
aliases: [/extras/crossreferences/]
---
@@ -35,7 +35,6 @@ The `ref` and `relref` shortcodes require a single parameter: the path to a cont
The pages can be referenced as follows:
-
```text
{{</* ref "document2" */>}} // <- From pages/document1.md, relative path
{{</* ref "document2#anchor" */>}}
@@ -138,7 +137,7 @@ produces this HTML:
## Ref and RelRef Configuration
-The behavior can, since Hugo 0.45, be configured in `hugo.toml`:
+The behavior can be configured in `hugo.toml`:
refLinksErrorLevel ("ERROR")
: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
@@ -146,7 +145,6 @@ refLinksErrorLevel ("ERROR")
refLinksNotFoundURL
: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
-
[lists]: /templates/lists/
[output formats]: /templates/output-formats/
[shortcode]: /content-management/shortcodes/
diff --git a/docs/content/en/content-management/diagrams.md b/docs/content/en/content-management/diagrams.md
index c0b2349b0..17407098f 100644
--- a/docs/content/en/content-management/diagrams.md
+++ b/docs/content/en/content-management/diagrams.md
@@ -7,12 +7,12 @@ menu:
docs:
parent: content-management
weight: 50
-toc: true
weight: 50
+toc: true
---
-{{< new-in "0.93.0" >}}
+{{< 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:
@@ -165,7 +165,6 @@ Created from <https://arthursonzogni.com/Diagon/#Tree>
└─Fedora
```
-
### Sequence diagram
<https://arthursonzogni.com/Diagon/#Sequence>
@@ -186,7 +185,6 @@ Created from <https://arthursonzogni.com/Diagon/#Tree>
```
-
### Flowchart
<https://arthursonzogni.com/Diagon/#Flowchart>
@@ -232,7 +230,6 @@ Created from <https://arthursonzogni.com/Diagon/#Tree>
```
-
### Table
<https://arthursonzogni.com/Diagon/#Table>
diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md
index ccc45b943..76c8102b5 100644
--- a/docs/content/en/content-management/formats.md
+++ b/docs/content/en/content-management/formats.md
@@ -7,8 +7,8 @@ menu:
docs:
parent: content-management
weight: 40
-toc: true
weight: 40
+toc: true
aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/]
---
@@ -24,12 +24,12 @@ The current list of content formats in Hugo:
| Name | Markup identifiers | Comment |
| ------------- | ------------- |-------------|
-| Goldmark | md, markdown, goldmark |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).|
-|Emacs Org-Mode|org|See [go-org](https://github.com/niklasfasching/go-org).|
-|AsciiDoc|asciidocext, adoc, ad|Needs [Asciidoctor][ascii] installed.|
-|RST|rst|Needs [RST](https://docutils.sourceforge.io/rst.html) installed.|
-|Pandoc|pandoc, pdc|Needs [Pandoc](https://www.pandoc.org/) installed.|
-|HTML|html, htm|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.|
+| Goldmark | `markdown`, `goldmark` |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).|
+|Emacs Org-Mode|`org`|See [go-org](https://github.com/niklasfasching/go-org).|
+|AsciiDoc|`asciidocext`, `adoc`, `ad`|Needs [Asciidoctor][ascii] installed.|
+|RST|`rst`|Needs [RST](https://docutils.sourceforge.io/rst.html) installed.|
+|Pandoc|`pandoc`, `pdc`|Needs [Pandoc](https://www.pandoc.org/) installed.|
+|HTML|`html`, `htm`|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.|
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/).
@@ -59,7 +59,7 @@ optional extensions like `asciidoctor-diagram` or `asciidoctor-html5s` are insta
External `asciidoctor` command requires Hugo rendering to _disk_ to a specific destination directory. It is required to run Hugo with the command option `--destination`.
{{% /note %}}
-Some Asciidoctor parameters can be customized in Hugo. See [details].
+Some Asciidoctor parameters can be customized in Hugo. See&nbsp;[details].
[details]: /getting-started/configuration-markup/#asciidoc
@@ -75,7 +75,6 @@ Markdown syntax is simple enough to learn in a single sitting. The following are
[ascii]: https://asciidoctor.org/
[config]: /getting-started/configuration/
[developer tools]: /tools/
-[emojis]: https://www.webpagefx.com/tools/emoji-cheat-sheet/
[fireball]: https://daringfireball.net/projects/markdown/
[gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax
[helperssource]: https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65
diff --git a/docs/content/en/content-management/front-matter.md b/docs/content/en/content-management/front-matter.md
index 10317e805..dba67ba10 100644
--- a/docs/content/en/content-management/front-matter.md
+++ b/docs/content/en/content-management/front-matter.md
@@ -2,13 +2,13 @@
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"]
+keywords: [front matter,yaml,toml,json,metadata,archetypes]
menu:
docs:
parent: content-management
weight: 60
-toc: true
weight: 60
+toc: true
aliases: [/content/front-matter/]
---
@@ -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`.
markup
: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
@@ -131,7 +131,7 @@ videos
weight
: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight.
-\<taxonomies\>
+taxonomies
: Field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.*
{{% note %}}
@@ -144,7 +144,7 @@ You can add fields to your front matter arbitrarily to meet your needs. These us
The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables] section provides more information on using Hugo's page- and site-level variables in your templates.
-{{< code-toggle copy=false >}}
+{{< code-toggle >}}
include_toc: true
show_comments: false
{{</ code-toggle >}}
@@ -157,7 +157,7 @@ Any node or section can pass down to descendants a set of front matter values as
The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
-{{< code-toggle copy=false >}}
+{{< code-toggle >}}
title ="Blog"
[[cascade]]
background = "yosemite.jpg"
@@ -187,11 +187,17 @@ environment
Any of the above can be omitted.
+{{% note %}}
+When making a site that supports multiple languages, defining a `[[cascade]]` is recommended to be done in [Site Config](../../getting-started/configuration/#cascade) to prevent duplication.
+
+If you instea define a `[[cascade]]` in front matter for multiple languages, an `content/XX/foo/_index.md` file needs to be made on a per-language basis, with `XX` the glob pattern matching the Page's language. In this case, the **lang** keyword is ignored.
+{{% /note %}}
+
### Example
In `content/blog/_index.md`
-{{< code-toggle copy=false >}}
+{{< code-toggle >}}
title: Blog
cascade:
banner: images/typewriter.jpg
@@ -219,13 +225,12 @@ It's possible to set some options for Markdown rendering in a content's front ma
[variables]: /variables/
[aliases]: /content-management/urls/#aliases
[archetype]: /content-management/archetypes/
-[bylinktitle]: /templates/lists/#by-link-title
[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
-[lists]: /templates/lists/#order-content
+[lists]: /templates/lists/#sort-content
[lookup]: /templates/lookup-order/
[ordering]: /templates/lists/
[outputs]: /templates/output-formats/
diff --git a/docs/content/en/content-management/image-processing/index.md b/docs/content/en/content-management/image-processing/index.md
index 9cce9070a..511365700 100644
--- a/docs/content/en/content-management/image-processing/index.md
+++ b/docs/content/en/content-management/image-processing/index.md
@@ -1,8 +1,8 @@
---
title: Image processing
description: Resize, crop, rotate, filter, and convert images.
-categories: [fundamentals,content management]
-keywords: [resources, images]
+categories: [content management,fundamentals]
+keywords: [resources,images]
menu:
docs:
parent: content-management
@@ -10,6 +10,7 @@ menu:
toc: true
weight: 90
---
+
## Image resources
To process an image you must access the file as a page resource, global resource, or remote resource.
@@ -50,7 +51,7 @@ To access an image as a global resource:
### Remote resource
-A remote resource is a file on a remote server, accessible via http or https. To access an image as a remote resource:
+A remote resource is a file on a remote server, accessible via HTTP or HTTPS. To access an image as a remote resource:
```go-html-template
{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}
@@ -104,15 +105,15 @@ Example 4: Skips rendering if there's problem accessing a remote resource.
The `image` resource implements the [`Process`], [`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 %}}
### Process
-{{< new-in "0.119.0" >}}
+{{< new-in 0.119.0 >}}
{{% note %}}
-The `Process` method is also available as a filter, which is more effective if need to apply multiple filters to an image. See [Process filter](/functions/images/#process).
+The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process).
{{% /note %}}
Process processes the image with the given specification. The specification can contain an optional action, one of `resize`, `crop`, `fit` or `fill`. This means that you can use this method instead of [`Resize`], [`Fit`], [`Fill`], or [`Crop`].
@@ -139,10 +140,9 @@ Some more examples:
{{ $image := $image.Process "fill 600x400" }}
```
-
### Resize
-Resize an image to the specified width and/or height.
+Resize an image to the given width and/or height.
If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio.
@@ -205,7 +205,7 @@ Sometimes it can be useful to create the filter chain once and then reuse it.
### Colors
-{{< new-in "0.104.0" >}}
+{{< new-in 0.104.0 >}}
`.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method.
@@ -215,7 +215,6 @@ 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
Provides an [EXIF] object containing image metadata.
@@ -266,7 +265,7 @@ You may also access EXIF fields individually, using the [`lang.FormatNumber`] fu
## 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.
+The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-delimited, case-insensitive list of options. The order of the options within the list is irrelevant.
### Dimensions
@@ -347,9 +346,9 @@ The default value is 75. You may override the default value in the [site configu
### Hint
-<!-- Specifies a libwebp preset, not a libwebp image hint. -->
+Applicable to WebP images, this option corresponds to a set of predefined encoding parameters, and is equivalent to the `-preset` flag for the [`cwebp`] encoder.
-Applicable to WebP images, this option corresponds to a set of predefined encoding parameters.
+[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
Value|Example
:--|:--
@@ -369,7 +368,7 @@ The default value is `photo`. You may override the default value in the [site co
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.
-Use either a 3-digit or a 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`).
+Use either a 3-digit or 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`).
The default value is `#ffffff` (white). You may override the default value in the [site configuration].
@@ -402,28 +401,26 @@ See [github.com/disintegration/imaging] for the complete list of resampling filt
_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)_
-{{< imgproc sunset Resize "300x" />}}
+{{< imgproc "sunset.jpg" "resize 300x" />}}
-{{< imgproc sunset Fill "90x120 left" />}}
+{{< imgproc "sunset.jpg" "fill 90x120 left" />}}
-{{< imgproc sunset Fill "90x120 right" />}}
+{{< imgproc "sunset.jpg" "fill 90x120 right" />}}
-{{< imgproc sunset Fit "90x90" />}}
+{{< imgproc "sunset.jpg" "fit 90x90" />}}
-{{< imgproc sunset Crop "250x250 center" />}}
+{{< imgproc "sunset.jpg" "crop 250x250 center" />}}
-{{< imgproc sunset Resize "300x q10" />}}
+{{< imgproc "sunset.jpg" "resize 300x q10" />}}
This is the shortcode used to generate the examples above:
-{{< code file="layouts/shortcodes/imgproc.html" >}}
-{{< readfile file="layouts/shortcodes/imgproc.html" >}}
-{{< /code >}}
+{{< readfile file=layouts/shortcodes/imgproc.html highlight=go-html-template >}}
Call the shortcode from your Markdown like this:
```go-html-template
-{{</* imgproc sunset Resize "300x" /*/>}}
+{{</* imgproc "sunset.jpg" "resize 300x" /*/>}}
```
{{% note %}}
@@ -436,7 +433,7 @@ Note the self-closing shortcode syntax above. You may call the `imgproc` shortco
Define an `imaging` section in your site configuration to set the default [image processing options](#image-processing-options).
-{{< code-toggle config="imaging" />}}
+{{< code-toggle config=imaging />}}
anchor
: See image processing options: [anchor](#anchor).
@@ -457,7 +454,7 @@ resampleFilter
Define an `imaging.exif` section in your site configuration to control the availability of EXIF data.
-{{< code-toggle file="hugo" copy=true >}}
+{{< code-toggle file=hugo >}}
[imaging.exif]
includeFields = ""
excludeFields = ""
@@ -478,7 +475,9 @@ 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;`".*"`.
{{% 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`.
+To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
+
+To control tag availability, change the `excludeFields` or `includeFields` settings as described above.
{{% /note %}}
## Smart cropping of images
@@ -487,9 +486,9 @@ By default, Hugo uses the [Smartcrop] library when cropping images with the `Cro
Examples using the sunset image from above:
-{{< imgproc sunset Fill "200x200 smart" />}}
+{{< imgproc "sunset.jpg" "fill 200x200 smart" />}}
-{{< imgproc sunset Crop "200x200 smart" />}}
+{{< imgproc "sunset.jpg" "crop 200x200 smart" />}}
## Image processing performance consideration
@@ -497,7 +496,7 @@ Hugo caches processed images in the `resources` directory. If you include this d
If you change image processing methods or options, or if you rename or remove images, the `resources` directory will contain unused images. To remove the unused images, perform garbage collection with:
-```bash
+```sh
hugo --gc
```
diff --git a/docs/content/en/content-management/menus.md b/docs/content/en/content-management/menus.md
index 07bf41669..e2a72f124 100644
--- a/docs/content/en/content-management/menus.md
+++ b/docs/content/en/content-management/menus.md
@@ -7,8 +7,8 @@ menu:
docs:
parent: content-management
weight: 190
-toc: true
weight: 190
+toc: true
aliases: [/extras/menus/]
---
@@ -36,7 +36,7 @@ Although you can use these methods in combination when defining a menu, the menu
To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration.
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
sectionPagesMenu = "main"
{{< /code-toggle >}}
@@ -46,7 +46,7 @@ This creates a menu structure that you can access with `site.Menus.main` in your
To add a page to the "main" menu:
-{{< code-toggle file="content/about.md" copy=false fm=true >}}
+{{< code-toggle file=content/about.md fm=true >}}
title = 'About'
menu = 'main'
{{< /code-toggle >}}
@@ -55,7 +55,7 @@ Access the entry with `site.Menus.main` in your templates. See [menu templates]
To add a page to the "main" and "footer" menus:
-{{< code-toggle file="content/contact.md" copy=false fm=true >}}
+{{< code-toggle file=content/contact.md fm=true >}}
title = 'Contact'
menu = ['main','footer']
{{< /code-toggle >}}
@@ -94,7 +94,7 @@ weight
This front matter menu entry demonstrates some of the available properties:
-{{< code-toggle file="content/products/software.md" copy=false fm=true >}}
+{{< code-toggle file=content/products/software.md fm=true >}}
title = 'Software'
[menu.main]
parent = 'Products'
@@ -106,12 +106,11 @@ class = 'center'
Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
-
## Define in site configuration
To define entries for the "main" menu:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[[menu.main]]
name = 'Home'
pageRef = '/'
@@ -132,7 +131,7 @@ This creates a menu structure that you can access with `site.Menus.main` in your
To define entries for the "footer" menu:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[[menu.footer]]
name = 'Terms'
pageRef = '/terms'
@@ -177,7 +176,7 @@ url
This nested menu demonstrates some of the available properties:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[[menu.main]]
name = 'Products'
pageRef = '/products'
diff --git a/docs/content/en/content-management/multilingual.md b/docs/content/en/content-management/multilingual.md
index 6e787c526..07eecbaaf 100644
--- a/docs/content/en/content-management/multilingual.md
+++ b/docs/content/en/content-management/multilingual.md
@@ -3,13 +3,13 @@ title: Multilingual mode
linkTitle: Multilingual
description: Hugo supports the creation of websites with multiple languages side by side.
categories: [content management]
-keywords: [multilingual,i18n, internationalization]
+keywords: [multilingual,i18n,internationalization]
menu:
docs:
parent: content-management
weight: 230
-toc: true
weight: 230
+toc: true
aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/]
---
@@ -21,11 +21,11 @@ Also See [Hugo Multilingual Part 1: Content translation].
This is the default language configuration:
-{{< code-toggle config="languages" />}}
+{{< code-toggle config=languages />}}
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" >}}
+{{< code-toggle file=hugo >}}
defaultContentLanguage = 'de'
defaultContentLanguageInSubdir = true
@@ -54,39 +54,39 @@ weight = 2
subtitle = 'Reference, Tutorials, and Explanations'
{{< /code-toggle >}}
-`defaultContentLanguage`
+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:
- `en`
- `en-gb`
- `pt-br`
-`defaultContentLanguageInSubdir`
+defaultContentLanguageInSubdir
: (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`.
-`contentDir`
+contentDir
: (`string`) The content directory for this language. Omit if [translating by file name].
-`disabled`
+disabled
: (`bool`) If `true`, Hugo will not render content for this language. Default is `false`.
-`languageCode`
+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:
- `en`
- `en-GB`
- `pt-BR`
-`languageDirection`
+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`
+languageName
: (`string`) The language name, typically used when rendering a language switcher.
-`title`
+title
: (`string`) The language title. When set, this overrides the site title for this language.
-`weight`
+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
@@ -97,14 +97,14 @@ subtitle = 'Reference, Tutorials, and Explanations'
### Changes in Hugo 0.112.0
-{{< new-in "0.112.0" >}}
+{{< new-in 0.112.0 >}}
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 parameters to the top level language configuration is deprecated. Define custom parameters within `languages.xx.params`. See `color` in the example below.
-{{< code-toggle file=hugo copy=false >}}
+{{< code-toggle file=hugo >}}
title = "My blog"
languageCode = "en-us"
@@ -129,20 +129,20 @@ In the example above, all settings except `color` below `params` map to predefin
To disable a language within a `languages` object in your site configuration:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[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 >}}
+{{< code-toggle file=hugo >}}
disableLanguages = ["es", "fr"]
{{< /code-toggle >}}
To disable one or more languages using an environment variable:
-```bash
+```sh
HUGO_DISABLELANGUAGES="es fr" hugo
```
@@ -160,7 +160,7 @@ If a `baseURL` is set on the `language` level, then all languages must have one
Example:
-{{< code-toggle file="hugo" >}}
+{{< code-toggle file=hugo >}}
[languages]
[languages.fr]
baseURL = "https://example.fr"
@@ -169,7 +169,7 @@ weight = 1
title = "En Français"
[languages.en]
-baseURL = "https://example.com"
+baseURL = "https://example.org/"
languageName = "English"
weight = 2
title = "In English"
@@ -183,13 +183,13 @@ public
└── fr
```
-**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.**
+**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.org/`.**
When you run `hugo server` we will start multiple HTTP servers. You will typically see something like this in the console:
```text
-Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1)
-Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1)
+Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) fr
+Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) en
Press Ctrl+C to stop
```
@@ -221,7 +221,7 @@ If a file has no language code, it will be assigned the default language.
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" >}}
+{{< code-toggle file=hugo >}}
languages:
en:
weight: 10
@@ -277,7 +277,7 @@ To localize URLs:
For example, a French translation can have its own localized slug.
-{{< code-toggle file="content/about.fr.md" fm=true copy=false >}}
+{{< code-toggle file=content/about.fr.md fm=true >}}
title: A Propos
slug: "a-propos"
{{< /code-toggle >}}
@@ -303,13 +303,13 @@ Page Bundle resources follow the same language assignment logic as content files
To create a list of links to translated content, use a template similar to the following:
-{{< code file="layouts/partials/i18nlist.html" >}}
+{{< code file=layouts/partials/i18nlist.html >}}
{{ if .IsTranslated }}
<h4>{{ i18n "translations" }}</h4>
<ul>
{{ range .Translations }}
<li>
- <a href="{{ .Permalink }}">{{ .Lang }}: {{ .Title }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
+ <a href="{{ .RelPermalink }}">{{ .Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
</li>
{{ end }}
</ul>
@@ -324,10 +324,10 @@ The above also uses the [`i18n` function][i18func] described in the next section
`.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:
-{{< code file="layouts/partials/allLanguages.html" >}}
+{{< code file=layouts/partials/allLanguages.html >}}
<ul>
{{ range $.Site.Home.AllTranslations }}
-<li><a href="{{ .Permalink }}">{{ .Language.LanguageName }}</a></li>
+<li><a href="{{ .RelPermalink }}">{{ .Language.LanguageName }}</a></li>
{{ end }}
</ul>
{{< /code >}}
@@ -349,7 +349,9 @@ Private use subtags must not exceed 8 alphanumeric characters.
### Query basic translation
-From within your templates, use the `i18n` function like this:
+From within your templates, use the [`i18n`] function like this:
+
+[`i18n`]: /functions/lang/translate
```go-html-template
{{ i18n "home" }}
@@ -357,7 +359,7 @@ From within your templates, use the `i18n` function like this:
The function will search for the `"home"` id:
-{{< code-toggle file="i18n/en-US" >}}
+{{< code-toggle file=i18n/en-US >}}
[home]
other = "Home"
{{< /code-toggle >}}
@@ -378,7 +380,7 @@ Often you will want to use the page variables in the translation strings. To do
The function will pass the `.` context to the `"wordCount"` id:
-{{< code-toggle file="i18n/en-US" >}}
+{{< code-toggle file=i18n/en-US >}}
[wordCount]
other = "This article has {{ .WordCount }} words."
{{< /code-toggle >}}
@@ -399,7 +401,7 @@ To enable pluralization when translating, pass a map with a numeric `.Count` pro
The function will read `.Count` from `.ReadingTime` and evaluate whether the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file:
-{{< code-toggle file="i18n/en-US" >}}
+{{< code-toggle file=i18n/en-US >}}
[readingTime]
one = "One minute to read"
other = "{{ .Count }} minutes to read"
@@ -427,7 +429,7 @@ In case you need to pass a custom data: (`(dict "Count" numeric_value_only)` is
The following localization examples assume your site's primary language is English, with translations to French and German.
-{{< code-toggle file="hugo" >}}
+{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
[languages]
@@ -530,7 +532,7 @@ Localization of menu entries depends on how you define them:
- When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry.
- When you define menu entries [in front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry.
-- When you define menu entries [in site configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficent, use translation tables to localize each entry.
+- When you define menu entries [in site configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry.
### Create language-specific menu entries
@@ -538,7 +540,7 @@ Localization of menu entries depends on how you define them:
For a simple menu with a small number of entries, use a single configuration file. For example:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[languages.de]
languageCode = 'de-DE'
languageName = 'Deutsch'
@@ -583,7 +585,7 @@ config/
└── hugo.toml
```
-{{< code-toggle file="config/_default/menus/menu.de" copy=false >}}
+{{< code-toggle file=config/_default/menus/menu.de >}}
[[main]]
name = 'Produkte'
pageRef = '/products'
@@ -594,7 +596,7 @@ pageRef = '/services'
weight = 20
{{< /code-toggle >}}
-{{< code-toggle file="config/_default/menus/menu.en" copy=false >}}
+{{< code-toggle file=config/_default/menus/menu.en >}}
[[main]]
name = 'Products'
pageRef = '/products'
@@ -624,7 +626,7 @@ The `identifier` depends on how you define menu entries:
For example, if you define menu entries in site configuration:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[[menu.main]]
identifier = 'products'
name = 'Products'
@@ -639,7 +641,7 @@ For example, if you define menu entries in site configuration:
Create corresponding entries in the translation tables:
-{{< code-toggle file="i18n/de" copy=false >}}
+{{< code-toggle file=i18n/de >}}
products = 'Produkte'
services = 'Leistungen'
{{< / code-toggle >}}
@@ -663,7 +665,7 @@ For merging of content from other languages (i.e. missing content translations),
To track down missing translation strings, run Hugo with the `--printI18nWarnings` flag:
-```bash
+```sh
hugo --printI18nWarnings | grep i18n
i18n|MISSING_TRANSLATION|en|wordCount
```
@@ -677,19 +679,18 @@ To support Multilingual mode in your themes, some considerations must be taken f
If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites).
-
## Generate multilingual content with `hugo new content`
If you organize content with translations in the same directory:
-```text
+```sh
hugo new content post/test.en.md
hugo new content post/test.de.md
```
If you organize content with translations in different directories:
-```text
+```sh
hugo new content content/en/post/test.md
hugo new content content/de/post/test.md
```
diff --git a/docs/content/en/content-management/organization/index.md b/docs/content/en/content-management/organization/index.md
index 2c0d2e604..22b341fcf 100644
--- a/docs/content/en/content-management/organization/index.md
+++ b/docs/content/en/content-management/organization/index.md
@@ -2,14 +2,14 @@
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: [fundamentals,content management]
+categories: [content management,fundamentals]
keywords: [sections,content,organization,bundle,resources]
menu:
docs:
parent: content-management
weight: 20
-toc: true
weight: 20
+toc: true
aliases: [/content/sections/]
---
@@ -19,16 +19,14 @@ Hugo `0.32` announced page-relative images and other resources packaged into `Pa
These terms are connected, and you also need to read about [Page Resources](/content-management/page-resources) and [Image Processing](/content-management/image-processing) to get the full picture.
-{{< imgproc 1-featured Resize "300x" >}}
+{{< imgproc "1-featured-content-bundles.png" "resize 300x" >}}
The illustration shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed.
{{< /imgproc >}}
-
{{% note %}}
The bundle documentation is a **work in progress**. We will publish more comprehensive docs about this soon.
{{% /note %}}
-
## Organization of content source
In Hugo, your content should be organized in a manner that reflects the rendered website.
@@ -41,33 +39,31 @@ Without any additional configuration, the following will automatically work:
.
└── content
└── about
- | └── index.md // <- https://example.com/about/
+ | └── index.md // <- https://example.org/about/
├── posts
- | ├── firstpost.md // <- https://example.com/posts/firstpost/
+ | ├── firstpost.md // <- https://example.org/posts/firstpost/
| ├── happy
- | | └── ness.md // <- https://example.com/posts/happy/ness/
- | └── secondpost.md // <- https://example.com/posts/secondpost/
+ | | └── ness.md // <- https://example.org/posts/happy/ness/
+ | └── secondpost.md // <- https://example.org/posts/secondpost/
└── quote
- ├── first.md // <- https://example.com/quote/first/
- └── second.md // <- https://example.com/quote/second/
+ ├── first.md // <- https://example.org/quote/first/
+ └── second.md // <- https://example.org/quote/second/
```
## 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].
+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.org"` in your [site's configuration file][config].
### 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].
{{% note %}}
-**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/getpage/).
+**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/methods/page/getpage).
{{% /note %}}
You can create one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website:
-
```txt
. url
. ⊢--^-⊣
@@ -88,17 +84,15 @@ At build, this will output to the following destination with the associated valu
⊢--------^---------⊣⊢-^-⊣
permalink
⊢----------^-------------⊣
-https://example.com/posts/index.html
+https://example.org/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 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`:
-
```txt
path ("posts/my-first-hugo-post.md")
. ⊢-----------^------------⊣
@@ -117,10 +111,9 @@ When Hugo builds your site, the content will be output to the following destinat
⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣
permalink
⊢--------------------^---------------------⊣
-https://example.com/posts/my-first-hugo-post/index.html
+https://example.org/posts/my-first-hugo-post/index.html
```
-
## 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.
@@ -147,7 +140,7 @@ The `url` is the entire URL path, defined by the file path and optionally overri
[config]: /getting-started/configuration/
[formats]: /content-management/formats/
[front matter]: /content-management/front-matter/
-[getpage]: /functions/getpage/
+[getpage]: /methods/page/getpage
[homepage template]: /templates/homepage/
[homepage]: /templates/homepage/
[lists]: /templates/lists/
diff --git a/docs/content/en/content-management/page-bundles.md b/docs/content/en/content-management/page-bundles.md
index c4ce69f5f..860fff2bb 100644
--- a/docs/content/en/content-management/page-bundles.md
+++ b/docs/content/en/content-management/page-bundles.md
@@ -1,14 +1,14 @@
---
title: Page bundles
description: Content organization using Page Bundles
-keywords: [page, bundle, leaf, branch]
categories: [content management]
+keywords: [page,bundle,leaf,branch]
menu :
docs:
parent: content-management
weight: 30
-toc: true
weight: 30
+toc: true
---
Page Bundles are a way to group [Page Resources](/content-management/page-resources/).
@@ -48,24 +48,24 @@ content/
│ │ ├── image2.png
│ │ └── index.md
│ └── my-other-post
-│    └── index.md
+│ └── index.md
└── another-section
├── ..
-    └── not-a-leaf-bundle
+ └── not-a-leaf-bundle
├── ..
-    └── another-leaf-bundle
-    └── index.md
+ └── another-leaf-bundle
+ └── index.md
```
In the above example `content/` directory, there are four leaf
bundles:
-`about`
+about
: This leaf bundle is at the root level (directly under
`content` directory) and has only the `index.md`.
-`my-post`
+my-post
: This leaf bundle has the `index.md`, two other content
Markdown files and two image files.
@@ -78,10 +78,10 @@ These content files are page resources of `my-post`
and only available in `my-post/index.md` resources.
They will **not** be rendered as individual pages.
-`my-other-post`
+my-other-post
: This leaf bundle has only the `index.md`.
-`another-leaf-bundle`
+another-leaf-bundle
: This leaf bundle is nested under couple of
directories. This bundle also has only the `index.md`.
@@ -90,7 +90,6 @@ The hierarchy depth at which a leaf bundle is created does not matter,
as long as it is not inside another **leaf** bundle.
{{% /note %}}
-
### Headless bundle
A headless bundle is a bundle that is configured to not get published
@@ -128,7 +127,7 @@ Explanation of the above example:
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 >}}
+{{< code-toggle file=content/headless/index.md fm=true >}}
headless = true
{{< /code-toggle >}}
@@ -149,17 +148,16 @@ Here `md` (markdown) is used just as an example. You can use any file
type as a content resource as long as it is a content type recognized by Hugo.
{{% /note %}}
-
### Examples of branch bundle organization
```text
content/
├── branch-bundle-1
-│   ├── branch-content1.md
-│   ├── branch-content2.md
-│   ├── image1.jpg
-│   ├── image2.png
-│   └── _index.md
+│ ├── branch-content1.md
+│ ├── branch-content2.md
+│ ├── image1.jpg
+│ ├── image2.png
+│ └── _index.md
└── branch-bundle-2
├── _index.md
└── a-leaf-bundle
@@ -169,11 +167,11 @@ content/
In the above example `content/` directory, there are two branch
bundles (and a leaf bundle):
-`branch-bundle-1`
+branch-bundle-1
: This branch bundle has the `_index.md`, two
other content Markdown files and two image files.
-`branch-bundle-2`
+branch-bundle-2
: This branch bundle has the `_index.md` and a
nested leaf bundle.
diff --git a/docs/content/en/content-management/page-resources.md b/docs/content/en/content-management/page-resources.md
index bbf288459..f141510bb 100644
--- a/docs/content/en/content-management/page-resources.md
+++ b/docs/content/en/content-management/page-resources.md
@@ -7,8 +7,8 @@ menu:
docs:
parent: content-management
weight: 80
-toc: true
weight: 80
+toc: true
---
Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or
`_index.md` files at their root. Page resources are only available to the
@@ -112,7 +112,6 @@ GetMatch
.Resources.Match "*" 🚫
.Resources.Match "sunset.jpg" 🚫
.Resources.Match "*sunset.jpg" 🚫
-
```
## Page resources metadata
@@ -138,7 +137,7 @@ params
### Resources metadata example
-{{< code-toggle copy=false >}}
+{{< code-toggle >}}
title: Application
date : 2018-01-25
resources :
@@ -184,7 +183,8 @@ The counter starts at 1 the first time they are used in either `name` or `title`
For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as:
-{{< code-toggle copy=false >}}
+{{< code-toggle file=content/inspections/engine/index.md fm=true >}}
+title = 'Engine inspections'
[[resources]]
src = "*specs.pdf"
title = "Specification #:counter"
diff --git a/docs/content/en/content-management/related.md b/docs/content/en/content-management/related.md
index 42d577b95..e73dfc32a 100644
--- a/docs/content/en/content-management/related.md
+++ b/docs/content/en/content-management/related.md
@@ -7,8 +7,8 @@ menu:
docs:
parent: content-management
weight: 110
-toc: true
weight: 110
+toc: true
aliases: [/content/related/,/related/]
---
@@ -18,13 +18,13 @@ Hugo uses a set of factors to identify a page's related content based on front m
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:
-{{< code file="layouts/partials/related.html" >}}
+{{< code file=layouts/partials/related.html >}}
{{ $related := .Site.RegularPages.Related . | first 5 }}
{{ with $related }}
<h3>See Also</h3>
<ul>
{{ range . }}
- <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
{{ end }}
@@ -33,22 +33,25 @@ To list up to 5 related pages (which share the same _date_ or _keyword_ paramete
The `Related` method takes one argument which may be a `Page` or a options map. The options map have these options:
indices
-: The indices to search in.
+: (`slice`) The indices to search within.
document
-: The document to search for related content for.
+: (`page`) The page for which to find related content. Required when specifying an options map.
namedSlices
-: The keywords to search for.
+: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function.
fragments
-: Fragments holds a a list of special keywords that is used for indices configured as type "fragments". This will match the fragment identifiers of the documents.
+: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment] identifiers of the documents.
+
+[fragment]: /getting-started/glossary/#fragment
+[`keyVals`]: /functions/collections/keyvals/
A fictional example using all of the above options:
```go-html-template
{{ $page := . }}
-{{ $opts :=
+{{ $opts := dict
"indices" (slice "tags" "keywords")
"document" $page
"namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date))
@@ -57,16 +60,16 @@ A fictional example using all of the above options:
```
{{% note %}}
-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.
+We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndices`. 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
-{{< new-in "0.111.0" >}}
+{{< new-in 0.111.0 >}}
Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[related]
threshold = 20
includeNewer = true
@@ -74,7 +77,7 @@ toLower = false
[[related.indices]]
name = "fragmentrefs"
type = "fragments"
-applyFilter = false
+applyFilter = true
weight = 80
{{< /code-toggle >}}
@@ -88,7 +91,7 @@ weight = 80
<ul>
{{ range $i, $p := . }}
<li>
- <a href="{{ .RelPermalink }}">{{ .Title }}</a>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
{{ with .HeadingsFiltered }}
<ul>
{{ range . }}
@@ -113,7 +116,7 @@ Hugo provides a sensible default configuration of Related Content, but you can f
Without any `related` configuration set on the project, Hugo's Related Content methods will use the following.
-{{< code-toggle config="related" />}}
+{{< code-toggle config=related />}}
Custom configuration should be set using the same syntax.
@@ -124,37 +127,36 @@ If you add a `related` configuration section, you need to add a complete configu
### Top level configuration options
threshold
-: A value between 0-100. Lower value will give more, but maybe not so relevant, matches.
+: (`int`) A value between 0-100. Lower value will give more, but maybe not so relevant, matches.
includeNewer
-: Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added.
+: (`bool`) Set to `true` to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added.
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.
+: (`bool`) 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.
### Configuration options per index
name
-: 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.
+: (`string`) 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`.
+type {{< new-in 0.111.0 >}}
+: (`string`) One of `basic`(default) or `fragments`.
-applyFilter
-: {{< new-in "0.111.0" >}}. Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type.
+applyFilter {{< new-in 0.111.0 >}}
+: (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type.
weight
-: An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best.
-
+: (`int`) An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best.
-cardinalityThreshold (default 0)
-: {{< new-in "0.111.0" >}}. A percentage (0-100) used to remove common keywords from the index. As an example, setting this to 50 will remove all keywords that are used in more than 50% of the documents in the index.
+cardinalityThreshold {{< new-in 0.111.0 >}}
+: (`int`) A percentage (0-100) used to remove common keywords from the index. As an example, setting this to `50` will remove all keywords that are used in more than 50% of the documents in the index. Default is `0`.
pattern
-: This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default.
+: (`string`) This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default.
toLower
-: See above.
+: (`bool`) See above.
## Performance considerations
diff --git a/docs/content/en/content-management/sections.md b/docs/content/en/content-management/sections.md
index a3e4397f3..1b694ce44 100644
--- a/docs/content/en/content-management/sections.md
+++ b/docs/content/en/content-management/sections.md
@@ -8,8 +8,8 @@ menu:
docs:
parent: content-management
weight: 120
-toc: true
weight: 120
+toc: true
aliases: [/content/sections/]
---
@@ -26,35 +26,35 @@ A typical site consists of one or more sections. For example:
```text
content/
├── articles/ <-- section (top-level directory)
-│   ├── 2022/
-│   │   ├── article-1/
-│   │   │   ├── cover.jpg
-│   │   │   └── index.md
-│   │   └── article-2.md
-│   └── 2023/
-│   ├── article-3.md
-│   └── article-4.md
+│ ├── 2022/
+│ │ ├── article-1/
+│ │ │ ├── cover.jpg
+│ │ │ └── index.md
+│ │ └── article-2.md
+│ └── 2023/
+│ ├── article-3.md
+│ └── article-4.md
├── products/ <-- section (top-level directory)
-│   ├── product-1/ <-- section (has _index.md file)
-│   │   ├── benefits/ <-- section (has _index.md file)
-│   │   │   ├── _index.md
-│   │   │   ├── benefit-1.md
-│   │   │   └── benefit-2.md
-│   │   ├── features/ <-- section (has _index.md file)
-│   │   │   ├── _index.md
-│   │   │   ├── feature-1.md
-│   │   │   └── feature-2.md
-│   │   └── _index.md
-│   └── product-2/ <-- section (has _index.md file)
-│   ├── benefits/ <-- section (has _index.md file)
-│   │   ├── _index.md
-│   │   ├── benefit-1.md
-│   │   └── benefit-2.md
-│   ├── features/ <-- section (has _index.md file)
-│   │   ├── _index.md
-│   │   ├── feature-1.md
-│   │   └── feature-2.md
-│   └── _index.md
+│ ├── product-1/ <-- section (has _index.md file)
+│ │ ├── benefits/ <-- section (has _index.md file)
+│ │ │ ├── _index.md
+│ │ │ ├── benefit-1.md
+│ │ │ └── benefit-2.md
+│ │ ├── features/ <-- section (has _index.md file)
+│ │ │ ├── _index.md
+│ │ │ ├── feature-1.md
+│ │ │ └── feature-2.md
+│ │ └── _index.md
+│ └── product-2/ <-- section (has _index.md file)
+│ ├── benefits/ <-- section (has _index.md file)
+│ │ ├── _index.md
+│ │ ├── benefit-1.md
+│ │ └── benefit-2.md
+│ ├── features/ <-- section (has _index.md file)
+│ │ ├── _index.md
+│ │ ├── feature-1.md
+│ │ └── feature-2.md
+│ └── _index.md
├── _index.md
└── about.md
```
@@ -77,7 +77,7 @@ With the file structure from the [example above](#overview):
1. The articles/2022 and articles/2023 directories do not have list pages; they are not sections.
-1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `.RegularPagesRecursive` collection instead of the `.Pages` collection in the list template. See [details](/variables/page/#page-collections).
+1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `.RegularPagesRecursive` collection instead of the `.Pages` collection in the list template. See&nbsp;[details](/variables/page/#page-collections).
1. All directories in the products section have list pages; each directory is a section.
@@ -106,8 +106,7 @@ If you need to use a different template for a subsection, specify `type` and/or
## Ancestors and descendants
-A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview):
-
+A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview):
```text
content/products/product-1/benefits/benefit-1.md
@@ -117,16 +116,16 @@ The content file (benefit-1.md) has four ancestors: benefits, product-1, product
For example, use the `.Ancestors` method to render breadcrumb navigation.
-{{< code file="layouts/partials/breadcrumb.html" >}}
+{{< code file=layouts/partials/breadcrumb.html >}}
<nav aria-label="breadcrumb" class="breadcrumb">
<ol>
{{ range .Ancestors.Reverse }}
<li>
- <a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
</li>
{{ end }}
<li class="active">
- <a aria-current="page" href="{{ .Permalink }}">{{ .LinkTitle }}</a>
+ <a aria-current="page" href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
</li>
</ol>
</nav>
@@ -154,7 +153,6 @@ Hugo renders this, where each breadcrumb is a link to the corresponding page:
Home » Products » Product 1 » Benefits » Benefit 1
```
-
[archetype]: /content-management/archetypes/
[content type]: /content-management/types/
[directory structure]: /getting-started/directory-structure/
diff --git a/docs/content/en/content-management/shortcodes.md b/docs/content/en/content-management/shortcodes.md
index b1e32d902..bbc2b0cc8 100644
--- a/docs/content/en/content-management/shortcodes.md
+++ b/docs/content/en/content-management/shortcodes.md
@@ -7,8 +7,8 @@ menu:
docs:
parent: content-management
weight: 100
-toc: true
weight: 100
+toc: true
aliases: [/extras/shortcodes/]
testparam: "Hugo Rocks!"
---
@@ -58,7 +58,6 @@ and a new line with a "quoted string".` */>}}
Shortcodes using the `%` as the outer-most delimiter will be fully rendered when sent to the content renderer. This means that the rendered output from a shortcode can be part of the page's table of contents, footnotes, etc.
-
### Shortcodes without markdown
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML:
@@ -100,7 +99,7 @@ title
: Image title.
caption
-: Image caption. Markdown within the value of `caption` will be rendered.
+: Image caption. Markdown within the value of `caption` will be rendered.
class
: `class` attribute of the HTML `figure` tag.
@@ -122,7 +121,7 @@ attrlink
#### Example `figure` input
-{{< code file="figure-input-example.md" >}}
+{{< code file=figure-input-example.md >}}
{{</* figure src="elephant.jpg" title="An elephant at sunset" */>}}
{{< /code >}}
@@ -131,7 +130,7 @@ attrlink
```html
<figure>
<img src="elephant.jpg">
- <figcaption>An elephant at sunset</figcaption>
+ <figcaption><h4>An elephant at sunset</h4></figcaption>
</figure>
```
@@ -153,17 +152,17 @@ Include this in your markdown:
This will display all files in the gist alphabetically by file name.
-{{< gist jmooring 50a7482715eac222e230d1e64dd9a89b >}}
+{{< gist jmooring 23932424365401ffa5e9d9810102a477 >}}
To display a specific file within the gist:
```text
-{{</* gist user 50a7482715eac222e230d1e64dd9a89b 1-template.html */>}}
+{{</* gist user 23932424365401ffa5e9d9810102a477 list.html */>}}
```
Rendered:
-{{< gist jmooring 50a7482715eac222e230d1e64dd9a89b 1-template.html >}}
+{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}}
### `highlight`
@@ -220,14 +219,14 @@ You must obtain an Access Token to use the `instagram` shortcode.
If your site configuration is private:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[services.instagram]
accessToken = 'xxx'
{{< /code-toggle >}}
If your site configuration is _not_ private, set the Access Token with an environment variable:
-```text
+```sh
HUGO_SERVICES_INSTAGRAM_ACCESSTOKEN=xxx hugo --gc --minify
```
@@ -251,7 +250,7 @@ Include this in your markdown:
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
+```sh
{{</* param testparam */>}}
```
@@ -261,7 +260,7 @@ Since `testparam` is a parameter defined in front matter of this page with the v
To access deeply nested parameters, use "dot syntax", e.g:
-```bash
+```sh
{{</* param "my.nested.param" */>}}
```
@@ -289,7 +288,7 @@ Read a more extensive description of `ref` and `relref` in the [cross references
Assuming that standard Hugo pretty URLs are turned on.
```html
-<a href="https://example.com/blog/neat">Neat</a>
+<a href="https://example.org/blog/neat">Neat</a>
<a href="/about/#who">Who</a>
```
@@ -349,20 +348,19 @@ https://www.youtube.com/watch?v=w7Ft2ymGmfc
Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
-{{< code file="example-youtube-input.md" >}}
+{{< code file=example-youtube-input.md >}}
{{</* youtube w7Ft2ymGmfc */>}}
{{< /code >}}
Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named and unnamed parameters, so you'll need to assign the yet unnamed video ID to the parameter `id`:
-
-{{< code file="example-youtube-input-with-autoplay.md" >}}
+{{< code file=example-youtube-input-with-autoplay.md >}}
{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
{{< /code >}}
-For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video. You can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used.
+For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video. You can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used.
-{{< code file="example-youtube-input-with-title.md" >}}
+{{< code file=example-youtube-input-with-title.md >}}
{{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}}
{{< /code >}}
@@ -370,7 +368,7 @@ For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titl
Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
-{{< code file="example-youtube-output.html" >}}
+{{< code file=example-youtube-output.html >}}
{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
{{< /code >}}
@@ -398,7 +396,7 @@ To learn more about creating custom shortcodes, see the [shortcode template docu
[partials]: /templates/partials/
[quickstart]: /getting-started/quick-start/
[sctemps]: /templates/shortcode-templates/
-[scvars]: /variables/shortcodes/
+[scvars]: /variables/shortcode/
[shortcode template documentation]: /templates/shortcode-templates/
[templatessection]: /templates/
[Vimeo]: https://vimeo.com/
diff --git a/docs/content/en/content-management/static-files.md b/docs/content/en/content-management/static-files.md
index 78772af99..c1197ede1 100644
--- a/docs/content/en/content-management/static-files.md
+++ b/docs/content/en/content-management/static-files.md
@@ -7,8 +7,8 @@ menu:
docs:
parent: content-management
weight: 200
-toc: true
weight: 200
+toc: true
aliases: [/static-files]
---
@@ -27,13 +27,13 @@ This union filesystem will be served from your site root. So a file
Here's an example of setting `staticDir` and `staticDir2` for a
multi-language site:
-{{< code-toggle copy=false file="hugo" >}}
+{{< code-toggle file=hugo >}}
staticDir = ["static1", "static2"]
[languages]
[languages.en]
staticDir2 = "static_en"
-baseURL = "https://example.com"
+baseURL = "https://example.org/"
languageName = "English"
weight = 2
title = "In English"
diff --git a/docs/content/en/content-management/summaries.md b/docs/content/en/content-management/summaries.md
index 74c5623cb..2ff1fec34 100644
--- a/docs/content/en/content-management/summaries.md
+++ b/docs/content/en/content-management/summaries.md
@@ -8,11 +8,13 @@ menu:
docs:
parent: content-management
weight: 160
-toc: true
weight: 160
+toc: true
aliases: [/content/summaries/,/content-management/content-summaries/]
---
+<!--more-->
+
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
@@ -37,7 +39,7 @@ The Hugo-defined summaries are set to use word count calculated by splitting the
### 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.
+Alternatively, you may add the `<!--more-->` summary divider where you want to split the article.
For [Org mode content][org], use `# more` where you want to split the article.
@@ -48,42 +50,42 @@ The concept of a *summary divider* is not unique to Hugo. It is also called the
{{% /note %}}
Pros
-: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved.
+: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved.
Cons
-: Extra work for content authors, since they need to remember to type <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/).
+: Extra work for content authors, since they need to remember to type `<!--more-->` (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/).
-{{% warning "Be Precise with the Summary Divider" %}}
-Be careful to enter <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> exactly; i.e., all lowercase and with no whitespace.
+{{% note %}}
+Be careful to enter `<!--more-->` exactly; i.e., all lowercase and with no whitespace.
{{% /note %}}
### 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.
+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.
Pros
-: Complete freedom of text independent of the content of the article. Markup can be used within the summary.
+: Complete freedom of text independent of the content of the article. Markup can be used within the summary.
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
-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:
+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:
-1. If there is a <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider present in the article the text up to the divider will be provided as per the manual summary split method
+1. If there is a `<!--more-->`> summary divider present in the article the text up to the divider will be provided as per the manual summary split method
2. If there is a `summary` variable in the article front matter the value of the variable will be provided as per the front matter summary method
3. The text at the start of the article will be provided as per the automatic summary split method
-{{% warning "Competing selections" %}}
-Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider Hugo will use the manual summary split method.
+{{% note %}}
+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 `<!--more-->` summary divider Hugo will use the manual summary split method.
{{% /note %}}
## 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].
-{{< code file="page-list-with-summaries.html" >}}
+{{< code file=page-list-with-summaries.html >}}
{{ range first 10 .Pages }}
<article>
<!-- this <div> includes the title summary -->
diff --git a/docs/content/en/content-management/syntax-highlighting.md b/docs/content/en/content-management/syntax-highlighting.md
index 39fef0f9b..62071cd46 100644
--- a/docs/content/en/content-management/syntax-highlighting.md
+++ b/docs/content/en/content-management/syntax-highlighting.md
@@ -1,14 +1,14 @@
---
title: Syntax highlighting
description: Hugo comes with really fast syntax highlighting from Chroma.
-keywords: [highlighting,chroma,code blocks,syntax]
categories: [content management]
+keywords: [highlighting,chroma,code blocks,syntax]
menu:
docs:
parent: content-management
weight: 240
-toc: true
weight: 240
+toc: true
aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
---
@@ -24,7 +24,7 @@ If you run with `markup.highlight.noClasses=false` in your site configuration, y
You can generate one with Hugo:
-```bash
+```sh
hugo gen chromastyles --style=monokai > syntax.css
```
@@ -41,7 +41,7 @@ Options:
* `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" >}}
+* `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
@@ -104,7 +104,6 @@ Highlighting in code fences is enabled by default.
```
````
-
Gives this:
```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
diff --git a/docs/content/en/content-management/taxonomies.md b/docs/content/en/content-management/taxonomies.md
index af8297876..94f2f6357 100644
--- a/docs/content/en/content-management/taxonomies.md
+++ b/docs/content/en/content-management/taxonomies.md
@@ -1,14 +1,14 @@
---
title: Taxonomies
description: Hugo includes support for user-defined taxonomies.
-keywords: [taxonomies,metadata,front matter,terms]
categories: [content management]
+keywords: [taxonomies,metadata,front matter,terms]
menu:
docs:
parent: content-management
weight: 150
-toc: true
weight: 150
+toc: true
aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes]
---
@@ -27,7 +27,6 @@ Term
Value
: a piece of content assigned to a term
-
## Example taxonomy: movie website
Let's assume you are making a website about movies. You may want to include the following taxonomies:
@@ -82,15 +81,15 @@ Hugo natively supports taxonomies.
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 config="taxonomies" />}}
+{{< code-toggle config=taxonomies />}}
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 >}}
+{{< code-toggle file=hugo >}}
disableKinds = ["taxonomy","term"]
{{</ code-toggle >}}
-{{% page-kinds %}}
+{{% include "content-management/_common/page-kinds.md" %}}
### Default destinations
@@ -109,7 +108,7 @@ Custom taxonomies other than the [defaults](#default-taxonomies) must be defined
While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_.
{{% /note %}}
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[taxonomies]
tag = "tags"
category = "categories"
@@ -120,7 +119,7 @@ While adding custom taxonomies, you need to put in the default taxonomies too, _
If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so by modifying the `taxonomies` value in your [site configuration].
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[taxonomies]
tag = "tags"
{{</ code-toggle >}}
@@ -129,14 +128,6 @@ If you want to disable all taxonomies altogether, see the use of `disableKinds`
{{% note %}}
You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
-
-Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not.
-{{% /note %}}
-
-{{% note %}}
-The configuration option `preserveTaxonomyNames` was removed in Hugo 0.55.
-
-You can now use `.Page.Title` on the relevant taxonomy node to get the original value.
{{% /note %}}
## Add taxonomies to content
@@ -151,7 +142,7 @@ If you would like the ability to quickly generate content files with preconfigur
### Example: front matter with taxonomies
-{{< code-toggle file="content/example.md" fm=true copy=false >}}
+{{< code-toggle file=content/example.md fm=true >}}
title = "Hugo: A fast and flexible static site generator"
tags = [ "Development", "Go", "fast", "Blogging" ]
categories = [ "Development" ]
@@ -168,7 +159,7 @@ The following show a piece of content that has a weight of 22, which can be used
### Example: taxonomic `weight`
-{{< code-toggle copy=false >}}
+{{< code-toggle >}}
title = "foo"
tags = [ "a", "b", "c" ]
tags_weight = 22
@@ -178,15 +169,11 @@ categories_weight = 44
By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies.
-{{% note %}}
-Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight--date--linktitle--filepath). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/).
-{{% /note %}}
-
## 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:
-{{< code-toggle file="content/actors/bruce-willis/_index.md" fm=true copy=false >}}
+{{< code-toggle file=content/actors/bruce-willis/_index.md fm=true >}}
title: "Bruce Willis"
wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
{{< /code-toggle >}}
diff --git a/docs/content/en/content-management/toc.md b/docs/content/en/content-management/toc.md
index ca179c77d..69021ac45 100644
--- a/docs/content/en/content-management/toc.md
+++ b/docs/content/en/content-management/toc.md
@@ -7,8 +7,8 @@ menu:
docs:
parent: content-management
weight: 210
-toc: true
weight: 210
+toc: true
aliases: [/extras/toc/]
---
@@ -37,7 +37,7 @@ He lay on his armour-like back, and if he lifted his head a little he could see
### My Subheading
-A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
+A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
```
Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`.
@@ -48,7 +48,7 @@ The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">`
The following is an example of a very basic [single page template]:
-{{< code file="layout/_default/single.html" >}}
+{{< code file=layout/_default/single.html >}}
{{ define "main" }}
<main>
<article>
@@ -68,7 +68,7 @@ The following is an example of a very basic [single page template]:
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals] in your templating:
-{{< code file="layouts/partials/toc.html" >}}
+{{< code file=layouts/partials/toc.html >}}
{{ if and (gt .WordCount 400 ) (.Params.toc) }}
<aside>
<header>
@@ -105,8 +105,9 @@ He lay on his armour-like back, and if he lifted his head a little he could see
=== My Subheading
-A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
+A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
```
+
Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown.
[conditionals]: /templates/introduction/#conditionals
diff --git a/docs/content/en/content-management/types.md b/docs/content/en/content-management/types.md
index e72361f1c..67dbe1596 100644
--- a/docs/content/en/content-management/types.md
+++ b/docs/content/en/content-management/types.md
@@ -2,13 +2,13 @@
title: Content types
description: Hugo is built around content organized in sections.
categories: [content management]
-keywords: [lists, sections, content types, types, organization]
+keywords: [lists,sections,content types,types,organization]
menu:
docs:
parent: content-management
weight: 130
-toc: true
weight: 130
+toc: true
aliases: [/content/types]
---
diff --git a/docs/content/en/content-management/urls.md b/docs/content/en/content-management/urls.md
index 60f9615b8..a91fe21c0 100644
--- a/docs/content/en/content-management/urls.md
+++ b/docs/content/en/content-management/urls.md
@@ -7,8 +7,8 @@ menu:
docs:
parent: content-management
weight: 180
-toc: true
weight: 180
+toc: true
aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
---
@@ -28,7 +28,7 @@ You can change the structure and appearance of URLs with front matter values and
Set the `slug` in front matter to override the last segment of the path. The `slug` value does not affect section pages.
-{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}}
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
title = 'My First Post'
slug = 'my-first-post'
{{< /code-toggle >}}
@@ -45,7 +45,7 @@ Set the `url` in front matter to override the entire path. Use this with either
With this front matter:
-{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}}
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
title = 'My First Article'
url = '/articles/my-first-article'
{{< /code-toggle >}}
@@ -58,7 +58,7 @@ https://example.org/articles/my-first-article/
If you include a file extension:
-{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}}
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
title = 'My First Article'
url = '/articles/my-first-article.html'
{{< /code-toggle >}}
@@ -112,7 +112,7 @@ content/
Render tutorials under "training", and render the posts under "articles" with a date-base hierarchy:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[permalinks.page]
posts = '/articles/:year/:month/:slug/'
tutorials = '/training/:slug/'
@@ -145,14 +145,14 @@ public/
To create a date-based hierarchy for regular pages in the content root:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[permalinks.page]
"/" = "/:year/:month/:slug/"
{{< /code-toggle >}}
Use the same approach with taxonomy terms. For example, to omit the taxonomy segment of the URL:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
[permalinks.term]
'tags' = '/:slug/'
{{< /code-toggle >}}
@@ -179,7 +179,7 @@ content/
And this site configuration:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
@@ -280,7 +280,7 @@ For time-related values, you can also use the layout string components defined i
[time package]: https://pkg.go.dev/time#pkg-constants
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
permalinks:
posts: /:06/:1/:2/:title/
{{< /code-toggle >}}
@@ -296,7 +296,7 @@ pretty|content/about.md|`https://example.org/about/`
By default, Hugo produces pretty URLs. To generate ugly URLs, change your site configuration:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
uglyURLs = true
{{< /code-toggle >}}
@@ -314,7 +314,7 @@ This is a legacy configuration option, superseded by template functions and mark
If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then prepends the `baseURL` to create absolute URLs.
-```text
+```html
<a href="/about"> → <a href="https://example.org/about/">
<img src="/a.gif"> → <img src="https://example.org/a.gif">
```
@@ -323,7 +323,7 @@ This is an imperfect, brute force approach that can affect content as well as HT
To enable:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
canonifyURLs = true
{{< /code-toggle >}}
@@ -337,7 +337,7 @@ If enabled, Hugo performs a search and replace _after_ it renders the page. It s
For example, when rendering `content/posts/post-1`:
-```text
+```html
<a href="/about"> → <a href="../../about">
<img src="/a.gif"> → <img src="../../a.gif">
```
@@ -346,7 +346,7 @@ This is an imperfect, brute force approach that can affect content as well as HT
To enable:
-{{< code-toggle file="hugo" copy=false >}}
+{{< code-toggle file=hugo >}}
relativeURLs = true
{{< /code-toggle >}}
@@ -361,7 +361,7 @@ Create redirects from old URLs to new URLs with aliases:
Change the file name of an existing page, and create an alias from the previous URL to the new URL:
-{{< code-toggle file="content/posts/new-file-name.md" copy=false >}}
+{{< code-toggle file=content/posts/new-file-name.md >}}
aliases = ['/posts/previous-file-name']
{{< /code-toggle >}}
@@ -373,13 +373,13 @@ Each of these directory-relative aliases is equivalent to the site-relative alia
You can create more than one alias to the current page:
-{{< code-toggle file="content/posts/new-file-name.md" copy=false >}}
+{{< code-toggle file=content/posts/new-file-name.md >}}
aliases = ['previous-file-name','original-file-name']
{{< /code-toggle >}}
In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias:
-{{< code-toggle file="content/posts/new-file-name.de.md" copy=false >}}
+{{< code-toggle file=content/posts/new-file-name.de.md >}}
aliases = ['/de/posts/previous-file-name']
{{< /code-toggle >}}
@@ -400,7 +400,7 @@ public/
The alias from the previous URL to the new URL is a client-side redirect:
-{{< code file="posts/previous-file-name/index.html" copy=false >}}
+{{< code file=posts/previous-file-name/index.html >}}
<!DOCTYPE html>
<html lang="en-us">
<head>
@@ -425,8 +425,8 @@ Hugo renders alias files before rendering pages. A new page with the previous fi
Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context:
-`Permalink`
+Permalink
: the link to the page being aliased
-`Page`
+Page
: the Page data for the page being aliased