blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-24 15:28:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Namespace functions and methods

Browse Source
This commit is contained in:
Joe Mooring
2023-11-04 21:01:42 -07:00
committed by GitHub
parent 40212779ae
commit 723a827fdc
687 changed files with 20449 additions and 5821 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cspell.json
+3 -2
View File
@@ -335,7 +335,7 @@
"مدونتي"
],
"language": "en,en-US,de,fr",
"allowCompoundWords": true,
"allowCompoundWords": false,
"files": [
"**/*.md"
],
@@ -354,7 +354,8 @@
"**/node_modules/**",
"*.min.*",
"**/news/*",
"**/showcase/*"
"**/showcase/*",
"**/content-management/emoji-shortcodes.md"
],
"useGitignore": true,
"enabled": true
LICENSE.md
+168 -161
View File
@@ -1,194 +1,201 @@
Apache License
==============
Version 2.0, January 2004
http://www.apache.org/licenses/
_Version 2.0, January 2004_
_&lt;<http://www.apache.org/licenses/>&gt;_
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
### Terms and Conditions for use, reproduction, and distribution
1. Definitions.
#### 1. Definitions
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
“License” shall mean the terms and conditions for use, reproduction, and
distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
“Licensor” shall mean the copyright owner or entity authorized by the copyright
owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
“Legal Entity” shall mean the union of the acting entity and all other entities
that control, are controlled by, or are under common control with that entity.
For the purposes of this definition, “control” means **(i)** the power, direct or
indirect, to cause the direction or management of such entity, whether by
contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the
outstanding shares, or **(iii)** beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
“You” (or “Your”) shall mean an individual or Legal Entity exercising
permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
“Source” form shall mean the preferred form for making modifications, including
but not limited to software source code, documentation source, and configuration
files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
“Object” form shall mean any form resulting from mechanical transformation or
translation of a Source form, including but not limited to compiled object code,
generated documentation, and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
“Work” shall mean the work of authorship, whether in Source or Object form, made
available under the License, as indicated by a copyright notice that is included
in or attached to the work (an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
“Derivative Works” shall mean any work, whether in Source or Object form, that
is based on (or derived from) the Work and for which the editorial revisions,
annotations, elaborations, or other modifications represent, as a whole, an
original work of authorship. For the purposes of this License, Derivative Works
shall not include works that remain separable from, or merely link (or bind by
name) to the interfaces of, the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
“Contribution” shall mean any work of authorship, including the original version
of the Work and any modifications or additions to that Work or Derivative Works
thereof, that is intentionally submitted to Licensor for inclusion in the Work
by the copyright owner or by an individual or Legal Entity authorized to submit
on behalf of the copyright owner. For the purposes of this definition,
“submitted” means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems, and
issue tracking systems that are managed by, or on behalf of, the Licensor for
the purpose of discussing and improving the Work, but excluding communication
that is conspicuously marked or otherwise designated in writing by the copyright
owner as “Not a Contribution.”
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
“Contributor” shall mean Licensor and any individual or Legal Entity on behalf
of whom a Contribution has been received by Licensor and subsequently
incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
#### 2. Grant of Copyright License
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the Work and such
Derivative Works in Source or Object form.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
#### 3. Grant of Patent License
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable (except as stated in this section) patent license to make, have
made, use, offer to sell, sell, import, and otherwise transfer the Work, where
such license applies only to those patent claims licensable by such Contributor
that are necessarily infringed by their Contribution(s) alone or by combination
of their Contribution(s) with the Work to which such Contribution(s) was
submitted. If You institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work or a
Contribution incorporated within the Work constitutes direct or contributory
patent infringement, then any patent licenses granted to You under this License
for that Work shall terminate as of the date such litigation is filed.
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
#### 4. Redistribution
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
You may reproduce and distribute copies of the Work or Derivative Works thereof
in any medium, with or without modifications, and in Source or Object form,
provided that You meet the following conditions:
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
* **(a)** You must give any other recipients of the Work or Derivative Works a copy of
this License; and
* **(b)** You must cause any modified files to carry prominent notices stating that You
changed the files; and
* **(c)** You must retain, in the Source form of any Derivative Works that You distribute,
all copyright, patent, trademark, and attribution notices from the Source form
of the Work, excluding those notices that do not pertain to any part of the
Derivative Works; and
* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any
Derivative Works that You distribute must include a readable copy of the
attribution notices contained within such NOTICE file, excluding those notices
that do not pertain to any part of the Derivative Works, in at least one of the
following places: within a NOTICE text file distributed as part of the
Derivative Works; within the Source form or documentation, if provided along
with the Derivative Works; or, within a display generated by the Derivative
Works, if and wherever such third-party notices normally appear. The contents of
the NOTICE file are for informational purposes only and do not modify the
License. You may add Your own attribution notices within Derivative Works that
You distribute, alongside or as an addendum to the NOTICE text from the Work,
provided that such additional attribution notices cannot be construed as
modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
You may add Your own copyright statement to Your modifications and may provide
additional or different license terms and conditions for use, reproduction, or
distribution of Your modifications, or for any such Derivative Works as a whole,
provided Your use, reproduction, and distribution of the Work otherwise complies
with the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
#### 5. Submission of Contributions
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
Unless You explicitly state otherwise, any Contribution intentionally submitted
for inclusion in the Work by You to the Licensor shall be under the terms and
conditions of this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify the terms of
any separate license agreement you may have executed with Licensor regarding
such Contributions.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
#### 6. Trademarks
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
This License does not grant permission to use the trade names, trademarks,
service marks, or product names of the Licensor, except as required for
reasonable and customary use in describing the origin of the Work and
reproducing the content of the NOTICE file.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
#### 7. Disclaimer of Warranty
END OF TERMS AND CONDITIONS
Unless required by applicable law or agreed to in writing, Licensor provides the
Work (and each Contributor provides its Contributions) on an “AS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
including, without limitation, any warranties or conditions of TITLE,
NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
solely responsible for determining the appropriateness of using or
redistributing the Work and assume any risks associated with Your exercise of
permissions under this License.
APPENDIX: How to apply the Apache License to your work.
#### 8. Limitation of Liability
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
In no event and under no legal theory, whether in tort (including negligence),
contract, or otherwise, unless required by applicable law (such as deliberate
and grossly negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special, incidental,
or consequential damages of any character arising as a result of this License or
out of the use or inability to use the Work (including but not limited to
damages for loss of goodwill, work stoppage, computer failure or malfunction, or
any and all other commercial damages or losses), even if such Contributor has
been advised of the possibility of such damages.
Copyright [yyyy] [name of copyright owner]
#### 9. Accepting Warranty or Additional Liability
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
While redistributing the Work or Derivative Works thereof, You may choose to
offer, and charge a fee for, acceptance of support, warranty, indemnity, or
other liability obligations and/or rights consistent with this License. However,
in accepting such obligations, You may act only on Your own behalf and on Your
sole responsibility, not on behalf of any other Contributor, and only if You
agree to indemnify, defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason of your
accepting any such warranty or additional liability.
http://www.apache.org/licenses/LICENSE-2.0
_END OF TERMS AND CONDITIONS_
### APPENDIX: How to apply the Apache License to your work
To apply the Apache License to your work, attach the following boilerplate
notice, with the fields enclosed by brackets `[]` replaced with your own
identifying information. (Don't include the brackets!) The text should be
enclosed in the appropriate comment syntax for the file format. We also
recommend that a file or class name and description of purpose be included on
the same “printed page” as the copyright notice for easier identification within
third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
README.md
+3 -4
View File
@@ -19,12 +19,11 @@ Spelling fixes are most welcomed, and if you want to contribute longer sections
* For example, try to find short snippets that teaches people about the concept. If the example is also useful as-is (copy and paste), then great. Don't list long and similar examples just so people can use them on their sites.
* Hugo has users from all over the world, so easy to understand and [simple English](https://simple.wikipedia.org/wiki/Basic_English) is good.
## Edit the theme
If you want to do docs-related theme changes, the simplest way is to have both `hugoDocs` and `gohugoioTheme` cloned as sibling directories, and then run:
```
```sh
HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"
```
@@ -37,7 +36,7 @@ HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"
To view the documentation site locally, you need to clone this repository:
```bash
```sh
git clone https://github.com/gohugoio/hugoDocs.git
```
@@ -45,7 +44,7 @@ Also note that the documentation version for a given version of Hugo can also be
Then to view the docs in your browser, run Hugo and open up the link:
```bash
```sh
▶ hugo server
Started building sites ...
archetypes/functions.md
+3 -6
View File
@@ -1,14 +1,11 @@
---
title: {{ replace .File.ContentBaseName "-" " " | title }}
description:
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: []
related: []
returnType:
signatures: []
relatedFunctions: []
---
archetypes/methods.md
+10
View File
@@ -0,0 +1,10 @@
---
title: {{ replace .File.ContentBaseName "-" " " | title }}
description:
categories: []
keywords: []
action:
related: []
returnType:
signatures: []
---
archetypes/showcase/bio.md
+2 -3
View File
@@ -3,6 +3,5 @@ Add some **general info** about {{ replace .Name "-" " " | title }} here.
The site is built by:
* [Person 1](https://example.com)
* [Person 1](https://example.com)
* [Person 1](https://example.org)
* [Person 1](https://example.org)
assets/images/examples/zion-national-park-grayscale.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

assets/images/examples/zion-national-park.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

assets/images/logos/logo-128x128.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.6 KiB

assets/images/logos/logo-256x256.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.6 KiB

assets/images/logos/logo-512x512.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 72 KiB

assets/images/logos/logo-64x64.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.5 KiB

assets/images/logos/logo-96x96.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.6 KiB

config/_default/menus/menus.en.toml
+103 -93
View File
@@ -1,142 +1,152 @@
[[docs]]
name = "About Hugo"
weight = 10
identifier = "about"
url = "/about/"
identifier = 'about'
name = 'About Hugo'
pageRef = '/about/'
weight = 10
[[docs]]
name = "Installation"
weight = 20
identifier = "installation"
url = "/installation/"
name = 'Installation'
weight = 20
identifier = 'installation'
pageRef = '/installation/'
[[docs]]
name = "Getting started"
weight = 30
identifier = "getting-started"
url = "/getting-started/"
name = 'Getting started'
weight = 30
identifier = 'getting-started'
pageRef = '/getting-started/'
[[docs]]
name = "Hugo Modules"
weight = 40
identifier = "modules"
post = "break"
url = "/hugo-modules/"
# Core menus
name = 'Hugo Modules'
weight = 40
identifier = 'modules'
post = 'break'
pageRef = '/hugo-modules/'
[[docs]]
name = "Content management"
weight = 50
identifier = "content-management"
post = "expanded"
url = "/content-management/"
name = 'Content management'
weight = 50
identifier = 'content-management'
post = 'expanded'
pageRef = '/content-management/'
[[docs]]
name = "Templates"
weight = 60
identifier = "templates"
url = "/templates/"
name = 'Templates'
weight = 60
identifier = 'templates'
pageRef = '/templates/'
[[docs]]
name = "Functions"
weight = 70
identifier = "functions"
url = "/functions/"
name = 'Functions'
weight = 70
identifier = 'functions'
pageRef = '/functions/'
[[docs]]
name = "Variables"
weight = 80
identifier = "variables"
url = "/variables/"
name = 'Methods'
weight = 80
identifier = 'methods'
pageRef = '/methods/'
[[docs]]
name = "Hugo Pipes"
weight = 90
identifier = "hugo-pipes"
url = "/hugo-pipes/"
name = 'Quick reference'
weight = 90
identifier = 'quick-reference'
pageRef = '/quick-reference/'
[[docs]]
name = "CLI"
weight = 100
post = "break"
identifier = "commands"
url = "/commands/"
name = 'Variables'
weight = 95
identifier = 'variables'
pageRef = '/variables/'
[[docs]]
name = 'Hugo Pipes'
weight = 100
identifier = 'hugo-pipes'
pageRef = '/hugo-pipes/'
[[docs]]
name = 'CLI'
weight = 110
post = 'break'
identifier = 'commands'
pageRef = '/commands/'
# Low level items
[[docs]]
name = "Troubleshooting"
weight = 110
identifier = "troubleshooting"
url = "/troubleshooting/"
name = 'Troubleshooting'
weight = 120
identifier = 'troubleshooting'
pageRef = '/troubleshooting/'
[[docs]]
name = "Developer tools"
weight = 120
identifier = "developer-tools"
url = "/tools/"
name = 'Developer tools'
weight = 130
identifier = 'developer-tools'
pageRef = '/tools/'
[[docs]]
name = "Hosting and deployment"
weight = 130
identifier = "hosting-and-deployment"
url = "/hosting-and-deployment/"
name = 'Hosting and deployment'
weight = 140
identifier = 'hosting-and-deployment'
pageRef = '/hosting-and-deployment/'
[[docs]]
name = "Contribute"
weight = 140
post = "break"
identifier = "contribute"
url = "/contribute/"
name = 'Contribute'
weight = 150
post = 'break'
identifier = 'contribute'
pageRef = '/contribute/'
######## QUICKLINKS
[[quicklinks]]
name = "Fundamentals"
weight = 1
identifier = "fundamentals"
url = "/tags/fundamentals/"
identifier = 'fundamentals'
name = 'Fundamentals'
pageRef = '/tags/fundamentals/'
weight = 1
######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES
[[global]]
name = "News"
weight = 1
identifier = "news"
url = "/news/"
name = 'News'
weight = 1
identifier = 'news'
pageRef = '/news/'
[[global]]
name = "Docs"
weight = 5
identifier = "docs"
url = "/documentation/"
name = 'Docs'
weight = 5
identifier = 'docs'
url = '/documentation/'
[[global]]
name = "Themes"
weight = 10
identifier = "themes"
url = "https://themes.gohugo.io/"
name = 'Themes'
weight = 10
identifier = 'themes'
url = 'https://themes.gohugo.io/'
[[global]]
name = "Showcase"
weight = 20
identifier = "showcase"
url = "/showcase/"
name = 'Showcase'
weight = 20
identifier = 'showcase'
pageRef = '/showcase/'
# Anything with a weight > 100 gets an external icon
[[global]]
name = "Community"
weight = 150
icon = true
identifier = "community"
post = "external"
url = "https://discourse.gohugo.io/"
name = 'Community'
weight = 150
icon = true
identifier = 'community'
post = 'external'
url = 'https://discourse.gohugo.io/'
[[global]]
name = "GitHub"
weight = 200
identifier = "github"
post = "external"
url = "https://github.com/gohugoio/hugo"
name = 'GitHub'
weight = 200
identifier = 'github'
post = 'external'
url = 'https://github.com/gohugoio/hugo'
config/_default/params.toml
+3
View File
@@ -22,3 +22,6 @@ flex_box_interior_classes = "flex-auto w-100 w-40-l mr3 mb3 bg-white ba b--moon-
[social]
twitter = "GoHugoIO"
[render_hooks.link]
errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
content/en/about/hugo-and-gdpr.md
+4 -4
View File
@@ -29,7 +29,7 @@ toc: true
Below are all privacy settings and their default value. These settings need to be put in your site configuration (e.g. `hugo.toml`).
{{< code-toggle file="hugo" >}}
{{< code-toggle file=hugo >}}
[privacy]
[privacy.disqus]
disable = false
@@ -58,7 +58,7 @@ privacyEnhanced = false
An example privacy configuration that disables all the relevant services in Hugo. With this configuration, the other settings will not matter.
{{< code-toggle file="hugo" >}}
{{< code-toggle file=hugo >}}
[privacy]
[privacy.disqus]
disable = true
@@ -98,7 +98,7 @@ simple
**Note:** If you use the _simple mode_ for Instagram and a site styled with Bootstrap 4, you may want to disable the inline styles provided by Hugo:
{{< code-toggle file="hugo" >}}
{{< code-toggle file=hugo >}}
[services]
[services.instagram]
disableInlineCSS = true
@@ -114,7 +114,7 @@ simple
**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inline styles provided by Hugo:
{{< code-toggle file="hugo" >}}
{{< code-toggle file=hugo >}}
[services]
[services.twitter]
disableInlineCSS = true
content/en/about/license.md
+32 -112
View File
@@ -1,160 +1,80 @@
---
title: License
description: Hugo v0.15 and later are released under the Apache 2.0 license.
description: Hugo is released under the Apache 2.0 license.
categories: ["about hugo"]
keywords: ["License","apache"]
keywords: ["license","apache"]
menu:
docs:
parent: about
weight: 70
weight: 70
aliases: [/meta/license]
toc: true
---
{{% note %}}
Hugo v0.15 and later are released under the Apache 2.0 license.
Earlier versions of Hugo were released under the [Simple Public License](https://opensource.org/license/simpl-2-0-html/).
{{% /note %}}
## Apache License
_Version 2.0, January 2004_ <br>
<https://www.apache.org/licenses/LICENSE-2.0>
*Terms and Conditions for use, reproduction, and distribution*
_Version 2.0, January 2004_
_<http://www.apache.org/licenses/>_
## 1. Definitions
### Terms and Conditions for use, reproduction, and distribution
“License” shall mean the terms and conditions for use, reproduction, and
distribution as defined by Sections 1 through 9 of this document.
#### 1. Definitions
“Licensor” shall mean the copyright owner or entity authorized by the copyright
owner that is granting the License.
“License” shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
“Legal Entity” shall mean the union of the acting entity and all other entities
that control, are controlled by, or are under common control with that entity.
For the purposes of this definition, “control” means **(i)** the power, direct or
indirect, to cause the direction or management of such entity, whether by
contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the
outstanding shares, or **(iii)** beneficial ownership of such entity.
“Licensor” shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
“You” (or “Your”) shall mean an individual or Legal Entity exercising
permissions granted by this License.
“Legal Entity” shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, “control” means **(i)** the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the outstanding shares, or **(iii)** beneficial ownership of such entity.
“Source” form shall mean the preferred form for making modifications, including
but not limited to software source code, documentation source, and configuration
files.
“You” (or “Your”) shall mean an individual or Legal Entity exercising permissions granted by this License.
“Object” form shall mean any form resulting from mechanical transformation or
translation of a Source form, including but not limited to compiled object code,
generated documentation, and conversions to other media types.
“Source” form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
“Work” shall mean the work of authorship, whether in Source or Object form, made
available under the License, as indicated by a copyright notice that is included
in or attached to the work (an example is provided in the Appendix below).
“Object” form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
“Derivative Works” shall mean any work, whether in Source or Object form, that
is based on (or derived from) the Work and for which the editorial revisions,
annotations, elaborations, or other modifications represent, as a whole, an
original work of authorship. For the purposes of this License, Derivative Works
shall not include works that remain separable from, or merely link (or bind by
name) to the interfaces of, the Work and Derivative Works thereof.
“Work” shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
“Contribution” shall mean any work of authorship, including the original version
of the Work and any modifications or additions to that Work or Derivative Works
thereof, that is intentionally submitted to Licensor for inclusion in the Work
by the copyright owner or by an individual or Legal Entity authorized to submit
on behalf of the copyright owner. For the purposes of this definition,
“submitted” means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems, and
issue tracking systems that are managed by, or on behalf of, the Licensor for
the purpose of discussing and improving the Work, but excluding communication
that is conspicuously marked or otherwise designated in writing by the copyright
owner as “Not a Contribution.”
“Derivative Works” shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
“Contributor” shall mean Licensor and any individual or Legal Entity on behalf
of whom a Contribution has been received by Licensor and subsequently
incorporated within the Work.
“Contribution” shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, “submitted” means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as “Not a Contribution.”
## 2. Grant of Copyright License
“Contributor” shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the Work and such
Derivative Works in Source or Object form.
#### 2. Grant of Copyright License
## 3. Grant of Patent License
Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable (except as stated in this section) patent license to make, have
made, use, offer to sell, sell, import, and otherwise transfer the Work, where
such license applies only to those patent claims licensable by such Contributor
that are necessarily infringed by their Contribution(s) alone or by combination
of their Contribution(s) with the Work to which such Contribution(s) was
submitted. If You institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work or a
Contribution incorporated within the Work constitutes direct or contributory
patent infringement, then any patent licenses granted to You under this License
for that Work shall terminate as of the date such litigation is filed.
#### 3. Grant of Patent License
## 4. Redistribution
Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
You may reproduce and distribute copies of the Work or Derivative Works thereof
in any medium, with or without modifications, and in Source or Object form,
provided that You meet the following conditions:
#### 4. Redistribution
* **(a)** You must give any other recipients of the Work or Derivative Works a copy of
this License; and
* **(b)** You must cause any modified files to carry prominent notices stating that You
changed the files; and
* **\(c)** You must retain, in the Source form of any Derivative Works that You distribute,
all copyright, patent, trademark, and attribution notices from the Source form
of the Work, excluding those notices that do not pertain to any part of the
Derivative Works; and
You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
* **(a)** You must give any other recipients of the Work or Derivative Works a copy of this License; and
* **(b)** You must cause any modified files to carry prominent notices stating that You changed the files; and
* **(c)** You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
## 5. Submission of Contributions
#### 5. Submission of Contributions
Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
## 6. Trademarks
#### 6. Trademarks
This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
## 7. Disclaimer of Warranty
#### 7. Disclaimer of Warranty
Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
## 8. Limitation of Liability
#### 8. Limitation of Liability
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
## 9. Accepting Warranty or Additional Liability
#### 9. Accepting Warranty or Additional Liability
While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
_END OF TERMS AND CONDITIONS_
## APPENDIX: How to apply the Apache License to your work
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets `[]` replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same “printed page” as the copyright notice for easier identification within third-party archives.
{{< code file="apache-notice.txt" >}}
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
{{< /code >}}
content/en/content-management/_common/_index.md
+13
View File
@@ -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.
-->
layouts/shortcodes/page-kinds.html → content/en/content-management/_common/page-kinds.md
+10
View File
@@ -1,3 +1,7 @@
---
# Do not remove front matter.
---
| Kind | Description | Example |
|----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------|
| `home` | The landing page for the home page | `/index.html` |
@@ -5,3 +9,9 @@
| `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 >}}
content/en/content-management/archetypes.md
+13 -14
View File
@@ -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
```
content/en/content-management/build-options.md
+4 -4
View File
@@ -51,7 +51,7 @@ If set to `true` (default) the [Bundle's Resources](/content-management/page-bun
Setting this to `false` will still publish Resources on demand (when a resource's `.Permalink` or `.RelPermalink` is invoked from the templates) but will skip the others.
{{% note %}}
Any page, regardless of their build options, will always be available using the [`.GetPage`](/functions/getpage) methods.
Any page, regardless of their build options, will always be available using the [`.GetPage`](/methods/page/getpage) methods.
{{% /note %}}
### Illustrative use cases
@@ -60,14 +60,14 @@ Any page, regardless of their build options, will always be available using the
Project needs a "Who We Are" content file for front matter and body to be used by the homepage but nowhere else.
{{< code-toggle file="content/who-we-are.md" fm=true copy=false >}}
{{< code-toggle file="content/who-we-are.md" fm=true >}}
title: Who we are
_build:
list: false
render: false
{{< /code-toggle >}}
{{< code file="layouts/index.html" copy=false >}}
{{< code file="layouts/index.html" >}}
<section id="who-we-are">
{{ with site.GetPage "who-we-are" }}
{{ .Content }}
@@ -91,7 +91,7 @@ cascade:
list: true # default
{{< /code-toggle >}}
{{< code file="layouts/_defaults/testimonials.html" copy=false >}}
{{< code file="layouts/_defaults/testimonials.html" >}}
<section id="testimonials">
{{ range first 5 .Pages }}
<blockquote cite="{{ .Params.cite }}">
content/en/content-management/comments.md
+2 -3
View File
@@ -24,9 +24,8 @@ Hugo comes with all the code you need to load Disqus into your templates. Before
Disqus comments require you set a single value in your [site's configuration file][configuration] like so:
{{< code-toggle file="hugo" >}}
[services.disqus]
shortname = 'your-disqus-shortname'
{{< code-toggle file=hugo >}}
disqusShortname = "yourDisqusShortname"
{{</ code-toggle >}}
For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter] of a single content file:
content/en/content-management/cross-references.md
+1 -3
View File
@@ -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/
content/en/content-management/diagrams.md
-3
View File
@@ -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>
content/en/content-management/formats.md
+2 -3
View File
@@ -24,7 +24,7 @@ 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/).|
| 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.|
@@ -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
content/en/content-management/front-matter.md
+5 -6
View File
@@ -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.
@@ -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"
@@ -191,7 +191,7 @@ Any of the above can be omitted.
In `content/blog/_index.md`
{{< code-toggle copy=false >}}
{{< code-toggle >}}
title: Blog
cascade:
banner: images/typewriter.jpg
@@ -219,13 +219,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/
content/en/content-management/image-processing/index.md
+18 -21
View File
@@ -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" }}
@@ -112,7 +113,7 @@ Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. U
{{< 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.
@@ -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
@@ -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 %}}
@@ -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 = ""
@@ -487,9 +484,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 +494,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
```
content/en/content-management/menus.md
+7 -8
View File
@@ -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'
content/en/content-management/multilingual.md
+20 -21
View File
@@ -25,7 +25,7 @@ This is the default language configuration:
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
@@ -104,7 +104,7 @@ In Hugo `v0.112.0` we consolidated all configuration options, and improved how t
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,7 +183,7 @@ 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:
@@ -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 >}}
@@ -427,7 +427,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 +530,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 +538,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 +583,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 +594,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 +624,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 +639,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 +663,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 +677,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
```
content/en/content-management/organization/index.md
+12 -19
View File
@@ -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/
content/en/content-management/page-bundles.md
+10 -12
View File
@@ -48,14 +48,14 @@ 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
@@ -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
content/en/content-management/page-resources.md
+3 -3
View File
@@ -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"
content/en/content-management/related.md
+10 -8
View File
@@ -33,16 +33,19 @@ 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:
@@ -57,7 +60,7 @@ 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
@@ -66,7 +69,7 @@ We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 di
Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration:
{{< 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 >}}
@@ -146,7 +149,6 @@ applyFilter
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.
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.
content/en/content-management/sections.md
+31 -33
View File
@@ -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.
@@ -108,7 +108,6 @@ If you need to use a different template for a subsection, specify `type` and/or
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
```
@@ -122,11 +121,11 @@ For example, use the `.Ancestors` method to render breadcrumb navigation.
<ol>
{{ range .Ancestors.Reverse }}
<li>
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
<a href="{{ .Permalink }}">{{ .Title }}</a>
</li>
{{ end }}
<li class="active">
<a aria-current="page" href="{{ .Permalink }}">{{ .LinkTitle }}</a>
<a aria-current="page" href="{{ .Permalink }}">{{ .Title }}</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/
content/en/content-management/shortcodes.md
+10 -12
View File
@@ -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:
@@ -172,7 +171,7 @@ To display a highlighted code sample:
```text
{{</* highlight go-html-template */>}}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}
{{</* /highlight */>}}
```
@@ -181,7 +180,7 @@ Rendered:
{{< highlight go-html-template >}}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}
{{< /highlight >}}
@@ -192,7 +191,7 @@ To specify one or more [highlighting options], include a quotation-encapsulated,
```text
{{</* highlight go-html-template "lineNos=inline, lineNoStart=42" */>}}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}
{{</* /highlight */>}}
```
@@ -201,7 +200,7 @@ Rendered:
{{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}
{{< /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>
```
@@ -355,7 +354,6 @@ Copy the YouTube video ID that follows `v=` in the video's URL and pass it to th
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" >}}
{{</* 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/
content/en/content-management/static-files.md
+2 -2
View File
@@ -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"
content/en/content-management/summaries.md
+2 -2
View File
@@ -53,7 +53,7 @@ Pros
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/).
{{% warning "Be Precise with the Summary Divider" %}}
{{% note %}}
Be careful to enter <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> exactly; i.e., all lowercase and with no whitespace.
{{% /note %}}
@@ -75,7 +75,7 @@ Because there are multiple ways in which a summary can be specified it is useful
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" %}}
{{% 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 <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider Hugo will use the manual summary split method.
{{% /note %}}
content/en/content-management/syntax-highlighting.md
+1 -2
View File
@@ -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
```
@@ -104,7 +104,6 @@ Highlighting in code fences is enabled by default.
```
````
Gives this:
```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
content/en/content-management/taxonomies.md
+7 -20
View File
@@ -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:
@@ -86,11 +85,11 @@ Without adding a single line to your [site configuration] file, Hugo will automa
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 >}}
content/en/content-management/toc.md
+3 -2
View File
@@ -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`.
@@ -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
content/en/content-management/urls.md
+17 -17
View File
@@ -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>
content/en/contribute/development.md
+1 -1
View File
@@ -313,7 +313,7 @@ git commit --amend
#### Modify multiple commits
{{% warning "Be Careful Modifying Multiple Commits"%}}
{{% note %}}
Modifications such as those described in this section can have serious unintended consequences. Skip this section if you're not sure!
{{% /note %}}
content/en/contribute/documentation.md
+4 -4
View File
@@ -24,7 +24,7 @@ Step 2
Step 3
: Create a new branch with a descriptive name.
```bash
```sh
git checkout -b fix/typos-site-variables
```
@@ -34,7 +34,7 @@ Step 4
Step 5
: Commit your changes with a descriptive commit message, typically 50 characters or less. Included the "Closes" keyword if your change addresses one or more open [issues].
```bash
```sh
git commit -m "Fix typos on site variables page
Closes #1234
@@ -128,7 +128,7 @@ fm
#### Site configuration example
```text
{{</* code-toggle file="hugo" */>}}
{{</* code-toggle file=hugo */>}}
baseURL = 'https://example.org'
languageCode = 'en-US'
title = "Example Site"
@@ -137,7 +137,7 @@ title = "Example Site"
Rendered:
{{< code-toggle file="hugo" >}}
{{< code-toggle file=hugo >}}
baseURL = 'https://example.org'
languageCode = 'en-US'
title = "Example Site"
content/en/documentation.md
+9 -1
View File
@@ -9,6 +9,14 @@ weight: 1
layout: documentation-home
---
Hugo is the **world's fastest static website engine.** It's written in Go (aka Golang) and developed by [bep](https://github.com/bep), [spf13](https://github.com/spf13) and [friends](https://github.com/gohugoio/hugo/graphs/contributors).
A fast and flexible [static site generator] built with love by [bep], [spf13], and [friends] in [Go].
Hugo is optimized for speed and designed for flexibility. With its advanced templating system and fast asset pipelines, Hugo renders a complete site in seconds, often less.
[bep]: https://github.com/bep
[spf13]: https://github.com/spf13
[friends]: https://github.com/gohugoio/hugo/graphs/contributors
[go]: https://go.dev/
[static site generator]: https://en.wikipedia.org/wiki/Static_site_generator
Below you will find some of the most common and helpful pages from our documentation.
content/en/functions/Get.md
-26
View File
@@ -1,26 +0,0 @@
---
title: .Get
description: Accesses positional and ordered parameters in shortcode declaration.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
returnType: any
signatures:
- .Get INDEX
- .Get KEY
relatedFunctions: []
---
`.Get` is specifically used when creating your own [shortcode template][sc], to access the [positional and named](/templates/shortcode-templates/#positional-vs-named-parameters) parameters passed to it. When used with a numeric INDEX, it queries positional parameters (starting with 0). With a string KEY, it queries named parameters.
When accessing named or positional parameters that do not exist, `.Get` returns an empty string instead of interrupting the build. This allows you to chain `.Get` with `if`, `with`, `default` or `cond` to check for parameter existence. For example:
```go-html-template
{{ $quality := default "100" (.Get 1) }}
```
[sc]: /templates/shortcode-templates/
content/en/functions/GetPage.md
-84
View File
@@ -1,84 +0,0 @@
---
title: .GetPage
description: Gets a `Page` of a given `path`.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
returnType:
signatures: [.GetPage PATH]
relatedFunctions: []
---
`.GetPage` returns a page of a given `path`. Both `Site` and `Page` implements this method. The `Page` variant will, if given a relative path -- i.e. a path without a leading `/` -- try look for the page relative to the current page.
{{% note %}}
**Note:** We overhauled and simplified the `.GetPage` API in Hugo 0.45. Before that you needed to provide a `Kind` attribute in addition to the path, e.g. `{{ .Site.GetPage "section" "blog" }}`. This will still work, but is now superfluous.
{{% /note %}}
```go-html-template
{{ with .Site.GetPage "/blog" }}{{ .Title }}{{ end }}
```
This method will return `nil` when no page could be found, so the above will not print anything if the blog section is not found.
To find a regular page in the blog section::
```go-html-template
{{ with .Site.GetPage "/blog/my-post.md" }}{{ .Title }}{{ end }}
```
And since `Page` also provides a `.GetPage` method, the above is the same as:
```go-html-template
{{ with .Site.GetPage "/blog" }}
{{ with .GetPage "my-post.md" }}{{ .Title }}{{ end }}
{{ end }}
```
## .GetPage and multilingual sites
The previous examples have used the full content file name to look up the post. Depending on how you have organized your content (whether you have the language code in the file name or not, e.g. `my-post.en.md`), you may want to do the lookup without extension. This will get you the current language's version of the page:
```go-html-template
{{ with .Site.GetPage "/blog/my-post" }}{{ .Title }}{{ end }}
```
## .GetPage example
This code snippet---in the form of a [partial template][partials]---allows you to do the following:
1. Grab the index object of your `tags` [taxonomy].
2. Assign this object to a variable, `$t`
3. Sort the terms associated with the taxonomy by popularity.
4. Grab the top two most popular terms in the taxonomy (i.e., the two most popular tags assigned to content.
{{< code file="grab-top-two-tags.html" >}}
<ul class="most-popular-tags">
{{ $t := .Site.GetPage "/tags" }}
{{ range first 2 $t.Data.Terms.ByCount }}
<li>{{ . }}</li>
{{ end }}
</ul>
{{< /code >}}
## `.GetPage` on page bundles
If the page retrieved by `.GetPage` is a [Leaf Bundle][leaf_bundle], and you
need to get the nested _**page** resources_ in that, you will need to use the
methods in `.Resources` as explained in the [Page Resources][page_resources]
section.
See the [Headless Bundle][headless_bundle] documentation for an example.
[partials]: /templates/partials/
[taxonomy]: /content-management/taxonomies/
[page_kinds]: /templates/section-templates/#page-kinds
[leaf_bundle]: /content-management/page-bundles/#leaf-bundles
[headless_bundle]: /content-management/page-bundles/#headless-bundle
[page_resources]: /content-management/page-resources/
content/en/functions/Param.md
-50
View File
@@ -1,50 +0,0 @@
---
title: .Param
description: Returns a page parameter, falling back to a site parameter if present.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
returnType: any
signatures: [.Param KEY]
relatedFunctions: []
---
The `.Param` method on `.Page` looks for the given `KEY` in page parameters, and returns the corresponding value. If it cannot find the `KEY` in page parameters, it looks for the `KEY` in site parameters. If it cannot find the `KEY` in either location, the `.Param` method returns `nil`.
Site and theme developers commonly set parameters at the site level, allowing content authors to override those parameters at the page level.
For example, to show a table of contents on every page, but allow authors to hide the table of contents as needed:
**Configuration**
{{< code-toggle file="hugo" copy=false >}}
[params]
display_toc = true
{{< /code-toggle >}}
**Content**
{{< code-toggle file="content/example.md" fm=true copy=false >}}
title = 'Example'
date = 2023-01-01
draft = false
display_toc = false
{{< /code-toggle >}}
**Template**
{{< code file="layouts/_default/single.html" copy=false >}}
{{ if .Param "display_toc" }}
{{ .TableOfContents }}
{{ end }}
{{< /code >}}
The `.Param` method returns the value associated with the given `KEY`, regardless of whether the value is truthy or falsy. If you need to ignore falsy values, use this construct instead:
{{< code file="layouts/_default/single.html" copy=false >}}
{{ or .Params.foo site.Params.foo }}
{{< /code >}}
content/en/functions/Render.md
-28
View File
@@ -1,28 +0,0 @@
---
title: .Render
description: Takes a view to apply when rendering content.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
returnType: template.HTML
signatures: [.Render LAYOUT]
relatedFunctions: []
---
The view is an alternative layout and should be a file name that points to a template in one of the locations specified in the documentation for [Content Views](/templates/views).
This function is only available when applied to a single piece of content within a [list context].
This example could render a piece of content using the content view located at `/layouts/_default/summary.html`:
```go-html-template
{{ range .Pages }}
{{ .Render "summary" }}
{{ end }}
```
[list context]: /templates/lists/
content/en/functions/RenderString.md
-35
View File
@@ -1,35 +0,0 @@
---
title: .RenderString
description: Renders markup to HTML.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
returnType: template.HTML
signatures: ['.RenderString MARKUP [OPTIONS]']
---
`.RenderString` is a method on `Page` that renders some markup to HTML using the content renderer defined for that page (if not set in the options).
The method takes an optional map argument with these options:
display ("inline")
: `inline` or `block`. If `inline` (default), surrounding `<p></p>` on short snippets will be trimmed.
markup (defaults to the Page's markup)
: See identifiers in [List of content formats](/content-management/formats/#list-of-content-formats).
Some examples:
```go-html-template
{{ $optBlock := dict "display" "block" }}
{{ $optOrg := dict "markup" "org" }}
{{ "**Bold Markdown**" | $p.RenderString }}
{{ "**Bold Block Markdown**" | $p.RenderString $optBlock }}
{{ "/italic org mode/" | $p.RenderString $optOrg }}
```
{{< new-in "0.93.0" >}} **Note**: [markdownify](/functions/transform/markdownify) uses this function in order to support [Render Hooks](/getting-started/configuration-markup/#markdown-render-hooks).
content/en/functions/Scratch.md
-151
View File
@@ -1,151 +0,0 @@
---
title: .Scratch
description: Acts as a "scratchpad" to store and manipulate data.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
returnType:
signatures: []
relatedFunctions:
- .Store
- .Scratch
aliases: [/extras/scratch/,/doc/scratch/]
---
Scratch is a Hugo feature designed to conveniently manipulate data in a Go Template world. It is either a Page or Shortcode method for which the resulting data will be attached to the given context, or it can live as a unique instance stored in a variable.
{{% note %}}
Note that Scratch was initially created as a workaround for a [Go template scoping limitation](https://github.com/golang/go/issues/10608) that affected Hugo versions prior to 0.48. For a detailed analysis of `.Scratch` and contextual use cases, see [this blog post](https://regisphilibert.com/blog/2017/04/hugo-scratch-explained-variable/).
{{% /note %}}
### Contexted `.Scratch` vs. local `newScratch`
Since Hugo 0.43, there are two different ways of using Scratch:
#### The Page's `.Scratch`
`.Scratch` is available as a Page method or a Shortcode method and attaches the "scratched" data to the given page. Either a Page or a Shortcode context is required to use `.Scratch`.
```go-html-template
{{ .Scratch.Set "greeting" "bonjour" }}
{{ range .Pages }}
{{ .Scratch.Set "greeting" (print "bonjour" .Title) }}
{{ end }}
```
#### The local `newScratch`
A Scratch instance can also be assigned to any variable using the `newScratch` function. In this case, no Page or Shortcode context is required and the scope of the scratch is only local. The methods detailed below are available from the variable the Scratch instance was assigned to.
```go-html-template
{{ $data := newScratch }}
{{ $data.Set "greeting" "hola" }}
```
### Methods
A Scratch has the following methods:
{{% note %}}
Note that the following examples assume a [local Scratch instance](#the-local-newscratch) has been stored in `$scratch`.
{{% /note %}}
#### .Set
Set the value of a given key.
```go-html-template
{{ $scratch.Set "greeting" "Hello" }}
```
#### .Get
Get the value of a given key.
```go-html-template
{{ $scratch.Set "greeting" "Hello" }}
----
{{ $scratch.Get "greeting" }} > Hello
```
#### .Add
Add a given value to existing value(s) of the given key.
For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be [appended](/functions/collections/append/) to that list.
```go-html-template
{{ $scratch.Add "greetings" "Hello" }}
{{ $scratch.Add "greetings" "Welcome" }}
----
{{ $scratch.Get "greetings" }} > HelloWelcome
```
```go-html-template
{{ $scratch.Add "total" 3 }}
{{ $scratch.Add "total" 7 }}
----
{{ $scratch.Get "total" }} > 10
```
```go-html-template
{{ $scratch.Add "greetings" (slice "Hello") }}
{{ $scratch.Add "greetings" (slice "Welcome" "Cheers") }}
----
{{ $scratch.Get "greetings" }} > []interface {}{"Hello", "Welcome", "Cheers"}
```
#### .SetInMap
Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
```go-html-template
{{ $scratch.SetInMap "greetings" "english" "Hello" }}
{{ $scratch.SetInMap "greetings" "french" "Bonjour" }}
----
{{ $scratch.Get "greetings" }} > map[french:Bonjour english:Hello]
```
#### .DeleteInMap
Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
```go-html-template
{{ .Scratch.SetInMap "greetings" "english" "Hello" }}
{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
----
{{ .Scratch.DeleteInMap "greetings" "english" }}
----
{{ .Scratch.Get "greetings" }} > map[french:Bonjour]
```
#### .GetSortedMapValues
Return an array of values from `key` sorted by `mapKey`.
```go-html-template
{{ $scratch.SetInMap "greetings" "english" "Hello" }}
{{ $scratch.SetInMap "greetings" "french" "Bonjour" }}
----
{{ $scratch.GetSortedMapValues "greetings" }} > [Hello Bonjour]
```
#### .Delete
Remove the given key.
```go-html-template
{{ $scratch.Set "greeting" "Hello" }}
----
{{ $scratch.Delete "greeting" }}
```
#### .Values
Return the raw backing map. Note that you should only use this method on the locally scoped Scratch instances you obtain via [`newScratch`](#the-local-newscratch), not `.Page.Scratch` etc., as that will lead to concurrency issues.
[pagevars]: /variables/page/
content/en/functions/Store.md
-111
View File
@@ -1,111 +0,0 @@
---
title: .Store
description: Returns a Scratch that is not reset on server rebuilds.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
returnType:
signatures: []
relatedFunctions:
- .Store
- .Scratch
---
The `.Store` method on `.Page` returns a [Scratch] to store and manipulate data. In contrast to the `.Scratch` method, this Scratch is not reset on server rebuilds.
[Scratch]: /functions/scratch/
### Methods
#### .Set
Sets the value of a given key.
```go-html-template
{{ .Store.Set "greeting" "Hello" }}
```
#### .Get
Gets the value of a given key.
```go-html-template
{{ .Store.Set "greeting" "Hello" }}
{{ .Store.Get "greeting" }} → Hello
```
#### .Add
Adds a given value to existing value(s) of the given key.
For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
```go-html-template
{{ .Store.Add "greetings" "Hello" }}
{{ .Store.Add "greetings" "Welcome" }}
{{ .Store.Get "greetings" }} → HelloWelcome
```
```go-html-template
{{ .Store.Add "total" 3 }}
{{ .Store.Add "total" 7 }}
{{ .Store.Get "total" }} → 10
```
```go-html-template
{{ .Store.Add "greetings" (slice "Hello") }}
{{ .Store.Add "greetings" (slice "Welcome" "Cheers") }}
{{ .Store.Get "greetings" }} → []interface {}{"Hello", "Welcome", "Cheers"}
```
#### .SetInMap
Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
```go-html-template
{{ .Store.SetInMap "greetings" "english" "Hello" }}
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
{{ .Store.Get "greetings" }} → map[french:Bonjour english:Hello]
```
#### .DeleteInMap
Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
```go-html-template
{{ .Store.SetInMap "greetings" "english" "Hello" }}
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
{{ .Store.DeleteInMap "greetings" "english" }}
{{ .Store.Get "greetings" }} → map[french:Bonjour]
```
#### .GetSortedMapValues
Returns an array of values from `key` sorted by `mapKey`.
```go-html-template
{{ .Store.SetInMap "greetings" "english" "Hello" }}
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
{{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
```
#### .Delete
Removes the given key.
```go-html-template
{{ .Store.Set "greeting" "Hello" }}
{{ .Store.Delete "greeting" }}
```
content/en/functions/Unix.md
-36
View File
@@ -1,36 +0,0 @@
---
title: .Unix
description: Converts a time.Time value to the number of seconds elapsed since the Unix epoch, excluding leap seconds. The Unix epoch is 00:00:00&nbsp;UTC on 1 January 1970.
categories: [functions]
menu:
docs:
parent: functions
function:
aliases: []
returnType: int64
signatures:
- .Unix
- .UnixMilli
- .UnixMicro
- .UnixNano
relatedFunctions: []
---
The `Milli`, `Micro`, and `Nano` variants return the number of milliseconds, microseconds, and nanoseconds (respectively) elapsed since the Unix epoch.
```go-html-template
.Date.Unix → 1637259694
.ExpiryDate.Unix → 1672559999
.Lastmod.Unix → 1637361786
.PublishDate.Unix → 1637421261
("1970-01-01T00:00:00-00:00" | time.AsTime).Unix → 0
("1970-01-01T00:00:42-00:00" | time.AsTime).Unix → 42
("1970-04-11T01:48:29-08:00" | time.AsTime).Unix → 8675309
("2026-05-02T20:09:31-07:00" | time.AsTime).Unix → 1777777771
now.Unix → 1637447841
now.UnixMilli → 1637447841347
now.UnixMicro → 1637447841347378
now.UnixNano → 1637447841347378799
```
content/en/functions/_common/_index.md
+13
View File
@@ -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.
-->
content/en/functions/_common/glob-patterns.md
+23
View File
@@ -0,0 +1,23 @@
---
# Do not remove front matter.
---
Path|Pattern|Match
:--|:--|:--
`images/foo/a.jpg`|`images/foo/*.jpg`|`true`
`images/foo/a.jpg`|`images/foo/*.*`|`true`
`images/foo/a.jpg`|`images/foo/*`|`true`
`images/foo/a.jpg`|`images/*/*.jpg`|`true`
`images/foo/a.jpg`|`images/*/*.*`|`true`
`images/foo/a.jpg`|`images/*/*`|`true`
`images/foo/a.jpg`|`*/*/*.jpg`|`true`
`images/foo/a.jpg`|`*/*/*.*`|`true`
`images/foo/a.jpg`|`*/*/*`|`true`
`images/foo/a.jpg`|`**/*.jpg`|`true`
`images/foo/a.jpg`|`**/*.*`|`true`
`images/foo/a.jpg`|`**/*`|`true`
`images/foo/a.jpg`|`**`|`true`
`images/foo/a.jpg`|`*/*.jpg`|`false`
`images/foo/a.jpg`|`*.jpg`|`false`
`images/foo/a.jpg`|`*.*`|`false`
`images/foo/a.jpg`|`*`|`false`
content/en/functions/_common/go-template-functions.md
-3
View File
@@ -1,3 +0,0 @@
See Go's [text/template] documentation for more details.
[text/template]: https://pkg.go.dev/text/template
content/en/functions/_common/index.md
-3
View File
@@ -1,3 +0,0 @@
+++
headless = true
+++
content/en/functions/_common/locales.md
+7
View File
@@ -1,3 +1,10 @@
---
# Do not remove front matter.
---
{{% note %}}
Localization of dates, currencies, numbers, and percentages is performed by the [gohugoio/locales] package. The language tag of the current site must match one of the listed locales.
[gohugoio/locales]: https://github.com/gohugoio/locales
{{% /note %}}
content/en/functions/_common/regular-expressions.md
+4
View File
@@ -1,3 +1,7 @@
---
# Do not remove front matter.
---
When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes.
Go's regular expression package implements the [RE2 syntax]. The RE2 syntax is a subset of that accepted by [PCRE], roughly speaking, and with various [caveats]. Note that the RE2 `\C` escape sequence is not supported.
content/en/functions/_common/time-layout-string.md
+7 -3
View File
@@ -1,12 +1,16 @@
---
# Do not remove front matter.
---
Format a `time.Time` value based on [Go's reference time]:
[Go's reference time]: https://pkg.go.dev/time#pkg-constants
```text {copy=false}
```text
Mon Jan 2 15:04:05 MST 2006
```
Create a format string using these components:
Create a layout string using these components:
Description|Valid components
:--|:--
@@ -21,7 +25,7 @@ Second|`"5" "05"`
AM/PM mark|`"PM"`
Time zone offsets|`"-0700" "-07:00" "-07" "-070000" "-07:00:00"`
Replace the sign in the format string with a Z to print Z instead of an offset for the UTC zone.
Replace the sign in the layout string with a Z to print Z instead of an offset for the UTC zone.
Description|Valid components
:--|:--
content/en/functions/_index.md
+4 -4
View File
@@ -1,7 +1,8 @@
---
title: Functions
linkTitle: Overview
description: Comprehensive list of Hugo templating functions, including basic and advanced usage examples.
description: A list of Hugo template functions including examples.
categories: []
keywords: []
menu:
docs:
@@ -9,9 +10,8 @@ menu:
parent: functions
weight: 10
weight: 10
showSectionMenu: true
aliases: [/layout/functions/,/templates/functions]
---
Go templates are lightweight but extensible. Go itself supplies built-in functions, including comparison operators and other basic tools. These are listed in the [Go template documentation][gofuncs]. Hugo has added additional functions to the basic template logic.
[gofuncs]: https://golang.org/pkg/text/template/#hdr-Functions
Use these functions within your templates and archetypes.
content/en/functions/cast/ToFloat.md
+6 -11
View File
@@ -1,20 +1,15 @@
---
title: cast.ToFloat
linkTitle: float
description: Casts a value to a decimal (base 10) floating point value.
categories: [functions]
description: Converts a value to a decimal floating-point number (base 10).
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [float]
related:
- functions/cast/ToInt
- functions/cast/ToString
returnType: float64
signatures: [cast.ToFloat INPUT]
relatedFunctions:
- cast.ToFloat
- cast.ToInt
- cast.ToString
aliases: [/functions/float]
---
content/en/functions/cast/ToInt.md
+9 -15
View File
@@ -1,20 +1,14 @@
---
title: cast.ToInt
linkTitle: int
description: Casts a value to a decimal (base 10) integer.
categories: [functions]
description: Converts a value to a decimal integer (base 10).
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [int]
related:
- functions/cast/ToFloat
- functions/cast/ToString
returnType: int
signatures: [cast.ToInt INPUT]
relatedFunctions:
- cast.ToFloat
- cast.ToInt
- cast.ToString
signatures: [cast/ToInt INPUT]
aliases: [/functions/int]
---
@@ -24,8 +18,8 @@ With a decimal (base 10) input:
{{ int 11 }} → 11 (int)
{{ int "11" }} → 11 (int)
{{ int 11.1 }} → 11 (int)
{{ int 11.9 }} → 11 (int)
{{ int 11/1 }} → 11 (int)
{{ int 11/9 }} → 11 (int)
```
With a binary (base 2) input:
@@ -55,5 +49,5 @@ With a hexadecimal (base 16) input:
{{% note %}}
Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros:
`{{ strings.TrimLeft "0" "0011" | int }} → 11`
`{{ strings/TrimLeft "0" "0011" | int }} → 11`
{{% /note %}}
content/en/functions/cast/ToString.md
+6 -11
View File
@@ -1,20 +1,15 @@
---
title: cast.ToString
linkTitle: string
description: Cast a value to a string.
categories: [functions]
description: Converts a value to a string.
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [string]
related:
- functions/cast/ToFloat
- functions/cast/ToInt
returnType: string
signatures: [cast.ToString INPUT]
relatedFunctions:
- cast.ToFloat
- cast.ToInt
- cast.ToString
aliases: [/functions/string]
---
content/en/functions/cast/_index.md
+12
View File
@@ -0,0 +1,12 @@
---
title: Cast functions
linkTitle: cast
description: Template functions to cast a value from one data type to another.
categories: []
keywords: []
menu:
docs:
parent: functions
---
Use these functions to cast a value from one data type to another.
content/en/functions/collections/After.md
+24 -29
View File
@@ -1,20 +1,15 @@
---
title: collections.After
linkTitle: after
description: Slices an array to the items after the Nth item.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [after]
related:
- functions/collections/First
- functions/collections/Last
returnType: any
signatures: [collections.After INDEX COLLECTION]
relatedFunctions:
- collections.After
- collections.First
- collections.Last
aliases: [/functions/after]
---
@@ -37,30 +32,30 @@ You can use `after` in combination with the [`first`] function and Hugo's [power
{{< code file="layouts/section/articles.html" >}}
{{ define "main" }}
<section class="row featured-article">
<h2>Featured Article</h2>
{{ range first 1 .Pages.ByPublishDate.Reverse }}
<header>
<section class="row featured-article">
<h2>Featured Article</h2>
{{ range first 1 .Pages.ByPublishDate.Reverse }}
<header>
<h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3>
</header>
<p>{{ .Description }}</p>
{{ end }}
</section>
<div class="row recent-articles">
<h2>Recent Articles</h2>
{{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
<section class="recent-article">
<header>
<h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3>
</header>
<p>{{ .Description }}</p>
</section>
</header>
<p>{{ .Description }}</p>
{{ end }}
</div>
</section>
<div class="row recent-articles">
<h2>Recent Articles</h2>
{{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
<section class="recent-article">
<header>
<h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3>
</header>
<p>{{ .Description }}</p>
</section>
{{ end }}
</div>
{{ end }}
{{< /code >}}
[`first`]: /functions/collections/first
[list/section page]: /templates/section-templates
[lists]: /templates/lists/#order-content
[lists]: /templates/lists/#sort-content
[`slice`]: /functions/collections/slice/
content/en/functions/collections/Append.md
+7 -12
View File
@@ -1,22 +1,17 @@
---
title: collections.Append
linkTitle: append
description: Appends one or more elements to a slice and returns the resulting slice.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [append]
related:
- functions/collections/Merge
- functions/collections/Slice
returnType: any
signatures:
- COLLECTION | collections.Append ELEMENT [ELEMENT]...
- COLLECTION | collections.Append ELEMENT [ELEMENT...]
- COLLECTION | collections.Append COLLECTION
relatedFunctions:
- collections.Append
- collections.Merge
- collections.Slice
aliases: [/functions/append]
---
@@ -100,7 +95,7 @@ Although the elements in the examples above are strings, you can use the `append
{{ with $p }}
<ul>
{{ range . }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
{{ end }}
</ul>
{{ end }}
content/en/functions/collections/Apply.md
+2 -8
View File
@@ -1,18 +1,13 @@
---
title: collections.Apply
linkTitle: apply
description: Returns a new collection with each element transformed by the given function.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [apply]
returnType: '[]any'
signatures: [collections.Apply COLLECTION FUNCTION PARAM...]
relatedFunctions:
- collections.Apply
- collections.Delimit
- collections.In
- collections.Reverse
@@ -25,7 +20,6 @@ The `apply` function takes three or more arguments, depending on the function be
The first argument is the collection itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the collection element.
```go-html-template
{{ $s := slice "hello" "world" }}
content/en/functions/collections/Complement.md
+10 -16
View File
@@ -1,21 +1,16 @@
---
title: collections.Complement
linkTitle: complement
description: Returns the elements of the last collection that are not in any of the others.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [complement]
related:
- functions/collections/Intersect
- functions/collections/SymDiff
- functions/collections/Union
returnType: any
signatures: ['collections.Complement COLLECTION [COLLECTION]...']
relatedFunctions:
- collections.Complement
- collections.Intersect
- collections.SymDiff
- collections.Union
signatures: ['collections.Complement COLLECTION [COLLECTION...]']
aliases: [/functions/complement]
---
@@ -35,7 +30,6 @@ Make your code simpler to understand by using a [chained pipeline]:
[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines
{{% /note %}}
```go-html-template
{{ $c3 | complement $c1 $c2 }} → [1 2]
```
@@ -57,7 +51,7 @@ To list everything except blog articles (`blog`) and frequently asked questions
{{ $blog := where site.RegularPages "Type" "blog" }}
{{ $faqs := where site.RegularPages "Type" "faqs" }}
{{ range site.RegularPages | complement $blog $faqs }}
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
<a href="{{ .RelPermalink }}">{{ .Title }}</a>
{{ end }}
```
@@ -65,11 +59,11 @@ To list everything except blog articles (`blog`) and frequently asked questions
Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
[`where`]: /functions/collections/where
{{% /note %}}
{{% /note %}}
```go-html-template
{{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }}
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
<a href="{{ .RelPermalink }}">{{ .Title }}</a>
{{ end }}
```
content/en/functions/collections/Delimit.md
+14 -19
View File
@@ -1,24 +1,19 @@
---
title: collections.Delimit
linkTitle: delimit
description: Loops through any array, slice, or map and returns a string of all the values separated by a delimiter.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [delimit]
returnType: template.HTML
related:
- functions/collections/Apply
- functions/collections/In
- functions/collections/Reverse
- functions/collections/Seq
- functions/collections/Slice
- functions/strings/Split
returnType: string
signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]']
relatedFunctions:
- collections.Apply
- collections.Delimit
- collections.In
- collections.Reverse
- collections.Seq
- collections.Slice
- strings.Split
aliases: [/functions/delimit]
---
@@ -26,8 +21,8 @@ Delimit a slice:
```go-html-template
{{ $s := slice "b" "a" "c" }}
{{ delimit $s ", " }} → "b, a, c"
{{ delimit $s ", " " and "}} → "b, a and c"
{{ delimit $s ", " }} → b, a, c
{{ delimit $s ", " " and "}} → b, a and c
```
Delimit a map:
@@ -38,6 +33,6 @@ The `delimit` function sorts maps by key, returning the values.
```go-html-template
{{ $m := dict "b" 2 "a" 1 "c" 3 }}
{{ delimit $m ", " }} → "1, 2, 3"
{{ delimit $m ", " " and "}} → "1, 2 and 3"
{{ delimit $m ", " }} → 1, 2, 3
{{ delimit $m ", " " and "}} → 1, 2 and 3
```
content/en/functions/collections/Dictionary.md
+22 -14
View File
@@ -1,22 +1,17 @@
---
title: collections.Dictionary
linkTitle: dict
description: Creates a map from a list of key and value pairs.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [dict]
related:
- functions/collections/Group
- functions/collections/IndexFunction
- functions/collections/IsSet
- functions/collections/Where
returnType: mapany
signatures: ['collections.Dictionary KEY VALUE [KEY VALUE]...']
relatedFunctions:
- collections.Dictionary
- collections.Group
- collections.Index
- collections.IsSet
- collections.Where
signatures: ['collections.Dictionary KEY VALUE [VALUE...]']
aliases: [/functions/dict]
---
@@ -24,10 +19,23 @@ aliases: [/functions/dict]
Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.:
```go-text-template
```go-html-template
{{ $m := dict (slice "a" "b" "c") "value" }}
```
The above produces this data structure:
```json
{
"a": {
"b": {
"c": "value"
}
}
}
```
## Example: using `dict` to pass multiple values to a `partial`
The partial below creates an SVG and expects `fill`, `height` and `width` from the caller:
content/en/functions/collections/EchoParam.md
-40
View File
@@ -1,40 +0,0 @@
---
title: collections.EchoParam
linkTitle: echoParam
description: Prints a parameter if it is set.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [echoParam]
returnType: any
signatures: [collections.EchoParam COLLECTION KEY]
relatedFunctions: []
aliases: [/functions/echoparam]
---
For example, consider this site configuration:
{{< code-toggle file=hugo copy=false >}}
[params.footer]
poweredBy = 'Hugo'
{{< /code-toggle >}}
To print the value of `poweredBy`:
```go-html-template
{{ echoParam site.Params.footer "poweredby" }} → Hugo
```
{{% note %}}
When using the `echoParam` function you must reference the key using lower case. See the previous example.
The `echoParam` function will be deprecated in a future release. Instead, use either of the constructs below.
{{% /note %}}
```go-html-template
{{ site.Params.footer.poweredBy }} → Hugo
{{ index site.Params.footer "poweredBy" }} → Hugo
```
content/en/functions/collections/First.md
+9 -16
View File
@@ -1,34 +1,28 @@
---
title: collections.First
linkTitle: first
description: Slices an array to the first N elements.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [first]
related:
- functions/collections/After
- functions/collections/Last
returnType: any
signatures: [collections.First LIMIT COLLECTION]
relatedFunctions:
- collections.After
- collections.First
- collections.Last
aliases: [/functions/first]
---
`first` works in a similar manner to the [`limit` keyword in
SQL][limitkeyword]. It reduces the array to only the `first N`
elements. It takes the array and number of elements as input.
`first` works in a similar manner to the [`limit` keyword in SQL][limitkeyword]. It reduces the array to only the `first N` elements. It takes the array and number of elements as input.
`first` takes two arguments:
1. `number of elements`
2. `array` *or* `slice of maps or structs`
{{< code file="layout/_default/section.html" >}}
{{ range first 10 .Pages }}
{{ .Render "summary" }}
{{ .Render "summary" }}
{{ end }}
{{< /code >}}
@@ -43,11 +37,10 @@ ranges through only the first 5 posts in that list:
{{< code file="first-and-where-together.html" >}}
{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections).ByTitle }}
{{ .Content }}
{{ .Content }}
{{ end }}
{{< /code >}}
[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php
[`where`]: /functions/collections/where
[main sections]: /functions/collections/where#mainsections
content/en/functions/collections/Group.md
+9 -14
View File
@@ -1,26 +1,21 @@
---
title: collections.Group
linkTitle: group
description: Groups a list of pages.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [group]
related:
- functions/collections/Dictionary
- functions/collections/IndexFunction
- functions/collections/IsSet
- functions/collections/Where
returnType: any
signatures: [PAGES | collections.Group KEY]
relatedFunctions:
- collections.Dictionary
- collections.Group
- collections.Index
- collections.IsSet
- collections.Where
aliases: [/functions/group]
---
{{< code file="layouts/partials/groups.html" >}}
```go-html-template
{{ $new := .Site.RegularPages | first 10 | group "New" }}
{{ $old := .Site.RegularPages | last 10 | group "Old" }}
{{ $groups := slice $new $old }}
@@ -35,6 +30,6 @@ aliases: [/functions/group]
{{ end }}
</ul>
{{ end }}
{{< /code >}}
```
The page group you get from `group` is of the same type you get from the built-in [group methods](/templates/lists#group-content) in Hugo. The above example can be [paginated](/templates/pagination/#list-paginator-pages).
content/en/functions/collections/In.md
+9 -9
View File
@@ -1,22 +1,22 @@
---
title: collections.In
linkTitle: in
description: Reports whether an element is in an array or slice, or if a substring is in a string.
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [in]
related:
- functions/collections/Slice
- functions/strings/Contains
- functions/strings/ContainsAny
- functions/strings/ContainsNonSpace
- functions/strings/HasPrefix
- functions/strings/HasSuffix
returnType: bool
signatures: [collections.In SET ITEM]
relatedFunctions:
- collections.Slice
aliases: [/functions/in]
---
```go-html-template
{{ $s := slice "a" "b" "c" }}
{{ in $s "b" }} → true
content/en/functions/collections/IndexFunction.md
+26 -31
View File
@@ -1,71 +1,66 @@
---
title: collections.Index
linkTitle: index
description: Looks up the index(es) or key(s) of the data structure passed into it.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [index]
related:
- functions/collections/Dictionary
- functions/collections/Group
- functions/collections/IsSet
- functions/collections/Where
returnType: any
signatures:
- collections.Index COLLECTION INDEXES
- collections.Index COLLECTION KEYS
relatedFunctions:
- collections.Dictionary
- collections.EchoParam
- collections.Group
- collections.Index
- collections.IsSet
- collections.Where
aliases: [/functions/index,/functions/index-function]
---
The `index` functions returns the result of indexing its first argument by the following arguments. Each indexed item must be a map or a slice, e.g.:
```go-text-template
```go-html-template
{{ $slice := slice "a" "b" "c" }}
{{ index $slice 1 }} => b
{{ index $slice 0 }} → a
{{ index $slice 1 }} → b
{{ $map := dict "a" 100 "b" 200 }}
{{ index $map "b" }} => 200
{{ index $map "b" }} → 200
```
The function takes multiple indices as arguments, and this can be used to get nested values, e.g.:
```go-text-template
```go-html-template
{{ $map := dict "a" 100 "b" 200 "c" (slice 10 20 30) }}
{{ index $map "c" 1 }} => 20
{{ index $map "c" 1 }} → 20
{{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
{{ index $map "c" "e" }} => 20
{{ index $map "c" "e" }} → 20
```
You may write multiple indices as a slice:
```go-text-template
```go-html-template
{{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
{{ $slice := slice "c" "e" }}
{{ index $map $slice }} => 20
{{ index $map $slice }} → 20
```
## Example: load data from a path based on front matter parameters
Assume you want to add a `location = ""` field to your front matter for every article written in `content/vacations/`. You want to use this field to populate information about the location at the bottom of the article in your `single.html` template. You also have a directory in `data/locations/` that looks like the following:
```
.
└── data
└── locations
├── abilene.toml
├── chicago.toml
├── oslo.toml
└── provo.toml
```text
data/
└── locations/
├── abilene.toml
├── chicago.toml
├── oslo.toml
└── provo.toml
```
Here is an example:
{{< code-toggle file="data/locations/oslo" copy=false >}}
{{< code-toggle file="data/locations/oslo" >}}
website = "https://www.oslo.kommune.no"
pop_city = 658390
pop_metro = 1717900
@@ -73,7 +68,7 @@ pop_metro = 1717900
The example we will use will be an article on Oslo, whose front matter should be set to exactly the same name as the corresponding file name in `data/locations/`:
{{< code-toggle file="content/articles/oslo.md" fm=true copy=false >}}
{{< code-toggle file="content/articles/oslo.md" fm=true >}}
title = "My Norwegian Vacation"
location = "oslo"
{{< /code-toggle >}}
content/en/functions/collections/Intersect.md
+6 -12
View File
@@ -1,21 +1,16 @@
---
title: collections.Intersect
linkTitle: intersect
description: Returns the common elements of two arrays or slices, in the same order as the first array.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [intersect]
related:
- functions/collections/Complement
- functions/collections/SymDiff
- functions/collections/Union
returnType: any
signatures: [collections.Intersect SET1 SET2]
relatedFunctions:
- collections.Complement
- collections.Intersect
- collections.SymDiff
- collections.Union
aliases: [/functions/intersect]
---
A useful example is to use it as `AND` filters when combined with where:
@@ -32,6 +27,5 @@ The above fetches regular pages not of `page` or `about` type unless they are pi
See [union](/functions/collections/union) for `OR`.
[partials]: /templates/partials/
[single]: /templates/single-page-templates/
content/en/functions/collections/IsSet.md
+10 -13
View File
@@ -1,28 +1,25 @@
---
title: collections.IsSet
linkTitle: isset
description: Reports whether the key exists within the collection.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [isset]
related:
- functions/collections/Dictionary
- functions/collections/Group
- functions/collections/IndexFunction
- functions/collections/Where
- functions/go-template/if
- functions/go-template/with
returnType: bool
signatures: [collections.IsSet COLLECTION KEY]
relatedFunctions:
- collections.Dictionary
- collections.Group
- collections.Index
- collections.IsSet
- collections.Where
aliases: [/functions/isset]
---
For example, consider this site configuration:
{{< code-toggle file=hugo copy=false >}}
{{< code-toggle file=hugo >}}
[params]
showHeroImage = false
{{< /code-toggle >}}
content/en/functions/collections/KeyVals.md
+8 -9
View File
@@ -1,21 +1,20 @@
---
title: collections.KeyVals
linkTitle: keyVals
description: Returns a KeyVals struct.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [keyVals]
returnType: KeyValues
related:
- methods/pages/Related
returnType: types.KeyValues
signatures: [collections.KeyVals KEY VALUES...]
relatedFunctions: []
aliases: [/functions/keyvals]
---
The primary application for this function is the definition of the `namedSlices` parameter in the options map passed to the `.Related` method on the `Page` object.
The primary application for this function is the definition of the `namedSlices` parameter in the options map passed to the [`Related`] method on the `Pages` object.
[`Related`]: /methods/pages/related
See [related content](/content-management/related).
content/en/functions/collections/Last.md
+5 -10
View File
@@ -1,20 +1,15 @@
---
title: collections.Last
linkTitle: last
description: Slices an array to the last N elements.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [last]
related:
- functions/collections/After
- functions/collections/First
returnType: any
signatures: [collections.Last INDEX COLLECTION]
relatedFunctions:
- collections.After
- collections.First
- collections.Last
aliases: [/functions/last]
---
content/en/functions/collections/Merge.md
+4 -9
View File
@@ -1,19 +1,14 @@
---
title: collections.Merge
linkTitle: merge
description: Returns the result of merging two or more maps.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [merge]
related:
- functions/collections/Append
returnType: any
signatures: [collections.Merge MAP MAP...]
relatedFunctions:
- collections.Append
- collections.Merge
aliases: [/functions/merge]
---
content/en/functions/collections/NewScratch.md
+98 -13
View File
@@ -1,22 +1,107 @@
---
title: collections.NewScratch
linkTitle: newScratch
description: Creates a new Scratch which can be used to store values in a thread safe way.
categories: [functions]
description: Returns a locally scoped "scratch pad" to store and manipulate data.
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [newScratch]
returnType: Scratch
related:
- methods/page/scratch
- methods/page/store
returnType: maps.Scratch
signatures: [collections.NewScratch ]
relatedFunctions: []
---
The `collections.NewScratch` function creates a locally scoped [scratch pad] to store and manipulate data. To create a scratch pad that is attached to a `Page` object, use the [`Scratch`] or [`Store`] method.
[`Scratch`]: /methods/page/scratch
[`Store`]: /methods/page/store
[scratch pad]: /getting-started/glossary/#scratch-pad
## Methods
Set
: Sets the value of a given key.
```go-html-template
{{ $scratch := newScratch }}
{{ $scratch.Add "b" 2 }}
{{ $scratch.Add "b" 2 }}
{{ $scratch.Get "b" }} → 4
{{ $s := newScratch }}
{{ $s.Set "greeting" "Hello" }}
```
Get
: Gets the value of a given key.
```go-html-template
{{ $s := newScratch }}
{{ $s.Set "greeting" "Hello" }}
{{ $s.Get "greeting" }} → Hello
```
Add
: Adds a given value to existing value(s) of the given key.
: For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
```go-html-template
{{ $s := newScratch }}
{{ $s.Set "greeting" "Hello" }}
{{ $s.Add "greeting" "Welcome" }}
{{ $s.Get "greeting" }} → HelloWelcome
```
```go-html-template
{{ $s := newScratch }}
{{ $s.Set "total" 3 }}
{{ $s.Add "total" 7 }}
{{ $s.Get "total" }} → 10
```
```go-html-template
{{ $s := newScratch }}
{{ $s.Set "greetings" (slice "Hello") }}
{{ $s.Add "greetings" (slice "Welcome" "Cheers") }}
{{ $s.Get "greetings" }} → [Hello Welcome Cheers]
```
SetInMap
: Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
```go-html-template
{{ $s := newScratch }}
{{ $s.SetInMap "greetings" "english" "Hello" }}
{{ $s.SetInMap "greetings" "french" "Bonjour" }}
{{ $s.Get "greetings" }} → map[english:Hello french:Bonjour]
```
DeleteInMap
: Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
```go-html-template
{{ $s := newScratch }}
{{ $s.SetInMap "greetings" "english" "Hello" }}
{{ $s.SetInMap "greetings" "french" "Bonjour" }}
{{ $s.DeleteInMap "greetings" "english" }}
{{ $s.Get "greetings" }} → map[french:Bonjour]
```
GetSortedMapValues
: Returns an array of values from `key` sorted by `mapKey`.
```go-html-template
{{ $s := newScratch }}
{{ $s.SetInMap "greetings" "english" "Hello" }}
{{ $s.SetInMap "greetings" "french" "Bonjour" }}
{{ $s.GetSortedMapValues "greetings" }} → [Hello Bonjour]
```
Delete
: Removes the given key.
```go-html-template
{{ $s := newScratch }}
{{ $s.Set "greeting" "Hello" }}
{{ $s.Delete "greeting" }}
```
Values
: Returns the raw backing map. Do not use with `Scratch` or `Store` methods on a `Page` object due to concurrency issues.
content/en/functions/collections/Querify.md
+4 -8
View File
@@ -1,19 +1,15 @@
---
title: collections.Querify
linkTitle: querify
description: Takes a set or slice of key-value pairs and returns a query string to be appended to URLs.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [querify]
returnType: string
signatures:
- collections.Querify KEY VALUE [KEY VALUE]...
- collections.Querify VALUE [VALUE...]
- collections.Querify COLLECTION
relatedFunctions:
related:
- collections.Querify
- urlquery
aliases: [/functions/querify]
content/en/functions/collections/Reverse.md
+3 -7
View File
@@ -1,16 +1,13 @@
---
title: collections.Reverse
description: Reverses the order of a collection.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: []
returnType: any
signatures: [collections.Reverse COLLECTION]
relatedFunctions:
related:
- collections.Apply
- collections.Delimit
- collections.In
@@ -20,7 +17,6 @@ relatedFunctions:
aliases: [/functions/collections.reverse]
---
```go-html-template
{{ slice 2 1 3 | collections.Reverse }} → [3 1 2]
```
content/en/functions/collections/Seq.md
+3 -7
View File
@@ -1,20 +1,16 @@
---
title: collections.Seq
linkTitle: seq
description: Returns a slice of integers.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [seq]
returnType: '[]int'
signatures:
- collections.Seq LAST
- collections.Seq FIRST LAST
- collections.Seq FIRST INCREMENT LAST
relatedFunctions:
related:
- collections.Apply
- collections.Delimit
- collections.In
content/en/functions/collections/Shuffle.md
+3 -8
View File
@@ -1,18 +1,13 @@
---
title: collections.Shuffle
linkTitle: shuffle
description: Returns a random permutation of a given array or slice.
keywords: [ordering]
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [shuffle]
returnType: any
signatures: [collections.Shuffle COLLECTION]
relatedFunctions:
related:
- collections.Reverse
- collections.Shuffle
- collections.Sort
content/en/functions/collections/Slice.md
+3 -9
View File
@@ -1,17 +1,13 @@
---
title: collections.Slice
linkTitle: slice
description: Creates a slice (array) of all passed arguments.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [slice]
returnType: any
signatures: [collections.Slice ITEM...]
relatedFunctions:
related:
- collections.Append
- collections.Apply
- collections.Delimit
@@ -22,8 +18,6 @@ relatedFunctions:
aliases: [/functions/slice]
---
One use case is the concatenation of elements in combination with the [`delimit` function]:
```go-html-template
{{ $s := slice "a" "b" "c" }}
{{ $s }} → [a b c]
content/en/functions/collections/Sort.md
+16 -21
View File
@@ -1,17 +1,13 @@
---
title: collections.Sort
linkTitle: sort
description: Sorts slices, maps, and page collections.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [sort]
returnType: any
signatures: ['collections.Sort COLLECTION [KEY] [ORDER]']
relatedFunctions:
related:
- collections.Reverse
- collections.Shuffle
- collections.Sort
@@ -27,7 +23,7 @@ The `ORDER` may be either `asc` (ascending) or `desc` (descending). The default
The examples below assume this site configuration:
{{< code-toggle file="hugo" copy=false >}}
{{< code-toggle file=hugo >}}
[params]
grades = ['b','a','c']
{{< /code-toggle >}}
@@ -36,10 +32,10 @@ grades = ['b','a','c']
Sort slice elements in ascending order using either of these constructs:
{{< code file="layouts/_default/single.html" copy=false >}}
```go-html-template
{{ sort site.Params.grades }} → [a b c]
{{ sort site.Params.grades "value" "asc" }} → [a b c]
{{< /code >}}
```
In the examples above, `value` is the `KEY` representing the value of the slice element.
@@ -47,9 +43,9 @@ In the examples above, `value` is the `KEY` representing the value of the slice
Sort slice elements in descending order:
{{< code file="layouts/_default/single.html" copy=false >}}
```go-html-template
{{ sort site.Params.grades "value" "desc" }} → [c b a]
{{< /code >}}
```
In the example above, `value` is the `KEY` representing the value of the slice element.
@@ -57,7 +53,7 @@ In the example above, `value` is the `KEY` representing the value of the slice e
The examples below assume this site configuration:
{{< code-toggle file="hugo" copy=false >}}
{{< code-toggle file=hugo >}}
[params.authors.a]
firstName = "Marius"
lastName = "Pontmercy"
@@ -77,7 +73,7 @@ When sorting maps, the `KEY` argument must be lowercase.
Sort map objects in ascending order using either of these constructs:
{{< code file="layouts/_default/single.html" copy=false >}}
```go-html-template
{{ range sort site.Params.authors "firstname" }}
{{ .firstName }}
{{ end }}
@@ -85,7 +81,7 @@ Sort map objects in ascending order using either of these constructs:
{{ range sort site.Params.authors "firstname" "asc" }}
{{ .firstName }}
{{ end }}
{{< /code >}}
```
These produce:
@@ -97,11 +93,11 @@ Jean Marius Victor
Sort map objects in descending order:
{{< code file="layouts/_default/single.html" copy=false >}}
```go-html-template
{{ range sort site.Params.authors "firstname" "desc" }}
{{ .firstName }}
{{ end }}
{{< /code >}}
```
This produces:
@@ -125,11 +121,10 @@ Although you can use the `sort` function to sort a page collection, Hugo provide
In this contrived example, sort the site's regular pages by `.Type` in descending order:
{{< code file="layouts/_default/home.html" copy=false >}}
```go-html-template
{{ range sort site.RegularPages "Type" "desc" }}
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}
{{< /code >}}
```
[built-in methods for sorting page collections]: /templates/lists/#order-content
[built-in methods for sorting page collections]: /templates/lists/#sort-content
content/en/functions/collections/SymDiff.md
+4 -8
View File
@@ -1,17 +1,13 @@
---
title: collections.SymDiff
linkTitle: symdiff
description: Returns the symmetric difference of two collections.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [symdiff]
returnType: any
signatures: [COLLECTION | collections.SymDiff COLLECTION]
relatedFunctions:
related:
- collections.Complement
- collections.Intersect
- collections.SymDiff
@@ -25,4 +21,4 @@ Example:
{{ slice 1 2 3 | symdiff (slice 3 4) }} → [1 2 4]
```
Also see https://en.wikipedia.org/wiki/Symmetric_difference
Also see <https://en.wikipedia.org/wiki/Symmetric_difference>.
content/en/functions/collections/Union.md
+3 -7
View File
@@ -1,17 +1,13 @@
---
title: collections.Union
linkTitle: union
description: Given two arrays or slices, returns a new array that contains the elements or objects that belong to either or both arrays/slices.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [union]
returnType: any
signatures: [collections.Union SET1 SET2]
relatedFunctions:
related:
- collections.Complement
- collections.Intersect
- collections.SymDiff
content/en/functions/collections/Uniq.md
+3 -8
View File
@@ -1,17 +1,13 @@
---
title: collections.Uniq
linkTitle: uniq
description: Takes in a slice or array and returns a slice with duplicate elements removed.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [uniq]
returnType: any
signatures: [collections.Uniq COLLECTION]
relatedFunctions:
related:
- collections.Reverse
- collections.Shuffle
- collections.Sort
@@ -19,7 +15,6 @@ relatedFunctions:
aliases: [/functions/uniq]
---
```go-html-template
{{ slice 1 3 2 1 | uniq }} → [1 3 2]
```
content/en/functions/collections/Where.md
+11 -15
View File
@@ -1,17 +1,13 @@
---
title: collections.Where
linkTitle: where
description: Filters an array to only the elements containing a matching value for a given field.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [where]
returnType: any
signatures: ['collections.Where COLLECTION KEY [OPERATOR] MATCH']
relatedFunctions:
related:
- collections.Dictionary
- collections.Group
- collections.Index
@@ -35,7 +31,7 @@ SQL][wherekeyword].
It can be used by dot-chaining the second argument to refer to a nested element of a value.
{{< code-toggle file="content/example.md" fm=true copy=false >}}
{{< code-toggle file="content/example.md" fm=true >}}
title: Example
series: golang
{{< /code-toggle >}}
@@ -106,13 +102,13 @@ When using booleans you should not put quotation marks.
You can also put the returned value of the `where` clauses into a variable:
{{< code file="where-intersect-variables.html" >}}
```go-html-template
{{ $v1 := where .Site.Pages "Params.a" "v1" }}
{{ $v2 := where .Site.Pages "Params.b" "v2" }}
{{ $filtered := $v1 | intersect $v2 }}
{{ range $filtered }}
{{ end }}
{{< /code >}}
```
## Use `where` with `like`
@@ -120,11 +116,11 @@ This example matches pages where the "foo" parameter begins with "ab":
```go-html-template
{{ range where site.RegularPages "Params.foo" "like" `^ab` }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}
```
{{% readfile file="/functions/_common/regular-expressions.md" %}}
{{% include "functions/_common/regular-expressions.md" %}}
## Use `where` with `first`
@@ -134,11 +130,11 @@ sections**](#mainsections), sorts it using the [default
ordering](/templates/lists/) for lists (i.e., `weight => date`), and
then ranges through only the first 5 posts in that list:
{{< code file="first-and-where-together.html" >}}
```go-html-template
{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections) }}
{{ .Content }}
{{ end }}
{{< /code >}}
```
## Nest `where` clauses
@@ -181,7 +177,7 @@ If the user has not set this configuration parameter in their site configuration
The user can override the default:
{{< code-toggle file="hugo" >}}
{{< code-toggle file=hugo >}}
[params]
mainSections = ["blog", "docs"]
{{< /code-toggle >}}
content/en/functions/collections/_index.md
+12
View File
@@ -0,0 +1,12 @@
---
title: Collections functions
linkTitle: collections
description: Template functions to work with arrays, slices, maps, and page collections.
categories: []
keywords: []
menu:
docs:
parent: functions
---
Use these functions to work with arrays, slices, maps, and page collections.
content/en/functions/compare/Cond.md → content/en/functions/compare/Conditional.md
+7 -13
View File
@@ -1,19 +1,14 @@
---
title: compare.Conditional
linkTitle: cond
description: Returns one of two arguments depending on the value of the control argument.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [cond]
related:
- functions/compare/Default
returnType: any
signatures: [compare.Conditional CONTROL ARG1 ARG2]
relatedFunctions:
- compare.Conditional
- compare.Default
aliases: [/functions/cond]
---
@@ -21,14 +16,14 @@ The CONTROL argument is a boolean value that indicates whether the function shou
```go-html-template
{{ $qty := 42 }}
{{ cond (le $qty 3) "few" "many" }} → "many"
{{ cond (le $qty 3) "few" "many" }} → many
```
The CONTROL argument must be either `true` or `false`. To cast a non-boolean value to boolean, pass it through the `not` operator twice.
```go-html-template
{{ cond (42 | not | not) "truthy" "falsy" }} → "truthy"
{{ cond ("" | not | not) "truthy" "falsy" }} → "falsy"
{{ cond (42 | not | not) "truthy" "falsy" }} → truthy
{{ cond ("" | not | not) "truthy" "falsy" }} → falsy
```
{{% note %}}
@@ -38,7 +33,6 @@ Unlike [ternary operators] in other languages, the `cond` function does not perf
[ternary operators]: https://en.wikipedia.org/wiki/Ternary_conditional_operator
{{% /note %}}
Due to the absence of short-circuit evaluation, these examples throw an error:
```go-html-template
content/en/functions/compare/Default.md
+28 -68
View File
@@ -1,88 +1,48 @@
---
title: compare.Default
linkTitle: default
description: Allows setting a default value that can be returned if a first value is not set.
categories: [functions]
description: Returns the second argument if set, else the first argument.
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [default]
related:
- functions/compare/Conditional
- functions/go-template/Or
returnType: any
signatures: [compare.Default DEFAULT INPUT]
relatedFunctions:
- compare.Conditional
- compare.Default
aliases: [/functions/default]
---
`default` checks whether a given value is set and returns a default value if it is not. *Set* in this context means different things depending on the data type:
The `default` function returns the second argument if set, else the first argument.
* non-zero for numeric types and times
* non-zero length for strings, arrays, slices, and maps
* any boolean or struct value
* non-nil for any other types
{{% note %}}
When the second argument is the boolean `false` value, the `default` function returns `false`. All _other_ falsy values are considered unset.
`default` function examples reference the following content page:
{{% include "functions/go-template/_common/truthy-falsy.md" %}}
{{< code file="content/posts/default-function-example.md" >}}
---
title: Sane Defaults
seo_title:
date: 2017-02-18
font:
oldparam: The default function helps make your templating DRYer.
newparam:
---
{{< /code >}}
To set a default value based on truthiness, use the [`or`] operator instead.
`default` can be written in more than one way:
[`or`]: /functions/go-template/or
{{% /note %}}
The `default` function returns the second argument if set:
```go-html-template
{{ .Params.font | default "Roboto" }}
{{ default "Roboto" .Params.font }}
{{ default 42 1 }} → 1
{{ default 42 "foo" }} → foo
{{ default 42 (dict "k" "v") }} → map[k:v]
{{ default 42 (slice "a" "b") }} → [a b]
{{ default 42 true }} → true
<!-- As noted above, the boolean "false" is considered set -->
{{ default 42 false }} → false
```
Both of the above `default` function calls return `Roboto`.
A `default` value, however, does not need to be hard coded like the previous example. The `default` value can be a variable or pulled directly from the front matter using dot notation:
The `default` function returns the first argument if the second argument is not set:
```go-html-template
{{ $old := .Params.oldparam }}
<p>{{ .Params.newparam | default $old }}</p>
```
Which would return:
```html
<p>The default function helps make your templating DRYer.</p>
```
And then using dot notation
```go-html-template
<title>{{ .Params.seo_title | default .Title }}</title>
```
Which would return
```html
<title>Sane Defaults</title>
```
The following have equivalent return values but are far less terse. This demonstrates the utility of `default`:
Using `if`:
```go-html-template
<title>{{ if .Params.seo_title }}{{ .Params.seo_title }}{{ else }}{{ .Title }}{{ end }}</title>
=> Sane Defaults
```
Using `with`:
```go-html-template
<title>{{ with .Params.seo_title }}{{ . }}{{ else }}{{ .Title }}{{ end }}</title>
=> Sane Defaults
{{ default 42 0 }} → 42
{{ default 42 "" }} → 42
{{ default 42 dict }} → 42
{{ default 42 slice }} → 42
{{ default 42 <nil> }} → 42
```
content/en/functions/compare/Eq.md
+8 -13
View File
@@ -1,23 +1,18 @@
---
title: compare.Eq
linkTitle: eq
description: Returns the boolean truth of arg1 == arg2 || arg1 == arg3.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [eq]
related:
- functions/compare/Ge
- functions/compare/Gt
- functions/compare/Le
- functions/compare/Lt
- functions/compare/Ne
returnType: bool
signatures: ['compare.Eq ARG1 ARG2 [ARG...]']
relatedFunctions:
- compare.Eq
- compare.Ge
- compare.Gt
- compare.Le
- compare.Lt
- compare.Ne
aliases: [/functions/eq]
---
content/en/functions/compare/Ge.md
+8 -13
View File
@@ -1,23 +1,18 @@
---
title: compare.Ge
linkTitle: ge
description: Returns the boolean truth of arg1 >= arg2 && arg1 >= arg3.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [ge]
related:
- functions/compare/Eq
- functions/compare/Gt
- functions/compare/Le
- functions/compare/Lt
- functions/compare/Ne
returnType: bool
signatures: ['compare.Ge ARG1 ARG2 [ARG...]']
relatedFunctions:
- compare.Eq
- compare.Ge
- compare.Gt
- compare.Le
- compare.Lt
- compare.Ne
aliases: [/functions/ge]
---
content/en/functions/compare/Gt.md
+8 -13
View File
@@ -1,23 +1,18 @@
---
title: compare.Gt
linkTitle: gt
description: Returns the boolean truth of arg1 > arg2 && arg1 > arg3.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [gt]
related:
- functions/compare/Eq
- functions/compare/Ge
- functions/compare/Le
- functions/compare/Lt
- functions/compare/Ne
returnType: bool
signatures: ['compare.Gt ARG1 ARG2 [ARG...]']
relatedFunctions:
- compare.Eq
- compare.Ge
- compare.Gt
- compare.Le
- compare.Lt
- compare.Ne
aliases: [/functions/gt]
---
content/en/functions/compare/Le.md
+8 -13
View File
@@ -1,23 +1,18 @@
---
title: compare.Le
linkTitle: le
description: Returns the boolean truth of arg1 <= arg2 && arg1 <= arg3.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [le]
related:
- functions/compare/Eq
- functions/compare/Ge
- functions/compare/Gt
- functions/compare/Lt
- functions/compare/Ne
returnType: bool
signatures: ['compare.Le ARG1 ARG2 [ARG...]']
relatedFunctions:
- compare.Eq
- compare.Ge
- compare.Gt
- compare.Le
- compare.Lt
- compare.Ne
aliases: [/functions/le]
---
content/en/functions/compare/Lt.md
+8 -13
View File
@@ -1,23 +1,18 @@
---
title: compare.Lt
linkTitle: lt
description: Returns the boolean truth of arg1 < arg2 && arg1 < arg3.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [lt]
related:
- functions/compare/Eq
- functions/compare/Ge
- functions/compare/Gt
- functions/compare/Le
- functions/compare/Ne
returnType: bool
signatures: ['compare.Lt ARG1 ARG2 [ARG...]']
relatedFunctions:
- compare.Eq
- compare.Ge
- compare.Gt
- compare.Le
- compare.Lt
- compare.Ne
aliases: [/functions/lt]
---
content/en/functions/compare/Ne.md
+8 -13
View File
@@ -1,23 +1,18 @@
---
title: compare.Ne
linkTitle: ne
description: Returns the boolean truth of arg1 != arg2 && arg1 != arg3.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [ne]
related:
- functions/compare/Eq
- functions/compare/Ge
- functions/compare/Gt
- functions/compare/Le
- functions/compare/Lt
returnType: bool
signatures: ['compare.Ne ARG1 ARG2 [ARG...]']
relatedFunctions:
- compare.Eq
- compare.Ge
- compare.Gt
- compare.Le
- compare.Lt
- compare.Ne
aliases: [/functions/ne]
---

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