diff --git a/.cspell.json b/.cspell.json index 0958b7645..13865a83c 100644 --- a/.cspell.json +++ b/.cspell.json @@ -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 diff --git a/LICENSE.md b/LICENSE.md index b62a9b5ff..b09cd7856 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,194 +1,201 @@ Apache License -============== + Version 2.0, January 2004 + http://www.apache.org/licenses/ -_Version 2.0, January 2004_ -_<>_ + 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. diff --git a/README.md b/README.md index 730ad5fc8..bf5d9402c 100644 --- a/README.md +++ b/README.md @@ -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 ... diff --git a/archetypes/functions.md b/archetypes/functions.md index cb0e7c930..44a2a5635 100644 --- a/archetypes/functions.md +++ b/archetypes/functions.md @@ -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: [] --- diff --git a/archetypes/methods.md b/archetypes/methods.md new file mode 100644 index 000000000..2c415547d --- /dev/null +++ b/archetypes/methods.md @@ -0,0 +1,10 @@ +--- +title: {{ replace .File.ContentBaseName "-" " " | title }} +description: +categories: [] +keywords: [] +action: + related: [] + returnType: + signatures: [] +--- diff --git a/archetypes/showcase/bio.md b/archetypes/showcase/bio.md index 2443c2f35..5d1708978 100644 --- a/archetypes/showcase/bio.md +++ b/archetypes/showcase/bio.md @@ -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) diff --git a/assets/images/examples/zion-national-park-grayscale.jpg b/assets/images/examples/zion-national-park-grayscale.jpg new file mode 100644 index 000000000..908bd88c6 Binary files /dev/null and b/assets/images/examples/zion-national-park-grayscale.jpg differ diff --git a/assets/images/examples/zion-national-park.jpg b/assets/images/examples/zion-national-park.jpg new file mode 100644 index 000000000..7980abccb Binary files /dev/null and b/assets/images/examples/zion-national-park.jpg differ diff --git a/assets/images/logos/logo-128x128.png b/assets/images/logos/logo-128x128.png new file mode 100644 index 000000000..ec1a2d6e1 Binary files /dev/null and b/assets/images/logos/logo-128x128.png differ diff --git a/assets/images/logos/logo-256x256.png b/assets/images/logos/logo-256x256.png new file mode 100644 index 000000000..d9fdb888a Binary files /dev/null and b/assets/images/logos/logo-256x256.png differ diff --git a/assets/images/logos/logo-512x512.png b/assets/images/logos/logo-512x512.png new file mode 100644 index 000000000..76d463600 Binary files /dev/null and b/assets/images/logos/logo-512x512.png differ diff --git a/assets/images/logos/logo-64x64.png b/assets/images/logos/logo-64x64.png new file mode 100644 index 000000000..9857bcea1 Binary files /dev/null and b/assets/images/logos/logo-64x64.png differ diff --git a/assets/images/logos/logo-96x96.png b/assets/images/logos/logo-96x96.png new file mode 100644 index 000000000..48d0cb98e Binary files /dev/null and b/assets/images/logos/logo-96x96.png differ diff --git a/config/_default/menus/menus.en.toml b/config/_default/menus/menus.en.toml index 327a5777b..1ea37f443 100644 --- a/config/_default/menus/menus.en.toml +++ b/config/_default/menus/menus.en.toml @@ -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' diff --git a/config/_default/params.toml b/config/_default/params.toml index 3fddf9dbc..b41679c61 100644 --- a/config/_default/params.toml +++ b/config/_default/params.toml @@ -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) diff --git a/content/en/about/hugo-and-gdpr.md b/content/en/about/hugo-and-gdpr.md index 85e996f59..ea588fb31 100644 --- a/content/en/about/hugo-and-gdpr.md +++ b/content/en/about/hugo-and-gdpr.md @@ -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 diff --git a/content/en/about/license.md b/content/en/about/license.md index dc560b33f..6e9d2ea19 100644 --- a/content/en/about/license.md +++ b/content/en/about/license.md @@ -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_
- -*Terms and Conditions for use, reproduction, and distribution* +_Version 2.0, January 2004_ +__ -## 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 >}} diff --git a/content/en/content-management/_common/_index.md b/content/en/content-management/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/content-management/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + + diff --git a/layouts/shortcodes/page-kinds.html b/content/en/content-management/_common/page-kinds.md similarity index 65% rename from layouts/shortcodes/page-kinds.html rename to content/en/content-management/_common/page-kinds.md index 968a7a5fb..07a53e8e6 100644 --- a/layouts/shortcodes/page-kinds.html +++ b/content/en/content-management/_common/page-kinds.md @@ -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 >}} diff --git a/content/en/content-management/archetypes.md b/content/en/content-management/archetypes.md index fe460f91f..0a33c9da6 100644 --- a/content/en/content-management/archetypes.md +++ b/content/en/content-management/archetypes.md @@ -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 `.gitkeep` file, an empty file commonly used to preserve otherwise empty directories in a Git repository. - To create a new gallery: -```text + +```sh hugo new galleries/bryce-canyon ``` @@ -166,13 +165,13 @@ archetypes/ To create an article using the articles archetype: -```text +```sh hugo new content articles/something.md ``` To create an article using the tutorials archetype: -```text +```sh hugo new content --kind tutorials articles/something.md ``` diff --git a/content/en/content-management/build-options.md b/content/en/content-management/build-options.md index 378a31144..fb3cca7cb 100644 --- a/content/en/content-management/build-options.md +++ b/content/en/content-management/build-options.md @@ -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" >}}
{{ 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" >}}
{{ range first 5 .Pages }}
diff --git a/content/en/content-management/comments.md b/content/en/content-management/comments.md index 39663013b..e85ea5a78 100644 --- a/content/en/content-management/comments.md +++ b/content/en/content-management/comments.md @@ -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" {{}} 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: diff --git a/content/en/content-management/cross-references.md b/content/en/content-management/cross-references.md index c989cc560..32e1d96ed 100644 --- a/content/en/content-management/cross-references.md +++ b/content/en/content-management/cross-references.md @@ -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 {{}} // <- From pages/document1.md, relative path {{}} @@ -138,7 +137,7 @@ produces this HTML: ## Ref and RelRef Configuration -The behavior can, since Hugo 0.45, be configured in `hugo.toml`: +The behavior can be configured in `hugo.toml`: refLinksErrorLevel ("ERROR") : When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). @@ -146,7 +145,6 @@ refLinksErrorLevel ("ERROR") refLinksNotFoundURL : URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. - [lists]: /templates/lists/ [output formats]: /templates/output-formats/ [shortcode]: /content-management/shortcodes/ diff --git a/content/en/content-management/diagrams.md b/content/en/content-management/diagrams.md index c0b2349b0..886b4c298 100644 --- a/content/en/content-management/diagrams.md +++ b/content/en/content-management/diagrams.md @@ -165,7 +165,6 @@ Created from └─Fedora ``` - ### Sequence diagram @@ -186,7 +185,6 @@ Created from ``` - ### Flowchart @@ -232,7 +230,6 @@ Created from ``` - ### Table diff --git a/content/en/content-management/formats.md b/content/en/content-management/formats.md index ccc45b943..85ca55ba7 100644 --- a/content/en/content-management/formats.md +++ b/content/en/content-management/formats.md @@ -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 [details]. [details]: /getting-started/configuration-markup/#asciidoc @@ -75,7 +75,6 @@ Markdown syntax is simple enough to learn in a single sitting. The following are [ascii]: https://asciidoctor.org/ [config]: /getting-started/configuration/ [developer tools]: /tools/ -[emojis]: https://www.webpagefx.com/tools/emoji-cheat-sheet/ [fireball]: https://daringfireball.net/projects/markdown/ [gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax [helperssource]: https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65 diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md index 10317e805..a23905df8 100644 --- a/content/en/content-management/front-matter.md +++ b/content/en/content-management/front-matter.md @@ -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 {{}} @@ -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/ diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index 9cce9070a..9ac1d5c43 100644 --- a/content/en/content-management/image-processing/index.md +++ b/content/en/content-management/image-processing/index.md @@ -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 -{{}} +{{}} ``` {{% 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 ``` diff --git a/content/en/content-management/menus.md b/content/en/content-management/menus.md index 07bf41669..f7f7cec4c 100644 --- a/content/en/content-management/menus.md +++ b/content/en/content-management/menus.md @@ -36,7 +36,7 @@ Although you can use these methods in combination when defining a menu, the menu To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration. -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} sectionPagesMenu = "main" {{< /code-toggle >}} @@ -46,7 +46,7 @@ This creates a menu structure that you can access with `site.Menus.main` in your To add a page to the "main" menu: -{{< code-toggle file="content/about.md" copy=false fm=true >}} +{{< code-toggle file="content/about.md" fm=true >}} title = 'About' menu = 'main' {{< /code-toggle >}} @@ -55,7 +55,7 @@ Access the entry with `site.Menus.main` in your templates. See [menu templates] To add a page to the "main" and "footer" menus: -{{< code-toggle file="content/contact.md" copy=false fm=true >}} +{{< code-toggle file="content/contact.md" fm=true >}} title = 'Contact' menu = ['main','footer'] {{< /code-toggle >}} @@ -94,7 +94,7 @@ weight This front matter menu entry demonstrates some of the available properties: -{{< code-toggle file="content/products/software.md" copy=false fm=true >}} +{{< code-toggle file="content/products/software.md" fm=true >}} title = 'Software' [menu.main] parent = 'Products' @@ -106,12 +106,11 @@ class = 'center' Access the entry with `site.Menus.main` in your templates. See [menu templates] for details. - ## Define in site configuration To define entries for the "main" menu: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [[menu.main]] name = 'Home' pageRef = '/' @@ -132,7 +131,7 @@ This creates a menu structure that you can access with `site.Menus.main` in your To define entries for the "footer" menu: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [[menu.footer]] name = 'Terms' pageRef = '/terms' @@ -177,7 +176,7 @@ url This nested menu demonstrates some of the available properties: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [[menu.main]] name = 'Products' pageRef = '/products' diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md index 6e787c526..910af91ce 100644 --- a/content/en/content-management/multilingual.md +++ b/content/en/content-management/multilingual.md @@ -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 ``` diff --git a/content/en/content-management/organization/index.md b/content/en/content-management/organization/index.md index 2c0d2e604..250e51460 100644 --- a/content/en/content-management/organization/index.md +++ b/content/en/content-management/organization/index.md @@ -19,16 +19,14 @@ Hugo `0.32` announced page-relative images and other resources packaged into `Pa These terms are connected, and you also need to read about [Page Resources](/content-management/page-resources) and [Image Processing](/content-management/image-processing) to get the full picture. -{{< imgproc 1-featured Resize "300x" >}} +{{< imgproc "1-featured-content-bundles.png" "resize 300x" >}} The illustration shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed. {{< /imgproc >}} - {{% note %}} The bundle documentation is a **work in progress**. We will publish more comprehensive docs about this soon. {{% /note %}} - ## Organization of content source In Hugo, your content should be organized in a manner that reflects the rendered website. @@ -41,33 +39,31 @@ Without any additional configuration, the following will automatically work: . └── content └── about - | └── index.md // <- https://example.com/about/ + | └── index.md // <- https://example.org/about/ ├── posts - | ├── firstpost.md // <- https://example.com/posts/firstpost/ + | ├── firstpost.md // <- https://example.org/posts/firstpost/ | ├── happy - | | └── ness.md // <- https://example.com/posts/happy/ness/ - | └── secondpost.md // <- https://example.com/posts/secondpost/ + | | └── ness.md // <- https://example.org/posts/happy/ness/ + | └── secondpost.md // <- https://example.org/posts/secondpost/ └── quote - ├── first.md // <- https://example.com/quote/first/ - └── second.md // <- https://example.com/quote/second/ + ├── first.md // <- https://example.org/quote/first/ + └── second.md // <- https://example.org/quote/second/ ``` ## Path breakdown in Hugo - -The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.com"` in your [site's configuration file][config]. +The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org"` in your [site's configuration file][config]. ### Index pages: `_index.md` `_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates], [taxonomy templates], [taxonomy terms templates], and your [homepage template]. {{% note %}} -**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/getpage/). +**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/methods/page/getpage). {{% /note %}} You can create one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website: - ```txt . url . ⊢--^-⊣ @@ -88,17 +84,15 @@ At build, this will output to the following destination with the associated valu ⊢--------^---------⊣⊢-^-⊣ permalink ⊢----------^-------------⊣ -https://example.com/posts/index.html +https://example.org/posts/index.html ``` The [sections] can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. `_index.md`). - ### Single pages in sections Single content files in each of your sections will be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`: - ```txt path ("posts/my-first-hugo-post.md") . ⊢-----------^------------⊣ @@ -117,10 +111,9 @@ When Hugo builds your site, the content will be output to the following destinat ⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣ permalink ⊢--------------------^---------------------⊣ -https://example.com/posts/my-first-hugo-post/index.html +https://example.org/posts/my-first-hugo-post/index.html ``` - ## Paths explained The following concepts provide more insight into the relationship between your project's organization and the default Hugo behavior when building output for the website. @@ -147,7 +140,7 @@ The `url` is the entire URL path, defined by the file path and optionally overri [config]: /getting-started/configuration/ [formats]: /content-management/formats/ [front matter]: /content-management/front-matter/ -[getpage]: /functions/getpage/ +[getpage]: /methods/page/getpage [homepage template]: /templates/homepage/ [homepage]: /templates/homepage/ [lists]: /templates/lists/ diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md index c4ce69f5f..91ed0d5df 100644 --- a/content/en/content-management/page-bundles.md +++ b/content/en/content-management/page-bundles.md @@ -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 diff --git a/content/en/content-management/page-resources.md b/content/en/content-management/page-resources.md index bbf288459..bcff98118 100644 --- a/content/en/content-management/page-resources.md +++ b/content/en/content-management/page-resources.md @@ -112,7 +112,6 @@ GetMatch .Resources.Match "*" 🚫 .Resources.Match "sunset.jpg" 🚫 .Resources.Match "*sunset.jpg" 🚫 - ``` ## Page resources metadata @@ -138,7 +137,7 @@ params ### Resources metadata example -{{< code-toggle copy=false >}} +{{< code-toggle >}} title: Application date : 2018-01-25 resources : @@ -184,7 +183,8 @@ The counter starts at 1 the first time they are used in either `name` or `title` For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as: -{{< code-toggle copy=false >}} +{{< code-toggle file="content/inspections/engine/index.md" fm=true >}} +title = 'Engine inspections' [[resources]] src = "*specs.pdf" title = "Specification #:counter" diff --git a/content/en/content-management/related.md b/content/en/content-management/related.md index 410e183b7..996831349 100644 --- a/content/en/content-management/related.md +++ b/content/en/content-management/related.md @@ -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. diff --git a/content/en/content-management/sections.md b/content/en/content-management/sections.md index a3e4397f3..8ee5c0d52 100644 --- a/content/en/content-management/sections.md +++ b/content/en/content-management/sections.md @@ -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 [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.
    {{ range .Ancestors.Reverse }}
  1. - {{ .LinkTitle }} + {{ .Title }}
    2. {{ end }}
  2. - {{ .LinkTitle }} + {{ .Title }}
@@ -154,7 +153,6 @@ Hugo renders this, where each breadcrumb is a link to the corresponding page: Home » Products » Product 1 » Benefits » Benefit 1 ``` - [archetype]: /content-management/archetypes/ [content type]: /content-management/types/ [directory structure]: /getting-started/directory-structure/ diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md index b1e32d902..29274486f 100644 --- a/content/en/content-management/shortcodes.md +++ b/content/en/content-management/shortcodes.md @@ -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 {{}} {{ range .Pages }} -

{{ .LinkTitle }}

+

{{ .Title }}

{{ end }} {{}} ``` @@ -181,7 +180,7 @@ Rendered: {{< highlight go-html-template >}} {{ range .Pages }} -

{{ .LinkTitle }}

+

{{ .Title }}

{{ end }} {{< /highlight >}} @@ -192,7 +191,7 @@ To specify one or more [highlighting options], include a quotation-encapsulated, ```text {{}} {{ range .Pages }} -

{{ .LinkTitle }}

+

{{ .Title }}

{{ end }} {{}} ``` @@ -201,7 +200,7 @@ Rendered: {{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}} {{ range .Pages }} -

{{ .LinkTitle }}

+

{{ .Title }}

{{ 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 {{}} ``` @@ -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 {{}} ``` @@ -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 -Neat +Neat Who ``` @@ -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" >}} {{}} {{< /code >}} @@ -398,7 +396,7 @@ To learn more about creating custom shortcodes, see the [shortcode template docu [partials]: /templates/partials/ [quickstart]: /getting-started/quick-start/ [sctemps]: /templates/shortcode-templates/ -[scvars]: /variables/shortcodes/ +[scvars]: /variables/shortcode/ [shortcode template documentation]: /templates/shortcode-templates/ [templatessection]: /templates/ [Vimeo]: https://vimeo.com/ diff --git a/content/en/content-management/static-files.md b/content/en/content-management/static-files.md index 78772af99..6eb4c0f86 100644 --- a/content/en/content-management/static-files.md +++ b/content/en/content-management/static-files.md @@ -27,13 +27,13 @@ This union filesystem will be served from your site root. So a file Here's an example of setting `staticDir` and `staticDir2` for a multi-language site: -{{< code-toggle copy=false file="hugo" >}} +{{< code-toggle file=hugo >}} staticDir = ["static1", "static2"] [languages] [languages.en] staticDir2 = "static_en" -baseURL = "https://example.com" +baseURL = "https://example.org/" languageName = "English" weight = 2 title = "In English" diff --git a/content/en/content-management/summaries.md b/content/en/content-management/summaries.md index 74c5623cb..120a07995 100644 --- a/content/en/content-management/summaries.md +++ b/content/en/content-management/summaries.md @@ -53,7 +53,7 @@ Pros Cons : Extra work for content authors, since they need to remember to type <!--more--> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/). -{{% warning "Be Precise with the Summary Divider" %}} +{{% note %}} Be careful to enter <!--more--> 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 <!--more--> summary divider Hugo will use the manual summary split method. {{% /note %}} diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md index 39fef0f9b..e8dae3afa 100644 --- a/content/en/content-management/syntax-highlighting.md +++ b/content/en/content-management/syntax-highlighting.md @@ -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} diff --git a/content/en/content-management/taxonomies.md b/content/en/content-management/taxonomies.md index af8297876..e9ca44ef7 100644 --- a/content/en/content-management/taxonomies.md +++ b/content/en/content-management/taxonomies.md @@ -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"] {{}} -{{% 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" {{}} @@ -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///_index.md` and add your metadata in its front matter. Continuing with our 'Actors' example, let's say you want to add a Wikipedia page link to each actor. Your terms pages would be something like this: -{{< code-toggle file="content/actors/bruce-willis/_index.md" fm=true copy=false >}} +{{< code-toggle file="content/actors/bruce-willis/_index.md" fm=true >}} title: "Bruce Willis" wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis" {{< /code-toggle >}} diff --git a/content/en/content-management/toc.md b/content/en/content-management/toc.md index ca179c77d..1474d1c7a 100644 --- a/content/en/content-management/toc.md +++ b/content/en/content-management/toc.md @@ -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 diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md index 60f9615b8..f1c3af2a5 100644 --- a/content/en/content-management/urls.md +++ b/content/en/content-management/urls.md @@ -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 → → ``` @@ -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 → → ``` @@ -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" >}} diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md index 7bc201288..2136b1692 100644 --- a/content/en/contribute/development.md +++ b/content/en/contribute/development.md @@ -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 %}} diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index 03939f837..3c4d99cd4 100644 --- a/content/en/contribute/documentation.md +++ b/content/en/contribute/documentation.md @@ -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 -{{}} +{{}} 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" diff --git a/content/en/documentation.md b/content/en/documentation.md index cf864e819..da7b3ef9b 100644 --- a/content/en/documentation.md +++ b/content/en/documentation.md @@ -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. diff --git a/content/en/functions/Get.md b/content/en/functions/Get.md deleted file mode 100644 index 142e9811b..000000000 --- a/content/en/functions/Get.md +++ /dev/null @@ -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/ diff --git a/content/en/functions/GetPage.md b/content/en/functions/GetPage.md deleted file mode 100644 index 4afebaca7..000000000 --- a/content/en/functions/GetPage.md +++ /dev/null @@ -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" >}} -
    -{{ $t := .Site.GetPage "/tags" }} -{{ range first 2 $t.Data.Terms.ByCount }} -
  • {{ . }}
    • -{{ end }} -
-{{< /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/ diff --git a/content/en/functions/Param.md b/content/en/functions/Param.md deleted file mode 100644 index a2826a3c8..000000000 --- a/content/en/functions/Param.md +++ /dev/null @@ -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 >}} diff --git a/content/en/functions/Render.md b/content/en/functions/Render.md deleted file mode 100644 index 02567845f..000000000 --- a/content/en/functions/Render.md +++ /dev/null @@ -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/ diff --git a/content/en/functions/RenderString.md b/content/en/functions/RenderString.md deleted file mode 100644 index 91414d6a0..000000000 --- a/content/en/functions/RenderString.md +++ /dev/null @@ -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 `

` 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). diff --git a/content/en/functions/Scratch.md b/content/en/functions/Scratch.md deleted file mode 100644 index 0640d6bcc..000000000 --- a/content/en/functions/Scratch.md +++ /dev/null @@ -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/ diff --git a/content/en/functions/Store.md b/content/en/functions/Store.md deleted file mode 100644 index 49b38188b..000000000 --- a/content/en/functions/Store.md +++ /dev/null @@ -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" }} -``` diff --git a/content/en/functions/Unix.md b/content/en/functions/Unix.md deleted file mode 100644 index ed49b72b5..000000000 --- a/content/en/functions/Unix.md +++ /dev/null @@ -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 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 -``` diff --git a/content/en/functions/_common/_index.md b/content/en/functions/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/functions/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + + diff --git a/content/en/functions/_common/glob-patterns.md b/content/en/functions/_common/glob-patterns.md new file mode 100644 index 000000000..3b0813f6f --- /dev/null +++ b/content/en/functions/_common/glob-patterns.md @@ -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` diff --git a/content/en/functions/_common/go-template-functions.md b/content/en/functions/_common/go-template-functions.md deleted file mode 100644 index b8722743e..000000000 --- a/content/en/functions/_common/go-template-functions.md +++ /dev/null @@ -1,3 +0,0 @@ -See Go's [text/template] documentation for more details. - -[text/template]: https://pkg.go.dev/text/template diff --git a/content/en/functions/_common/index.md b/content/en/functions/_common/index.md deleted file mode 100644 index cbb7365a6..000000000 --- a/content/en/functions/_common/index.md +++ /dev/null @@ -1,3 +0,0 @@ -+++ -headless = true -+++ diff --git a/content/en/functions/_common/locales.md b/content/en/functions/_common/locales.md index 259231cbf..fd8415781 100644 --- a/content/en/functions/_common/locales.md +++ b/content/en/functions/_common/locales.md @@ -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 %}} diff --git a/content/en/functions/_common/regular-expressions.md b/content/en/functions/_common/regular-expressions.md index 9da340849..48e020ac6 100644 --- a/content/en/functions/_common/regular-expressions.md +++ b/content/en/functions/_common/regular-expressions.md @@ -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. diff --git a/content/en/functions/_common/time-layout-string.md b/content/en/functions/_common/time-layout-string.md index 40932f8cf..827dc9894 100644 --- a/content/en/functions/_common/time-layout-string.md +++ b/content/en/functions/_common/time-layout-string.md @@ -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 :--|:-- diff --git a/content/en/functions/_index.md b/content/en/functions/_index.md index 4f8aa47ca..b4b58eada 100644 --- a/content/en/functions/_index.md +++ b/content/en/functions/_index.md @@ -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. diff --git a/content/en/functions/cast/ToFloat.md b/content/en/functions/cast/ToFloat.md index acf70bc43..51bc908b6 100644 --- a/content/en/functions/cast/ToFloat.md +++ b/content/en/functions/cast/ToFloat.md @@ -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] --- diff --git a/content/en/functions/cast/ToInt.md b/content/en/functions/cast/ToInt.md index b4a37cb6c..283da1e40 100644 --- a/content/en/functions/cast/ToInt.md +++ b/content/en/functions/cast/ToInt.md @@ -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 %}} diff --git a/content/en/functions/cast/ToString.md b/content/en/functions/cast/ToString.md index d677ecdbf..a701c9421 100644 --- a/content/en/functions/cast/ToString.md +++ b/content/en/functions/cast/ToString.md @@ -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] --- diff --git a/content/en/functions/cast/_index.md b/content/en/functions/cast/_index.md new file mode 100644 index 000000000..82389237a --- /dev/null +++ b/content/en/functions/cast/_index.md @@ -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. diff --git a/content/en/functions/collections/After.md b/content/en/functions/collections/After.md index e27c1507f..e5c2d9bd8 100644 --- a/content/en/functions/collections/After.md +++ b/content/en/functions/collections/After.md @@ -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" }} -
-

Featured Article

- {{ range first 1 .Pages.ByPublishDate.Reverse }} -
+
+

Featured Article

+ {{ range first 1 .Pages.ByPublishDate.Reverse }} +

{{ .Title }}

-
-

{{ .Description }}

-{{ end }} -
-
-

Recent Articles

- {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }} -
-
-

{{ .Title }}

-
-

{{ .Description }}

-
+
+

{{ .Description }}

{{ end }} - +
+
+

Recent Articles

+ {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }} +
+
+

{{ .Title }}

+
+

{{ .Description }}

+
+ {{ end }} +
{{ 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/ diff --git a/content/en/functions/collections/Append.md b/content/en/functions/collections/Append.md index 31657288f..db98355b4 100644 --- a/content/en/functions/collections/Append.md +++ b/content/en/functions/collections/Append.md @@ -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 }} {{ end }} diff --git a/content/en/functions/collections/Apply.md b/content/en/functions/collections/Apply.md index 4d972b853..abd6fca77 100644 --- a/content/en/functions/collections/Apply.md +++ b/content/en/functions/collections/Apply.md @@ -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" }} diff --git a/content/en/functions/collections/Complement.md b/content/en/functions/collections/Complement.md index 28b7ded3d..773323b38 100644 --- a/content/en/functions/collections/Complement.md +++ b/content/en/functions/collections/Complement.md @@ -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 }} - {{ .LinkTitle }} + {{ .Title }} {{ 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") }} - {{ .LinkTitle }} + {{ .Title }} {{ end }} ``` diff --git a/content/en/functions/collections/Delimit.md b/content/en/functions/collections/Delimit.md index 0fc3ef537..6aea467ee 100644 --- a/content/en/functions/collections/Delimit.md +++ b/content/en/functions/collections/Delimit.md @@ -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 ``` diff --git a/content/en/functions/collections/Dictionary.md b/content/en/functions/collections/Dictionary.md index 28c387726..a90c9e590 100644 --- a/content/en/functions/collections/Dictionary.md +++ b/content/en/functions/collections/Dictionary.md @@ -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: diff --git a/content/en/functions/collections/EchoParam.md b/content/en/functions/collections/EchoParam.md deleted file mode 100644 index 7617eedd9..000000000 --- a/content/en/functions/collections/EchoParam.md +++ /dev/null @@ -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 -``` diff --git a/content/en/functions/collections/First.md b/content/en/functions/collections/First.md index ddb045382..ab7ea0b72 100644 --- a/content/en/functions/collections/First.md +++ b/content/en/functions/collections/First.md @@ -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 diff --git a/content/en/functions/collections/Group.md b/content/en/functions/collections/Group.md index 29220f1f7..cc919ca2a 100644 --- a/content/en/functions/collections/Group.md +++ b/content/en/functions/collections/Group.md @@ -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 }} {{ 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). diff --git a/content/en/functions/collections/In.md b/content/en/functions/collections/In.md index 57ffbd653..8a3d31d0e 100644 --- a/content/en/functions/collections/In.md +++ b/content/en/functions/collections/In.md @@ -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 diff --git a/content/en/functions/collections/IndexFunction.md b/content/en/functions/collections/IndexFunction.md index cd063f36e..5bd189d9f 100644 --- a/content/en/functions/collections/IndexFunction.md +++ b/content/en/functions/collections/IndexFunction.md @@ -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 >}} diff --git a/content/en/functions/collections/Intersect.md b/content/en/functions/collections/Intersect.md index 6a2c131b4..efcbbf470 100644 --- a/content/en/functions/collections/Intersect.md +++ b/content/en/functions/collections/Intersect.md @@ -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/ diff --git a/content/en/functions/collections/IsSet.md b/content/en/functions/collections/IsSet.md index 93fb9f8f6..76b336ae3 100644 --- a/content/en/functions/collections/IsSet.md +++ b/content/en/functions/collections/IsSet.md @@ -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 >}} diff --git a/content/en/functions/collections/KeyVals.md b/content/en/functions/collections/KeyVals.md index f3e0c559d..6019ede51 100644 --- a/content/en/functions/collections/KeyVals.md +++ b/content/en/functions/collections/KeyVals.md @@ -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). diff --git a/content/en/functions/collections/Last.md b/content/en/functions/collections/Last.md index 3f8496354..4eda570ff 100644 --- a/content/en/functions/collections/Last.md +++ b/content/en/functions/collections/Last.md @@ -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] --- diff --git a/content/en/functions/collections/Merge.md b/content/en/functions/collections/Merge.md index 908f1738a..3f5208cfc 100644 --- a/content/en/functions/collections/Merge.md +++ b/content/en/functions/collections/Merge.md @@ -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] --- diff --git a/content/en/functions/collections/NewScratch.md b/content/en/functions/collections/NewScratch.md index 0df90bb96..1cfc2dc4b 100644 --- a/content/en/functions/collections/NewScratch.md +++ b/content/en/functions/collections/NewScratch.md @@ -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. diff --git a/content/en/functions/collections/Querify.md b/content/en/functions/collections/Querify.md index c94d51133..e195c417f 100644 --- a/content/en/functions/collections/Querify.md +++ b/content/en/functions/collections/Querify.md @@ -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] diff --git a/content/en/functions/collections/Reverse.md b/content/en/functions/collections/Reverse.md index 521adc6f2..12c964c76 100644 --- a/content/en/functions/collections/Reverse.md +++ b/content/en/functions/collections/Reverse.md @@ -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] ``` diff --git a/content/en/functions/collections/Seq.md b/content/en/functions/collections/Seq.md index 65ff1432f..fca3e92d7 100644 --- a/content/en/functions/collections/Seq.md +++ b/content/en/functions/collections/Seq.md @@ -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 diff --git a/content/en/functions/collections/Shuffle.md b/content/en/functions/collections/Shuffle.md index 8388d5332..18b8cc664 100644 --- a/content/en/functions/collections/Shuffle.md +++ b/content/en/functions/collections/Shuffle.md @@ -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 diff --git a/content/en/functions/collections/Slice.md b/content/en/functions/collections/Slice.md index a30800ed3..1e372ce44 100644 --- a/content/en/functions/collections/Slice.md +++ b/content/en/functions/collections/Slice.md @@ -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] diff --git a/content/en/functions/collections/Sort.md b/content/en/functions/collections/Sort.md index bb0f82cde..90fbc7591 100644 --- a/content/en/functions/collections/Sort.md +++ b/content/en/functions/collections/Sort.md @@ -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" }}

{{ .Title }}

{{ end }} -{{< /code >}} +``` - -[built-in methods for sorting page collections]: /templates/lists/#order-content +[built-in methods for sorting page collections]: /templates/lists/#sort-content diff --git a/content/en/functions/collections/SymDiff.md b/content/en/functions/collections/SymDiff.md index ea9f20123..828c10ce5 100644 --- a/content/en/functions/collections/SymDiff.md +++ b/content/en/functions/collections/SymDiff.md @@ -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 . diff --git a/content/en/functions/collections/Union.md b/content/en/functions/collections/Union.md index 119da6fb4..bdc7c2237 100644 --- a/content/en/functions/collections/Union.md +++ b/content/en/functions/collections/Union.md @@ -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 diff --git a/content/en/functions/collections/Uniq.md b/content/en/functions/collections/Uniq.md index 1b0a8f8f4..bda239568 100644 --- a/content/en/functions/collections/Uniq.md +++ b/content/en/functions/collections/Uniq.md @@ -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] ``` diff --git a/content/en/functions/collections/Where.md b/content/en/functions/collections/Where.md index df6cec89f..3b8bbdd37 100644 --- a/content/en/functions/collections/Where.md +++ b/content/en/functions/collections/Where.md @@ -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` }} -

{{ .LinkTitle }}

+

{{ .Title }}

{{ 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 >}} diff --git a/content/en/functions/collections/_index.md b/content/en/functions/collections/_index.md new file mode 100644 index 000000000..51981f79b --- /dev/null +++ b/content/en/functions/collections/_index.md @@ -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. diff --git a/content/en/functions/compare/Cond.md b/content/en/functions/compare/Conditional.md similarity index 79% rename from content/en/functions/compare/Cond.md rename to content/en/functions/compare/Conditional.md index 4b92a893c..6d693770d 100644 --- a/content/en/functions/compare/Cond.md +++ b/content/en/functions/compare/Conditional.md @@ -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 diff --git a/content/en/functions/compare/Default.md b/content/en/functions/compare/Default.md index 24ad37ef2..1e6bd7968 100644 --- a/content/en/functions/compare/Default.md +++ b/content/en/functions/compare/Default.md @@ -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 + + +{{ 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 }} -

{{ .Params.newparam | default $old }}

-``` - -Which would return: - -```html -

The default function helps make your templating DRYer.

-``` - -And then using dot notation - -```go-html-template -{{ .Params.seo_title | default .Title }} -``` - -Which would return - -```html -Sane Defaults -``` - -The following have equivalent return values but are far less terse. This demonstrates the utility of `default`: - -Using `if`: - -```go-html-template -{{ if .Params.seo_title }}{{ .Params.seo_title }}{{ else }}{{ .Title }}{{ end }} -=> Sane Defaults -``` - -Using `with`: - -```go-html-template -{{ with .Params.seo_title }}{{ . }}{{ else }}{{ .Title }}{{ end }} -=> Sane Defaults +{{ default 42 0 }} → 42 +{{ default 42 "" }} → 42 +{{ default 42 dict }} → 42 +{{ default 42 slice }} → 42 +{{ default 42 }} → 42 ``` diff --git a/content/en/functions/compare/Eq.md b/content/en/functions/compare/Eq.md index 010fc51b3..49350e676 100644 --- a/content/en/functions/compare/Eq.md +++ b/content/en/functions/compare/Eq.md @@ -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] --- diff --git a/content/en/functions/compare/Ge.md b/content/en/functions/compare/Ge.md index 6bb48dd00..479ecf990 100644 --- a/content/en/functions/compare/Ge.md +++ b/content/en/functions/compare/Ge.md @@ -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] --- diff --git a/content/en/functions/compare/Gt.md b/content/en/functions/compare/Gt.md index 4691718ef..0af289ce2 100644 --- a/content/en/functions/compare/Gt.md +++ b/content/en/functions/compare/Gt.md @@ -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] --- diff --git a/content/en/functions/compare/Le.md b/content/en/functions/compare/Le.md index 792ea6ce6..319d376f6 100644 --- a/content/en/functions/compare/Le.md +++ b/content/en/functions/compare/Le.md @@ -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] --- diff --git a/content/en/functions/compare/Lt.md b/content/en/functions/compare/Lt.md index 537c23b6f..3fe8f1d2c 100644 --- a/content/en/functions/compare/Lt.md +++ b/content/en/functions/compare/Lt.md @@ -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] --- diff --git a/content/en/functions/compare/Ne.md b/content/en/functions/compare/Ne.md index 412f43d49..2d9f826fc 100644 --- a/content/en/functions/compare/Ne.md +++ b/content/en/functions/compare/Ne.md @@ -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] --- diff --git a/content/en/functions/compare/_index.md b/content/en/functions/compare/_index.md new file mode 100644 index 000000000..a9b3a7b27 --- /dev/null +++ b/content/en/functions/compare/_index.md @@ -0,0 +1,12 @@ +--- +title: Compare functions +linkTitle: compare +description: Template functions to compare two or more values. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to compare two or more values. diff --git a/content/en/functions/crypto/FNV32a.md b/content/en/functions/crypto/FNV32a.md index 7a7fe303e..5c091ebee 100644 --- a/content/en/functions/crypto/FNV32a.md +++ b/content/en/functions/crypto/FNV32a.md @@ -1,21 +1,17 @@ --- title: crypto.FNV32a description: Returns the FNV (Fowler–Noll–Vo) 32 bit hash of a given string. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/crypto/HMAC + - functions/crypto/MD5 + - functions/crypto/SHA1 + - functions/crypto/SHA256 returnType: int signatures: [crypto.FNV32a STRING] -relatedFunctions: - - crypto.FNV32a - - crypto.HMAC - - crypto.MD5 - - crypto.SHA1 - - crypto.SHA256 aliases: [/functions/crypto.fnv32a] --- diff --git a/content/en/functions/crypto/HMAC.md b/content/en/functions/crypto/HMAC.md index e58619b38..1906689a2 100644 --- a/content/en/functions/crypto/HMAC.md +++ b/content/en/functions/crypto/HMAC.md @@ -1,22 +1,17 @@ --- title: crypto.HMAC -linkTitle: hmac description: Returns a cryptographic hash that uses a key to sign a message. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [hmac] + related: + - functions/crypto/FNV32a + - functions/crypto/MD5 + - functions/crypto/SHA1 + - functions/crypto/SHA256 returnType: string signatures: ['crypto.HMAC HASH_TYPE KEY MESSAGE [ENCODING]'] -relatedFunctions: - - crypto.FNV32a - - crypto.HMAC - - crypto.MD5 - - crypto.SHA1 - - crypto.SHA256 aliases: [/functions/hmac] --- diff --git a/content/en/functions/crypto/MD5.md b/content/en/functions/crypto/MD5.md index 9415e015c..6c78ae55f 100644 --- a/content/en/functions/crypto/MD5.md +++ b/content/en/functions/crypto/MD5.md @@ -1,28 +1,22 @@ --- title: crypto.MD5 -linkTitle: md5 -description: hashes the given input and returns its MD5 checksum. -categories: [functions] +description: Hashes the given input and returns its MD5 checksum. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [md5] + related: + - functions/crypto/FNV32a + - functions/crypto/HMAC + - functions/crypto/SHA1 + - functions/crypto/SHA256 returnType: string signatures: [crypto.MD5 INPUT] -relatedFunctions: - - crypto.FNV32a - - crypto.HMAC - - crypto.MD5 - - crypto.SHA1 - - crypto.SHA256 aliases: [/functions/md5] --- ```go-html-template {{ md5 "Hello world" }} → 3e25960a79dbc69b674cd4ec67a72c62 - ``` This can be useful if you want to use [Gravatar](https://en.gravatar.com/) for generating a unique avatar: diff --git a/content/en/functions/crypto/SHA1.md b/content/en/functions/crypto/SHA1.md index 6269efe38..247c9842a 100644 --- a/content/en/functions/crypto/SHA1.md +++ b/content/en/functions/crypto/SHA1.md @@ -1,22 +1,17 @@ --- title: crypto.SHA1 -linkTitle: sha1 description: Hashes the given input and returns its SHA1 checksum. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [sha1] + related: + - functions/crypto/FNV32a + - functions/crypto/HMAC + - functions/crypto/MD5 + - functions/crypto/SHA256 returnType: string signatures: [crypto.SHA1 INPUT] -relatedFunctions: - - crypto.FNV32a - - crypto.HMAC - - crypto.MD5 - - crypto.SHA1 - - crypto.SHA256 aliases: [/functions/sha,/functions/sha1] --- diff --git a/content/en/functions/crypto/SHA256.md b/content/en/functions/crypto/SHA256.md index 3019432d2..279cec35c 100644 --- a/content/en/functions/crypto/SHA256.md +++ b/content/en/functions/crypto/SHA256.md @@ -1,22 +1,17 @@ --- title: crypto.SHA256 -linkTitle: sha256 description: Hashes the given input and returns its SHA256 checksum. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [sha256] + related: + - functions/crypto/FNV32a + - functions/crypto/HMAC + - functions/crypto/MD5 + - functions/crypto/SHA1 returnType: string signatures: [crypto.SHA256 INPUT] -relatedFunctions: - - crypto.FNV32a - - crypto.HMAC - - crypto.MD5 - - crypto.SHA1 - - crypto.SHA256 aliases: [/functions/sha256] --- diff --git a/content/en/functions/crypto/_index.md b/content/en/functions/crypto/_index.md new file mode 100644 index 000000000..5c95aab6e --- /dev/null +++ b/content/en/functions/crypto/_index.md @@ -0,0 +1,12 @@ +--- +title: Crypto functions +linkTitle: crypto +description: Template functions to create cryptographic hashes. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to create cryptographic hashes. diff --git a/content/en/functions/data/GetCSV.md b/content/en/functions/data/GetCSV.md index e02c1588c..b49f190e3 100644 --- a/content/en/functions/data/GetCSV.md +++ b/content/en/functions/data/GetCSV.md @@ -1,19 +1,17 @@ --- title: data.GetCSV -linkTitle: getCSV description: Returns an array of arrays from a local or remote CSV file, or an error if the file does not exist. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [getCSV] - returnType: '[]string' - signatures: [data.GetCSV SEPARATOR PATHPART...] -relatedFunctions: - - data.GetCSV - - data.GetJSON + related: + - functions/data/GetJSON + - functions/resources/Get + - functions/resources/GetRemote + - methods/page/Resources + returnType: '[][]string' + signatures: ['data.GetCSV SEPARATOR INPUT... [OPTIONS]'] toc: true --- @@ -32,6 +30,12 @@ Access the data with either of the following: {{ $data := getCSV "," "other-files/" "pets.csv" }} ``` +{{% note %}} +When working with local data, the filepath is relative to the working directory. + +You must not place CSV files in the project's data directory. +{{% /note %}} + Access remote data with either of the following: ```go-html-template @@ -49,9 +53,25 @@ The resulting data structure is an array of arrays: ] ``` +## Options + +Add headers to the request by providing an options map: + +```go-html-template +{{ $opts := dict "Authorization" "Bearer abcd" }} +{{ $data := getCSV "," "https://example.org/pets.csv" $opts }} +``` + +Add multiple headers using a slice: + +```go-html-template +{{ $opts := dict "X-List" (slice "a" "b" "c") }} +{{ $data := getCSV "," "https://example.org/pets.csv" $opts }} +``` + ## Global resource alternative -Consider using `resources.Get` with [`transform.Unmarshal`] when accessing a global resource. +Consider using the [`resources.Get`] function with [`transform.Unmarshal`] when accessing a global resource. ```text my-project/ @@ -73,7 +93,9 @@ my-project/ ## Page resource alternative -Consider using `.Resources.Get` with [`transform.Unmarshal`] when accessing a page resource. +Consider using the [`Resources.Get`] method with [`transform.Unmarshal`] when accessing a page resource. + + ```text my-project/ @@ -97,7 +119,7 @@ my-project/ ## Remote resource alternative -Consider using `resources.GetRemote` with [`transform.Unmarshal`] for improved error handling when accessing a remote resource. +Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control. ```go-html-template {{ $data := "" }} @@ -114,4 +136,7 @@ Consider using `resources.GetRemote` with [`transform.Unmarshal`] for improved e {{ end }} ``` +[`Resources.Get`]: methods/page/Resources +[`resources.GetRemote`]: /functions/resources/getremote +[`resources.Get`]: /functions/resources/get [`transform.Unmarshal`]: /functions/transform/unmarshal diff --git a/content/en/functions/data/GetJSON.md b/content/en/functions/data/GetJSON.md index 37ee8e9a1..96812e7c0 100644 --- a/content/en/functions/data/GetJSON.md +++ b/content/en/functions/data/GetJSON.md @@ -1,19 +1,17 @@ --- title: data.GetJSON -linkTitle: getJSON description: Returns a JSON object from a local or remote JSON file, or an error if the file does not exist. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [getJSON] + related: + - functions/data/GetCSV + - functions/resources/Get + - functions/resources/GetRemote + - methods/page/Resources returnType: any - signatures: [data.GetJSON PATHPART...] -relatedFunctions: - - data.GetCSV - - data.GetJSON + signatures: ['data.GetJSON INPUT... [OPTIONS]'] toc: true --- @@ -28,15 +26,19 @@ my-project/ Access the data with either of the following: ```go-html-template -{{ $data := getCSV "," "other-files/books.json" }} -{{ $data := getCSV "," "other-files/" "books.json" }} +{{ $data := getJSON "other-files/books.json" }} +{{ $data := getJSON "other-files/" "books.json" }} ``` +{{% note %}} +When working with local data, the filepath is relative to the working directory. +{{% /note %}} + Access remote data with either of the following: ```go-html-template -{{ $data := getCSV "," "https://example.org/books.json" }} -{{ $data := getCSV "," "https://example.org/" "books.json" }} +{{ $data := getJSON "https://example.org/books.json" }} +{{ $data := getJSON "https://example.org/" "books.json" }} ``` The resulting data structure is a JSON object: @@ -56,9 +58,25 @@ The resulting data structure is a JSON object: ] ``` +## Options + +Add headers to the request by providing an options map: + +```go-html-template +{{ $opts := dict "Authorization" "Bearer abcd" }} +{{ $data := getJSON "https://example.org/books.json" $opts }} +``` + +Add multiple headers using a slice: + +```go-html-template +{{ $opts := dict "X-List" (slice "a" "b" "c") }} +{{ $data := getJSON "https://example.org/books.json" $opts }} +``` + ## Global resource alternative -Consider using `resources.Get` with [`transform.Unmarshal`] when accessing a global resource. +Consider using the [`resources.Get`] function with [`transform.Unmarshal`] when accessing a global resource. ```text my-project/ @@ -80,7 +98,7 @@ my-project/ ## Page resource alternative -Consider using `.Resources.Get` with [`transform.Unmarshal`] when accessing a page resource. +Consider using the [`Resources.Get`] method with [`transform.Unmarshal`] when accessing a page resource. ```text my-project/ @@ -104,7 +122,7 @@ my-project/ ## Remote resource alternative -Consider using `resources.GetRemote` with [`transform.Unmarshal`] for improved error handling when accessing a remote resource. +Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control. ```go-html-template {{ $data := "" }} @@ -121,4 +139,7 @@ Consider using `resources.GetRemote` with [`transform.Unmarshal`] for improved e {{ end }} ``` +[`Resources.Get`]: methods/page/Resources +[`resources.GetRemote`]: /functions/resources/getremote +[`resources.Get`]: /functions/resources/get [`transform.Unmarshal`]: /functions/transform/unmarshal diff --git a/content/en/functions/data/_index.md b/content/en/functions/data/_index.md new file mode 100644 index 000000000..142d6b528 --- /dev/null +++ b/content/en/functions/data/_index.md @@ -0,0 +1,12 @@ +--- +title: Data functions +linkTitle: data +description: Template functions to read local or remote data files. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to read local or remote data files. diff --git a/content/en/functions/debug/Dump.md b/content/en/functions/debug/Dump.md index ff505a76b..d3161605f 100644 --- a/content/en/functions/debug/Dump.md +++ b/content/en/functions/debug/Dump.md @@ -1,16 +1,13 @@ --- title: debug.Dump description: Returns an object dump as a string. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: [] returnType: string signatures: [debug.Dump VALUE] -relatedFunctions: [] --- ```go-html-template @@ -43,8 +40,6 @@ relatedFunctions: [] } ``` - - {{% note %}} Output from this function may change from one release to the next. Use for debugging only. {{% /note %}} diff --git a/content/en/functions/debug/Timer.md b/content/en/functions/debug/Timer.md index cfa2ad6dc..3e3af0a0c 100644 --- a/content/en/functions/debug/Timer.md +++ b/content/en/functions/debug/Timer.md @@ -1,21 +1,18 @@ --- title: debug.Timer description: Creates a named timer that reports elapsed time to the console. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: [] returnType: debug.Timer signatures: [debug.Timer NAME] -relatedFunctions: [] --- {{< new-in "0.120.0" >}} -Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottlenecks in templates. +Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottle necks in templates. The timer starts when you instantiate it, and stops when you call its `Stop` method. diff --git a/content/en/functions/debug/_index.md b/content/en/functions/debug/_index.md new file mode 100644 index 000000000..418828515 --- /dev/null +++ b/content/en/functions/debug/_index.md @@ -0,0 +1,12 @@ +--- +title: Debug functions +linkTitle: debug +description: Template functions to debug your templates. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to debug your templates. diff --git a/content/en/functions/encoding/Base64Decode.md b/content/en/functions/encoding/Base64Decode.md index 8bd554c83..821ca805a 100644 --- a/content/en/functions/encoding/Base64Decode.md +++ b/content/en/functions/encoding/Base64Decode.md @@ -1,24 +1,19 @@ --- title: encoding.Base64Decode -linkTitle: base64Decode description: Returns the base64 decoding of the given content. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [base64Decode] + related: + - functions/encoding/Base64Encode returnType: string signatures: [encoding.Base64Decode INPUT] -signatures: - - - - base64Decode INPUT aliases: [/functions/base64Decode] --- ```go-html-template -{{ "SHVnbw==" | base64Decode }} → "Hugo" +{{ "SHVnbw==" | base64Decode }} → Hugo ``` Use the `base64Decode` function to decode responses from APIs. For example, the result of this call to GitHub's API contains the base64-encoded representation of the repository's README file: diff --git a/content/en/functions/encoding/Base64Encode.md b/content/en/functions/encoding/Base64Encode.md index d548aca8e..14f67a132 100644 --- a/content/en/functions/encoding/Base64Encode.md +++ b/content/en/functions/encoding/Base64Encode.md @@ -1,22 +1,17 @@ --- title: encoding.Base64Encode -linkTitle: base64Encode description: Returns the base64 decoding of the given content. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [base64Encode] + related: + - functions/encoding/Base64Decode returnType: string signatures: [encoding.Base64Encode INPUT] -relatedFunctions: - - encoding.Base64Decode - - encoding.Base64Encode aliases: [/functions/base64, /functions/base64Encode] --- ```go-html-template -{{ "Hugo" | base64Encode }} → "SHVnbw==" +{{ "Hugo" | base64Encode }} → SHVnbw== ``` diff --git a/content/en/functions/encoding/Jsonify.md b/content/en/functions/encoding/Jsonify.md index 0b9cb2e74..09b181e31 100644 --- a/content/en/functions/encoding/Jsonify.md +++ b/content/en/functions/encoding/Jsonify.md @@ -1,31 +1,25 @@ --- title: encoding.Jsonify -linkTitle: jsonify description: Encodes a given object to JSON. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [jsonify] returnType: template.HTML + related: + - functions/transform/Remarshal + - functions/transform/Unmarshal signatures: - encoding.Jsonify INPUT - encoding.Jsonify OPTIONS INPUT -relatedFunctions: - - encoding.Jsonify - - transform.Remarshal - - transform.Unmarshal aliases: [/functions/jsonify] --- -To customize the printing of the JSON, pass a map of options as the first +To customize the printing of the JSON, pass an options map as the first argument. Supported options are "prefix" and "indent". Each JSON element in the output will begin on a new line beginning with *prefix* followed by one or more copies of *indent* according to the indentation nesting. - ```go-html-template {{ dict "title" .Title "content" .Plain | jsonify }} {{ dict "title" .Title "content" .Plain | jsonify (dict "indent" " ") }} @@ -34,15 +28,15 @@ more copies of *indent* according to the indentation nesting. ## Options -indent ("") -: Indentation to use. +indent +: (`string`) Indentation to use. Default is "". -prefix ("") -: Indentation prefix. +prefix +: (`string`) Indentation prefix. Default is "". noHTMLEscape (false) -: Disable escaping of problematic HTML characters inside JSON quoted strings. The default behavior is to escape &, <, and > to \u0026, \u003c, and \u003e to avoid certain safety problems that can arise when embedding JSON in HTML. +: (`bool`) Disable escaping of problematic HTML characters inside JSON quoted strings. The default behavior is to escape `&`, `<`, and `>` to `\u0026`, `\u003c`, and `\u003e` to avoid certain safety problems that can arise when embedding JSON in HTML. Default is `false`. -See also the `.PlainWords`, `.Plain`, and `.RawContent` [page variables][pagevars]. +See also the `.PlainWords`, `.Plain`, and `.RawContent` [page variables]. -[pagevars]: /variables/page/ +[page variables]: /variables/page/ diff --git a/content/en/functions/encoding/_index.md b/content/en/functions/encoding/_index.md new file mode 100644 index 000000000..3c4c4519e --- /dev/null +++ b/content/en/functions/encoding/_index.md @@ -0,0 +1,12 @@ +--- +title: Encoding functions +linkTitle: encoding +description: Template functions to encode and decode data. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to encode and decode data. diff --git a/content/en/functions/fmt/Errorf.md b/content/en/functions/fmt/Errorf.md index da9845073..c23d27372 100644 --- a/content/en/functions/fmt/Errorf.md +++ b/content/en/functions/fmt/Errorf.md @@ -1,20 +1,15 @@ --- title: fmt.Errorf -linkTitle: errorf description: Log an ERROR from a template. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [errorf] + related: + - functions/fmt/Erroridf + - functions/fmt/Warnf returnType: string signatures: ['fmt.Errorf FORMAT [INPUT]'] -relatedFunctions: - - fmt.Errorf - - fmt.Erroridf - - fmt.Warnf aliases: [/functions/errorf] --- diff --git a/content/en/functions/fmt/Erroridf.md b/content/en/functions/fmt/Erroridf.md index 986810436..a84671e3e 100644 --- a/content/en/functions/fmt/Erroridf.md +++ b/content/en/functions/fmt/Erroridf.md @@ -1,20 +1,15 @@ --- title: fmt.Erroridf -linkTitle: erroridf description: Log a suppressable ERROR from a template. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [erroridf] + related: + - functions/fmt/Errorf + - functions/fmt/Warnf returnType: string signatures: ['fmt.Erroridf ID FORMAT [INPUT]'] -relatedFunctions: - - fmt.Errorf - - fmt.Erroridf - - fmt.Warnf aliases: [/functions/erroridf] --- @@ -40,7 +35,7 @@ ignoreErrors = ["error-42"] To suppress this message: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} ignoreErrors = ["error-42"] {{< /code-toggle >}} diff --git a/content/en/functions/fmt/Print.md b/content/en/functions/fmt/Print.md index f9ff885f8..6f3128e5f 100644 --- a/content/en/functions/fmt/Print.md +++ b/content/en/functions/fmt/Print.md @@ -1,25 +1,20 @@ --- title: fmt.Print -linkTitle: print description: Prints the default representation of the given arguments using the standard `fmt.Print` function. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [print] + related: + - functions/fmt/Printf + - functions/fmt/Println returnType: string signatures: [fmt.Print INPUT] -relatedFunctions: - - fmt.Print - - fmt.Printf - - fmt.Println aliases: [/functions/print] --- ```go-html-template -{{ print "foo" }} → "foo" -{{ print "foo" "bar" }} → "foobar" +{{ print "foo" }} → foo +{{ print "foo" "bar" }} → foobar {{ print (slice 1 2 3) }} → [1 2 3] ``` diff --git a/content/en/functions/fmt/Printf.md b/content/en/functions/fmt/Printf.md index 06b7222e9..af2fd398d 100644 --- a/content/en/functions/fmt/Printf.md +++ b/content/en/functions/fmt/Printf.md @@ -1,20 +1,15 @@ --- title: fmt.Printf -linkTitle: printf description: Formats a string using the standard `fmt.Sprintf` function. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [printf] + related: + - functions/fmt/Print + - functions/fmt/Println returnType: string signatures: ['fmt.Printf FORMAT [INPUT]'] -relatedFunctions: - - fmt.Print - - fmt.Printf - - fmt.Println aliases: [/functions/printf] --- diff --git a/content/en/functions/fmt/Println.md b/content/en/functions/fmt/Println.md index 358b5f8ac..a4db56ffb 100644 --- a/content/en/functions/fmt/Println.md +++ b/content/en/functions/fmt/Println.md @@ -1,23 +1,18 @@ --- title: fmt.Println -linkTitle: println -description: Prints the default representation of the given argument using the standard `fmt.Print` function and enforces a linebreak. -categories: [functions] +description: Prints the default representation of the given argument using the standard `fmt.Print` function and enforces a line break. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [println] + related: + - functions/fmt/Print + - functions/fmt/Printf returnType: string signatures: [fmt.Println INPUT] -relatedFunctions: - - fmt.Print - - fmt.Printf - - fmt.Println aliases: [/functions/println] --- ```go-html-template -{{ println "foo" }} → "foo\n" +{{ println "foo" }} → foo\n ``` diff --git a/content/en/functions/fmt/Warnf.md b/content/en/functions/fmt/Warnf.md index be579a216..02dc0b9c1 100644 --- a/content/en/functions/fmt/Warnf.md +++ b/content/en/functions/fmt/Warnf.md @@ -1,20 +1,15 @@ --- title: fmt.Warnf -linkTitle: warnf description: Log a WARNING from a template. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [warnf] + related: + - functions/fmt/Errorf + - functions/fmt/Erroridf returnType: string signatures: ['fmt.Warnf FORMAT [INPUT]'] -relatedFunctions: - - fmt.Errorf - - fmt.Erroridf - - fmt.Warnf aliases: [/functions/warnf] --- diff --git a/content/en/functions/fmt/_index.md b/content/en/functions/fmt/_index.md new file mode 100644 index 000000000..51ef847ca --- /dev/null +++ b/content/en/functions/fmt/_index.md @@ -0,0 +1,12 @@ +--- +title: Fmt functions +linkTitle: fmt +description: Template functions to print strings within a template or to print messages to the terminal +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to print strings within a template or to print messages to the terminal. diff --git a/content/en/functions/global/_index.md b/content/en/functions/global/_index.md new file mode 100644 index 000000000..1e609b56e --- /dev/null +++ b/content/en/functions/global/_index.md @@ -0,0 +1,11 @@ +--- +title: Global functions +linkTitle: global +description: Global template functions to access page and site data. +categories: [] +menu: + docs: + parent: functions +--- + +Use these global functions to access page and site data. diff --git a/content/en/functions/page/index.md b/content/en/functions/global/page.md similarity index 91% rename from content/en/functions/page/index.md rename to content/en/functions/global/page.md index 01f014078..fda767f21 100644 --- a/content/en/functions/page/index.md +++ b/content/en/functions/global/page.md @@ -1,19 +1,15 @@ --- title: page -description: Provides global access to the .Page object. -categories: [functions] +description: Provides global access to a Page object. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/global/site returnType: signatures: [page] -relatedFunctions: - - hugo - - page - - site +toc: true aliases: [/functions/page] --- @@ -47,7 +43,7 @@ Use the global `page` function to access the `Page` object from anywhere in any ### Be aware of top-level context -The global `page` function accesses the `Page` object passed into the top-level template. +The global `page` function accesses the `Page` object passed into the top-level template. With this content structure: @@ -94,7 +90,7 @@ Consider this section template: ```go-html-template {{ range .Pages }} -

{{ .LinkTitle }}

+

{{ .Title }}

{{ .Summary }} {{ end }} ``` diff --git a/content/en/functions/site/index.md b/content/en/functions/global/site.md similarity index 75% rename from content/en/functions/site/index.md rename to content/en/functions/global/site.md index 3341bff98..2ae36d957 100644 --- a/content/en/functions/site/index.md +++ b/content/en/functions/global/site.md @@ -1,19 +1,14 @@ --- title: site -description: Provides global access to the .Site object. -categories: [functions] +description: Provides global access to the Site object. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/global/page returnType: signatures: [site] -relatedFunctions: - - hugo - - page - - site aliases: [/functions/site] --- diff --git a/content/en/functions/go-template/_common/_index.md b/content/en/functions/go-template/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/functions/go-template/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + + diff --git a/content/en/functions/go-template/_common/text-template.md b/content/en/functions/go-template/_common/text-template.md new file mode 100644 index 000000000..71718c3fd --- /dev/null +++ b/content/en/functions/go-template/_common/text-template.md @@ -0,0 +1,7 @@ +--- +# Do not remove front matter. +--- + +See Go's [text/template] documentation for more information. + +[text/template]: https://pkg.go.dev/text/template diff --git a/content/en/functions/go-template/_common/truthy-falsy.md b/content/en/functions/go-template/_common/truthy-falsy.md new file mode 100644 index 000000000..c8fc9e09e --- /dev/null +++ b/content/en/functions/go-template/_common/truthy-falsy.md @@ -0,0 +1,5 @@ +--- +# Do not remove front matter. +--- + +In Go templates, the falsy values are `false`, `0`, any nil pointer or interface value, and any array, slice, map, or string of length zero. Everything else is truthy. diff --git a/content/en/functions/go-template/_index.md b/content/en/functions/go-template/_index.md new file mode 100644 index 000000000..9d7f89e08 --- /dev/null +++ b/content/en/functions/go-template/_index.md @@ -0,0 +1,14 @@ +--- +title: Go template functions +linkTitle: go template +description: Template functions and statements provided by Go's text/template package. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +These are the statements, operators, and functions provided by Go's [text/template] package. + +[text/template]: https://pkg.go.dev/text/template diff --git a/content/en/functions/go-template/and.md b/content/en/functions/go-template/and.md new file mode 100644 index 000000000..6bc8c60a5 --- /dev/null +++ b/content/en/functions/go-template/and.md @@ -0,0 +1,26 @@ +--- +title: and +description: Returns the first falsy argument. If all arguments are truthy, returns the last argument. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/not + - functions/go-template/or + returnType: any + signatures: [and VALUE...] +--- + +{{% include "functions/go-template/_common/truthy-falsy.md" %}} + +```go-html-template +{{ and 1 0 "" }} → 0 (int) +{{ and 1 false 0 }} → false (bool) + +{{ and 1 2 3 }} → 3 (int) +{{ and "a" "b" "c" }} → c (string) +{{ and "a" 1 true }} → true (bool) +``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/content/en/functions/go-template/block.md b/content/en/functions/go-template/block.md new file mode 100644 index 000000000..f5c7644df --- /dev/null +++ b/content/en/functions/go-template/block.md @@ -0,0 +1,55 @@ +--- +title: block +description: Defines a template and executes it in place. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/define + - functions/go-template/end + returnType: + signatures: [block NAME CONTEXT] +--- + +A block is shorthand for defining a template: + +```go-html-template +{{ define "name" }} T1 {{ end }} +``` + +and then executing it in place: + +```go-html-template +{{ template "name" pipeline }} +``` +The typical use is to define a set of root templates that are then customized by redefining the block templates within. + +{{< code file="layouts/_default/baseof.html" >}} + +
+ {{ block "main" . }} + {{ print "default value if 'main' template is empty" }} + {{ end }} +
+ +{{< /code >}} + +{{< code file="layouts/_default/single.html" >}} +{{ define "main" }} +

{{ .Title }}

+ {{ .Content }} +{{ end }} +{{< /code >}} + +{{< code file="layouts/_default/list.html" >}} +{{ define "main" }} +

{{ .Title }}

+ {{ .Content }} + {{ range .Pages }} +

{{ .Title }}

+ {{ end }} +{{ end }} +{{< /code >}} + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/content/en/functions/go-template/break.md b/content/en/functions/go-template/break.md new file mode 100644 index 000000000..14074d7c0 --- /dev/null +++ b/content/en/functions/go-template/break.md @@ -0,0 +1,33 @@ +--- +title: break +description: Used with the range statement, stops the innermost iteration and bypasses all remaining iterations. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/continue + - functions/go-template/range + returnType: + signatures: [break] +--- + +This template code: + +```go-html-template +{{ $s := slice "foo" "bar" "baz" }} +{{ range $s }} + {{ if eq . "bar" }} + {{ break }} + {{ end }} +

{{ . }}

+{{ end }} +``` + +Is rendered to: + +```html +

foo

+``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/content/en/functions/go-template/continue.md b/content/en/functions/go-template/continue.md new file mode 100644 index 000000000..c8030b8b7 --- /dev/null +++ b/content/en/functions/go-template/continue.md @@ -0,0 +1,34 @@ +--- +title: continue +description: Used with the range statement, stops the innermost iteration and continues to the next iteration. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/break + - functions/go-template/range + returnType: + signatures: [continue] +--- + +This template code: + +```go-html-template +{{ $s := slice "foo" "bar" "baz" }} +{{ range $s }} + {{ if eq . "bar" }} + {{ continue }} + {{ end }} +

{{ . }}

+{{ end }} +``` + +Is rendered to: + +```html +

foo

+

baz

+``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/content/en/functions/go-template/define.md b/content/en/functions/go-template/define.md new file mode 100644 index 000000000..4d09c14f3 --- /dev/null +++ b/content/en/functions/go-template/define.md @@ -0,0 +1,55 @@ +--- +title: define +description: Defines a template. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/block + - functions/go-template/end + - functions/go-template/template + - functions/partials/Include + - functions/partials/IncludeCached + returnType: + signatures: [define NAME] +--- + +Use with the [`block`] statement: + +```go-html-template +{{ block "main" . }} + {{ print "default value if 'main' template is empty" }} +{{ end }} + +{{ define "main" }} +

{{ .Title }}

+ {{ .Content }} +{{ end }} +``` + +Use with the [`partial`] function: + +```go-html-template +{{ partial "inline/foo.html" (dict "answer" 42) }} + +{{ define "partials/inline/foo.html" }} + {{ printf "The answer is %v." .answer }} +{{ end }} +``` + +Use with the [`template`] function: + +```go-html-template +{{ template "foo" (dict "answer" 42) }} + +{{ define "foo" }} + {{ printf "The answer is %v." .answer }} +{{ end }} +``` + +[`block`]: /functions/go-template/block +[`template`]: /functions/go-template/block +[`partial`]: /functions/partials/include/ + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/content/en/functions/go-template/else.md b/content/en/functions/go-template/else.md new file mode 100644 index 000000000..ccb8b722c --- /dev/null +++ b/content/en/functions/go-template/else.md @@ -0,0 +1,69 @@ +--- +title: else +description: Begins an alternate block for if, with, and range statements. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/if + - functions/go-template/range + - functions/go-template/with + - functions/go-template/end + returnType: + signatures: [else VALUE] +--- + +Use with the [`if`] statement: + +```go-html-template +{{ $var := "foo" }} +{{ if $var }} + {{ $var }} → foo +{{ else }} + {{ print "var is falsy" }} +{{ end }} +``` + +Use with the [`with`] statement: + +```go-html-template +{{ $var := "foo" }} +{{ with $var }} + {{ . }} → foo +{{ else }} + {{ print "var is falsy" }} +{{ end }} +``` + +Use with the [`range`] statement: + +```go-html-template +{{ $var := slice 1 2 3 }} +{{ range $var }} + {{ . }} → 1 2 3 +{{ else }} + {{ print "var is falsy" }} +{{ end }} +``` + +Use `else if` to check multiple conditions. + +```go-html-template +{{ $var := 12 }} +{{ if eq $var 6 }} + {{ print "var is 6" }} +{{ else if eq $var 7 }} + {{ print "var is 7" }} +{{ else if eq $var 42 }} + {{ print "var is 42" }} +{{ else }} + {{ print "var is something else" }} +{{ end }} +``` + +{{% include "functions/go-template/_common/text-template.md" %}} + +[`if`]: /functions/go-template/if +[`with`]: /functions/go-template/with +[`range`]: /functions/go-template/range diff --git a/content/en/functions/go-template/end.md b/content/en/functions/go-template/end.md new file mode 100644 index 000000000..07d004de5 --- /dev/null +++ b/content/en/functions/go-template/end.md @@ -0,0 +1,65 @@ +--- +title: end +description: Terminates if, with, range, block, and define statements. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/block + - functions/go-template/define + - functions/go-template/if + - functions/go-template/range + - functions/go-template/with + returnType: + signatures: [end] +--- + +Use with the [`if`] statement: + +```go-html-template +{{ $var := "foo" }} +{{ if $var }} + {{ $var }} → foo +{{ end }} +``` + +Use with the [`with`] statement: + +```go-html-template +{{ $var := "foo" }} +{{ with $var }} + {{ . }} → foo +{{ end }} +``` + +Use with the [`range`] statement: + +```go-html-template +{{ $var := slice 1 2 3 }} +{{ range $var }} + {{ . }} → 1 2 3 +{{ end }} +``` + +Use with the [`block`] statement: + +```go-html-template +{{ block "main" . }}{{ end }} +``` + +Use with the [`define`] statement: + +```go-html-template +{{ define "main" }} + {{ print "this is the main section" }} +{{ end }} +``` + +{{% include "functions/go-template/_common/text-template.md" %}} + +[`block`]: /functions/go-template/block +[`define`]: /functions/go-template/define +[`if`]: /functions/go-template/if +[`range`]: /functions/go-template/range +[`with`]: /functions/go-template/with diff --git a/content/en/functions/go-template/if.md b/content/en/functions/go-template/if.md new file mode 100644 index 000000000..e63c382e1 --- /dev/null +++ b/content/en/functions/go-template/if.md @@ -0,0 +1,54 @@ +--- +title: if +description: Executes the block if the expression is truthy. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/with + - functions/go-template/else + - functions/go-template/end + - functions/collections/IsSet + returnType: + signatures: [if EXPR] +--- + +{{% include "functions/go-template/_common/truthy-falsy.md" %}} + +```go-html-template +{{ $var := "foo" }} +{{ if $var }} + {{ $var }} → foo +{{ end }} +``` + +Use with the [`else`] statement: + +```go-html-template +{{ $var := "foo" }} +{{ if $var }} + {{ $var }} → foo +{{ else }} + {{ print "var is falsy" }} +{{ end }} +``` + +Use `else if` to check multiple conditions. + +```go-html-template +{{ $var := 12 }} +{{ if eq $var 6 }} + {{ print "var is 6" }} +{{ else if eq $var 7 }} + {{ print "var is 7" }} +{{ else if eq $var 42 }} + {{ print "var is 42" }} +{{ else }} + {{ print "var is something else" }} +{{ end }} +``` + +{{% include "functions/go-template/_common/text-template.md" %}} + +[`else`]: /functions/go-template/else diff --git a/content/en/functions/go-template/len.md b/content/en/functions/go-template/len.md index b8be621e8..43f150a5f 100644 --- a/content/en/functions/go-template/len.md +++ b/content/en/functions/go-template/len.md @@ -1,26 +1,20 @@ --- title: len description: Returns the length of a string, slice, map, or collection. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Count + - functions/strings/CountRunes + - functions/strings/CountWords + - functions/strings/RuneCount returnType: int - signatures: [len INPUT] -relatedFunctions: - - len - - strings.Count - - strings.CountRunes - - strings.CountWords - - strings.RuneCount + signatures: [len VALUE] aliases: [/functions/len] --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} - With a string: ```go-html-template @@ -53,3 +47,5 @@ You may also determine the number of pages in a collection with: ```go-html-template {{ site.RegularPages.Len }} → 42 ``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/content/en/functions/go-template/not.md b/content/en/functions/go-template/not.md new file mode 100644 index 000000000..4c7747c7b --- /dev/null +++ b/content/en/functions/go-template/not.md @@ -0,0 +1,35 @@ +--- +title: not +description: Returns the boolean negation of its single argument. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/and + - functions/go-template/or + returnType: bool + signatures: [not VALUE] +--- + +Unlike the `and` and `or` operators, the `not` operator always returns a boolean value. + +```go-html-template +{{ not true }} → false +{{ not false }} → true + +{{ not 1 }} → false +{{ not 0 }} → true + +{{ not "x" }} → false +{{ not "" }} → true +``` + +Use the `not` operator, twice in succession, to cast any value to a boolean value. For example: + +```go-html-template +{{ 42 | not | not }} → true +{{ "" | not | not }} → false +``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/content/en/functions/go-template/or.md b/content/en/functions/go-template/or.md new file mode 100644 index 000000000..0d8619608 --- /dev/null +++ b/content/en/functions/go-template/or.md @@ -0,0 +1,26 @@ +--- +title: or +description: Returns the first truthy argument. If all arguments are falsy, returns the last argument. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/and + - functions/go-template/not + returnType: any + signatures: [or VALUE...] +--- + +{{% include "functions/go-template/_common/truthy-falsy.md" %}} + +```go-html-template +{{ or 0 1 2 }} → 1 +{{ or false "a" 1 }} → a +{{ or 0 true "a" }} → true + +{{ or false "" 0 }} → 0 +{{ or 0 "" false }} → false +``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/content/en/functions/go-template/range.md b/content/en/functions/go-template/range.md index cf01633b4..4c2c2e1c4 100644 --- a/content/en/functions/go-template/range.md +++ b/content/en/functions/go-template/range.md @@ -1,27 +1,86 @@ --- title: range -description: Iterates over slices, maps, and page collections. -categories: [functions] +description: Iterates over a non-empty collection, binds context (the dot) to successive elements, and executes the block. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/go-template/break + - functions/go-template/continue + - functions/go-template/else + - functions/go-template/end returnType: signatures: [range COLLECTION] -relatedFunctions: - - with - - range aliases: [/functions/range] toc: true --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} +{{% include "functions/go-template/_common/truthy-falsy.md" %}} -## Slices +```go-html-template +{{ $s := slice "foo" "bar" "baz" }} +{{ range $var }} + {{ . }} → foo "bar" "baz" +{{ end }} +``` -Template: +Use with the [`else`] statement: + +```go-html-template +{{ $s := slice "foo" "bar" "baz" }} +{{ range $s }} +

{{ . }}

+{{ else }} +

The collection is empty

+{{ end }} +``` + +Within a range block: + +- Use the [`continue`] statement to stop the innermost iteration and continue to the next iteration +- Use the [`break`] statement to stop the innermost iteration and bypass all remaining iterations + +## Understanding context + +At the top of a page template, the [context] (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element. + +With this contrived example that uses the [`seq`] function to generate a slice of integers: + +```go-html-template +{{ range seq 3 }} + {{ .Title }} +{{ end }} +``` + +Hugo will throw an error: + + can't evaluate field Title in type int + +The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Within the `range` block, if we want to render the page title, we need to get the context passed into the template. + +{{% note %}} +Use the `$` to get the context passed into the template. +{{% /note %}} + +This template will render the page title three times: + +```go-html-template +{{ range seq 3 }} + {{ $.Title }} +{{ end }} +``` + +{{% note %}} +Gaining a thorough understanding of context is critical for anyone writing template code. +{{% /note %}} + +[`seq`]: functions/collections/seq/ +[context]: /getting-started/glossary/#context + +## Array or slice of scalars + +This template code: ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -30,7 +89,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html

foo

@@ -38,7 +97,7 @@ Result:

baz

``` -Template: +This template code: ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -47,7 +106,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html

foo

@@ -55,7 +114,7 @@ Result:

baz

``` -Template: +This template code: ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -64,7 +123,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html

0: foo

@@ -72,9 +131,9 @@ Result:

2: baz

``` -## Maps +## Array or slice of maps -Template: +This template code: ```go-html-template {{ $m := slice @@ -87,7 +146,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html

John is 30

@@ -95,17 +154,17 @@ Result:

Joey is 24

``` -## Page collections +## Array or slice of pages -Template: +This template code: ```go-html-template {{ range where site.RegularPages "Type" "articles" }} -

{{ .LinkTitle }}

+

{{ .Title }}

{{ end }} ``` -Result: +Is rendered to: ```html

Article 3

@@ -113,47 +172,28 @@ Result:

Article 1

``` -## Break +## Maps -Use the `break` statement to stop the innermost iteration and bypass all remaining iterations. - -Template: +This template code: ```go-html-template -{{ $s := slice "foo" "bar" "baz" }} -{{ range $s }} - {{ if eq . "bar" }} - {{ break }} - {{ end }} -

{{ . }}

+{{ $m := dict "name" "John" "age" 30 }} +{{ range $k, $v := $m }} +

key = {{ $k }} value = {{ $v }}

{{ end }} ``` -Result: - -```html -

foo

-``` - -## Continue - -Use the `continue` statement to stop the innermost iteration and continue to the next iteration. - -Template: +Is rendered to: ```go-html-template -{{ $s := slice "foo" "bar" "baz" }} -{{ range $s }} - {{ if eq . "bar" }} - {{ continue }} - {{ end }} -

{{ . }}

-{{ end }} +

key = age value = 30

+

key = name value = John

``` -Result: +Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map. -```html -

foo

-

baz

-``` +{{% include "functions/go-template/_common/text-template.md" %}} + +[`else`]: /functions/go-template/else +[`break`]: /functions/go-template/break +[`continue`]: /functions/go-template/continue diff --git a/content/en/functions/go-template/template.md b/content/en/functions/go-template/template.md new file mode 100644 index 000000000..c089010ca --- /dev/null +++ b/content/en/functions/go-template/template.md @@ -0,0 +1,49 @@ +--- +title: template +description: Executes the given template, optionally passing context. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/define + - functions/partials/Include + - functions/partials/IncludeCached + returnType: + signatures: ['template NAME [CONTEXT]'] +--- + +Use the `template` function to execute [internal templates]. For example: + +```go-html-template +{{ range (.Paginate .Pages).Pages }} +

{{ .Title }}

+{{ end }} +{{ template "_internal/pagination.html" . }} +``` + +You can also use the `template` function to execute a defined template: + +```go-html-template +{{ template "foo" (dict "answer" 42) }} + +{{ define "foo" }} + {{ printf "The answer is %v." .answer }} +{{ end }} +``` + +The example above can be rewritten using an [inline partial] template: + +```go-html-template +{{ partial "inline/foo.html" (dict "answer" 42) }} + +{{ define "partials/inline/foo.html" }} + {{ printf "The answer is %v." .answer }} +{{ end }} +``` + +{{% include "functions/go-template/_common/text-template.md" %}} + +[`partial`]: /functions/partials/include/ +[inline partial]: /templates/partials/#inline-partials +[internal templates]: /templates/internal diff --git a/content/en/functions/go-template/urlquery.md b/content/en/functions/go-template/urlquery.md index cbbfdfa7d..946828f56 100644 --- a/content/en/functions/go-template/urlquery.md +++ b/content/en/functions/go-template/urlquery.md @@ -1,23 +1,17 @@ --- title: urlquery description: Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/collections/Querify returnType: string - signatures: ['urlquery INPUT [INPUT]...'] -relatedFunctions: - - collections.Querify - - urlquery + signatures: ['urlquery VALUE [VALUE...]'] aliases: [/functions/urlquery] --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} - This template code: ```go-html-template @@ -30,3 +24,5 @@ Is rendered to: ```html Link ``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/content/en/functions/go-template/with.md b/content/en/functions/go-template/with.md index 06ca38150..9245e563f 100644 --- a/content/en/functions/go-template/with.md +++ b/content/en/functions/go-template/with.md @@ -1,35 +1,77 @@ --- title: with -description: Rebinds the context (`.`) within its scope and skips the block if the variable is absent or empty. -categories: [functions] +description: Binds context (the dot) to the expression and executes the block if expression is truthy. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] - returnType: any - signatures: [with PIPELINE] -relatedFunctions: - - with - - range + related: + - functions/go-template/if + - functions/go-template/else + - functions/go-template/end + - functions/collections/IsSet + returnType: + signatures: [with EXPR] aliases: [/functions/with] +toc: true --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} +{{% include "functions/go-template/_common/truthy-falsy.md" %}} -An alternative way of writing an `if` statement and then referencing the same value is to use `with` instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent, unset or empty. +```go-html-template +{{ $var := "foo" }} +{{ with $var }} + {{ . }} → foo +{{ end }} +``` -The set of *empty* values is defined by [the Go templates package](https://golang.org/pkg/text/template/). Empty values include `false`, the number zero, and the empty string. +Use with the [`else`] statement: -If you want to render a block if an index or key is present in a slice, array, channel or map, regardless of whether the value is empty, you should use [`isset`](/functions/collections/isset) instead. +```go-html-template +{{ $var := "foo" }} +{{ with $var }} + {{ . }} → foo +{{ else }} + {{ print "var is falsy" }} +{{ end }} +``` -The following example checks for a [user-defined site variable](/variables/site/) called `twitteruser`. If the key-value is not set, the following will render nothing: +## Understanding context -{{< code file="layouts/partials/twitter.html" >}} -{{ with .Site.Params.twitteruser }}{{ end }} -{{< /code >}} +At the top of a page template, the [context] (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement. + +With this contrived example: + +```go-html-template +{{ with 42 }} + {{ .Title }} +{{ end }} +``` + +Hugo will throw an error: + + can't evaluate field Title in type int + +The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Inside of the `with` block, if we want to render the page title, we need to get the context passed into the template. + +{{% note %}} +Use the `$` to get the context passed into the template. +{{% /note %}} + +This template will render the page title as desired: + +```go-html-template +{{ with 42 }} + {{ $.Title }} +{{ end }} +``` + +{{% note %}} +Gaining a thorough understanding of context is critical for anyone writing template code. +{{% /note %}} + +[context]: /getting-started/glossary/#context + +{{% include "functions/go-template/_common/text-template.md" %}} + +[`else`]: /functions/go-template/else diff --git a/content/en/functions/hugo/BuildDate.md b/content/en/functions/hugo/BuildDate.md new file mode 100644 index 000000000..1fbdbeac6 --- /dev/null +++ b/content/en/functions/hugo/BuildDate.md @@ -0,0 +1,19 @@ +--- +title: hugo.BuildDate +description: Returns the compile date of the Hugo binary. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: string + signatures: [hugo.BuildDate] +--- + +The `hugo.BuildDate` function returns the compile date of the Hugo binary, formatted per [RFC 3339]. + +[RFC 3339]: https://datatracker.ietf.org/doc/html/rfc3339 + +```go-html-template +{{ hugo.BuildDate }} → 2023-11-01T17:57:00Z +``` diff --git a/content/en/functions/hugo/CommitHash.md b/content/en/functions/hugo/CommitHash.md new file mode 100644 index 000000000..cd4f2ce92 --- /dev/null +++ b/content/en/functions/hugo/CommitHash.md @@ -0,0 +1,15 @@ +--- +title: hugo.CommitHash +description: Returns the Git commit hash of the Hugo binary. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: string + signatures: [hugo.CommitHash] +--- + +```go-html-template +{{ hugo.CommitHash }} → a4892a07b41b7b3f1f143140ee4ec0a9a5cf3970 +``` diff --git a/content/en/functions/hugo/Deps.md b/content/en/functions/hugo/Deps.md new file mode 100644 index 000000000..2f3f75e65 --- /dev/null +++ b/content/en/functions/hugo/Deps.md @@ -0,0 +1,66 @@ +--- +title: hugo.Deps +description: Returns a slice of project dependencies, either Hugo Modules or local theme components. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: '[]hugo.Dependency' + signatures: [hugo.Deps] +--- + +The `hugo.Deps` function returns a slice of project dependencies, either Hugo Modules or local theme components. Each dependency contains: + +Owner +: (`hugo.Dependency`) In the dependency tree, this is the first module that defines this module as a dependency (e.g., `github.com/gohugoio/hugo-mod-bootstrap-scss/v5`). + +Path +: (`string`) The module path or the path below your `themes` directory (e.g., `github.com/gohugoio/hugo-mod-jslibs-dist/popperjs/v2`). + +Replace +: (`hugo.Dependency`) Replaced by this dependency. + +Time +: (`time.Time`) The time that the version was created (e.g., `2022-02-13 15:11:28 +0000 UTC`). + +Vendor +: (`bool`) Reports whether the dependency is vendored. + +Version +: (`string`) The module version (e.g., `v2.21100.20000`). + +An example table listing the dependencies: + +```go-html-template +

Dependencies

+ + + + + + + + + + + + + {{ range $index, $element := hugo.Deps }} + + + + + + + + + {{ end }} + +
#OwnerPathVersionTimeVendor
{{ add $index 1 }}{{ with $element.Owner }}{{ .Path }}{{ end }} + {{ $element.Path }} + {{ with $element.Replace }} + => {{ .Path }} + {{ end }} + {{ $element.Version }}{{ with $element.Time }}{{ . }}{{ end }}{{ $element.Vendor }}
+``` diff --git a/content/en/functions/hugo/Environment.md b/content/en/functions/hugo/Environment.md new file mode 100644 index 000000000..f17a1e603 --- /dev/null +++ b/content/en/functions/hugo/Environment.md @@ -0,0 +1,28 @@ +--- +title: hugo.Environment +description: Returns the current running environment. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: string + signatures: [hugo.Environment] +--- + +The `hugo.Environment` function returns the current running [environment] as defined through the `--environment` command line flag. + +```go-html-template +{{ hugo.Environment }} → production +``` + +Command line examples: + +Command|Environment +:--|:-- +`hugo`|`production` +`hugo --environment staging`|`staging` +`hugo server`|`development` +`hugo server --environment staging`|`staging` + +[environment]: /getting-started/glossary/#environment diff --git a/content/en/functions/hugo/Generator.md b/content/en/functions/hugo/Generator.md new file mode 100644 index 000000000..a9496d87f --- /dev/null +++ b/content/en/functions/hugo/Generator.md @@ -0,0 +1,15 @@ +--- +title: hugo.Generator +description: Renders an HTML meta element identifying the software that generated the site. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: template.HTML + signatures: [hugo.Generator] +--- + +```go-html-template +{{ hugo.Generator }} → +``` diff --git a/content/en/functions/hugo/GoVersion.md b/content/en/functions/hugo/GoVersion.md new file mode 100644 index 000000000..34c6266bf --- /dev/null +++ b/content/en/functions/hugo/GoVersion.md @@ -0,0 +1,15 @@ +--- +title: hugo.GoVersion +description: Returns the Go version used to compile the Hugo binary +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: string + signatures: [hugo.GoVersion] +--- + +```go-html-template +{{ hugo.GoVersion }} → go1.21.1 +``` diff --git a/content/en/functions/hugo/IsDevelopment.md b/content/en/functions/hugo/IsDevelopment.md new file mode 100644 index 000000000..361378b2f --- /dev/null +++ b/content/en/functions/hugo/IsDevelopment.md @@ -0,0 +1,15 @@ +--- +title: hugo.IsDevelopment +description: Reports whether the current running environment is "development". +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: bool + signatures: [hugo.IsDevelopment] +--- + +```go-html-template +{{ hugo.IsDevelopment }} → true/false +``` diff --git a/content/en/functions/hugo/IsExtended.md b/content/en/functions/hugo/IsExtended.md new file mode 100644 index 000000000..84b68e6d3 --- /dev/null +++ b/content/en/functions/hugo/IsExtended.md @@ -0,0 +1,15 @@ +--- +title: hugo.IsExtended +description: Reports whether the Hugo binary is the extended version. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: bool + signatures: [hugo.IsExtended] +--- + +```go-html-template +{{ hugo.IsExtended }} → true/false +``` diff --git a/content/en/functions/hugo/IsProduction.md b/content/en/functions/hugo/IsProduction.md new file mode 100644 index 000000000..77945f1a0 --- /dev/null +++ b/content/en/functions/hugo/IsProduction.md @@ -0,0 +1,15 @@ +--- +title: hugo.IsProduction +description: Reports whether the current running environment is "production". +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: bool + signatures: [hugo.IsProduction] +--- + +```go-html-template +{{ hugo.IsProduction }} → true/false +``` diff --git a/content/en/functions/hugo/IsServer.md b/content/en/functions/hugo/IsServer.md new file mode 100644 index 000000000..add88b8eb --- /dev/null +++ b/content/en/functions/hugo/IsServer.md @@ -0,0 +1,15 @@ +--- +title: hugo.IsServer +description: Reports whether the built-in development server is running. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: bool + signatures: [hugo.IsServer] +--- + +```go-html-template +{{ hugo.IsServer }} → true/false +``` diff --git a/content/en/functions/hugo/Version.md b/content/en/functions/hugo/Version.md new file mode 100644 index 000000000..9bb361a71 --- /dev/null +++ b/content/en/functions/hugo/Version.md @@ -0,0 +1,15 @@ +--- +title: hugo.Version +description: Returns the current version of the Hugo binary. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: hugo.VersionString + signatures: [hugo.Version] +--- + +```go-html-template +{{ hugo.Version }} → 0.120.3 +``` diff --git a/content/en/functions/hugo/WorkingDir.md b/content/en/functions/hugo/WorkingDir.md new file mode 100644 index 000000000..ac3835ea8 --- /dev/null +++ b/content/en/functions/hugo/WorkingDir.md @@ -0,0 +1,15 @@ +--- +title: hugo.WorkingDir +description: Returns the project working directory. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: string + signatures: [hugo.WorkingDir] +--- + +```go-html-template +{{ hugo.WorkingDir }} → /home/user/projects/my-hugo-site +``` diff --git a/content/en/functions/hugo/_index.md b/content/en/functions/hugo/_index.md new file mode 100644 index 000000000..e13c12b33 --- /dev/null +++ b/content/en/functions/hugo/_index.md @@ -0,0 +1,12 @@ +--- +title: Hugo functions +linkTitle: hugo +description: Template functions to access information about the Hugo application and the current environment. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to access information about the Hugo application and the current environment. diff --git a/content/en/functions/hugo/index.md b/content/en/functions/hugo/index.md deleted file mode 100644 index 64ea0db22..000000000 --- a/content/en/functions/hugo/index.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: hugo -description: Provides global access to Hugo-related data. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: - signatures: [hugo] -relatedFunctions: - - hugo - - page - - site -aliases: [/functions/hugo] ---- - -`hugo` returns an instance that contains the following functions: - -`hugo.BuildDate` -: (`string`) The compile date of the current Hugo binary formatted per [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) (e.g., `2023-05-23T08:14:20Z`). - -`hugo.CommitHash` -: (`string`) The Git commit hash of the Hugo binary (e.g., `0a95d6704a8ac8d41cc5ca8fffaad8c5c7a3754a`). - -`hugo.Deps` -: (`[]*hugo.Dependency`) See [hugo.Deps](#hugodeps). - -`hugo.Environment` -: (`string`) The current running environment as defined through the `--environment` CLI flag (e.g., `development`, `production`). - -`hugo.Generator` -: (`template.HTML`) Renders an HTML `meta` element identifying the software that generated the site (e.g., ``). - -`hugo.GoVersion` {{< new-in "0.101.0" >}} -: (`string`) The Go version used to compile the Hugo binary (e.g., `go1.20.4`). - -`hugo.IsDevelopment` {{< new-in "0.120.0" >}} -: (`bool`) Returns `true` if `hugo.Environment` is "development". - -`hugo.IsExtended` -: (`bool`) Returns `true` if the Hugo binary is the extended version. - -`hugo.IsProduction` -: (`bool`) Returns `true` if `hugo.Environment` is "production". - -`hugo.IsServer` {{< new-in "0.120.0" >}} -: (`bool`) Returns `true` if the site is being served with Hugo's built-in server. - -`hugo.Version` -: (`hugo.VersionString`) The current version of the Hugo binary (e.g., `0.112.1`). - -`hugo.WorkingDir` {{< new-in "0.112.0" >}} -: (`string`) The project working directory (e.g., `/home/user/projects/my-hugo-site`). - -## hugo.Deps - -{{< new-in "0.92.0" >}} - -`hugo.Deps` returns a list of dependencies for a project (either Hugo Modules or local theme components). - -Each dependency contains: - -Owner -: (`*hugo.Dependency`) In the dependency tree, this is the first module that defines this module as a dependency (e.g., `github.com/gohugoio/hugo-mod-bootstrap-scss/v5`). - -Path -: (`string`) The module path or the path below your `themes` directory (e.g., `github.com/gohugoio/hugo-mod-jslibs-dist/popperjs/v2`). - -Replace -: (`*hugo.Dependency`) Replaced by this dependency. - -Time -: (`time.Time`) The time that the version was created (e.g., `2022-02-13 15:11:28 +0000 UTC`). - -Vendor -: (`bool`) Returns `true` if the dependency is vendored. - -Version -: (`string`) The module version (e.g., `v2.21100.20000`). - -An example table listing the dependencies: - -```html -

Dependencies

- - - - - - - - - - - - - {{ range $index, $element := hugo.Deps }} - - - - - - - - - {{ end }} - -
#OwnerPathVersionTimeVendor
{{ add $index 1 }}{{ with $element.Owner }}{{ .Path }}{{ end }} - {{ $element.Path }} - {{ with $element.Replace }} - => {{ .Path }} - {{ end }} - {{ $element.Version }}{{ with $element.Time }}{{ . }}{{ end }}{{ $element.Vendor }}
-``` diff --git a/content/en/functions/images/Brightness.md b/content/en/functions/images/Brightness.md new file mode 100644 index 000000000..0001bcba8 --- /dev/null +++ b/content/en/functions/images/Brightness.md @@ -0,0 +1,36 @@ +--- +title: images.Brightness +description: Returns an image filter that changes the brightness of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Brightness PERCENTAGE] +toc: true +--- + +The percentage must be in the range [-100, 100] where 0 has no effect. A value of `-100` produces a solid black image, and a value of `100` produces a solid white image. + +## Usage + +Create the image filter: + +```go-html-template +{{ $filter := images.Brightness 12 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Brightness" + filterArgs="12" + example=true +>}} diff --git a/content/en/functions/images/ColorBalance.md b/content/en/functions/images/ColorBalance.md new file mode 100644 index 000000000..29829f9e6 --- /dev/null +++ b/content/en/functions/images/ColorBalance.md @@ -0,0 +1,36 @@ +--- +title: images.ColorBalance +description: Returns an image filter that changes the color balance of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.ColorBalance PCTRED PCTGREEN PCTBLUE] +toc: true +--- + +The percentage for each channel (red, green, blue) must be in the range [-100, 500]. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.ColorBalance -10 10 50 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="ColorBalance" + filterArgs="-10,10,50" + example=true +>}} diff --git a/content/en/functions/images/Colorize.md b/content/en/functions/images/Colorize.md new file mode 100644 index 000000000..c974103b9 --- /dev/null +++ b/content/en/functions/images/Colorize.md @@ -0,0 +1,40 @@ +--- +title: images.Colorize +description: Returns an image filter that produces a colorized version of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Colorize HUE SATURATION PERCENTAGE] +toc: true +--- + +The hue is the angle on the color wheel, typically in the range [0, 360]. + +The saturation must be in the range [0, 100]. + +The percentage specifies the strength of the effect, and must be in the range [0, 100]. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Colorize 180 50 20 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Colorize" + filterArgs="180,50,20" + example=true +>}} diff --git a/content/en/functions/images/Config.md b/content/en/functions/images/Config.md new file mode 100644 index 000000000..fafb5b024 --- /dev/null +++ b/content/en/functions/images/Config.md @@ -0,0 +1,31 @@ +--- +title: images.Config +description: Returns an image.Config structure from the image at the specified path, relative to the working directory. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: image.Config + signatures: [images.Config PATH] +aliases: [/functions/imageconfig] +--- + +See [image processing] for an overview of Hugo's image pipeline. + +[image processing]: /content-management/image-processing/ + +```go-html-template +{{ $ic := images.Config "/static/images/a.jpg" }} + +{{ $ic.Width }} → 600 (int) +{{ $ic.Height }} → 400 (int) +``` + +Supported image formats include GIF, JPEG, PNG, TIFF, and WebP. + +{{% note %}} +This is a legacy function, superseded by the `.Width` and `.Height` methods for global, page, and remote resources. See the [image processing] section for details. + +[image processing]: /content-management/image-processing +{{% /note %}} diff --git a/content/en/functions/images/Contrast.md b/content/en/functions/images/Contrast.md new file mode 100644 index 000000000..532ae8c9c --- /dev/null +++ b/content/en/functions/images/Contrast.md @@ -0,0 +1,36 @@ +--- +title: images.Contrast +description: Returns an image filter that changes the contrast of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Contrast PERCENTAGE] +toc: true +--- + +The percentage must be in the range [-100, 100] where 0 has no effect. A value of `-100` produces a solid grey image, and a value of `100` produces an over-contrasted image. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Contrast -20 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Contrast" + filterArgs="-20" + example=true +>}} diff --git a/content/en/functions/images/Filter.md b/content/en/functions/images/Filter.md new file mode 100644 index 000000000..450a64814 --- /dev/null +++ b/content/en/functions/images/Filter.md @@ -0,0 +1,67 @@ +--- +title: images.Filter +description: Applies one or more image filters to the given image resource. +categories: [] +keywords: [] +action: + aliases: [] + related: + - methods/resource/Filter + returnType: images.ImageResource + signatures: [images.Filter FILTERS... IMAGE] +toc: true +--- + +Apply one or more [image filters](#image-filters) to the given image. + +To apply a single filter: + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with images.Filter images.Grayscale . }} + + {{ end }} +{{ end }} +``` + +To apply two or more filters, executing from left to right: + +```go-html-template +{{ $filters := slice + images.Grayscale + (images.GaussianBlur 8) +}} +{{ with resources.Get "images/original.jpg" }} + {{ with images.Filter $filters . }} + + {{ end }} +{{ end }} +``` + +You can also apply image filters using the [`Filter`] method on a `Resource` object. + +[`Filter`]: /methods/resource/filter + +## Example + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with images.Filter images.Grayscale . }} + + {{ end }} +{{ end }} +``` + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Grayscale" + filterArgs="" + example=true +>}} + +## Image filters + +Use any of these filters with the `images.Filter` function, or with the `Filter` method on a `Resource` object. + +{{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}} diff --git a/content/en/functions/images/Gamma.md b/content/en/functions/images/Gamma.md new file mode 100644 index 000000000..affbdcfa8 --- /dev/null +++ b/content/en/functions/images/Gamma.md @@ -0,0 +1,36 @@ +--- +title: images.Gamma +description: Returns an image filter that performs gamma correction on an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Gamma GAMMA] +toc: true +--- + +The gamma value must be positive. A value greater than 1 lightens the image, while a value less than 1 darkens the image. The filter has no effect when the gamma value is 1. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Gamma 1.667 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Gamma" + filterArgs="1.667" + example=true +>}} diff --git a/content/en/functions/images/GaussianBlur.md b/content/en/functions/images/GaussianBlur.md new file mode 100644 index 000000000..e2f49a847 --- /dev/null +++ b/content/en/functions/images/GaussianBlur.md @@ -0,0 +1,36 @@ +--- +title: images.GaussianBlur +description: Returns an image filter that applies a gaussian blur to an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.GaussianBlur SIGMA] +toc: true +--- + +The sigma value must be positive, and indicates how much the image will be blurred. The blur-affected radius is approximately 3 times the sigma value. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.GaussianBlur 5 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="GaussianBlur" + filterArgs="5" + example=true +>}} diff --git a/content/en/functions/images/Grayscale.md b/content/en/functions/images/Grayscale.md new file mode 100644 index 000000000..d8a89b7f2 --- /dev/null +++ b/content/en/functions/images/Grayscale.md @@ -0,0 +1,34 @@ +--- +title: images.Grayscale +description: Returns an image filter that produces a grayscale version of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Grayscale] +toc: true +--- + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Grayscale }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Grayscale" + filterArgs="" + example=true +>}} diff --git a/content/en/functions/images/Hue.md b/content/en/functions/images/Hue.md new file mode 100644 index 000000000..6eafac437 --- /dev/null +++ b/content/en/functions/images/Hue.md @@ -0,0 +1,36 @@ +--- +title: images.Hue +description: Returns an image filter that rotates the hue of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Hue SHIFT] +toc: true +--- + +The hue angle shift is typically in the range [-180, 180] where 0 has no effect. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Hue -15 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Hue" + filterArgs="-15" + example=true +>}} diff --git a/content/en/functions/images/Invert.md b/content/en/functions/images/Invert.md new file mode 100644 index 000000000..1ee85e514 --- /dev/null +++ b/content/en/functions/images/Invert.md @@ -0,0 +1,34 @@ +--- +title: images.Invert +description: Returns an image filter that negates the colors of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Invert] +toc: true +--- + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Invert }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Invert" + filterArgs="" + example=true +>}} diff --git a/content/en/functions/images/Opacity.md b/content/en/functions/images/Opacity.md new file mode 100644 index 000000000..c3b09efc4 --- /dev/null +++ b/content/en/functions/images/Opacity.md @@ -0,0 +1,50 @@ +--- +title: images.Opacity +description: Returns an image filter that changes the opacity of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Opacity OPACITY] +toc: true +--- + +The opacity value must be in the range [0, 1]. A value of `0` produces a transparent image, and a value of `1` produces an opaque image (no transparency). + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Opacity 0.65 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +The `images.Opacity` filter is most useful for target formats such as PNG and WebP that support transparency. If the source image does not support transparency, combine this filter with the `images.Process` filter: + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ $filters := slice + (images.Opacity 0.65) + (images.Process "png") + }} + {{ with . | images.Filter $filters }} + + {{ end }} +{{ end }} +``` + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Opacity" + filterArgs="0.65" + example=true +>}} diff --git a/content/en/functions/images/Overlay.md b/content/en/functions/images/Overlay.md new file mode 100644 index 000000000..f04e3668b --- /dev/null +++ b/content/en/functions/images/Overlay.md @@ -0,0 +1,54 @@ +--- +title: images.Overlay +description: Returns an image filter that overlays the source image at the given coordinates. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Overlay RESOURCE X Y] +toc: true +--- + +The coordinates are relative to the upper left corner. + +## Usage + +Capture the overlay image as a resource: + +```go-html-template +{{ $overlay := "" }} +{{ $path := "images/logo.png" }} +{{ with resources.Get $path }} + {{ $overlay = . }} +{{ else }} + {{ errorf "Unable to get resource %q" $path }} +{{ end }} +``` + +The overlay image can be a [global resource], a [page resource], or a [remote resource]. + +[global resource]: /getting-started/glossary/#global-resource +[page resource]: /getting-started/glossary/#page-resource +[remote resource]: /getting-started/glossary/#remote-resource + +Create the filter: + +```go-html-template +{{ $filter := images.Overlay $overlay 20 20 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Overlay" + filterArgs="images/logos/logo-64x64.png,20,20" + example=true +>}} diff --git a/content/en/functions/images/Padding.md b/content/en/functions/images/Padding.md new file mode 100644 index 000000000..1362bc78e --- /dev/null +++ b/content/en/functions/images/Padding.md @@ -0,0 +1,73 @@ +--- +title: images.Padding +description: Returns an image filter that resizes the image canvas without resizing the image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: ['images.Padding V1 [V2] [V3] [V4] [COLOR]'] +toc: true +--- + +The last argument is the canvas color, expressed as an RGB or RGBA [hexadecimal color]. The default value is `ffffffff` (opaque white). The preceding arguments are the padding values, in pixels, using the CSS [shorthand property] syntax. Negative padding values will crop the image. + +[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color +[shorthand property]: https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Padding 20 40 "#976941" }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +Combine with the [`Colors`] method to create a border with one of the image's most dominant colors: + +[`Colors`]: /methods/resource/colors + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ $filter := images.Padding 20 40 (index .Colors 2) }} + {{ with . | images.Filter $filter }} + + {{ end }} +{{ end }} +``` + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Padding" + filterArgs="20,40,20,40,#976941" + example=true +>}} + +## Other recipes + +This example resizes an image to 300px wide, converts it to the WebP format, adds 20px vertical padding and 50px horizontal padding, then sets the canvas color to dark green with 33% opacity. + +Conversion to WebP is required to support transparency. PNG and WebP images have an alpha channel; JPEG and GIF do not. + +```go-html-template +{{ $img := resources.Get "images/a.jpg" }} +{{ $filters := slice + (images.Process "resize 300x webp") + (images.Padding 20 50 "#0705") +}} +{{ $img = $img.Filter $filters }} +``` + +To add a 2px gray border to an image: + +```go-html-template +{{ $img = $img.Filter (images.Padding 2 "#777") }} +``` diff --git a/content/en/functions/images/Pixelate.md b/content/en/functions/images/Pixelate.md new file mode 100644 index 000000000..2016877ed --- /dev/null +++ b/content/en/functions/images/Pixelate.md @@ -0,0 +1,34 @@ +--- +title: images.Pixelate +description: Returns an image filter that applies a pixelation effect to an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Pixelate SIZE] +toc: true +--- + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Pixelate 4 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Pixelate" + filterArgs="4" + example=true +>}} diff --git a/content/en/functions/images/Process.md b/content/en/functions/images/Process.md new file mode 100644 index 000000000..f3cf494be --- /dev/null +++ b/content/en/functions/images/Process.md @@ -0,0 +1,110 @@ +--- +title: images.Process +description: Returns an image filter that processes the given image using the given specification. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + - methods/resource/Process + returnType: images.filter + signatures: [images.Process SPEC] +toc: true +--- + +This filter has the same options as the [`Process`] method on a `Resource` object, but using it as a filter may be more effective if you need to apply multiple filters to an image. + +[`Process`]: /methods/resource/process + +The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence: + +action +: Specify zero or one of `resize`, `fit`, `fill`, or `crop`. If you specify an action you must also provide dimensions. See [details](content-management/image-processing/#image-processing-methods). + +```go-html-template +{{ $filter := images.Process "resize 300x" }} +``` + +dimensions +: Required if you specify an action. Provide width _or_ height when using `resize`, else provide both width _and_ height. See [details](/content-management/image-processing/#dimensions). + +```go-html-template +{{ $filter := images.Process "crop 200x200" }} +``` + +anchor +: Use with the `crop` or `fill` action. Specify zero or one of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. See [details](/content-management/image-processing/#anchor). + +```go-html-template +{{ $filter := images.Process "crop 200x200 center" }} +``` + +rotation +: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See [details](/content-management/image-processing/#rotation). + +```go-html-template +{{ $filter := images.Process "r90" }} +{{ $filter := images.Process "crop 200x200 center r90" }} +``` + +target format +: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See [details](/content-management/image-processing/#target-format). + +```go-html-template +{{ $filter := images.Process "webp" }} +{{ $filter := images.Process "crop 200x200 center r90 webp" }} +``` + +quality +: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See [details](/content-management/image-processing/#quality). + +```go-html-template +{{ $filter := images.Process "q50" }} +{{ $filter := images.Process "crop 200x200 center r90 webp q50" }} +``` + +hint +: Applicable to WebP images. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint). + +```go-html-template +{{ $filter := images.Process "webp" "icon" }} +{{ $filter := images.Process "crop 200x200 center r90 webp q50 icon" }} +``` + +background color +: When converting a PNG or WebP with transparency to a format that does not support transparency, optionally specify a background color using a 3-digit or a 6-digit hexadecimal color code. Default is `#ffffff` (white). See [details](/content-management/image-processing/#background-color). + +```go-html-template +{{ $filter := images.Process "jpeg #000" }} +{{ $filter := images.Process "crop 200x200 center r90 q50 jpeg #000" }} +``` + +resampling filter +: Typically specify zero or one of `Box`, `Lanczos`, `CatmullRom`, `MitchellNetravali`, `Linear`, or `NearestNeighbor`. Other resampling filters are available. See [details](/content-management/image-processing/#resampling-filter). + +```go-html-template +{{ $filter := images.Process "resize 300x lanczos" }} +{{ $filter := images.Process "resize 300x r90 q50 jpeg #000 lanczos" }} +``` + +## Usage + +Create a filter: + +```go-html-template +{{ $filter := images.Process "resize 256x q40 webp" }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Process" + filterArgs="resize 256x q40 webp" + example=true +>}} diff --git a/content/en/functions/images/Saturation.md b/content/en/functions/images/Saturation.md new file mode 100644 index 000000000..118bd0213 --- /dev/null +++ b/content/en/functions/images/Saturation.md @@ -0,0 +1,36 @@ +--- +title: images.Saturation +description: Returns an image filter that changes the saturation of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Saturation PERCENTAGE] +toc: true +--- + +The percentage must be in the range [-100, 500] where 0 has no effect. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Saturation 65 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Saturation" + filterArgs="65" + example=true +>}} diff --git a/content/en/functions/images/Sepia.md b/content/en/functions/images/Sepia.md new file mode 100644 index 000000000..9f0b7adfb --- /dev/null +++ b/content/en/functions/images/Sepia.md @@ -0,0 +1,36 @@ +--- +title: images.Sepia +description: Returns an image filter that produces a sepia-toned version of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Sepia PERCENTAGE] +toc: true +--- + +The percentage must be in the range [0, 100] where 0 has no effect. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Sepia 75 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Sepia" + filterArgs="75" + example=true +>}} diff --git a/content/en/functions/images/Sigmoid.md b/content/en/functions/images/Sigmoid.md new file mode 100644 index 000000000..32765f923 --- /dev/null +++ b/content/en/functions/images/Sigmoid.md @@ -0,0 +1,40 @@ +--- +title: images.Sigmoid +description: Returns an image filter that changes the contrast of an image using a sigmoidal function. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Sigmoid MIDPOINT FACTOR] +toc: true +--- + +This is a non-linear contrast change useful for photo adjustments; it preserves highlight and shadow detail. + +The midpoint is the midpoint of contrast. It must be in the range [0, 1], typically 0.5. + +The factor indicates how much to increase or decrease the contrast, typically in the range [-10, 10] where 0 has no effect. A positive value increases contrast, while a negative value decrease contrast. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Sigmoid 0.6 -4 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Sigmoid" + filterArgs="0.6,-4" + example=true +>}} diff --git a/content/en/functions/images/Text.md b/content/en/functions/images/Text.md new file mode 100644 index 000000000..0c1e74bce --- /dev/null +++ b/content/en/functions/images/Text.md @@ -0,0 +1,95 @@ +--- +title: images.Text +description: Returns an image filter that adds text to an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: ['images.Text TEXT [OPTIONS]'] +toc: true +--- + +## Options + +Although none of the options are required, at a minimum you will want to set the `size` to be some reasonable percentage of the image height. + +color +: (`string`) The font color, either a 3-digit or 6-digit hexadecimal color code. Default is `#ffffff` (white). + +font +: (`resource.Resource`) The font can be a [global resource], a [page resource], or a [remote resource]. Default is the "Go Regular" TrueType font. + +linespacing +: (`int`) The number of pixels between each line. For a line height of 1.4, set the `linespacing` to 0.4 multiplied by the `size`. Default is `2`. + +size +: (`int`) The font size in pixels. Default is `20`. + +x +: (`int`) The horizontal offset, in pixels, relative to the left of the image. Default is `10`. + +y +: (`int`) The vertical offset, in pixels, relative to the top of the image. Default is `10`. + +[global resource]: /getting-started/glossary/#global-resource +[page resource]: /getting-started/glossary/#page-resource +[remote resource]: /getting-started/glossary/#remote-resource + +## Usage + +Capture the font as a resource: + +```go-html-template +{{ $font := "" }} +{{ $path := "https://github.com/google/fonts/raw/main/apache/roboto/static/Roboto-Regular.ttf" }} +{{ with resources.GetRemote $path }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ $font = . }} + {{ end }} +{{ else }} + {{ errorf "Unable to get resource %q" $path }} +{{ end }} +``` + +Create the options map: + +```go-html-template +{{ $opts := dict + "color" "#fbfaf5" + "font" $font + "linespacing" 8 + "size" 40 + "x" 25 + "y" 190 +}} +``` + +Set the text: + +```go-html-template +{{ $text := "Zion National Park" }} +``` + +Create the filter: + +```go-html-template +{{ $filter := images.Text $text $opts }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Text" + filterArgs="Zion National Park,25,190,40,1.2,#fbfaf5" + example=true +>}} diff --git a/content/en/functions/images/UnsharpMask.md b/content/en/functions/images/UnsharpMask.md new file mode 100644 index 000000000..57a74a54a --- /dev/null +++ b/content/en/functions/images/UnsharpMask.md @@ -0,0 +1,40 @@ +--- +title: images.UnsharpMask +description: Returns an image filter that sharpens an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.UnsharpMask SIGMA AMOUNT THRESHOLD] +toc: true +--- + +The sigma parameter is used in a gaussian function and affects the radius of effect. Sigma must be positive. The sharpen radius is approximately 3 times the sigma value. + +The amount parameter controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5. + +The threshold parameter controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.UnsharpMask 10 0.4 0.03 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="UnsharpMask" + filterArgs="10,0.4,0.03" + example=true +>}} diff --git a/content/en/functions/images/_common/_index.md b/content/en/functions/images/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/functions/images/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + + diff --git a/content/en/functions/images/_common/apply-image-filter.md b/content/en/functions/images/_common/apply-image-filter.md new file mode 100644 index 000000000..acd3a733d --- /dev/null +++ b/content/en/functions/images/_common/apply-image-filter.md @@ -0,0 +1,27 @@ +--- +# Do not remove front matter. +--- + +Apply the filter using the [`images.Filter`] function: + +[`images.Filter`]: /functions/images/filter + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with . | images.Filter $filter }} + + {{ end }} +{{ end }} +``` + +You can also apply the filter using the [`Filter`] method on a `Resource` object: + +[`Filter`]: methods/resource/filter + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Filter $filter }} + + {{ end }} +{{ end }} +``` diff --git a/content/en/functions/images/_index.md b/content/en/functions/images/_index.md new file mode 100644 index 000000000..13542ea73 --- /dev/null +++ b/content/en/functions/images/_index.md @@ -0,0 +1,12 @@ +--- +title: Image functions +linkTitle: images +description: Use these functions to create an image filter, apply an image filter to an image, and to retrieve image information. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to create an image filter, apply an image filter to an image, and to retrieve image information. diff --git a/content/en/functions/images/index.md b/content/en/functions/images/index.md deleted file mode 100644 index a1351f190..000000000 --- a/content/en/functions/images/index.md +++ /dev/null @@ -1,302 +0,0 @@ ---- -title: Image filters -description: The images namespace provides a list of filters and other image related functions. -categories: [functions] -keywords: [] -aliases: [/functions/imageconfig/] -menu: - docs: - parent: functions -keywords: [images] -toc: true ---- - -See [images.Filter](#filter) for how to apply these filters to an image. - -## Process - -{{< new-in "0.119.0" >}} - -{{< funcsig >}} -images.Process SRC SPEC -{{< /funcsig >}} - -A general purpose image processing function. - -This filter has all the same options as the [Process](/content-management/image-processing/#process) method, but using it as a filter may be more effective if you need to apply multiple filters to an image: - -```go-html-template -{{ $filters := slice - images.Grayscale - (images.GaussianBlur 8) - (images.Process "resize 200x jpg q30") -}} -{{ $img = $img | images.Filter $filters }} -``` - -## Overlay - -{{< funcsig >}} -images.Overlay SRC X Y -{{< /funcsig >}} - -Overlay creates a filter that overlays the source image at position x y, e.g: - - -```go-html-template -{{ $logoFilter := (images.Overlay $logo 50 50 ) }} -{{ $img := $img | images.Filter $logoFilter }} -``` - -A shorter version of the above, if you only need to apply the filter once: - -```go-html-template -{{ $img := $img.Filter (images.Overlay $logo 50 50 )}} -``` - -The above will overlay `$logo` in the upper left corner of `$img` (at position `x=50, y=50`). - -## Opacity - -{{< new-in "0.119.0" >}} - -{{< funcsig >}} -images.Opacity SRC OPACITY -{{< /funcsig >}} - -Opacity creates a filter that changes the opacity of an image. -The OPACITY parameter must be in range (0, 1). - -```go-html-template -{{ $img := $img.Filter (images.Opacity 0.5 )}} -``` - -This filter is most useful for target formats that support transparency, e.g. PNG. If the source image is e.g. JPG, the most effective way would be to combine it with the [`Process`] filter: - -```go-html-template -{{ $png := $jpg.Filter - (images.Opacity 0.5) - (images.Process "png") -}} -``` - -## Text - -Using the `Text` filter, you can add text to an image. - -{{< funcsig >}} -images.Text TEXT MAP) -{{< /funcsig >}} - -The following example will add the text `Hugo rocks!` to the image with the specified color, size and position. - -```go-html-template -{{ $img := resources.Get "/images/background.png" }} -{{ $img = $img.Filter (images.Text "Hugo rocks!" (dict - "color" "#ffffff" - "size" 60 - "linespacing" 2 - "x" 10 - "y" 20 -))}} -``` - -You can load a custom font if needed. Load the font as a Hugo `Resource` and set it as an option: - -```go-html-template -{{ $font := resources.GetRemote "https://github.com/google/fonts/raw/main/apache/roboto/static/Roboto-Black.ttf" }} -{{ $img := resources.Get "/images/background.png" }} -{{ $img = $img.Filter (images.Text "Hugo rocks!" (dict - "font" $font -))}} -``` - -## Padding - -{{< new-in "0.120.0" >}} - -Padding creates a filter that resizes the image canvas without resizing the image. The last argument is the canvas color, expressed as an RGB or RGBA [hexadecimal color]. The default value is `ffffffff` (opaque white). The preceding arguments are the padding values, in pixels, using the CSS [shorthand property] syntax. Negative padding values will crop the image. - -[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color -[shorthand property]: https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box - -{{% funcsig %}} -images.Padding V1 [V2] [V3] [V4] [COLOR] -{{% /funcsig %}} - -This example resizes the image to 300px wide, converts it to the WebP format, adds 20px vertical padding and 50px horizontal padding, then sets the canvas color to dark green with 33% opacity. - -```go-html-template -{{ $img := resources.Get "images/a.jpg" }} -{{ $filters := slice - (images.Process "resize 300x webp") - (images.Padding 20 50 "#0705") -}} -{{ $img = $img.Filter $filters }} -``` - -To add a 2px gray border to an image: - -```go-html-template -{{ $img = $img.Filter (images.Padding 2 "#777") }} -``` - -## Brightness - -{{< funcsig >}} -images.Brightness PERCENTAGE -{{< /funcsig >}} - -Brightness creates a filter that changes the brightness of an image. -The percentage parameter must be in range (-100, 100). - -### ColorBalance - -{{< funcsig >}} -images.ColorBalance PERCENTAGERED PERCENTAGEGREEN PERCENTAGEBLUE -{{< /funcsig >}} - -ColorBalance creates a filter that changes the color balance of an image. -The percentage parameters for each color channel (red, green, blue) must be in range (-100, 500). - -## Colorize - -{{< funcsig >}} -images.Colorize HUE SATURATION PERCENTAGE -{{< /funcsig >}} - -Colorize creates a filter that produces a colorized version of an image. -The hue parameter is the angle on the color wheel, typically in range (0, 360). -The saturation parameter must be in range (0, 100). -The percentage parameter specifies the strength of the effect, it must be in range (0, 100). - -## Contrast - -{{< funcsig >}} -images.Contrast PERCENTAGE -{{< /funcsig >}} - -Contrast creates a filter that changes the contrast of an image. -The percentage parameter must be in range (-100, 100). - -## Gamma - -{{< funcsig >}} -images.Gamma GAMMA -{{< /funcsig >}} - -Gamma creates a filter that performs a gamma correction on an image. -The gamma parameter must be positive. Gamma = 1 gives the original image. -Gamma less than 1 darkens the image and gamma greater than 1 lightens it. - -## GaussianBlur - -{{< funcsig >}} -images.GaussianBlur SIGMA -{{< /funcsig >}} - -GaussianBlur creates a filter that applies a gaussian blur to an image. - -## Grayscale - -{{< funcsig >}} -images.Grayscale -{{< /funcsig >}} - -Grayscale creates a filter that produces a grayscale version of an image. - -## Hue - -{{< funcsig >}} -images.Hue SHIFT -{{< /funcsig >}} - -Hue creates a filter that rotates the hue of an image. -The hue angle shift is typically in range -180 to 180. - -## Invert - -{{< funcsig >}} -images.Invert -{{< /funcsig >}} - -Invert creates a filter that negates the colors of an image. - -## Pixelate - -{{< funcsig >}} -images.Pixelate SIZE -{{< /funcsig >}} - -Pixelate creates a filter that applies a pixelation effect to an image. - -## Saturation - -{{< funcsig >}} -images.Saturation PERCENTAGE -{{< /funcsig >}} - -Saturation creates a filter that changes the saturation of an image. - -## Sepia - -{{< funcsig >}} -images.Sepia PERCENTAGE -{{< /funcsig >}} - -Sepia creates a filter that produces a sepia-toned version of an image. - -## Sigmoid - -{{< funcsig >}} -images.Sigmoid MIDPOINT FACTOR -{{< /funcsig >}} - -Sigmoid creates a filter that changes the contrast of an image using a sigmoidal function and returns the adjusted image. -It's a non-linear contrast change useful for photo adjustments as it preserves highlight and shadow detail. - -## UnsharpMask - -{{< funcsig >}} -images.UnsharpMask SIGMA AMOUNT THRESHOLD -{{< /funcsig >}} - -UnsharpMask creates a filter that sharpens an image. -The sigma parameter is used in a gaussian function and affects the radius of effect. -Sigma must be positive. Sharpen radius roughly equals 3 * sigma. -The amount parameter controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5. -The threshold parameter controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05. - -## Other Functions - -### Filter - -{{< funcsig >}} -IMAGE | images.Filter FILTERS... -{{< /funcsig >}} - -Can be used to apply a set of filters to an image: - -```go-html-template -{{ $img := $img | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} -``` - -Also see the [Filter Method](/content-management/image-processing/#filter). - -### ImageConfig - -Parses the image and returns the height, width, and color model. - -The `imageConfig` function takes a single parameter, a file path (_string_) relative to the _project's root directory_, with or without a leading slash. - -{{< funcsig >}} -images.ImageConfig PATH -{{< /funcsig >}} - -```go-html-template -{{ with (imageConfig "favicon.ico") }} -favicon.ico: {{ .Width }} x {{ .Height }} -{{ end }} -``` - -[`Process`]: #process diff --git a/content/en/functions/inflect/Humanize.md b/content/en/functions/inflect/Humanize.md index 74d24f310..41d61a4e5 100644 --- a/content/en/functions/inflect/Humanize.md +++ b/content/en/functions/inflect/Humanize.md @@ -1,29 +1,26 @@ --- title: inflect.Humanize -linkTitle: humanize -description: Returns the humanized version of an argument with the first letter capitalized. -categories: [functions] +description: Returns the humanized version of the input with the first letter capitalized. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [humanize] + related: + - functions/inflect/Pluralize + - functions/inflect/Singularize returnType: string signatures: [inflect.Humanize INPUT] -relatedFunctions: - - inflect.Humanize - - inflect.Pluralize - - inflect.Singularize aliases: [/functions/humanize] --- +```go-html-template +{{ humanize "my-first-post" }} → My first post +{{ humanize "myCamelPost" }} → My camel post +``` + If the input is either an int64 value or the string representation of an integer, humanize returns the number with the proper ordinal appended. - ```go-html-template -{{ humanize "my-first-post" }} → "My first post" -{{ humanize "myCamelPost" }} → "My camel post" -{{ humanize "52" }} → "52nd" -{{ humanize 103 }} → "103rd" +{{ humanize "52" }} → 52nd +{{ humanize 103 }} → 103rd ``` diff --git a/content/en/functions/inflect/Pluralize.md b/content/en/functions/inflect/Pluralize.md index 5bb444114..c25f89617 100644 --- a/content/en/functions/inflect/Pluralize.md +++ b/content/en/functions/inflect/Pluralize.md @@ -1,23 +1,18 @@ --- title: inflect.Pluralize -linkTitle: pluralize -description: Pluralizes the given word according to a set of common English pluralization rules -categories: [functions] +description: Pluralizes the given word according to a set of common English pluralization rules. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [pluralize] + related: + - functions/inflect/Humanize + - functions/inflect/Singularize returnType: string signatures: [inflect.Pluralize INPUT] -relatedFunctions: - - inflect.Humanize - - inflect.Pluralize - - inflect.Singularize aliases: [/functions/pluralize] --- ```go-html-template -{{ "cat" | pluralize }} → "cats" +{{ "cat" | pluralize }} → cats ``` diff --git a/content/en/functions/inflect/Singularize.md b/content/en/functions/inflect/Singularize.md index 5aba4e4ee..29b543257 100644 --- a/content/en/functions/inflect/Singularize.md +++ b/content/en/functions/inflect/Singularize.md @@ -1,25 +1,20 @@ --- title: inflect.Singularize -linkTitle: singularize -description: Converts a word according to a set of common English singularization rules. -categories: [functions] +description: Singularizes the given word according to a set of common English singularization rules. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [singularize] + related: + - functions/inflect/Humanize + - functions/inflect/Pluralize returnType: string signatures: [inflect.Singularize INPUT] -relatedFunctions: - - inflect.Humanize - - inflect.Pluralize - - inflect.Singularize aliases: [/functions/singularize] --- ```go-html-template -{{ "cats" | singularize }} → "cat" +{{ "cats" | singularize }} → cat ``` See also the `.Data.Singular` [taxonomy variable](/variables/taxonomy/) for singularizing taxonomy names. diff --git a/content/en/functions/inflect/_index.md b/content/en/functions/inflect/_index.md new file mode 100644 index 000000000..601b409e6 --- /dev/null +++ b/content/en/functions/inflect/_index.md @@ -0,0 +1,12 @@ +--- +title: Inflect functions +linkTitle: inflect +description: Template functions to inflect English nouns. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +These functions provide word inflection features such as singularization and pluralization of English nouns. diff --git a/content/en/functions/js/Build.md b/content/en/functions/js/Build.md new file mode 100644 index 000000000..e3b40a2ac --- /dev/null +++ b/content/en/functions/js/Build.md @@ -0,0 +1,182 @@ +--- +title: js.Build +description: Bundles, transpiles, tree shakes, and minifies JavaScript resources. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/Babel + - functions/resources/Fingerprint + - functions/resources/Minify + returnType: resource.Resource + signatures: ['js.Build [OPTIONS] RESOURCE'] +toc: true +--- + +The `js.Build` function uses the [evanw/esbuild] package to: + +- Bundle +- Transpile (TypeScript and JSX) +- Tree shake +- Minify +- Create source maps + +[evanw/esbuild]: https://github.com/evanw/esbuild + +```go-html-template +{{ with resources.Get "js/main.js" }} + {{ if hugo.IsDevelopment }} + {{ with . | js.Build }} + + {{ end }} + {{ else }} + {{ $opts := dict "minify" true }} + {{ with . | js.Build $opts | fingerprint }} + + {{ end }} + {{ end }} +{{ end }} +``` + +## Options + +targetPath +: (`string`) If not set, the source path will be used as the base target path. +Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript. + +params [map or slice] +: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g. + +```go-html-template +{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }} +``` +And then in your JS file: + +```js +import * as params from '@params'; +``` + +Note that this is meant for small data sets, e.g. configuration settings. For larger data, please put/mount the files into `/assets` and import them directly. + +minify +: (`bool`)Let `js.Build` handle the minification. + +inject +: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject + +shims +: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development: + +```go-html-template +{{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }} +{{ $js = $js | js.Build dict "shims" $shims }} +``` + +The _shim_ files may look like these: + +```js +// js/shims/react.js +module.exports = window.React; +``` + +```js +// js/shims/react-dom.js +module.exports = window.ReactDOM; +``` + +With the above, these imports should work in both scenarios: + +```js +import * as React from 'react' +import * as ReactDOM from 'react-dom'; +``` + +target +: (`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`. Default is `esnext`. + +externals +: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external + +defines +: (`map`) Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value. + +```go-html-template +{{ $defines := dict "process.env.NODE_ENV" `"development"` }} +``` + +format +: (`string`) The output format. One of: `iife`, `cjs`, `esm`. Default is `iife`, a self-executing function, suitable for inclusion as a ` +``` diff --git a/content/en/functions/js/_index.md b/content/en/functions/js/_index.md new file mode 100644 index 000000000..3356e7c7b --- /dev/null +++ b/content/en/functions/js/_index.md @@ -0,0 +1,12 @@ +--- +title: JavaScript functions +linkTitle: js +description: Template functions to work with JavaScript and TypeScript files. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with JavaScript and TypeScript files. diff --git a/content/en/functions/lang/FormatAccounting.md b/content/en/functions/lang/FormatAccounting.md index 974dc4a1a..70365c216 100644 --- a/content/en/functions/lang/FormatAccounting.md +++ b/content/en/functions/lang/FormatAccounting.md @@ -1,27 +1,21 @@ --- title: lang.FormatAccounting -description: Returns a currency representation of a number for the given currency and precision for the current language in accounting notation. -categories: [functions] +description: Returns a currency representation of a number for the given currency and precision for the current language and region in accounting notation. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/lang/FormatCurrency + - functions/lang/FormatNumber + - functions/lang/FormatNumberCustom + - functions/lang/FormatPercent returnType: string signatures: [lang.FormatAccounting PRECISION CURRENCY NUMBER] -relatedFunctions: - - lang.FormatAccounting - - lang.FormatCurrency - - lang.FormatNumber - - lang.FormatNumberCustom - - lang.FormatPercent --- ```go-html-template {{ 512.5032 | lang.FormatAccounting 2 "NOK" }} → NOK512.50 ``` -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} +{{% include "functions/_common/locales.md" %}} diff --git a/content/en/functions/lang/FormatCurrency.md b/content/en/functions/lang/FormatCurrency.md index b29a807fe..91148c595 100644 --- a/content/en/functions/lang/FormatCurrency.md +++ b/content/en/functions/lang/FormatCurrency.md @@ -1,27 +1,21 @@ --- title: lang.FormatCurrency -description: Returns a currency representation of a number for the given currency and precision for the current language. -categories: [functions] +description: Returns a currency representation of a number for the given currency and precision for the current language and region. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/lang/FormatAccounting + - functions/lang/FormatNumber + - functions/lang/FormatNumberCustom + - functions/lang/FormatPercent returnType: string signatures: [lang.FormatAccounting PRECISION CURRENCY NUMBER] -relatedFunctions: - - lang.FormatAccounting - - lang.FormatCurrency - - lang.FormatNumber - - lang.FormatNumberCustom - - lang.FormatPercent --- ```go-html-template {{ 512.5032 | lang.FormatCurrency 2 "USD" }} → $512.50 ``` -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} +{{% include "functions/_common/locales.md" %}} diff --git a/content/en/functions/lang/FormatNumber.md b/content/en/functions/lang/FormatNumber.md index dd878fdef..597df742a 100644 --- a/content/en/functions/lang/FormatNumber.md +++ b/content/en/functions/lang/FormatNumber.md @@ -1,27 +1,21 @@ --- title: lang.FormatNumber -description: Returns a numeric representation of a number with the given precision for the current language. -categories: [functions] +description: Returns a numeric representation of a number with the given precision for the current language and region. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/lang/FormatAccounting + - functions/lang/FormatCurrency + - functions/lang/FormatNumberCustom + - functions/lang/FormatPercent returnType: string signatures: [lang.FormatNumber PRECISION NUMBER] -relatedFunctions: - - lang.FormatAccounting - - lang.FormatCurrency - - lang.FormatNumber - - lang.FormatNumberCustom - - lang.FormatPercent --- ```go-html-template {{ 512.5032 | lang.FormatNumber 2 }} → 512.50 ``` -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} +{{% include "functions/_common/locales.md" %}} diff --git a/content/en/functions/lang/FormatNumberCustom.md b/content/en/functions/lang/FormatNumberCustom.md index 97b022567..0b72f4983 100644 --- a/content/en/functions/lang/FormatNumberCustom.md +++ b/content/en/functions/lang/FormatNumberCustom.md @@ -1,31 +1,26 @@ --- title: lang.FormatNumberCustom description: Returns a numeric representation of a number with the given precision using negative, decimal, and grouping options. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/lang/FormatAccounting + - functions/lang/FormatCurrency + - functions/lang/FormatNumber + - functions/lang/FormatPercent returnType: string signatures: ['lang.FormatNumberCustom PRECISION NUMBER [OPTIONS...]'] -relatedFunctions: - - lang.FormatAccounting - - lang.FormatCurrency - - lang.FormatNumber - - lang.FormatNumberCustom - - lang.FormatPercent aliases: ['/functions/numfmt/'] --- This function formats a number with the given precision. The first options parameter is a space-delimited string of characters to represent negativity, the decimal point, and grouping. The default value is `- . ,`. The second options parameter defines an alternate delimiting character. -Note that numbers are rounded up at 5 or greater. So, with precision set to 0, 1.5 becomes 2, and 1.4 becomes 1. +Note that numbers are rounded up at 5 or greater. So, with precision set to 0, 1.5 becomes 2, and 1.4 becomes 1. For a simpler function that adapts to the current language, see [`lang.FormatNumber`]. - ```go-html-template {{ lang.FormatNumberCustom 2 12345.6789 }} → 12,345.68 {{ lang.FormatNumberCustom 2 12345.6789 "- , ." }} → 12.345,68 @@ -34,8 +29,6 @@ For a simpler function that adapts to the current language, see [`lang.FormatNum {{ lang.FormatNumberCustom 0 -12345.6789 "-|.| " "|" }} → -12 346 ``` -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} +{{% include "functions/_common/locales.md" %}} [`lang.FormatNumber`]: /functions/lang/formatnumber diff --git a/content/en/functions/lang/FormatPercent.md b/content/en/functions/lang/FormatPercent.md index dd2042490..529ada67b 100644 --- a/content/en/functions/lang/FormatPercent.md +++ b/content/en/functions/lang/FormatPercent.md @@ -1,27 +1,21 @@ --- title: lang.FormatPercent -description: Returns a percentage representation of a number with the given precision for the current language. -categories: [functions] +description: Returns a percentage representation of a number with the given precision for the current language and region. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/lang/FormatAccounting + - functions/lang/FormatCurrency + - functions/lang/FormatNumber + - functions/lang/FormatNumberCustom returnType: string signatures: [lang.FormatPercent PRECISION NUMBER] -relatedFunctions: - - lang.FormatAccounting - - lang.FormatCurrency - - lang.FormatNumber - - lang.FormatNumberCustom - - lang.FormatPercent --- ```go-html-template {{ 512.5032 | lang.FormatPercent 2 }} → 512.50% ``` -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} +{{% include "functions/_common/locales.md" %}} diff --git a/content/en/functions/lang/Merge.md b/content/en/functions/lang/Merge.md index b3d21cd7a..75f5cdf01 100644 --- a/content/en/functions/lang/Merge.md +++ b/content/en/functions/lang/Merge.md @@ -1,31 +1,27 @@ --- title: lang.Merge description: Merge missing translations from other languages. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: [] returnType: any signatures: [lang.Merge FROM TO] -relatedFunctions: [] aliases: [/functions/lang.merge] --- As an example: -```bash +```sh {{ $pages := .Site.RegularPages | lang.Merge $frSite.RegularPages | lang.Merge $enSite.RegularPages }} ``` Will "fill in the gaps" in the current site with, from left to right, content from the French site, and lastly the English. - A more practical example is to fill in the missing translations from the other languages: -```bash +```sh {{ $pages := .Site.RegularPages }} {{ range .Site.Home.Translations }} {{ $pages = $pages | lang.Merge .Site.RegularPages }} diff --git a/content/en/functions/lang/Translate.md b/content/en/functions/lang/Translate.md index 718d8cfb2..630098a96 100644 --- a/content/en/functions/lang/Translate.md +++ b/content/en/functions/lang/Translate.md @@ -1,23 +1,19 @@ --- title: lang.Translate -linkTitle: i18n description: Translates a string using the translation tables in the i18n directory. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: - aliases: [i18n,T] +action: + aliases: [T, i18n] + related: [] returnType: string signatures: ['lang.Translate KEY [CONTEXT]'] -relatedFunctions: [] aliases: [/functions/i18n] --- Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory. -``` +```text i18n/ ├── en.toml └── pl.toml @@ -34,12 +30,10 @@ The Unicode [CLDR Plural Rules chart] describes the pluralization categories for The English translation table: -{{< code-toggle file=i18n/en copy=false >}} -# simple translations +{{< code-toggle file=i18n/en >}} privacy = 'privacy' security = 'security' -# translations with pluralization [day] one = 'day' other = 'days' @@ -51,12 +45,10 @@ other = '{{ . }} days' The Polish translation table: -{{< code-toggle file=i18n/pl copy=false >}} -# simple translations +{{< code-toggle file=i18n/pl >}} privacy = 'prywatność' security = 'bezpieczeństwo' -# translations with pluralization [day] one = 'miesiąc' few = 'miesiące' @@ -108,17 +100,17 @@ When viewing the Polish language site: {{ T "day_with_count" 5 }} → 5 miesięcy ``` -In the pluralization examples above, we passed an integer in context (the second argument). You can also pass a map in context, creating a `count` key to control pluralization. +In the pluralization examples above, we passed an integer in context (the second argument). You can also pass a map in context, providing a `count` key to control pluralization. Translation table: -{{< code-toggle file=i18n/en copy=false >}} +{{< code-toggle file=i18n/en >}} [age] one = '{{ .name }} is {{ .count }} year old.' other = '{{ .name }} is {{ .count }} years old.' {{< /code-toggle >}} -Template: +Template code: ```go-html-template {{ T "age" (dict "name" "Will" "count" 1) }} → Will is 1 year old. diff --git a/content/en/functions/lang/_index.md b/content/en/functions/lang/_index.md new file mode 100644 index 000000000..934d97bff --- /dev/null +++ b/content/en/functions/lang/_index.md @@ -0,0 +1,12 @@ +--- +title: Lang functions +linkTitle: lang +description: Template functions to adapt your site to meet language and regional requirements. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to adapt your site to meet language and regional requirements. diff --git a/content/en/functions/math/Abs.md b/content/en/functions/math/Abs.md new file mode 100644 index 000000000..6e907d564 --- /dev/null +++ b/content/en/functions/math/Abs.md @@ -0,0 +1,15 @@ +--- +title: math.Abs +description: Returns the absolute value of the given number. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: float64 + signatures: [math.Abs VALUE] +--- + +```go-html-template +{{ math.Abs -2.1 }} → 2.1 +``` diff --git a/content/en/functions/math/Add.md b/content/en/functions/math/Add.md new file mode 100644 index 000000000..5e3bfb162 --- /dev/null +++ b/content/en/functions/math/Add.md @@ -0,0 +1,22 @@ +--- +title: math.Add +description: Adds two or more numbers. +categories: [] +keywords: [] +action: + aliases: [add] + related: + - functions/math/Div + - functions/math/Mul + - functions/math/Product + - functions/math/Sub + - functions/math/Sum + returnType: any + signatures: [math.Add VALUE VALUE...] +--- + +If one of the numbers is a float, the result is a float. + +```go-html-template +{{ add 12 3 2 }} → 17 +``` diff --git a/content/en/functions/math/Ceil.md b/content/en/functions/math/Ceil.md new file mode 100644 index 000000000..9f74991c3 --- /dev/null +++ b/content/en/functions/math/Ceil.md @@ -0,0 +1,17 @@ +--- +title: math.Ceil +description: Returns the least integer value greater than or equal to the given number. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Floor + - functions/math/Round + returnType: float64 + signatures: [math.Ceil VALUE] +--- + +```go-html-template +{{ math.Ceil 2.1 }} → 3 +``` diff --git a/content/en/functions/math/Counter.md b/content/en/functions/math/Counter.md new file mode 100644 index 000000000..7f53bdd0c --- /dev/null +++ b/content/en/functions/math/Counter.md @@ -0,0 +1,35 @@ +--- +title: math.Counter +description: Increments and returns a global counter. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: uint64 + signatures: [math.Counter] +--- + +The counter is global for both monolingual and multilingual sites, and its initial value for each build is 1. + +```go-html-template +{{ warnf "single.html called %d times" math.Counter }} +``` + +```sh +WARN single.html called 1 times +WARN single.html called 2 times +WARN single.html called 3 times +``` + +Use this function to: + +- Create unique warnings as shown above; the [`warnf`] function suppresses duplicate messages +- Create unique target paths for the `resources.FromString` function where the target path is also the cache key + +[`warnf`]: /functions/fmt/warnf +[`resources.FromString`]: /functions/resources/fromstring + +{{% note %}} +Due to concurrency, the value returned in a given template for a given page will vary from one build to the next. You cannot use this function to assign a static id to each page. +{{% /note %}} diff --git a/content/en/functions/math/Div.md b/content/en/functions/math/Div.md new file mode 100644 index 000000000..5123791b2 --- /dev/null +++ b/content/en/functions/math/Div.md @@ -0,0 +1,22 @@ +--- +title: math.Div +description: Divides the first number by one or more numbers. +categories: [] +keywords: [] +action: + aliases: [div] + related: + - functions/math/Add + - functions/math/Mul + - functions/math/Product + - functions/math/Sub + - functions/math/Sum + returnType: any + signatures: [math.Div VALUE VALUE...] +--- + +If one of the numbers is a float, the result is a float. + +```go-html-template +{{ div 12 3 2 }} → 2 +``` diff --git a/content/en/functions/math/Floor.md b/content/en/functions/math/Floor.md new file mode 100644 index 000000000..10ad758b6 --- /dev/null +++ b/content/en/functions/math/Floor.md @@ -0,0 +1,17 @@ +--- +title: math.Floor +description: Returns the greatest integer value less than or equal to the given number. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Ceil + - functions/math/Round + returnType: float64 + signatures: [math.Floor VALUE] +--- + +```go-html-template +{{ math.Floor 1.9 }} → 1 +``` diff --git a/content/en/functions/math/Log.md b/content/en/functions/math/Log.md new file mode 100644 index 000000000..84edcb288 --- /dev/null +++ b/content/en/functions/math/Log.md @@ -0,0 +1,15 @@ +--- +title: math.Log +description: Returns the natural logarithm of the given number. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: float64 + signatures: [math.Log VALUE] +--- + +```go-html-template +{{ math.Log 42 }} → 3.737 +``` diff --git a/content/en/functions/math/Max.md b/content/en/functions/math/Max.md new file mode 100644 index 000000000..9beff5630 --- /dev/null +++ b/content/en/functions/math/Max.md @@ -0,0 +1,16 @@ +--- +title: math.Max +description: Returns the greater of all numbers. Accepts scalars, slices, or both. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Min + returnType: float64 + signatures: [math.Max VALUE...] +--- + +```go-html-template +{{ math.Max 1 (slice 2 3) 4 }} → 4 +``` diff --git a/content/en/functions/math/Min.md b/content/en/functions/math/Min.md new file mode 100644 index 000000000..79e464c74 --- /dev/null +++ b/content/en/functions/math/Min.md @@ -0,0 +1,16 @@ +--- +title: math.Min +description: Returns the smaller of all numbers. Accepts scalars, slices, or both. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Max + returnType: float64 + signatures: [math.Min VALUE...] +--- + +```go-html-template +{{ math.Min 1 (slice 2 3) 4 }} → 1 +``` diff --git a/content/en/functions/math/Mod.md b/content/en/functions/math/Mod.md new file mode 100644 index 000000000..d312730c5 --- /dev/null +++ b/content/en/functions/math/Mod.md @@ -0,0 +1,16 @@ +--- +title: math.Mod +description: Returns the modulus of two integers. +categories: [] +keywords: [] +action: + aliases: [mod] + related: + - functions/math/ModBool + returnType: int64 + signatures: [math.Mod VALUE1 VALUE2] +--- + +```go-html-template +{{ mod 15 3 }} → 0 +``` diff --git a/content/en/functions/math/ModBool.md b/content/en/functions/math/ModBool.md new file mode 100644 index 000000000..d915ff614 --- /dev/null +++ b/content/en/functions/math/ModBool.md @@ -0,0 +1,16 @@ +--- +title: math.ModBool +description: Reports whether the modulus of two integers equals 0. +categories: [] +keywords: [] +action: + aliases: [modBool] + related: + - functions/math/Mod + returnType: bool + signatures: [math.ModBool VALUE1 VALUE2] +--- + +```go-html-template +{{ modBool 15 3 }} → true +``` diff --git a/content/en/functions/math/Mul.md b/content/en/functions/math/Mul.md new file mode 100644 index 000000000..1db8ad9eb --- /dev/null +++ b/content/en/functions/math/Mul.md @@ -0,0 +1,22 @@ +--- +title: math.Mul +description: Multiplies two or more numbers. +categories: [] +keywords: [] +action: + aliases: [mul] + related: + - functions/math/Add + - functions/math/Div + - functions/math/Product + - functions/math/Sub + - functions/math/Sum + returnType: any + signatures: [math.Mul VALUE VALUE...] +--- + +If one of the numbers is a float, the result is a float. + +```go-html-template +{{ mul 12 3 2 }} → 72 +``` diff --git a/content/en/functions/math/Pow.md b/content/en/functions/math/Pow.md new file mode 100644 index 000000000..5a1482d73 --- /dev/null +++ b/content/en/functions/math/Pow.md @@ -0,0 +1,16 @@ +--- +title: math.Pow +description: Returns the first number raised to the power of the second number. +categories: [] +keywords: [] +action: + aliases: [pow] + related: + - functions/math/Sqrt + returnType: float64 + signatures: [math.Pow VALUE1 VALUE2] +--- + +```go-html-template +{{ math.Pow 2 3 }} → 8 +``` diff --git a/content/en/functions/math/Product.md b/content/en/functions/math/Product.md new file mode 100644 index 000000000..343e9f73d --- /dev/null +++ b/content/en/functions/math/Product.md @@ -0,0 +1,20 @@ +--- +title: math.Product +description: Returns the product of all numbers. Accepts scalars, slices, or both. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Add + - functions/math/Div + - functions/math/Mul + - functions/math/Sub + - functions/math/Sum + returnType: float64 + signatures: [math.Product VALUE...] +--- + +```go-html-template +{{ math.Product 1 (slice 2 3) 4 }} → 24 +``` diff --git a/content/en/functions/math/Round.md b/content/en/functions/math/Round.md new file mode 100644 index 000000000..e0678eb78 --- /dev/null +++ b/content/en/functions/math/Round.md @@ -0,0 +1,17 @@ +--- +title: math.Round +description: Returns the nearest integer, rounding half away from zero. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Ceil + - functions/math/Floor + returnType: float64 + signatures: [math.Round VALUE] +--- + +```go-html-template +{{ math.Round 1.5 }} → 2 +``` diff --git a/content/en/functions/math/Sqrt.md b/content/en/functions/math/Sqrt.md new file mode 100644 index 000000000..436cb31c3 --- /dev/null +++ b/content/en/functions/math/Sqrt.md @@ -0,0 +1,16 @@ +--- +title: math.Sqrt +description: Returns the square root of the given number. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Pow + returnType: float64 + signatures: [math.Sqrt VALUE] +--- + +```go-html-template +{{ math.Sqrt 81 }} → 9 +``` diff --git a/content/en/functions/math/Sub.md b/content/en/functions/math/Sub.md new file mode 100644 index 000000000..6c4ef10d5 --- /dev/null +++ b/content/en/functions/math/Sub.md @@ -0,0 +1,21 @@ +--- +title: math.Sub +description: Subtracts one or more numbers from the first number. +categories: [] +action: + aliases: [sub] + related: + - functions/math/Add + - functions/math/Div + - functions/math/Mul + - functions/math/Product + - functions/math/Sum + returnType: any + signatures: [math.Sub VALUE VALUE...] +--- + +If one of the numbers is a float, the result is a float. + +```go-html-template +{{ sub 12 3 2 }} → 7 +``` diff --git a/content/en/functions/math/Sum.md b/content/en/functions/math/Sum.md new file mode 100644 index 000000000..ae1419fb3 --- /dev/null +++ b/content/en/functions/math/Sum.md @@ -0,0 +1,19 @@ +--- +title: math.Sum +description: Returns the sum of all numbers. Accepts scalars, slices, or both. +categories: [] +action: + aliases: [] + related: + - functions/math/Add + - functions/math/Div + - functions/math/Mul + - functions/math/Product + - functions/math/Sub + returnType: float64 + signatures: [math.Sum VALUE...] +--- + +```go-html-template +{{ math.Sum 1 (slice 2 3) 4 }} → 10 +``` diff --git a/content/en/functions/math/_index.md b/content/en/functions/math/_index.md new file mode 100644 index 000000000..76713bc99 --- /dev/null +++ b/content/en/functions/math/_index.md @@ -0,0 +1,11 @@ +--- +title: Math functions +linkTitle: math +description: Template functions to perform mathematical operations. +categories: [] +menu: + docs: + parent: functions +--- + +Use these functions to perform mathematical operations. diff --git a/content/en/functions/math/index.md b/content/en/functions/math/index.md deleted file mode 100644 index fd4d10a31..000000000 --- a/content/en/functions/math/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: math -description: Hugo provides mathematical operators in templates. -categories: [functions] -keywords: [] - -menu: - docs: - parent: functions -function: - aliases: [] - returnType: - signatures: [] -relatedFunctions: [] ---- - -| Function | Description | Example | -|-----------------|-----------------------------------------------------------------------------|---------------------------------------------------| -| `add` | Adds two or more numbers. | `{{ add 12 3 2 }}` → `17` | -| | *If one of the numbers is a float, the result is a float.* | `{{ add 1.1 2 }}` → `3.1` | -| `sub` | Subtracts one or more numbers from the first number. | `{{ sub 12 3 2 }}` → `7` | -| | *If one of the numbers is a float, the result is a float.* | `{{ sub 3 2.5 }}` → `0.5` | -| `mul` | Multiplies two or more numbers. | `{{ mul 12 3 2 }}` → `72` | -| | *If one of the numbers is a float, the result is a float.* | `{{ mul 2 3.1 }}` → `6.2` | -| `div` | Divides the first number by one or more numbers. | `{{ div 12 3 2 }}` → `2` | -| | *If one of the numbers is a float, the result is a float.* | `{{ div 6 4.0 }}` → `1.5` | -| `mod` | Modulus of two integers. | `{{ mod 15 3 }}` → `0` | -| `modBool` | Boolean of modulus of two integers. Evaluates to `true` if result equals 0. | `{{ modBool 15 3 }}` → `true` | -| `math.Abs` | Returns the absolute value of the given number. | `{{ math.Abs -2.1 }}` → `2.1` | -| `math.Ceil` | Returns the least integer value greater than or equal to the given number. | `{{ math.Ceil 2.1 }}` → `3` | -| `math.Floor` | Returns the greatest integer value less than or equal to the given number. | `{{ math.Floor 1.9 }}` → `1` | -| `math.Log` | Returns the natural logarithm of the given number. | `{{ math.Log 42 }}` → `3.737` | -| `math.Max` | Returns the greater of all numbers. Accepts scalars, slices, or both. | `{{ math.Max 1 (slice 2 3) 4 }}` → `4` | -| `math.Min` | Returns the smaller of all numbers. Accepts scalars, slices, or both. | `{{ math.Min 1 (slice 2 3) 4 }}` → `1` | -| `math.Product` | Returns the product of all numbers. Accepts scalars, slices, or both. | `{{ math.Product 1 (slice 2 3) 4 }}` → `24` | -| `math.Pow` | Returns the first number raised to the power of the second number. | `{{ math.Pow 2 3 }}` → `8` | -| `math.Round` | Returns the nearest integer, rounding half away from zero. | `{{ math.Round 1.5 }}` → `2` | -| `math.Sqrt` | Returns the square root of the given number. | `{{ math.Sqrt 81 }}` → `9` | -| `math.Sum` | Returns the sum of all numbers. Accepts scalars, slices, or both. | `{{ math.Sum 1 (slice 2 3) 4 }}` → `10` | diff --git a/content/en/functions/os/FileExists.md b/content/en/functions/os/FileExists.md index 52cfe32c8..b8104a066 100644 --- a/content/en/functions/os/FileExists.md +++ b/content/en/functions/os/FileExists.md @@ -1,22 +1,17 @@ --- title: os.FileExists -linkTitle: fileExists description: Reports whether the file or directory exists. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [fileExists] + related: + - functions/os/Getenv + - functions/os/ReadDir + - functions/os/ReadFile + - functions/os/Stat returnType: bool signatures: [os.FileExists PATH] -relatedFunctions: - - os.FileExists - - os.Getenv - - os.ReadDir - - os.ReadFile - - os.Stat aliases: [/functions/fileexists] --- @@ -36,11 +31,11 @@ content/ The function returns these values: ```go-html-template -{{ os.FileExists "content" }} → true -{{ os.FileExists "content/news" }} → true -{{ os.FileExists "content/news/article-1" }} → false -{{ os.FileExists "content/news/article-1.md" }} → true -{{ os.FileExists "news" }} → true -{{ os.FileExists "news/article-1" }} → false -{{ os.FileExists "news/article-1.md" }} → true +{{ fileExists "content" }} → true +{{ fileExists "content/news" }} → true +{{ fileExists "content/news/article-1" }} → false +{{ fileExists "content/news/article-1.md" }} → true +{{ fileExists "news" }} → true +{{ fileExists "news/article-1" }} → false +{{ fileExists "news/article-1.md" }} → true ``` diff --git a/content/en/functions/os/Getenv.md b/content/en/functions/os/Getenv.md index 16f73f5aa..084d498ce 100644 --- a/content/en/functions/os/Getenv.md +++ b/content/en/functions/os/Getenv.md @@ -1,35 +1,49 @@ --- title: os.Getenv -linkTitle: getenv description: Returns the value of an environment variable, or an empty string if the environment variable is not set. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [getenv] + related: + - functions/os/FileExists + - functions/os/ReadDir + - functions/os/ReadFile + - functions/os/Stat returnType: string signatures: [os.Getenv VARIABLE] -relatedFunctions: - - os.FileExists - - os.Getenv - - os.ReadDir - - os.ReadFile - - os.Stat aliases: [/functions/getenv] +toc: true --- -Examples: +## Security + +By default, when using the `os.Getenv` function Hugo allows access to: + +- The `CI` environment variable +- Any environment variable beginning with `HUGO_` + +To access other environment variables, adjust your site configuration. For example, to allow access to the `HOME` and `USER` environment variables: + +{{< code-toggle file=hugo >}} +[security.funcs] +getenv = ['^HUGO_', '^CI$', '^USER$', '^HOME$'] +{{< /code-toggle >}} + +Read more about Hugo's [security policy]. + +[security policy]: /about/security-model/#security-policy + +## Examples ```go-html-template -{{ os.Getenv "HOME" }} → /home/victor -{{ os.Getenv "USER" }} → victor +{{ getenv "HOME" }} → /home/victor +{{ getenv "USER" }} → victor ``` You can pass values when building your site: -```bash +```sh MY_VAR1=foo MY_VAR2=bar hugo OR @@ -42,8 +56,6 @@ hugo And then retrieve the values within a template: ```go-html-template -{{ os.Getenv "MY_VAR1" }} → foo -{{ os.Getenv "MY_VAR2" }} → bar +{{ getenv "MY_VAR1" }} → foo +{{ getenv "MY_VAR2" }} → bar ``` - -With Hugo v0.91.0 and later, you must explicitly allow access to environment variables. For details, review [Hugo's Security Policy](/about/security-model/#security-policy). By default, environment variables beginning with `HUGO_` are allowed when using the `os.Getenv` function. diff --git a/content/en/functions/os/ReadDir.md b/content/en/functions/os/ReadDir.md index d0ed87bdf..63af850b7 100644 --- a/content/en/functions/os/ReadDir.md +++ b/content/en/functions/os/ReadDir.md @@ -1,22 +1,17 @@ --- title: os.ReadDir -linkTitle: readDir description: Returns an array of FileInfo structures sorted by file name, one element for each directory entry. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [readDir] - returnType: FileInfo + related: + - functions/os/FileExists + - functions/os/Getenv + - functions/os/ReadFile + - functions/os/Stat + returnType: os.FileInfo signatures: [os.ReadDir PATH] -relatedFunctions: - - os.FileExists - - os.Getenv - - os.ReadDir - - os.ReadFile - - os.Stat aliases: [/functions/readdir] --- @@ -36,7 +31,7 @@ content/ This template code: ```go-html-template -{{ range os.ReadDir "content" }} +{{ range readDir "content" }} {{ .Name }} → {{ .IsDir }} {{ end }} ``` diff --git a/content/en/functions/os/ReadFile.md b/content/en/functions/os/ReadFile.md index 30f2b3056..654e300ac 100644 --- a/content/en/functions/os/ReadFile.md +++ b/content/en/functions/os/ReadFile.md @@ -1,22 +1,17 @@ --- title: os.ReadFile -linkTitle: readFile description: Returns the contents of a file. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [readFile] + related: + - functions/os/FileExists + - functions/os/Getenv + - functions/os/ReadDir + - functions/os/Stat returnType: string signatures: [os.ReadFile PATH] -relatedFunctions: - - os.FileExists - - os.Getenv - - os.ReadDir - - os.ReadFile - - os.Stat aliases: [/functions/readfile] --- @@ -31,7 +26,7 @@ This is **bold** text. This template code: ```go-html-template -{{ os.ReadFile "README.md" }} +{{ readFile "README.md" }} ``` Produces: diff --git a/content/en/functions/os/Stat.md b/content/en/functions/os/Stat.md index dfef3c815..6b6f668de 100644 --- a/content/en/functions/os/Stat.md +++ b/content/en/functions/os/Stat.md @@ -1,21 +1,17 @@ --- title: os.Stat description: Returns a FileInfo structure describing a file or directory. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] - returnType: FileInfo + related: + - functions/os/FileExists + - functions/os/Getenv + - functions/os/ReadDir + - functions/os/ReadFile + returnType: os.FileInfo signatures: [os.Stat PATH] -relatedFunctions: - - os.FileExists - - os.Getenv - - os.ReadDir - - os.ReadFile - - os.Stat aliases: [/functions/os.stat] --- diff --git a/content/en/functions/os/_index.md b/content/en/functions/os/_index.md new file mode 100644 index 000000000..c080d0092 --- /dev/null +++ b/content/en/functions/os/_index.md @@ -0,0 +1,12 @@ +--- +title: OS functions +linkTitle: os +description: Template functions to interact with the operating system. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to interact with the operating system. diff --git a/content/en/functions/partials/Include.md b/content/en/functions/partials/Include.md index ea9dfb31a..e9ed093d8 100644 --- a/content/en/functions/partials/Include.md +++ b/content/en/functions/partials/Include.md @@ -1,19 +1,16 @@ --- title: partials.Include -linkTitle: partial -description: Executes the named partial template. If the partial contains a return statement, returns that value, else returns the rendered output. -categories: [functions] +description: Executes the given partial template, optionally passing context. If the partial contains a return statement, returns that value, else returns the rendered output. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [partial] + related: + - functions/go-template/template + - functions/partials/IncludeCached + - methods/page/Render returnType: any - signatures: ['partials.Include LAYOUT [CONTEXT]'] -relatedFunctions: - - partials.Include - - partials.IncludeCached + signatures: ['partials.Include NAME [CONTEXT]'] aliases: [/functions/partial] --- @@ -63,5 +60,4 @@ Then, within the partial template:

{{ .name }} is majoring in {{ .major }}. Their grade point average is {{ .gpa }}.

``` - [breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants diff --git a/content/en/functions/partials/IncludeCached.md b/content/en/functions/partials/IncludeCached.md index ab9a77835..4067eb905 100644 --- a/content/en/functions/partials/IncludeCached.md +++ b/content/en/functions/partials/IncludeCached.md @@ -1,22 +1,19 @@ --- title: partials.IncludeCached -linkTitle: partialCached -description: Allows for caching of partials that do not need to be re-rendered on every invocation. -categories: [functions] +description: Executes the given template and caches the result, optionally passing context. If the partial contains a return statement, returns that value, else returns the rendered output. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [partialCached] + related: + - functions/go-template/template + - functions/partials/Include + - methods/page/Render returnType: any signatures: ['partials.IncludeCached LAYOUT CONTEXT [VARIANT...]'] -relatedFunctions: - - partials.Include - - partials.IncludeCached signatures: - - partials.IncludeCached LAYOUT CONTEXT [VARIANT...] - - partialCached LAYOUT CONTEXT [VARIANT...] + - partials.IncludeCached NAME CONTEXT [VARIANT...] + - partialCached NAME CONTEXT [VARIANT...] aliases: [/functions/partialcached] --- diff --git a/content/en/functions/partials/_index.md b/content/en/functions/partials/_index.md new file mode 100644 index 000000000..0a7d4d6d0 --- /dev/null +++ b/content/en/functions/partials/_index.md @@ -0,0 +1,12 @@ +--- +title: Partial functions +linkTitle: partials +description: Template functions to call partial templates. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to call partial templates. diff --git a/content/en/functions/path/Base.md b/content/en/functions/path/Base.md index c00873524..2071f8bea 100644 --- a/content/en/functions/path/Base.md +++ b/content/en/functions/path/Base.md @@ -1,35 +1,26 @@ --- title: path.Base -description: Base returns the last element of a path. -categories: [functions] +description: Replaces path separators with slashes (`/`) and returns the last element of the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/BaseName + - functions/path/Clean + - functions/path/Dir + - functions/path/Ext + - functions/path/Join + - functions/path/Split returnType: string signatures: [path.Base PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.base] --- -`path.Base` returns the last element of `PATH`. - -If `PATH` is empty, `.` is returned. - -**Note:** On Windows, `PATH` is converted to slash (`/`) separators. - ```go-html-template -{{ path.Base "a/news.html" }} → "news.html" -{{ path.Base "news.html" }} → "news.html" -{{ path.Base "a/b/c" }} → "c" -{{ path.Base "/x/y/z/" }} → "z" +{{ path.Base "a/news.html" }} → news.html +{{ path.Base "news.html" }} → news.html +{{ path.Base "a/b/c" }} → c +{{ path.Base "/x/y/z/" }} → z +{{ path.Base "" }} → . ``` diff --git a/content/en/functions/path/BaseName.md b/content/en/functions/path/BaseName.md index a357ed403..477c8d319 100644 --- a/content/en/functions/path/BaseName.md +++ b/content/en/functions/path/BaseName.md @@ -1,33 +1,26 @@ --- title: path.BaseName -description: BaseName returns the last element of a path, removing the extension if present. -categories: [functions] +description: Replaces path separators with slashes (`/`) and returns the last element of the given path, removing the extension if present. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Base + - functions/path/Clean + - functions/path/Dir + - functions/path/Ext + - functions/path/Join + - functions/path/Split returnType: string signatures: [path.BaseName PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.basename] --- -If `PATH` is empty, `.` is returned. - -**Note:** On Windows, `PATH` is converted to slash (`/`) separators. - ```go-html-template -{{ path.BaseName "a/news.html" }} → "news" -{{ path.BaseName "news.html" }} → "news" -{{ path.BaseName "a/b/c" }} → "c" -{{ path.BaseName "/x/y/z/" }} → "z" +{{ path.BaseName "a/news.html" }} → news +{{ path.BaseName "news.html" }} → news +{{ path.BaseName "a/b/c" }} → c +{{ path.BaseName "/x/y/z/" }} → z +{{ path.BaseName "" }} → . ``` diff --git a/content/en/functions/path/Clean.md b/content/en/functions/path/Clean.md index 98160c568..57a665c03 100644 --- a/content/en/functions/path/Clean.md +++ b/content/en/functions/path/Clean.md @@ -1,35 +1,33 @@ --- title: path.Clean -description: Replaces path separators with slashes (`/`) and removes extraneous separators. -categories: [functions] +description: Replaces path separators with slashes (`/`) and returns the shortest path name equivalent to the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Base + - functions/path/BaseName + - functions/path/Dir + - functions/path/Ext + - functions/path/Join + - functions/path/Split returnType: string signatures: [path.Clean PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.clean] --- -`path.Clean` replaces path separators with slashes (`/`) and removes extraneous separators, including trailing separators. +See Go's [`path.Clean`] documentation for details. + +[`path.Clean`]: https://pkg.go.dev/path#Clean ```go-html-template -{{ path.Clean "foo//bar" }} → "foo/bar" -{{ path.Clean "/foo/bar/" }} → "/foo/bar" -``` - -On a Windows system, if `.File.Path` is `foo\bar.md`, then: - -```go-html-template -{{ path.Clean .File.Path }} → "foo/bar.md" +{{ path.Clean "foo/bar" }} → foo/bar +{{ path.Clean "/foo/bar" }} → /foo/bar +{{ path.Clean "/foo/bar/" }} → /foo/bar +{{ path.Clean "/foo//bar/" }} → /foo/bar +{{ path.Clean "/foo/./bar/" }} → /foo/bar +{{ path.Clean "/foo/../bar/" }} → /bar +{{ path.Clean "/../foo/../bar/" }} → /bar +{{ path.Clean "" }} → . ``` diff --git a/content/en/functions/path/Dir.md b/content/en/functions/path/Dir.md index 0a2928696..6d5e5c975 100644 --- a/content/en/functions/path/Dir.md +++ b/content/en/functions/path/Dir.md @@ -1,36 +1,27 @@ --- title: path.Dir -description: Dir returns all but the last element of a path. -categories: [functions] +description: Replaces path separators with slashes (/) and returns all but the last element of the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Base + - functions/path/BaseName + - functions/path/Clean + - functions/path/Ext + - functions/path/Join + - functions/path/Split returnType: string signatures: [path.Dir PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.dir] --- -`path.Dir` returns all but the last element of `PATH`, typically `PATH`'s directory. - -The returned path will never end in a slash. -If `PATH` is empty, `.` is returned. - -**Note:** On Windows, `PATH` is converted to slash (`/`) separators. - ```go-html-template -{{ path.Dir "a/news.html" }} → "a" -{{ path.Dir "news.html" }} → "." -{{ path.Dir "a/b/c" }} → "a/b" -{{ path.Dir "/x/y/z" }} → "/x/y" +{{ path.Dir "a/news.html" }} → a +{{ path.Dir "news.html" }} → . +{{ path.Dir "a/b/c" }} → a/b +{{ path.Dir "/a/b/c" }} → /a/b +{{ path.Dir "/a/b/c/" }} → /a/b/c +{{ path.Dir "" }} → . ``` diff --git a/content/en/functions/path/Ext.md b/content/en/functions/path/Ext.md index 6b5685948..f3e47aecd 100644 --- a/content/en/functions/path/Ext.md +++ b/content/en/functions/path/Ext.md @@ -1,33 +1,24 @@ --- title: path.Ext -description: Ext returns the file name extension of a path. -categories: [functions] +description: Replaces path separators with slashes (`/`) and returns the file name extension of the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Base + - functions/path/BaseName + - functions/path/Clean + - functions/path/Dir + - functions/path/Join + - functions/path/Split returnType: string signatures: [path.Ext PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.ext] --- -`path.Ext` returns the file name extension `PATH`. - -The extension is the suffix beginning at the final dot in the final slash-separated element `PATH`; -it is empty if there is no dot. - -**Note:** On Windows, `PATH` is converted to slash (`/`) separators. +The extension is the suffix beginning at the final dot in the final slash-separated element of path; it is empty if there is no dot. ```go-html-template -{{ path.Ext "a/b/c/news.html" }} → ".html" +{{ path.Ext "a/b/c/news.html" }} → .html ``` diff --git a/content/en/functions/path/Join.md b/content/en/functions/path/Join.md index 4f5c51c0f..dc701b731 100644 --- a/content/en/functions/path/Join.md +++ b/content/en/functions/path/Join.md @@ -1,34 +1,36 @@ --- title: path.Join -description: Join path elements into a single path. -categories: [functions] +description: Replaces path separators with slashes (`/`), joins the given path elements into a single path, and returns the shortest path name equivalent to the result. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Base + - functions/path/BaseName + - functions/path/Clean + - functions/path/Dir + - functions/path/Ext + - functions/path/Split + - functions/urls/JoinPath returnType: string signatures: [path.Join ELEMENT...] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split - - urls.JoinPath aliases: [/functions/path.join] --- -`path.Join` joins path elements into a single path, adding a separating slash if necessary. -All empty strings are ignored. +See Go's [`path.Join`] and [`path.Clean`] documentation for details. + +[`path.Clean`]: https://pkg.go.dev/path#Clean +[`path.Join`]: https://pkg.go.dev/path#Join -**Note:** All path elements on Windows are converted to slash ('/') separators. ```go-html-template -{{ path.Join "partial" "news.html" }} → "partial/news.html" -{{ path.Join "partial/" "news.html" }} → "partial/news.html" -{{ path.Join "foo/baz" "bar" }} → "foo/baz/bar" +{{ path.Join "partial" "news.html" }} → partial/news.html +{{ path.Join "partial/" "news.html" }} → partial/news.html +{{ path.Join "foo/bar" "baz" }} → foo/bar/baz +{{ path.Join "foo" "bar" "baz" }} → foo/bar/baz +{{ path.Join "foo" "" "baz" }} → foo/baz +{{ path.Join "foo" "." "baz" }} → foo/baz +{{ path.Join "foo" ".." "baz" }} → baz +{{ path.Join "/.." "foo" ".." "baz" }} → baz ``` diff --git a/content/en/functions/path/Split.md b/content/en/functions/path/Split.md index bde412743..329d73954 100644 --- a/content/en/functions/path/Split.md +++ b/content/en/functions/path/Split.md @@ -1,43 +1,34 @@ --- title: path.Split -description: Split path immediately following the final slash. -categories: [functions] +description: Replaces path separators with slashes (`/`) and splits the resulting path immediately following the final slash, separating it into a directory and file name component. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] - returnType: DirFile + related: + - functions/path/Base + - functions/path/BaseName + - functions/path/Clean + - functions/path/Dir + - functions/path/Ext + - functions/path/Join + returnType: paths.DirFile signatures: [path.Split PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.split] --- -`path.Split` splits `PATH` immediately following the final slash, separating it into a directory and a base component. - -The returned values have the property that `PATH` = `DIR`+`BASE`. -If there is no slash in `PATH`, it returns an empty directory and the base is set to `PATH`. - -**Note:** On Windows, `PATH` is converted to slash (`/`) separators. +If there is no slash in the given path, `path.Split` returns an empty directory, and file set to path. The returned values have the property that path = dir+file. ```go-html-template {{ $dirFile := path.Split "a/news.html" }} -{{ $dirFile.Dir }} → "a/" -{{ $dirFile.File }} → "news.html" +{{ $dirFile.Dir }} → a/ +{{ $dirFile.File }} → news.html {{ $dirFile := path.Split "news.html" }} -{{ $dirFile.Dir }} → "" -{{ $dirFile.File }} → "news.html" +{{ $dirFile.Dir }} → "" (empty string) +{{ $dirFile.File }} → news.html {{ $dirFile := path.Split "a/b/c" }} -{{ $dirFile.Dir }} → "a/b/" -{{ $dirFile.File }} → "c" +{{ $dirFile.Dir }} → a/b/ +{{ $dirFile.File }} → c ``` diff --git a/content/en/functions/path/_index.md b/content/en/functions/path/_index.md new file mode 100644 index 000000000..2d7ce8e90 --- /dev/null +++ b/content/en/functions/path/_index.md @@ -0,0 +1,12 @@ +--- +title: Path functions +linkTitle: path +description: Template functions to work with file paths. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with file paths. diff --git a/content/en/functions/reflect/IsMap.md b/content/en/functions/reflect/IsMap.md index 7d89bb38a..c2c441b5c 100644 --- a/content/en/functions/reflect/IsMap.md +++ b/content/en/functions/reflect/IsMap.md @@ -1,19 +1,14 @@ --- title: reflect.IsMap description: Reports whether the value is a map. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/reflect/IsSlice returnType: bool signatures: [reflect.IsMap INPUT] -namespace: reflect -relatedFunctions: - - reflect.IsMap - - reflect.IsSlice aliases: [/functions/reflect.ismap] --- diff --git a/content/en/functions/reflect/IsSlice.md b/content/en/functions/reflect/IsSlice.md index 09bab7127..13ab6e519 100644 --- a/content/en/functions/reflect/IsSlice.md +++ b/content/en/functions/reflect/IsSlice.md @@ -1,19 +1,14 @@ --- title: reflect.IsSlice description: Reports whether the value is a slice. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/reflect/IsMap returnType: bool signatures: [reflect.IsSlice INPUT] -namespace: reflect -relatedFunctions: - - reflect.IsMap - - reflect.IsSlice aliases: [/functions/reflect.isslice] --- diff --git a/content/en/functions/reflect/_index.md b/content/en/functions/reflect/_index.md new file mode 100644 index 000000000..711908ee2 --- /dev/null +++ b/content/en/functions/reflect/_index.md @@ -0,0 +1,12 @@ +--- +title: Reflect functions +linkTitle: reflect +description: Template functions to determine a value's data type. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to determine a value's data type. diff --git a/content/en/functions/resources/Babel.md b/content/en/functions/resources/Babel.md new file mode 100644 index 000000000..57ddb7d23 --- /dev/null +++ b/content/en/functions/resources/Babel.md @@ -0,0 +1,88 @@ +--- +title: resources.Babel +description: Compiles the given JavaScript resource with Babel. +categories: [] +keywords: [] +action: + aliases: [babel] + related: + - functions/js/Build + - functions/resources/Fingerprint + - functions/resources/Minify + returnType: resource.Resource + signatures: ['resources.Babel [OPTIONS] RESOURCE'] +toc: true +--- + +```go-html-template +{{ with resources.Get "js/main.js" }} + {{ if hugo.IsDevelopment }} + {{ with . | babel }} + + {{ end }} + {{ else }} + {{ $opts := dict "minified" true }} + {{ with . | babel $opts | fingerprint }} + + {{ end }} + {{ end }} +{{ end }} +``` + +## Setup + +Step 1 +: Install [Node.js](https://nodejs.org/en/download) + +Step 2 +: Install the required Node.js packages in the root of your project. + +```sh +npm install --save-dev @babel/core @babel/cli +``` + +Step 3 +: Add the babel executable to Hugo's `security.exec.allow` list in your site configuration: + +{{< code-toggle file=hugo >}} +[security.exec] + allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^babel$'] +{{< /code-toggle >}} + +## Configuration + +We add the main project's `node_modules` to `NODE_PATH` when running Babel and similar tools. There are some known [issues](https://github.com/babel/babel/issues/5618) with Babel in this area, so if you have a `babel.config.js` living in a Hugo Module (and not in the project itself), we recommend using `require` to load the presets/plugins, e.g.: + +```js +module.exports = { + presets: [ + [ + require("@babel/preset-env"), + { + useBuiltIns: "entry", + corejs: 3, + }, + ], + ], +}; +``` + +## Options + +config +: (`string`) Path to the Babel configuration file. Hugo will, by default, look for a `babel.config.js` in your project. More information on these configuration files can be found here: [babel configuration](https://babeljs.io/docs/en/configuration). + +minified +: (`bool`) Save as many bytes as possible when printing + +noComments +: (`bool`) Write comments to generated output (true by default) + +compact +: (`bool`) Do not include superfluous whitespace characters and line terminators. Defaults to `auto` if not set. + +verbose +: (`bool`) Log everything + +sourceMap +: (`string`) Output `inline` or `external` sourcemap from the babel compile. External sourcemaps will be written to the target with the output file name + ".map". Input sourcemaps can be read from js.Build and node modules and combined into the output sourcemaps. diff --git a/content/en/functions/resources/ByType.md b/content/en/functions/resources/ByType.md new file mode 100644 index 000000000..a5df3befb --- /dev/null +++ b/content/en/functions/resources/ByType.md @@ -0,0 +1,34 @@ +--- +title: resources.ByType +description: Returns a collection of global resources of the given media type, or nil if none found. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/Get + - functions/resources/GetMatch + - functions/resources/GetRemote + - functions/resources/Match + - methods/page/Resources + returnType: resource.Resources + signatures: [resources.ByType MEDIATYPE] +--- + +The [media type] is typically one of `image`, `text`, `audio`, `video`, or `application`. + +```go-html-template +{{ range resources.ByType "image" }} + +{{ end }} +``` + +{{% note %}} +This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. + +For page resources, use the [`Resources.ByType`] method on the Page object. + +[`Resources.ByType`]: /methods/page/resources +{{% /note %}} + +[media type]: https://en.wikipedia.org/wiki/Media_type diff --git a/content/en/functions/resources/Concat.md b/content/en/functions/resources/Concat.md new file mode 100644 index 000000000..3bdf975bf --- /dev/null +++ b/content/en/functions/resources/Concat.md @@ -0,0 +1,21 @@ +--- +title: resources.Concat +description: Concatenates a slice of resources. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: resource.Resource + signatures: ['resources.Concat TARGETPATH [RESOURCE...]'] +--- + +```go-html-template +{{ $plugins := resources.Get "js/plugins.js" }} +{{ $global := resources.Get "js/global.js" }} +{{ $js := slice $plugins $global | resources.Concat "js/bundle.js" }} +``` + +Asset files of the same [media type] can be bundled into one resource using the `resources.Concat` function which takes two arguments, the target path for the created resource bundle and a slice of resource objects to be concatenated. + +[media type]: https://en.wikipedia.org/wiki/Media_type diff --git a/content/en/functions/resources/Copy.md b/content/en/functions/resources/Copy.md new file mode 100644 index 000000000..9df88b0a0 --- /dev/null +++ b/content/en/functions/resources/Copy.md @@ -0,0 +1,30 @@ +--- +title: resources.Copy +description: Copies the given resource to the target path. +categories: [] +action: + aliases: [] + related: [] + returnType: resource.Resource + signatures: [resources.Copy TARGETPATH RESOURCE] +--- + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with resources.Copy "img/new-image-name.jpg" . }} + + {{ end }} +{{ end }} +``` + +The relative URL of the new published resource will be: + +```text +/img/new-image-name.jpg +``` + +The target path must be different than the source path, as shown in the example above. + +{{% note %}} +Use the `resources.Copy` function with global, page, and remote resources. +{{% /note %}} diff --git a/content/en/functions/resources/ExecuteAsTemplate.md b/content/en/functions/resources/ExecuteAsTemplate.md new file mode 100644 index 000000000..815cbe490 --- /dev/null +++ b/content/en/functions/resources/ExecuteAsTemplate.md @@ -0,0 +1,56 @@ +--- +title: resources.ExecuteAsTemplate +description: Creates a resource from a Go template, parsed and executed with the given context. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/FromString + returnType: resource.Resource + signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE] +--- + +Hugo publishes the resource to the target path when you call its`.Publish`, `.Permalink`, or `.RelPermalink` method. The resource is cached, using the target path as the cache key. + +Let's say you have a CSS file that you wish to populate with values from your site configuration: + +{{< code lang=go-html-template file=assets/css/template.css >}} +body { + background-color: {{ site.Params.style.bg_color }}; + color: {{ site.Params.style.text_color }}; +} +{{< /code >}} + +And your site configuration contains: + +{{< code-toggle file=hugo >}} +[params.style] +bg_color = '#fefefe' +text_color = '#222' +{{< /code-toggle >}} + +Place this in your baseof.html template: + +```go-html-template +{{ with resources.Get "css/template.css" }} + {{ with resources.ExecuteAsTemplate "css/main.css" $ . }} + + {{ end }} +{{ end }} +``` + +The example above: + +1. Captures the template as a resource +2. Executes the resource as a template, passing the current page in context +3. Publishes the resource to css/main.css + +The result is: + +{{< code file="public/css/main.css" >}} +body { + background-color: #fefefe; + color: #222; +} +{{< /code >}} diff --git a/content/en/functions/resources/Fingerprint.md b/content/en/functions/resources/Fingerprint.md new file mode 100644 index 000000000..685214f96 --- /dev/null +++ b/content/en/functions/resources/Fingerprint.md @@ -0,0 +1,42 @@ +--- +title: resources.Fingerprint +description: Cryptographically hashes the content of the given resource. +categories: [] +keywords: [] +action: + aliases: [fingerprint] + related: + - functions/js/Build + - functions/resources/Babel + - functions/resources/Minify + - functions/resources/PostCSS + - functions/resources/PostProcess + - functions/resources/ToCSS + returnType: resource.Resource + signatures: ['resources.Fingerprint [ALGORITHM] RESOURCE'] +--- + +```go-html-template +{{ with resources.Get "js/main.js" }} + {{ with . | fingerprint "sha256" }} + + {{ end }} +{{ end }} +``` + +Hugo renders this to something like: + +```html + +``` + +Although most commonly used with CSS and JavaScript resources, you can use the `resources.Fingerprint` function with any resource type. + +The hash algorithm may be one of `md5`, `sha256` (default), `sha384`, or `sha512`. + +After cryptographically hashing the resource content: + +1. The values returned by the `.Permalink` and `.RelPermalink` methods include the hash sum +2. The resource's `.Data.Integrity` method returns a [Subresource Integrity] (SRI) value consisting of the name of the hash algorithm, one hyphen, and the base64-encoded hash sum + +[Subresource Integrity]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity diff --git a/content/en/functions/resources/FromString.md b/content/en/functions/resources/FromString.md new file mode 100644 index 000000000..6c22b5310 --- /dev/null +++ b/content/en/functions/resources/FromString.md @@ -0,0 +1,71 @@ +--- +title: resources.FromString +description: Creates a resource from a string. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/ExecuteAsTemplate + returnType: resource.Resource + signatures: [resources.FromString TARGETPATH STRING] +--- + +Hugo publishes the resource to the target path when you call its`.Publish`, `.Permalink`, or `.RelPermalink` method. The resource is cached, using the target path as the cache key. + +Let's say you need to publish a file named "site.json" in the root of your public directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example: + +```json +{ + "build_date": "2023-10-03T10:50:40-07:00", + "hugo_version": "0.120.0", + "last_modified": "2023-10-02T15:21:27-07:00" +} +``` + +Place this in your baseof.html template: + +```go-html-template +{{ if .IsHome }} + {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }} + {{ $m := dict + "hugo_version" hugo.Version + "build_date" (now.Format $rfc3339) + "last_modified" (site.LastChange.Format $rfc3339) + }} + {{ $json := jsonify $m }} + {{ $r := resources.FromString "site.json" $json }} + {{ $r.Publish }} +{{ end }} +``` + +The example above: + +1. Creates a map with the relevant key/value pairs using the [`dict`] function +2. Encodes the map as a JSON string using the [`jsonify`] function +3. Creates a resource from the JSON string using the `resources.FromString` function +4. Publishes the file to the root of the public directory using the resource's `.Publish` method + +Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your string contains template actions. Rewriting the example above: + +```go-html-template +{{ if .IsHome }} + {{ $string := ` + {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }} + {{ $m := dict + "hugo_version" hugo.Version + "build_date" (now.Format $rfc3339) + "last_modified" (site.LastChange.Format $rfc3339) + }} + {{ $json := jsonify $m }} + ` + }} + {{ $r := resources.FromString "" $string }} + {{ $r = $r | resources.ExecuteAsTemplate "site.json" . }} + {{ $r.Publish }} +{{ end }} +``` + +[`dict`]: /functions/collections/dictionary +[`jsonify`]: /functions/encoding/jsonify +[`resources.ExecuteAsTemplate`]: /functions/resources/executeastemplate diff --git a/content/en/functions/resources/Get.md b/content/en/functions/resources/Get.md new file mode 100644 index 000000000..a8b75d52b --- /dev/null +++ b/content/en/functions/resources/Get.md @@ -0,0 +1,30 @@ +--- +title: resources.Get +description: Returns a global resource from the given path, or nil if none found. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/ByType + - functions/resources/GetMatch + - functions/resources/GetRemote + - functions/resources/Match + - methods/page/Resources + returnType: resource.Resource + signatures: [resources.Get PATH] +--- + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + +{{ end }} +``` + +{{% note %}} +This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. + +For page resources, use the [`Resources.Get`] method on the Page object. + +[`Resources.Get`]: /methods/page/resources +{{% /note %}} diff --git a/content/en/functions/resources/GetMatch.md b/content/en/functions/resources/GetMatch.md new file mode 100644 index 000000000..fde26c09d --- /dev/null +++ b/content/en/functions/resources/GetMatch.md @@ -0,0 +1,36 @@ +--- +title: resources.GetMatch +description: Returns the first global resource from paths matching the given glob pattern, or nil if none found. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/ByType + - functions/resources/Get + - functions/resources/GetRemote + - functions/resources/Match + - methods/page/Resources + returnType: resource.Resource + signatures: [resources.GetMatch PATTERN] +--- + +```go-html-template +{{ with resources.GetMatch "images/*.jpg" }} + +{{ end }} +``` + +{{% note %}} +This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. + +For page resources, use the [`Resources.GetMatch`] method on the Page object. + +[`Resources.GetMatch`]: /methods/page/resources +{{% /note %}} + +Hugo determines a match using a case-insensitive [glob pattern]. + +{{% include "functions/_common/glob-patterns.md" %}} + +[glob pattern]: https://github.com/gobwas/glob#example diff --git a/content/en/functions/resources/GetRemote.md b/content/en/functions/resources/GetRemote.md new file mode 100644 index 000000000..fdd639195 --- /dev/null +++ b/content/en/functions/resources/GetRemote.md @@ -0,0 +1,176 @@ +--- +title: resources.GetRemote +description: Returns a remote resource from the given URL, or nil if none found. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/data/GetCSV + - functions/data/GetJSON + - functions/resources/ByType + - functions/resources/Get + - functions/resources/GetMatch + - functions/resources/Match + - methods/page/Resources + returnType: resource.Resource + signatures: ['resources.GetRemote URL [OPTIONS]'] +toc: true +--- + +```go-html-template +{{ $url := "https://example.org/images/a.jpg" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +## Options + +The `resources.GetRemote` function takes an optional map of options. + +```go-html-template +{{ $url := "https://example.org/api" }} +{{ $opts := dict + "headers" (dict "Authorization" "Bearer abcd") +}} +{{ $resource := resources.GetRemote $url $opts }} +``` + +If you need multiple values for the same header key, use a slice: + +```go-html-template +{{ $url := "https://example.org/api" }} +{{ $opts := dict + "headers" (dict "X-List" (slice "a" "b" "c")) +}} +{{ $resource := resources.GetRemote $url $opts }} +``` + +You can also change the request method and set the request body: + +```go-html-template +{{ $url := "https://example.org/api" }} +{{ $opts := dict + "method" "post" + "body" `{"complete": true}` + "headers" (dict "Content-Type" "application/json") +}} +{{ $resource := resources.GetRemote $url $opts }} +``` + +## Remote data + +When retrieving remote data, use the [`transform.Unmarshal`] function to unmarshal the response to a map. + +[`transform.Unmarshal`]: /functions/transform/unmarshal + +```go-html-template +{{ $data := "" }} +{{ $url := "https://example.org/books.json" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ $data = . | transform.Unmarshal }} + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +## Error handling + +The [`Err`] method on a resource returned by the `resources.GetRemote` function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build. + +[`Err`]: /methods/resource/err + +```go-html-template +{{ $url := "https://broken-example.org/images/a.jpg" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +To log an error as a warning instead of an error: + +```go-html-template +{{ $url := "https://broken-example.org/images/a.jpg" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ warnf "%s" . }} + {{ else }} + + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +## HTTP response + +The [`Data`] method on a resource returned by the `resources.GetRemote` function returns information from the HTTP response. + +[`Data`]: /methods/resource/data + +```go-html-template +{{ $url := "https://example.org/images/a.jpg" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ with .Data }} + {{ .ContentLength }} → 42764 + {{ .ContentType }} → image/jpeg + {{ .Status }} → 200 OK + {{ .StatusCode }} → 200 + {{ .TransferEncoding }} → [] + {{ end }} + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +ContentLength +: (`int`) The content length in bytes. + +ContentType +: (`string`) The content type. + +Status +: (`string`) The HTTP status text. + +StatusCode +: (`int`) The HTTP status code. + +TransferEncoding +: (`string`) The transfer encoding. + +## Caching + +Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches] for details. + +By default, Hugo derives the cache key from the arguments passed to the function, the URL and the options map, if any. + +Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource. + +```go-html-template +{{ $url := "https://example.org/images/a.jpg" }} +{{ $cacheKey := print $url (now.Format "2006-01-02") }} +{{ $resource := resource.GetRemote $url (dict "key" $cacheKey) }} +``` + +[configure file caches]: /getting-started/configuration/#configure-file-caches diff --git a/content/en/functions/resources/Match.md b/content/en/functions/resources/Match.md new file mode 100644 index 000000000..0044351f1 --- /dev/null +++ b/content/en/functions/resources/Match.md @@ -0,0 +1,36 @@ +--- +title: resources.Match +description: Returns a collection of global resources from paths matching the given glob pattern, or nil if none found. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/ByType + - functions/resources/Get + - functions/resources/GetMatch + - functions/resources/GetRemote + - methods/page/Resources + returnType: resource.Resources + signatures: [resources.Match PATTERN] +--- + +```go-html-template +{{ range resources.Match "images/*.jpg" }} + +{{ end }} +``` + +{{% note %}} +This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. + +For page resources, use the [`Resources.Match`] method on the Page object. + +[`Resources.Match`]: /methods/page/resources +{{% /note %}} + +Hugo determines a match using a case-insensitive [glob pattern]. + +{{% include "functions/_common/glob-patterns.md" %}} + +[glob pattern]: https://github.com/gobwas/glob#example diff --git a/content/en/functions/resources/Minify.md b/content/en/functions/resources/Minify.md new file mode 100644 index 000000000..44f5f990b --- /dev/null +++ b/content/en/functions/resources/Minify.md @@ -0,0 +1,23 @@ +--- +title: resources.Minify +description: Minifies the given resource. +categories: [] +keywords: [] +action: + aliases: [minify] + related: + - functions/js/Build + - functions/resources/Babel + - functions/resources/Fingerprint + - functions/resources/PostCSS + - functions/resources/ToCSS + returnType: resource.Resource + signatures: [resources.Minify RESOURCE] +--- + +```go-html-template +{{ $css := resources.Get "css/main.css" }} +{{ $style := $css | minify }} +``` + +Any CSS, JS, JSON, HTML, SVG or XML resource can be minified using resources.Minify which takes for argument the resource object. diff --git a/content/en/functions/resources/PostCSS.md b/content/en/functions/resources/PostCSS.md new file mode 100644 index 000000000..a9f9ed3c8 --- /dev/null +++ b/content/en/functions/resources/PostCSS.md @@ -0,0 +1,129 @@ +--- +title: resources.PostCSS +description: Processes the given resource with PostCSS using any PostCSS plugin. +categories: [] +keywords: [] +action: + aliases: [postCSS] + related: + - functions/resources/Fingerprint + - functions/resources/Minify + - functions/resources/PostProcess + - functions/resources/ToCSS + returnType: resource.Resource + signatures: ['resources.PostCSS [OPTIONS] RESOURCE'] +toc: true +--- + +```go-html-template +{{ with resources.Get "css/main.css" | postCSS }} + +{{ end }} +``` + +## Setup + +Follow the steps below to transform CSS using any of the available [PostCSS plugins]. + +Step 1 +: Install [Node.js]. + +Step 2 +: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules: + +```sh +npm i -D postcss postcss-cli autoprefixer +``` + +Step 3 +: Create a PostCSS configuration file in the root of your project. You must name this file `postcss.config.js` or another [supported file name]. For example: + +```js +module.exports = { + plugins: [ + require('autoprefixer') + ] +}; +``` + +{{% note %}} +{{% include "functions/resources/_common/postcss-windows-warning.md" %}} +{{% /note %}} + +Step 4 +: Place your CSS file within the `assets/css` directory. + +Step 5 +: Process the resource with PostCSS: + +```go-html-template +{{ with resources.Get "css/main.css" | postCSS }} + +{{ end }} +``` + +## Options + +The `resources.PostCSS` method takes an optional map of options. + +config +: (`string`) The directory that contains the PostCSS configuration file. Default is the root of the project directory. + +noMap +: (`bool`) Default is `false`. If `true`, disables inline sourcemaps. + +inlineImports +: (`bool`) Default is `false`. Enable inlining of @import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides. + +skipInlineImportsNotFound +: (`bool`) Default is `false`. Before Hugo 0.99.0 when `inlineImports` was enabled and we failed to resolve an import, we logged it as a warning. We now fail the build. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set `skipInlineImportsNotFound` to true. + +```go-html-template +{{ $opts := dict "config" "config-directory" "noMap" true }} +{{ with resources.Get "css/main.css" | postCSS $opts }} + +{{ end }} +``` + +## No configuration file + +To avoid using a PostCSS configuration file, you can specify a minimal configuration using the options map. + +use +: (`string`) A space-delimited list of PostCSS plugins to use. + +parser +: (`string`) A custom PostCSS parser. + +stringifier +: (`string`) A custom PostCSS stringifier. + +syntax +: (`string`) Custom postcss syntax. + +```go-html-template +{{ $opts := dict "use" "autoprefixer postcss-color-alpha" }} +{{ with resources.Get "css/main.css" | postCSS $opts }} + +{{ end }} +``` + +## Check environment + +The current Hugo environment name (set by `--environment` or in configuration or OS environment) is available in the Node context, which allows constructs like this: + +```js +const autoprefixer = require('autoprefixer'); +const purgecss = require('@fullhuman/postcss-purgecss'); +module.exports = { + plugins: [ + autoprefixer, + process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null + ] +} +``` + +[node.js]: https://nodejs.org/en/download +[postcss plugins]: https://www.postcss.parts/ +[supported file name]: https://github.com/postcss/postcss-load-config#usage +[transpile to CSS]: /functions/resources/tocss.md diff --git a/content/en/functions/resources/PostProcess.md b/content/en/functions/resources/PostProcess.md new file mode 100644 index 000000000..f765ea9af --- /dev/null +++ b/content/en/functions/resources/PostProcess.md @@ -0,0 +1,160 @@ +--- +title: resources.PostProcess +description: Processes the given resource after the build. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/Fingerprint + - functions/resources/Minify + - functions/resources/PostCSS + - functions/resources/ToCSS + returnType: postpub.PostPublishedResource + signatures: [resources.PostProcess RESOURCE] +toc: true +--- + +```go-html-template +{{ with resources.Get "css/main.css" }} + {{ if hugo.IsDevelopment }} + + {{ else }} + {{ with . | postCSS | minify | fingerprint | resources.PostProcess }} + + {{ end }} + {{ end }} +{{ end }} +``` + +Marking a resource with `resources.PostProcess` postpones transformations until the build has finished. + +Call `resources.PostProcess` when one or more of the steps in the transformation chain depends on the result of the build. + +A prime use case for this is purging unused CSS rules using the [PurgeCSS] plugin for the PostCSS Node.js package. + +## CSS Purging + +{{% note %}} +There are several ways to set up CSS purging with PostCSS in Hugo. If you have a simple project, you should consider going the simpler route and drop the use of `resources.PostProcess` and just extract keywords from the templates. See the [Tailwind documentation](https://tailwindcss.com/docs/controlling-file-size/#app) for examples. +{{% /note %}} + +Step 1 +: Install [Node.js]. + +Step 2 +: Install the required Node.js packages in the root of your project: + +```sh +npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss +``` + +Step 3 +: Create a PostCSS configuration file in the root of your project. You must name this file `postcss.config.js` or another [supported file name]. For example: + +```js +const autoprefixer = require('autoprefixer'); +const purgecss = require('@fullhuman/postcss-purgecss')({ + content: ['./hugo_stats.json'], + defaultExtractor: content => { + const els = JSON.parse(content).htmlElements; + return [ + ...(els.tags || []), + ...(els.classes || []), + ...(els.ids || []), + ]; + }, + // https://purgecss.com/safelisting.html + safelist: [] +}); + +module.exports = { + plugins: [ + autoprefixer, + process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null + ] +}; +``` + +{{% note %}} +{{% include "functions/resources/_common/postcss-windows-warning.md" %}} +{{% /note %}} + +Step 4 +: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [config/production]. + +{{< code-toggle file=hugo >}} +[build.buildStats] +enable = true +{{< /code-toggle >}} + +See the [configure build] documentation for details and options. + +Step 5 +: Place your CSS file within the `assets/css` directory. + +Step 6 +: If the current environment is not `development`, process the resource with PostCSS: + +```go-html-template +{{ with resources.Get "css/main.css" }} + {{ if hugo.IsDevelopment }} + + {{ else }} + {{ with . | postCSS | minify | fingerprint | resources.PostProcess }} + + {{ end }} + {{ end }} +{{ end }} +``` + +## Environment variables + +Hugo passes these environment variables to PostCSS, which allows you to do something like: + +```js +process.env.HUGO_ENVIRONMENT === 'production' ? [autoprefixer] : [] +``` + +PWD +: The absolute path to the project working directory. + +HUGO_ENVIRONMENT +: The current Hugo environment, set with the `--environment` command line flag. +Default is `production` for `hugo` and `development` for `hugo server`. + +HUGO_PUBLISHDIR +: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this folder from PostCSS when running the server, you could run the server with one of these flags: + +```sh +hugo server --renderToDisk +hugo server --renderStaticToDisk +``` + +Also, Hugo will add environment variables for all files mounted below `assets/_jsconfig`. A default mount will be set up with files in the project root matching this regexp: `(babel|postcss|tailwind)\.config\.js`. + +These will get environment variables named on the form `HUGO_FILE_:filename:` where `:filename:` is all upper case with periods replaced with underscore. This allows you to do something like: + +```js +let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.js'; +``` + +## Limitations + +Do not use `resources.PostProcess` when running Hugo's built-in development server. The examples above specifically prevent this by verifying that the current environment is not "development". + +The `resources.PostProcess` function only works within templates that produce HTML files. + +You cannot manipulate the values returned from the resource’s methods. For example, the `strings.ToUpper` function in this example will not work as expected: + +```go-html-template +{{ $css := resources.Get "css/main.css" }} +{{ $css = $css | resources.PostCSS | minify | fingerprint | resources.PostProcess }} +{{ $css.RelPermalink | strings.ToUpper }} +``` + +[node.js]: https://nodejs.org/en/download +[supported file name]: https://github.com/postcss/postcss-load-config#usage +[config/production]: /getting-started/configuration/#configuration-directory +[configure build]: /getting-started/configuration/#configure-build +[purgecss]: https://github.com/FullHuman/purgecss#readme diff --git a/content/en/functions/resources/ToCSS.md b/content/en/functions/resources/ToCSS.md new file mode 100644 index 000000000..872bf996b --- /dev/null +++ b/content/en/functions/resources/ToCSS.md @@ -0,0 +1,224 @@ +--- +title: resources.ToCSS +description: Transpiles Sass to CSS. +categories: [] +keywords: [] +action: + aliases: [toCSS] + related: + - functions/resources/Fingerprint + - functions/resources/Minify + - functions/resources/PostCSS + - functions/resources/PostProcess + returnType: resource.Resource + signatures: ['resources.ToCSS [OPTIONS] RESOURCE'] +toc: true +--- + +```go-html-template +{{ with resources.Get "sass/main.scss" }} + {{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }} + {{ with . | toCSS $opts }} + {{ if hugo.IsDevelopment }} + + {{ else }} + {{ with . | minify | fingerprint }} + + {{ end }} + {{ end }} + {{ end }} +{{ end }} +``` + +Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended edition, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language. + +Sass has two forms of syntax: [SCSS] and [indented]. Hugo supports both. + +[scss]: https://sass-lang.com/documentation/syntax#scss +[indented]: https://sass-lang.com/documentation/syntax#the-indented-syntax + +## Options + +transpiler +: (`string`) The transpiler to use, either `libsass` (default) or `dartsass`. Hugo's extended edition includes the LibSass transpiler. To use the Dart Sass transpiler, see the [installation instructions](#dart-sass) below. + +targetPath +: (`string`) If not set, the transformed resource's target path will be the original path of the asset file with its extension replaced by `.css`. + +vars +: (`map`) A map of key/value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/). + +```scss +// LibSass +@import "hugo:vars"; + +// Dart Sass +@use "hugo:vars" as v; +``` + +outputStyle +: (`string`) Output styles available to LibSass include `nested` (default), `expanded`, `compact`, and `compressed`. Output styles available to Dart Sass include `expanded` (default) and `compressed`. + +precision +: (`int`) Precision of floating point math. Not applicable to Dart Sass. + +enableSourceMap +: (`bool`) If `true`, generates a source map. + +sourceMapIncludeSources +: (`bool`) If `true`, embeds sources in the generated source map. Not applicable to LibSass. + +includePaths +: (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements. + +```go-html-template +{{ $opts := dict + "transpiler" "dartsass" + "targetPath" "css/style.css" + "vars" site.Params.styles + "enableSourceMap" (not hugo.IsProduction) + "includePaths" (slice "node_modules/bootstrap/scss") +}} +{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }} + +{{ end }} +``` + +## Dart Sass + +The extended version of Hugo includes [LibSass] to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of [Dart Sass]. + +Use the latest features of the Sass language by installing Dart Sass in your development and production environments. + +### Installation overview + +Dart Sass is compatible with Hugo v0.114.0 and later. + +If you have been using Embedded Dart Sass[^1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass. + +If you install Hugo as a [Snap package] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass. + +[^1]: In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass. + +### Installing in a development environment + +When you install Dart Sass somewhere in your PATH, Hugo will find it. + +OS|Package manager|Site|Installation +:--|:--|:--|:-- +Linux|Homebrew|[brew.sh]|`brew install sass/sass/sass` +Linux|Snap|[snapcraft.io]|`sudo snap install dart-sass` +macOS|Homebrew|[brew.sh]|`brew install sass/sass/sass` +Windows|Chocolatey|[chocolatey.org]|`choco install sass` +Windows|Scoop|[scoop.sh]|`scoop install sass` + +You may also install [prebuilt binaries] for Linux, macOS, and Windows. + +Run `hugo env` to list the active transpilers. + +### Installing in a production environment + +For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries. + +[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your resources directory to your repository. + +#### GitHub Pages + +To install Dart Sass for your builds on GitHub Pages, add this step to the GitHub Pages workflow file: + +```yaml +- name: Install Dart Sass + run: sudo snap install dart-sass +``` + +If you are using GitHub Pages for the first time with your repository, GitHub provides a [starter workflow] for Hugo that includes Dart Sass. This is the simplest way to get started. + +#### GitLab Pages + +To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file should look something like this: + +```yaml +variables: + HUGO_VERSION: 0.115.1 + DART_SASS_VERSION: 1.63.6 + GIT_DEPTH: 0 + GIT_STRATEGY: clone + GIT_SUBMODULE_STRATEGY: recursive + TZ: America/Los_Angeles +image: + name: golang:1.20-buster +pages: + script: + # Install Dart Sass + - curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz + - tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz + - cp -r dart-sass/* /usr/local/bin + - rm -rf dart-sass* + # Install Hugo + - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb + - apt install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb + - rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb + # Build + - hugo --gc --minify + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH +``` + +#### Netlify + +To install Dart Sass for your builds on Netlify, the `netlify.toml` file should look something like this: + +```toml +[build.environment] +HUGO_VERSION = "0.115.1" +DART_SASS_VERSION = "1.63.6" +TZ = "America/Los_Angeles" + +[build] +publish = "public" +command = """\ + curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \ + tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \ + rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \ + export PATH=/opt/build/repo/dart-sass:$PATH && \ + hugo --gc --minify \ + """ +``` + +### Example + +To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `resources.ToCSS`. For example: + +```go-html-template +{{ with resources.Get "sass/main.scss" }} + {{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }} + {{ with . | toCSS $opts }} + {{ if hugo.IsDevelopment }} + + {{ else }} + {{ with . | minify | fingerprint }} + + {{ end }} + {{ end }} + {{ end }} +{{ end }} +``` + +### Miscellaneous + +If you build Hugo from source and run `mage test -v`, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package's strict confinement model. + +[brew.sh]: https://brew.sh/ +[chocolatey.org]: https://community.chocolatey.org/packages/sass +[ci/cd]: https://en.wikipedia.org/wiki/CI/CD +[dart sass]: https://sass-lang.com/dart-sass +[libsass]: https://sass-lang.com/libsass +[prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest +[scoop.sh]: https://scoop.sh/#/apps?q=sass +[site configuration]: /getting-started/configuration/#configure-build +[snap package]: /installation/linux/#snap +[snapcraft.io]: https://snapcraft.io/dart-sass +[starter workflow]: https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml diff --git a/content/en/functions/resources/_common/_index.md b/content/en/functions/resources/_common/_index.md new file mode 100644 index 000000000..b57b688b3 --- /dev/null +++ b/content/en/functions/resources/_common/_index.md @@ -0,0 +1,12 @@ +--- +_build: + list: never + publishResources: false + render: never +--- + + diff --git a/content/en/functions/resources/_common/postcss-windows-warning.md b/content/en/functions/resources/_common/postcss-windows-warning.md new file mode 100644 index 000000000..1b72e74db --- /dev/null +++ b/content/en/functions/resources/_common/postcss-windows-warning.md @@ -0,0 +1,8 @@ +--- +# Do not remove front matter. +--- + +If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333]. + +[this example]: https://github.com/postcss/postcss-load-config#packagejson +[#7333]: https://github.com/gohugoio/hugo/issues/7333 diff --git a/content/en/functions/resources/_index.md b/content/en/functions/resources/_index.md new file mode 100644 index 000000000..364b9448d --- /dev/null +++ b/content/en/functions/resources/_index.md @@ -0,0 +1,12 @@ +--- +title: Resource functions +linkTitle: resources +description: Template functions to work with resources. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with resources. diff --git a/content/en/functions/safe/CSS.md b/content/en/functions/safe/CSS.md index d5dcdfb66..dc0539bde 100644 --- a/content/en/functions/safe/CSS.md +++ b/content/en/functions/safe/CSS.md @@ -1,23 +1,18 @@ --- title: safe.CSS -linkTitle: safeCSS -description: Declares the provided string as a known "safe" CSS string. -categories: [functions] +description: Declares the provided string as safe CSS string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeCSS] + related: + - functions/safe/HTML + - functions/safe/HTMLAttr + - functions/safe/JS + - functions/safe/JSStr + - functions/safe/URL returnType: template.CSS signatures: [safe.CSS INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safecss] --- diff --git a/content/en/functions/safe/HTML.md b/content/en/functions/safe/HTML.md index ea3afe8f3..3cfb6ebdc 100644 --- a/content/en/functions/safe/HTML.md +++ b/content/en/functions/safe/HTML.md @@ -1,23 +1,18 @@ --- title: safe.HTML -linkTitle: safeHTML -description: Declares a provided string as a "safe" HTML document to avoid escaping by Go templates. -categories: [functions] +description: Declares a provided string as a safeHTML string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeHTML] + related: + - functions/safe/CSS + - functions/safe/HTMLAttr + - functions/safe/JS + - functions/safe/JSStr + - functions/safe/URL returnType: template.HTML signatures: [safe.HTML INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safehtml] --- @@ -25,7 +20,7 @@ It should not be used for HTML from a third-party, or HTML with unclosed tags or Given a site-wide [`hugo.toml`][config] with the following `copyright` value: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} copyright = "© 2015 Jane Doe. Some rights reserved." {{< /code-toggle >}} diff --git a/content/en/functions/safe/HTMLAttr.md b/content/en/functions/safe/HTMLAttr.md index 7d1b06c47..1ac8b294e 100644 --- a/content/en/functions/safe/HTMLAttr.md +++ b/content/en/functions/safe/HTMLAttr.md @@ -1,29 +1,24 @@ --- title: safe.HTMLAttr -linkTitle: safeHTMLAttr description: Declares the provided string as a safe HTML attribute. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeHTMLAttr] + related: + - functions/safe/CSS + - functions/safe/HTML + - functions/safe/JS + - functions/safe/JSStr + - functions/safe/URL returnType: template.HTMLAttr signatures: [safe.HTMLAttr INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safehtmlattr] --- Given a site configuration that contains this menu entry: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [[menu.main]] name = "IRC" url = "irc://irc.freenode.net/#golang" @@ -35,7 +30,7 @@ Attempting to use the `url` value directly in an attribute: {{ range site.Menus.main }} {{ .Name }} {{ end }} -``` +``` Will produce: diff --git a/content/en/functions/safe/JS.md b/content/en/functions/safe/JS.md index e679b5f85..a33e19f0f 100644 --- a/content/en/functions/safe/JS.md +++ b/content/en/functions/safe/JS.md @@ -1,23 +1,18 @@ --- title: safe.JS -linkTitle: safeJS -description: Declares the provided string as a known safe JavaScript string. -categories: [functions] +description: Declares the provided string as a safe JavaScript string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeJS] + related: + - functions/safe/CSS + - functions/safe/HTML + - functions/safe/HTMLAttr + - functions/safe/JSStr + - functions/safe/URL returnType: template.JS signatures: [safe.JS INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safejs] --- diff --git a/content/en/functions/safe/JSStr.md b/content/en/functions/safe/JSStr.md index 790de3a73..762d2a0df 100644 --- a/content/en/functions/safe/JSStr.md +++ b/content/en/functions/safe/JSStr.md @@ -1,23 +1,18 @@ --- title: safe.JSStr -linkTitle: safeJSStr description: Declares the provided string as a known safe JavaScript string. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeJSStr] + related: + - functions/safe/CSS + - functions/safe/HTML + - functions/safe/HTMLAttr + - functions/safe/JS + - functions/safe/URL returnType: template.JSStr signatures: [safe.JSStr INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safejsstr] --- @@ -34,7 +29,6 @@ Without declaring a variable to be a safe JavaScript string: Rendered: - ```html + + {{ end }} + ... + +{{< /code >}} diff --git a/content/en/methods/page/HeadingsFiltered.md b/content/en/methods/page/HeadingsFiltered.md new file mode 100644 index 000000000..a39c48da1 --- /dev/null +++ b/content/en/methods/page/HeadingsFiltered.md @@ -0,0 +1,18 @@ +--- +title: HeadingsFiltered +description: Returns a slice of headings for each page related to the given page. +categories: [] +keywords: [] +action: + related: + - methods/pages/Related + - methods/page/Fragments + returnType: tableofcontents.Headings + signatures: [PAGE.HeadingsFiltered] +--- + +Use in conjunction with the [`Related`] method on a [`Pages`] object. See [details]. + +[`Pages`]: /methods/pages/ +[`Related`]: /methods/pages/related +[details]: /content-management/related/#index-content-headings-in-related-content diff --git a/content/en/methods/page/InSection.md b/content/en/methods/page/InSection.md new file mode 100644 index 000000000..b98fbc808 --- /dev/null +++ b/content/en/methods/page/InSection.md @@ -0,0 +1,102 @@ +--- +title: InSection +description: Reports whether the given page is in the given section. +categories: [] +keywords: [] +action: + related: + - methods/page/Ancestors + - methods/page/CurrentSection + - methods/page/FirstSection + - methods/page/IsAncestor + - methods/page/IsDescendant + - methods/page/Parent + - methods/page/Sections + returnType: bool + signatures: [PAGE.InSection SECTION] +toc: true +--- + +The `InSection` method on a page object reports whether the given page is in the given section. Note that the method returns `true` when comparing a page to a sibling. + +{{% include "methods/page/_common/definition-of-section.md" %}} + +With this content structure: + +```text +content/ +├── auctions/ +│ ├── 2023-11/ +│ │ ├── _index.md +│ │ ├── auction-1.md +│ │ └── auction-2.md +│ ├── 2023-12/ +│ │ ├── _index.md +│ │ ├── auction-3.md +│ │ └── auction-4.md +│ ├── _index.md +│ ├── bidding.md +│ └── payment.md +└── _index.md +``` + +When rendering the "auction-1" page: + +```go-html-template +{{ with .Site.GetPage "/" }} + {{ $.InSection . }} → false +{{ end }} + +{{ with .Site.GetPage "/auctions" }} + {{ $.InSection . }} → false +{{ end }} + +{{ with .Site.GetPage "/auctions/2023-11" }} + {{ $.InSection . }} → true +{{ end }} + +{{ with .Site.GetPage "/auctions/2023-11/auction-2" }} + {{ $.InSection . }} → true +{{ end }} +``` + +In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting: + +```go-html-template +{{ $path := "/auctions/2023-11" }} +{{ with .Site.GetPage $path }} + {{ $.InSection . }} → true +{{ else }} + {{ errorf "Unable to find the section with path %s" $path }} +{{ end }} + ``` + +## Understanding context + +Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax: + +```go-html-template +{{ with .Site.GetPage "/auctions" }} + {{ .InSection . }} → true +{{ end }} +``` + +The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. + +{{% note %}} +Use the `$` to get the context passed into the template. +{{% /note %}} + +```go-html-template +{{ with .Site.GetPage "/auctions" }} + {{ $.InSection . }} → true +{{ end }} +``` + +{{% note %}} +Gaining a thorough understanding of context is critical for anyone writing template code. +{{% /note %}} + +[context]: /getting-started/glossary/#context +[`with`]: /functions/go-template/with +[`else`]: /functions/go-template/else diff --git a/content/en/methods/page/IsAncestor.md b/content/en/methods/page/IsAncestor.md new file mode 100644 index 000000000..ca23c0868 --- /dev/null +++ b/content/en/methods/page/IsAncestor.md @@ -0,0 +1,100 @@ +--- +title: IsAncestor +description: Reports whether PAGE1 in an ancestor of PAGE2. +categories: [] +keywords: [] +action: + related: + - methods/page/Ancestors + - methods/page/CurrentSection + - methods/page/FirstSection + - methods/page/InSection + - methods/page/IsDescendant + - methods/page/Parent + - methods/page/Sections + returnType: bool + signatures: [PAGE1.IsAncestor PAGE2] +toc: true +--- + +{{% include "methods/page/_common/definition-of-section.md" %}} + +With this content structure: + +```text +content/ +├── auctions/ +│ ├── 2023-11/ +│ │ ├── _index.md +│ │ ├── auction-1.md +│ │ └── auction-2.md +│ ├── 2023-12/ +│ │ ├── _index.md +│ │ ├── auction-3.md +│ │ └── auction-4.md +│ ├── _index.md +│ ├── bidding.md +│ └── payment.md +└── _index.md +``` + +When rendering the "auctions" page: + +```go-html-template +{{ with .Site.GetPage "/" }} + {{ $.IsAncestor . }} → false +{{ end }} + +{{ with .Site.GetPage "/auctions" }} + {{ $.IsAncestor . }} → false +{{ end }} + +{{ with .Site.GetPage "/auctions/2023-11" }} + {{ $.IsAncestor . }} → true +{{ end }} + +{{ with .Site.GetPage "/auctions/2023-11/auction-2" }} + {{ $.IsAncestor . }} → true +{{ end }} +``` + +In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting: + +```go-html-template +{{ $path := "/auctions/2023-11" }} +{{ with .Site.GetPage $path }} + {{ $.IsAncestor . }} → true +{{ else }} + {{ errorf "Unable to find the section with path %s" $path }} +{{ end }} + ``` + +## Understanding context + +Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax: + +```go-html-template +{{ with .Site.GetPage "/auctions" }} + {{ .IsAncestor . }} → true +{{ end }} +``` + +The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. + +{{% note %}} +Use the `$` to get the context passed into the template. +{{% /note %}} + +```go-html-template +{{ with .Site.GetPage "/auctions" }} + {{ $.IsAncestor . }} → true +{{ end }} +``` + +{{% note %}} +Gaining a thorough understanding of context is critical for anyone writing template code. +{{% /note %}} + +[context]: /getting-started/glossary/#context +[`with`]: /functions/go-template/with +[`else`]: /functions/go-template/else diff --git a/content/en/methods/page/IsDescendant.md b/content/en/methods/page/IsDescendant.md new file mode 100644 index 000000000..f1042564e --- /dev/null +++ b/content/en/methods/page/IsDescendant.md @@ -0,0 +1,99 @@ +--- +title: IsDescendant +description: Reports whether PAGE1 in a descendant of PAGE2. +categories: [] +keywords: [] +action: + related: + - methods/page/Ancestors + - methods/page/CurrentSection + - methods/page/FirstSection + - methods/page/InSection + - methods/page/IsAncestor + - methods/page/Parent + - methods/page/Sections + returnType: bool + signatures: [PAGE1.IsDescendant PAGE2] +--- + +{{% include "methods/page/_common/definition-of-section.md" %}} + +With this content structure: + +```text +content/ +├── auctions/ +│ ├── 2023-11/ +│ │ ├── _index.md +│ │ ├── auction-1.md +│ │ └── auction-2.md +│ ├── 2023-12/ +│ │ ├── _index.md +│ │ ├── auction-3.md +│ │ └── auction-4.md +│ ├── _index.md +│ ├── bidding.md +│ └── payment.md +└── _index.md +``` + +When rendering the "auctions" page: + +```go-html-template +{{ with .Site.GetPage "/" }} + {{ $.IsDescendant . }} → true +{{ end }} + +{{ with .Site.GetPage "/auctions" }} + {{ $.IsDescendant . }} → false +{{ end }} + +{{ with .Site.GetPage "/auctions/2023-11" }} + {{ $.IsDescendant . }} → false +{{ end }} + +{{ with .Site.GetPage "/auctions/2023-11/auction-2" }} + {{ $.IsDescendant . }} → false +{{ end }} +``` + +In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting: + +```go-html-template +{{ $path := "/auctions/2023-11" }} +{{ with .Site.GetPage $path }} + {{ $.IsDescendant . }} → true +{{ else }} + {{ errorf "Unable to find the section with path %s" $path }} +{{ end }} + ``` + +## Understanding context + +Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax: + +```go-html-template +{{ with .Site.GetPage "/auctions" }} + {{ .IsDescendant . }} → true +{{ end }} +``` + +The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. + +{{% note %}} +Use the `$` to get the context passed into the template. +{{% /note %}} + +```go-html-template +{{ with .Site.GetPage "/auctions" }} + {{ $.IsDescendant . }} → true +{{ end }} +``` + +{{% note %}} +Gaining a thorough understanding of context is critical for anyone writing template code. +{{% /note %}} + +[context]: /getting-started/glossary/#context +[`with`]: /functions/go-template/with +[`else`]: /functions/go-template/else diff --git a/content/en/methods/page/IsHome.md b/content/en/methods/page/IsHome.md new file mode 100644 index 000000000..b688f88c0 --- /dev/null +++ b/content/en/methods/page/IsHome.md @@ -0,0 +1,31 @@ +--- +title: IsHome +description: Reports whether the given page is the home page. +categories: [] +keywords: [] +action: + related: + - methods/page/IsNode + - methods/page/IsPage + - methods/page/IsSection + returnType: bool + signatures: [PAGE.IsHome] +--- + +The `IsHome` method on a `Page` object returns `true` if the [page kind] is `home`. + +```text +content/ +├── books/ +│ ├── book-1/ +│ │ └── index.md <-- kind = page +│ ├── book-2.md <-- kind = page +│ └── _index.md <-- kind = section +└── _index.md <-- kind = home +``` + +```go-html-template +{{ .IsHome }} +``` + +[page kind]: /getting-started/glossary/#page-kind diff --git a/content/en/functions/IsMenuCurrent.md b/content/en/methods/page/IsMenuCurrent.md similarity index 81% rename from content/en/functions/IsMenuCurrent.md rename to content/en/methods/page/IsMenuCurrent.md index c9980b3e8..61283fd8b 100644 --- a/content/en/functions/IsMenuCurrent.md +++ b/content/en/methods/page/IsMenuCurrent.md @@ -1,18 +1,14 @@ --- -title: .IsMenuCurrent +title: IsMenuCurrent description: Reports whether the given page object matches the page object associated with the given menu entry in the given menu. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] +action: + related: + - methods/page/HasMenuCurrent returnType: bool signatures: [PAGE.IsMenuCurrent MENU MENUENTRY] -relatedFunctions: - - .HasMenuCurrent - - .IsMenuCurrent +aliases: [/functions/ismenucurrent] --- ```go-html-template diff --git a/content/en/methods/page/IsNode.md b/content/en/methods/page/IsNode.md new file mode 100644 index 000000000..dfdf435c5 --- /dev/null +++ b/content/en/methods/page/IsNode.md @@ -0,0 +1,36 @@ +--- +title: IsNode +description: Reports whether the given page is a node. +categories: [] +keywords: [] +action: + related: + - methods/page/IsHome + - methods/page/IsPage + - methods/page/IsSection + returnType: bool + signatures: [PAGE.IsNode] +--- + +The `IsNode` method on a `Page` object returns `true` if the [page kind] is `home`, `section`, `taxonomy`, or `term`. + +It returns `false` is the page kind is `page`. + +```text +content/ +├── books/ +│ ├── book-1/ +│ │ └── index.md <-- kind = page, node = false +│ ├── book-2.md <-- kind = page, node = false +│ └── _index.md <-- kind = section, node = true +├── tags/ +│ ├── fiction/ +│ │ └── _index.md <-- kind = term, node = true +│ └── _index.md <-- kind = taxonomy, node = true +└── _index.md <-- kind = home, node = true +``` + +```go-html-template +{{ .IsNode }} +``` +[page kind]: /getting-started/glossary/#page-kind diff --git a/content/en/methods/page/IsPage.md b/content/en/methods/page/IsPage.md new file mode 100644 index 000000000..672ee61f4 --- /dev/null +++ b/content/en/methods/page/IsPage.md @@ -0,0 +1,31 @@ +--- +title: IsPage +description: Reports whether the given page is a regular page. +categories: [] +keywords: [] +action: + related: + - methods/page/IsHome + - methods/page/IsNode + - methods/page/IsSection + returnType: bool + signatures: [PAGE.IsPage] +--- + +The `IsPage` method on a `Page` object returns `true` if the [page kind] is `page`. + +```text +content/ +├── books/ +│ ├── book-1/ +│ │ └── index.md <-- kind = page +│ ├── book-2.md <-- kind = page +│ └── _index.md <-- kind = section +└── _index.md <-- kind = home +``` + +```go-html-template +{{ .IsPage }} +``` + +[page kind]: /getting-started/glossary/#page-kind diff --git a/content/en/methods/page/IsSection.md b/content/en/methods/page/IsSection.md new file mode 100644 index 000000000..b02e58a45 --- /dev/null +++ b/content/en/methods/page/IsSection.md @@ -0,0 +1,31 @@ +--- +title: IsSection +description: Reports whether the given page is a section page. +categories: [] +keywords: [] +action: + related: + - methods/page/IsHome + - methods/page/IsNode + - methods/page/IsPage + returnType: bool + signatures: [PAGE.IsSection] +--- + +The `IsSection` method on a `Page` object returns `true` if the [page kind] is `section`. + +```text +content/ +├── books/ +│ ├── book-1/ +│ │ └── index.md <-- kind = page +│ ├── book-2.md <-- kind = page +│ └── _index.md <-- kind = section +└── _index.md <-- kind = home +``` + +```go-html-template +{{ .IsSection }} +``` + +[page kind]: /getting-started/glossary/#page-kind diff --git a/content/en/methods/page/IsTranslated.md b/content/en/methods/page/IsTranslated.md new file mode 100644 index 000000000..6a8f3f69e --- /dev/null +++ b/content/en/methods/page/IsTranslated.md @@ -0,0 +1,59 @@ +--- +title: IsTranslated +description: Reports whether the given page has one or more translations. +categories: [] +keywords: [] +action: + related: + - methods/page/Translations + - methods/page/AllTranslations + - methods/page/TranslationKey + returnType: bool + signatures: [PAGE.IsTranslated] +--- + +With this site configuration: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'en' + +[languages.en] +contentDir = 'content/en' +languageCode = 'en-US' +languageName = 'English' +weight = 1 + +[languages.de] +contentDir = 'content/de' +languageCode = 'de-DE' +languageName = 'Deutsch' +weight = 2 +{{< /code-toggle >}} + +And this content: + +```text +content/ +├── de/ +│ ├── books/ +│ │ └── book-1.md +│ └── _index.md +├── en/ +│ ├── books/ +│ │ ├── book-1.md +│ │ └── book-2.md +│ └── _index.md +└── _index.md +``` + +When rendering content/en/books/book-1.md: + +```go-html-template +{{ .IsTranslated }} → true +``` + +When rendering content/en/books/book-2.md: + +```go-html-template +{{ .IsTranslated }} → false +``` diff --git a/content/en/methods/page/Keywords.md b/content/en/methods/page/Keywords.md new file mode 100644 index 000000000..5ad37ce51 --- /dev/null +++ b/content/en/methods/page/Keywords.md @@ -0,0 +1,46 @@ +--- +title: Keywords +description: Returns a slice of keywords as defined in front matter. +categories: [] +keywords: [] +action: + related: [] + returnType: '[]string' + signatures: [PAGE.Keywords] +--- + +By default, Hugo evaluates the keywords when creating collections of [related content]. + +[related content]: /content-management/related + +{{< code-toggle file=content/recipes/sushi.md fm=true >}} +title = 'How to make spicy tuna hand rolls' +keywords = ['tuna','sriracha','nori','rice'] +{{< /code-toggle >}} + +To list the keywords within a template: + +```go-html-template +{{ range .Keywords }} + {{ . }} +{{ end }} +``` + +Or use the [delimit] function: + +```go-html-template +{{ delimit .Keywords ", " ", and " }} → tuna, sriracha, nori, and rice +``` + +[delimit]: /functions/collections/delimit + +Keywords are also a useful [taxonomy]: + +{{< code-toggle file=hugo >}} +[taxonomies] +tag = 'tags' +keyword = 'keywords' +category = 'categories' +{{< /code-toggle >}} + +[taxonomy]: /content-management/taxonomies diff --git a/content/en/methods/page/Kind.md b/content/en/methods/page/Kind.md new file mode 100644 index 000000000..d901e9a7d --- /dev/null +++ b/content/en/methods/page/Kind.md @@ -0,0 +1,35 @@ +--- +title: Kind +description: Returns the kind of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Type + returnType: string + signatures: [PAGE.Kind] +--- + +The [page kind] is one of `home`, `page`, `section`, `taxonomy`, or `term`. + +```text +content/ +├── books/ +│ ├── book-1/ +│ │ └── index.md <-- kind = page +│ ├── book-2.md <-- kind = page +│ └── _index.md <-- kind = section +├── tags/ +│ ├── fiction/ +│ │ └── _index.md <-- kind = term +│ └── _index.md <-- kind = taxonomy +└── _index.md <-- kind = home +``` + +To get the value within a template: + +```go-html-template +{{ .Kind }} +``` + +[page kind]: /getting-started/glossary/#page-kind diff --git a/content/en/methods/page/Language.md b/content/en/methods/page/Language.md new file mode 100644 index 000000000..4e65107da --- /dev/null +++ b/content/en/methods/page/Language.md @@ -0,0 +1,65 @@ +--- +title: Language +description: Returns the language object for the given page. +categories: [] +keywords: [] +action: + related: + - methods/site/Language + returnType: langs.Language + signatures: [PAGE.Language] +--- + +The `Language` method on a `Page` object returns the language object for the given page. The language object points to the language definition in the site configuration. + +You can also use the `Language` method on a `Site` object. See [details]. + +## Methods + +The examples below assume the following in your site configuration: + +{{< code-toggle file=hugo >}} +[languages.de] +languageCode = 'de-DE' +languageDirection = 'ltr' +languageName = 'Deutsch' +weight = 2 +{{< /code-toggle >}} + +Lang +: (`string`) The language tag as defined by [RFC 5646]. + +```go-html-template +{{ .Language.Lang }} → de +``` + +LanguageCode +: (`string`) The language code from the site configuration. + +```go-html-template +{{ .Language.LanguageCode }} → de-DE +``` + +LanguageDirection +: (`string`) The language direction from the site configuration, either `ltr` or `rtl`. + +```go-html-template +{{ .Language.LanguageDirection }} → ltr +``` + +LanguageName +: (`string`) The language name from the site configuration. + +```go-html-template +{{ .Language.LanguageName }} → Deutsch +``` + +Weight +: (`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object. + +```go-html-template +{{ .Language.Weight }} → 2 +``` + +[details]: /methods/site/language +[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 diff --git a/content/en/methods/page/Lastmod.md b/content/en/methods/page/Lastmod.md new file mode 100644 index 000000000..c1692233d --- /dev/null +++ b/content/en/methods/page/Lastmod.md @@ -0,0 +1,40 @@ +--- +title: Lastmod +description: Returns the last modification date of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Date + - methods/page/ExpiryDate + - methods/page/PublishDate + - methods/page/GitInfo + returnType: time.Time + signatures: [PAGE.Lastmod] +--- + +Set the last modification date in front matter: + +{{< code-toggle file=content/news/article-1.md fm=true >}} +title = 'Article 1' +lastmod = 2023-10-19T00:40:04-07:00 +{{< /code-toggle >}} + +The last modification date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods]. + +```go-html-template +{{ .Lastmod | time.Format ":date_medium" }} → Oct 19, 2023 +``` + +In the example above we explicitly set the last modification date in front matter. With Hugo's default configuration, the `Lastmod` method returns the front matter value. This behavior is configurable, allowing you to: + +- Set the last modification date to the Author Date of the last Git commit for that file. See [`GitInfo`] for details. +- Set fallback values if the last modification date is not defined in front matter. + +Learn more about [date configuration]. + +[`gitinfo`]: /methods/page/gitinfo +[`time.format`]: /functions/time/format +[date configuration]: /getting-started/configuration/#configure-dates +[time methods]: /methods/time +[time.time]: https://pkg.go.dev/time#time diff --git a/content/en/methods/page/Layout.md b/content/en/methods/page/Layout.md new file mode 100644 index 000000000..3d0cdc437 --- /dev/null +++ b/content/en/methods/page/Layout.md @@ -0,0 +1,40 @@ +--- +title: Layout +description: Returns the layout for the given page as defined in front matter. +categories: [] +keywords: [] +action: + related: + - methods/page/Type + returnType: string + signatures: [PAGE.Layout] +--- + +Specify the `layout` field in front matter to target a particular template. See [details]. + +[details]: /templates/lookup-order/#target-a-template + +{{< code-toggle file=content/contact.md >}} +title = 'Contact' +layout = 'contact' +{{< /code-toggle >}} + +Hugo will render the page using contact.html. + +```text +layouts/ +└── _default/ + ├── baseof.html + ├── contact.html + ├── home.html + ├── list.html + └── single.html +``` + +Although rarely used within a template, you can access the value with: + +```go-html-template +{{ .Layout }} +``` + +The `Layout` method returns an empty string if the `layout` field in front matter is not defined. diff --git a/content/en/methods/page/LinkTitle.md b/content/en/methods/page/LinkTitle.md new file mode 100644 index 000000000..746e433bb --- /dev/null +++ b/content/en/methods/page/LinkTitle.md @@ -0,0 +1,30 @@ +--- +title: LinkTitle +description: Returns the link title of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Title + returnType: string + signatures: [PAGE.LinkTitle] +--- + +The `LinkTitle` method returns the `linkTitle` field as defined in front matter, falling back to the value returned by the [`Title`] method. + +[`Title`]: /methods/page/title + +{{< code-toggle file=content/articles/healthy-desserts.md fm=true >}} +title = 'Seventeen delightful recipes for healthy desserts' +linkTitle = 'Dessert recipes' +{{< /code-toggle >}} + +```go-html-template +{{ .LinkTitle }} → Dessert recipes +``` + +As demonstrated above, defining a link title in front matter is advantageous when the page title is long. Use it when generating anchor elements in your templates: + +```go-html-template +{{ .LinkTitle }} +``` diff --git a/content/en/methods/page/Next.md b/content/en/methods/page/Next.md new file mode 100644 index 000000000..3c9e3495a --- /dev/null +++ b/content/en/methods/page/Next.md @@ -0,0 +1,53 @@ +--- +title: Next +description: Returns the next page in a global page collection, relative to the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Prev + - methods/page/NextInSection + - methods/page/PrevInSection + - methods/pages/Next + - methods/pages/Prev + returnType: hugolib.pageState + signatures: [PAGE.Next] +toc: true +--- + +The behavior of the `Prev` and `Next` methods on a `Page` object is probably the reverse of what you expect. + +With this content structure: + +```text +content/ +├── pages/ +│ ├── _index.md +│ ├── page-1.md <-- front matter: weight = 10 +│ ├── page-2.md <-- front matter: weight = 20 +│ └── page-3.md <-- front matter: weight = 30 +└── _index.md +``` + +When you visit page-2: + +- The `Prev` method points to page-3 +- The `Next` method points to page-1 + +{{% note %}} +Use the opposite label in your navigation links as shown in the example below. +{{% /note %}} + +```go-html-template +{{ with .Next }} + Prev +{{ end }} + +{{ with .Prev }} + Next +{{ end }} +``` + +## Compare to Pages methods + +{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}} diff --git a/content/en/methods/page/NextInSection.md b/content/en/methods/page/NextInSection.md new file mode 100644 index 000000000..dfee353b2 --- /dev/null +++ b/content/en/methods/page/NextInSection.md @@ -0,0 +1,71 @@ +--- +title: NextInSection +description: Returns the next page within a section, relative to the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/PrevInSection + - methods/page/Next + - methods/page/Prev + - methods/pages/Next + - methods/pages/Prev + returnType: hugolib.pageState + signatures: [PAGE.NextInSection] +--- + +The behavior of the `PrevInSection` and `NextInSection` methods on a `Page` object is probably the reverse of what you expect. + +With this content structure: + +```text +content/ +├── books/ +│ ├── _index.md +│ ├── book-1.md +│ ├── book-2.md +│ └── book-3.md +├── films/ +│ ├── _index.md +│ ├── film-1.md +│ ├── film-2.md +│ └── film-3.md +└── _index.md +``` + +When you visit book-2: + +- The `PrevInSection` method points to book-3 +- The `NextInSection` method points to book-1 + +{{% note %}} +Use the opposite label in your navigation links as shown in the example below. +{{% /note %}} + +```go-html-template +{{ with .NextInSection }} + Previous in section +{{ end }} + +{{ with .PrevInSection }} + Next in section +{{ end }} +``` + +{{% note %}} +The navigation sort order may be different than the page collection sort order. +{{% /note %}} + +With the `PrevInSection` and `NextInSection` methods, the navigation sort order is fixed, using Hugo’s default sort order. In order of precedence: + +1. Page [weight] +2. Page [date] (descending) +3. Page [linkTitle], falling back to page [title] +4. Page file path if the page is backed by a file + +For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are a generally a better choice. + +[date]: /methods/page/date +[weight]: /methods/page/weight +[linkTitle]: /methods/page/linktitle +[title]: /methods/page/title diff --git a/content/en/methods/page/OutputFormats.md b/content/en/methods/page/OutputFormats.md new file mode 100644 index 000000000..03343cf8c --- /dev/null +++ b/content/en/methods/page/OutputFormats.md @@ -0,0 +1,40 @@ +--- +title: OutputFormats +description: Returns a slice of OutputFormat objects, each representing one of the output formats enabled for the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/AlternativeOutputFormats + returnType: '[]OutputFormat' + signatures: [PAGE.OutputFormats] +toc: true +--- + +{{% include "methods/page/_common/output-format-definition.md" %}} + +The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, each representing one of the output formats enabled for the given page. See [details](/templates/output-formats/). + +## Methods + +{{% include "methods/page/_common/output-format-methods.md" %}} + +## Example + +To link to the RSS feed for the current page: + +```go-html-template +{{ with .OutputFormats.Get "rss" -}} + RSS Feed +{{ end }} +``` + +On the site's home page, Hugo renders this to: + +```html +RSS Feed +``` + +Please see the [link to output formats] section to understand the importance of the construct above. + +[link to output formats]: /templates/output-formats/#link-to-output-formats diff --git a/content/en/methods/page/Page.md b/content/en/methods/page/Page.md new file mode 100644 index 000000000..1c73c60fc --- /dev/null +++ b/content/en/methods/page/Page.md @@ -0,0 +1,40 @@ +--- +title: Page +description: Returns the Page object of the given page. +categories: [] +keywords: [] +action: + related: [] + returnType: hugolib.pageState + signatures: [PAGE.Page] +--- + +This is a convenience method, useful within partial templates that are called from both [shortcodes] and page templates. + +{{< code file="layouts/shortcodes/foo.html" lang=go-html-template >}} +{{ partial "my-partial.html" . }} +{{< /code >}} + +When the shortcode calls the partial, it passes the current [context] (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`. + +{{< code file="layouts/_default/single.html" lang=go-html-template >}} +{{ partial "my-partial.html" . }} +{{< /code >}} + +When the page template calls the partial, it also passes the current context (the dot). But in this case, the dot _is_ the `Page` object. + +{{< code file="layouts/partials/my-partial.html" lang=go-html-template >}} +The page title is: {{ .Page.Title }} +{{< /code >}} + +To handle both scenarios, the partial template must be able to access the `Page` object with `Page.Page`. + +{{% note %}} +And yes, that means you can do `.Page.Page.Page.Page.Title` too. + +But don't. +{{% /note %}} + + +[context]: getting-started/glossary/#context +[shortcodes]: /getting-started/glossary/#shortcode diff --git a/content/en/methods/page/Pages.md b/content/en/methods/page/Pages.md new file mode 100644 index 000000000..9bd8fc0a7 --- /dev/null +++ b/content/en/methods/page/Pages.md @@ -0,0 +1,90 @@ +--- +title: Pages +description: Returns a collection of regular pages within the current section, and section pages of immediate descendant sections. +categories: [] +keywords: [] +action: + related: + - methods/page/RegularPages + - methods/page/RegularPagesRecursive + returnType: page.Pages + signatures: [PAGE.Pages] +--- + +The `Pages` method on a `Page` object is available to these [page kinds]: `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection] in [context]. + +Range through the page collection in your template: + +```go-html-template +{{ range .Pages.ByTitle }} +

{{ .LinkTitle }}

+{{ end }} +``` + +Consider this content structure: + +```text +content/ +├── lessons/ +│ ├── lesson-1/ +│ │ ├── _index.md +│ │ ├── part-1.md +│ │ └── part-2.md +│ ├── lesson-2/ +│ │ ├── resources/ +│ │ │ ├── task-list.md +│ │ │ └── worksheet.md +│ │ ├── _index.md +│ │ ├── part-1.md +│ │ └── part-2.md +│ ├── _index.md +│ ├── grading-policy.md +│ └── lesson-plan.md +├── _index.md +├── contact.md +└── legal.md +``` + +When rendering the home page, the `Pages` method returns: + + contact.md + legal.md + lessons/_index.md + +When rendering the lessons page, the `Pages` method returns: + + lessons/grading-policy.md + lessons/lesson-plan.md + lessons/lesson-1/_index.md + lessons/lesson-2/_index.md + +When rendering lesson-1, the `Pages` method returns: + + lessons/lesson-1/part-1.md + lessons/lesson-1/part-2.md + +When rendering lesson-2, the `Pages` method returns: + + lessons/lesson-2/part-1.md + lessons/lesson-2/part-2.md + lessons/lesson-2/resources/task-list.md + lessons/lesson-2/resources/worksheet.md + +In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section]---it does not contain an _index.md file. Its contents are part of the lesson-2 section. + +{{% note %}} +When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details]. + +[details]: /methods/site/pages +{{% /note %}} + +```go-html-template +{{ range .Site.Pages.ByTitle }} +

{{ .LinkTitle }}

+{{ end }} +``` + +[collection]: /getting-started/glossary/#collection +[context]: /getting-started/glossary/#context +[page kinds]: /getting-started/glossary/#page-kind +[section]: /getting-started/glossary/#section diff --git a/content/en/methods/page/Paginate.md b/content/en/methods/page/Paginate.md new file mode 100644 index 000000000..878cae0a5 --- /dev/null +++ b/content/en/methods/page/Paginate.md @@ -0,0 +1,50 @@ +--- +title: Paginate +description: Paginates a collection of pages. +categories: [] +keywords: [] +action: + related: + - methods/page/Paginator + returnType: page.Pager + signatures: ['PAGE.Paginate COLLECTION [N]'] +--- + +[Pagination] is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. + +By default, the number of elements on each pager is determined by the value of the `paginate` setting in your site configuration. The default value is `10`. Override the value in your site configuration by providing a second argument, an integer, when calling the `Paginate` method. + +{{% note %}} +There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection. + +The `Paginate` method is more flexible. +{{% /note %}} + +You can invoke pagination on the home page template, [`section`] templates, [`taxonomy`] templates, and [`term`] templates. + +{{< code file=layouts/_default/list.html >}} +{{ $pages := where .Site.RegularPages "Section" "articles" }} +{{ $pages = $pages.ByTitle }} +{{ range (.Paginate $pages 7).Pages }} +

{{ .LinkTitle }}

+{{ end }} +{{ template "_internal/pagination.html" . }} +{{< /code >}} + +In the example above, we: + +1. Build a page collection +2. Sort the collection by title +3. Paginate the collection, with 7 elements per pager +4. Range over the paginated page collection, rendering a link to each page +5. Call the internal "pagination" template to create the navigation links between pagers. + +{{% note %}} +Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. +{{% /note %}} + +[context]: /getting-started/glossary/#context +[pagination]: /templates/pagination/ +[`section`]: /getting-started/glossary/#section +[`taxonomy`]: /getting-started/glossary/#taxonomy +[`term`]: /getting-started/glossary/#term diff --git a/content/en/methods/page/Paginator.md b/content/en/methods/page/Paginator.md new file mode 100644 index 000000000..b1540286a --- /dev/null +++ b/content/en/methods/page/Paginator.md @@ -0,0 +1,42 @@ +--- +title: Paginator +description: Paginates the collection of regular pages received in context. +categories: [] +keywords: [] +action: + related: + - methods/page/Paginate + returnType: page.Pager + signatures: [PAGE.Paginator] +--- + +[Pagination] is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. The number of elements on each pager is determined by the value of the `paginate` setting in your site configuration. The default value is `10`. + +You can invoke pagination on the home page template, [`section`] templates, [`taxonomy`] templates, and [`term`] templates. Each of these receive a collection of regular pages in [context]. When you invoke the `Paginator` method, it paginates the page collection received in context. + +{{< code file=layouts/_default/list.html >}} +{{ range .Paginator.Pages }} +

{{ .LinkTitle }}

+{{ end }} +{{ template "_internal/pagination.html" . }} +{{< /code >}} + +In the example above, the internal "pagination" template creates the navigation links between pagers. + +{{% note %}} +Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context. + +The [`Paginate`] method is more flexible, and strongly recommended. + +[`paginate`]: /methods/page/paginate +{{% /note %}} + +{{% note %}} +Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. +{{% /note %}} + +[context]: /getting-started/glossary/#context +[pagination]: /templates/pagination/ +[`section`]: /getting-started/glossary/#section +[`taxonomy`]: /getting-started/glossary/#taxonomy +[`term`]: /getting-started/glossary/#term diff --git a/content/en/methods/page/Param.md b/content/en/methods/page/Param.md new file mode 100644 index 000000000..18fd67dfe --- /dev/null +++ b/content/en/methods/page/Param.md @@ -0,0 +1,47 @@ +--- +title: Param +description: Returns a page parameter with the given key, falling back to a site parameter if present. +categories: [] +keywords: [] +action: + related: [] + returnType: any + signatures: [PAGE.Param KEY] +aliases: [/functions/param] +--- + +The `Param` method on a `Page` object 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 >}} +[params] +display_toc = true +{{< /code-toggle >}} + +Content: + +{{< code-toggle file="content/example.md" fm=true >}} +title = 'Example' +date = 2023-01-01 +draft = false +display_toc = false +{{< /code-toggle >}} + +Template: + +```go-html-template +{{ if .Param "display_toc" }} + {{ .TableOfContents }} +{{ end }} +``` + +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: + +```go-html-template +{{ or .Params.foo site.Params.foo }} +``` diff --git a/content/en/methods/page/Params.md b/content/en/methods/page/Params.md new file mode 100644 index 000000000..efe8287e0 --- /dev/null +++ b/content/en/methods/page/Params.md @@ -0,0 +1,43 @@ +--- +title: Params +description: Returns a map of custom parameters as defined in the front matter of the given page. +categories: [] +keywords: [] +action: + related: + - functions/collections/IndexFunction + - methods/site/Params + - methods/page/Param + returnType: maps.Params + signatures: [PAGE.Params] +--- + +With this front matter: + +{{< code-toggle file="content/news/annual-conference.md" >}} +title = 'Annual conference' +date = 2023-10-17T15:11:37-07:00 +display_related = true +event-date = '2023' +[params.author] + email = 'jsmith@example.org' + name = 'John Smith' +{{< /code-toggle >}} + +The `title` and `date` fields are standard parameters---the other fields are user-defined. + +Access the custom parameters by [chaining] the [identifiers]: + +```go-html-template +{{ .Params.display_related }} → true +{{ .Params.author.name }} → John Smith +``` + +In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function: + +```go-html-template +{{ index .Params "event-date" }} → 2023 +``` +[`index`]: /functions/collections/indexfunction +[chaining]: /getting-started/glossary/#chain +[identifiers]: /getting-started/glossary/#identifier diff --git a/content/en/methods/page/Parent.md b/content/en/methods/page/Parent.md new file mode 100644 index 000000000..dbd2cb9b3 --- /dev/null +++ b/content/en/methods/page/Parent.md @@ -0,0 +1,60 @@ +--- +title: Parent +description: Returns the Page object of the parent section of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Ancestors + - methods/page/CurrentSection + - methods/page/FirstSection + - methods/page/InSection + - methods/page/IsAncestor + - methods/page/IsDescendant + - methods/page/Sections + returnType: hugolib.pageState + signatures: [PAGE.Parent] +--- + +{{% include "methods/page/_common/definition-of-section.md" %}} + +{{% note %}} +The parent section of a regular page is the [current section]. + +[current section]: /methods/page/currentsection +{{% /note %}} + +Consider this content structure: + +```text +content/ +├── auctions/ +│ ├── 2023-11/ +│ │ ├── _index.md <-- parent: auctions +│ │ ├── auction-1.md +│ │ └── auction-2.md <-- parent: 2023-11 +│ ├── 2023-12/ +│ │ ├── _index.md +│ │ ├── auction-3.md +│ │ └── auction-4.md +│ ├── _index.md <-- parent: home +│ ├── bidding.md +│ └── payment.md <-- parent: auctions +├── books/ +│ ├── _index.md <-- parent: home +│ ├── book-1.md +│ └── book-2.md <-- parent: books +├── films/ +│ ├── _index.md <-- parent: home +│ ├── film-1.md +│ └── film-2.md <-- parent: films +└── _index.md <-- parent: nil +``` + +In the example above, note the parent section of the home page is nil. Code defensively by verifying existence of the parent section before calling methods on its `Page` object. To create a link to the parent section page of the current page: + +```go-html-template +{{ with .Parent }} + {{ .LinkTitle }} +{{ end }} +``` diff --git a/content/en/methods/page/Permalink.md b/content/en/methods/page/Permalink.md new file mode 100644 index 000000000..be6df5aad --- /dev/null +++ b/content/en/methods/page/Permalink.md @@ -0,0 +1,25 @@ +--- +title: Permalink +description: Returns the permalink of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/RelPermalink + returnType: string + signatures: [PAGE.Permalink] +--- + +Site configuration: + +{{< code-toggle file=hugo >}} +title = 'Documentation' +baseURL = 'https://example.org/docs/' +{{< /code-toggle >}} + +Template: + +```go-html-template +{{ $page := .Site.GetPage "/about" }} +{{ $page.RelPermalink }} → https://example.org/docs/about/ +``` diff --git a/content/en/methods/page/Plain.md b/content/en/methods/page/Plain.md new file mode 100644 index 000000000..6fdf60b62 --- /dev/null +++ b/content/en/methods/page/Plain.md @@ -0,0 +1,28 @@ +--- +title: Plain +description: Returns the rendered content of the given page, removing all HTML tags. +categories: [] +keywords: [] +action: + related: + - methods/page/Content + - methods/page/RawContent + - methods/page/PlainWords + - methods/page/RenderShortcodes + returnType: string + signatures: [PAGE.Plain] +--- + +The `Plain` method on a `Page` object renders markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter. + +To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function. + +```go-html-template +{{ .Plain | htmlUnescape }} +``` + +[shortcodes]: /getting-started/glossary/#shortcode +[html/template]: https://pkg.go.dev/html/template +[entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity +[tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag +[`htmlUnescape`]: /functions/ diff --git a/content/en/methods/page/PlainWords.md b/content/en/methods/page/PlainWords.md new file mode 100644 index 000000000..f0a6a9c42 --- /dev/null +++ b/content/en/methods/page/PlainWords.md @@ -0,0 +1,34 @@ +--- +title: PlainWords +description: Calls the Plain method, splits the result into a slice of words, and returns the slice. +categories: [] +keywords: [] +action: + related: + - methods/page/Content + - methods/page/RawContent + - methods/page/Plain + returnType: '[]string' + signatures: [PAGE.PlainWords] +--- + +The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words. + +{{% note %}} +_Fields splits the string s around each instance of one or more consecutive white space characters, as defined by unicode.IsSpace, returning a slice of substrings of s or an empty slice if s contains only white space._ +{{% /note %}} + +As a result, elements within the slice may contain leading or trailing punctuation. + +```go-html-template +{{ .PlainWords }} +``` + +To determine the approximate number of unique words on a page: + +```go-html-template +{{ .PlainWords | uniq }} → 42 +``` + +[`Plain`]: /methods/page/plain +[`strings.Fields`]: https://pkg.go.dev/strings#Fields diff --git a/content/en/methods/page/Prev.md b/content/en/methods/page/Prev.md new file mode 100644 index 000000000..cde83b0f2 --- /dev/null +++ b/content/en/methods/page/Prev.md @@ -0,0 +1,53 @@ +--- +title: Prev +description: Returns the previous page in a global page collection, relative to the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Next + - methods/page/PrevInSection + - methods/page/NextInSection + - methods/pages/Prev + - methods/pages/Next + returnType: hugolib.pageState + signatures: [PAGE.Prev] +toc: true +--- + +The behavior of the `Prev` and `Next` methods on a `Page` object is probably the reverse of what you expect. + +With this content structure: + +```text +content/ +├── pages/ +│ ├── _index.md +│ ├── page-1.md <-- front matter: weight = 10 +│ ├── page-2.md <-- front matter: weight = 20 +│ └── page-3.md <-- front matter: weight = 30 +└── _index.md +``` + +When you visit page-2: + +- The `Prev` method points to page-3 +- The `Next` method points to page-1 + +{{% note %}} +Use the opposite label in your navigation links as shown in the example below. +{{% /note %}} + +```go-html-template +{{ with .Next }} + Prev +{{ end }} + +{{ with .Prev }} + Next +{{ end }} +``` + +## Compare to Pages methods + +{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}} diff --git a/content/en/methods/page/PrevInSection.md b/content/en/methods/page/PrevInSection.md new file mode 100644 index 000000000..bfbb86f3c --- /dev/null +++ b/content/en/methods/page/PrevInSection.md @@ -0,0 +1,72 @@ +--- +title: PrevInSection +description: Returns the previous page within a section, relative to the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/NextInSection + - methods/page/Next + - methods/pages/Next + - methods/page/Prev + - methods/pages/Prev + returnType: hugolib.pageState + signatures: [PAGE.PrevInSection] +--- + + +The behavior of the `PrevInSection` and `NextInSection` methods on a `Page` object is probably the reverse of what you expect. + +With this content structure: + +```text +content/ +├── books/ +│ ├── _index.md +│ ├── book-1.md +│ ├── book-2.md +│ └── book-3.md +├── films/ +│ ├── _index.md +│ ├── film-1.md +│ ├── film-2.md +│ └── film-3.md +└── _index.md +``` + +When you visit book-2: + +- The `PrevInSection` method points to book-3 +- The `NextInSection` method points to book-1 + +{{% note %}} +Use the opposite label in your navigation links as shown in the example below. +{{% /note %}} + +```go-html-template +{{ with .NextInSection }} + Previous in section +{{ end }} + +{{ with .PrevInSection }} + Next in section +{{ end }} +``` + +{{% note %}} +The navigation sort order may be different than the page collection sort order. +{{% /note %}} + +With the `PrevInSection` and `NextInSection` methods, the navigation sort order is fixed, using Hugo’s default sort order. In order of precedence: + +1. Page [weight] +2. Page [date] (descending) +3. Page [linkTitle], falling back to page [title] +4. Page file path if the page is backed by a file + +For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are a generally a better choice. + +[date]: /methods/page/date +[weight]: /methods/page/weight +[linkTitle]: /methods/page/linktitle +[title]: /methods/page/title diff --git a/content/en/methods/page/PublishDate.md b/content/en/methods/page/PublishDate.md new file mode 100644 index 000000000..b1c0717a9 --- /dev/null +++ b/content/en/methods/page/PublishDate.md @@ -0,0 +1,35 @@ +--- +title: PublishDate +description: Returns the publish date of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Date + - methods/page/ExpiryDate + - methods/page/LastMod + returnType: time.Time + signatures: [PAGE.PublishDate] +--- + +By default, Hugo excludes pages with future publish dates when building your site. To include future pages, use the `--buildFuture` command line flag. + +Set the publish date in front matter: + +{{< code-toggle file=content/news/article-1.md fm=true >}} +title = 'Article 1' +publishDate = 2023-10-19T00:40:04-07:00 +{{< /code-toggle >}} + +The publish date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods]. + +```go-html-template +{{ .PublishDate | time.Format ":date_medium" }} → Oct 19, 2023 +``` + +In the example above we explicitly set the publish date in front matter. With Hugo's default configuration, the `PublishDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the publish date is not defined in front matter. See [details]. + +[`time.Format`]: /functions/time/format +[details]: /getting-started/configuration/#configure-dates +[time methods]: /methods/time +[time.Time]: https://pkg.go.dev/time#Time diff --git a/content/en/methods/page/RawContent.md b/content/en/methods/page/RawContent.md new file mode 100644 index 000000000..9fea16db6 --- /dev/null +++ b/content/en/methods/page/RawContent.md @@ -0,0 +1,31 @@ +--- +title: RawContent +description: Returns the raw content of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Content + - methods/page/Plain + - methods/page/PlainWords + - methods/page/RenderShortcodes + returnType: string + signatures: [PAGE.RawContent] +--- + +The `RawContent` method on a `Page` object returns the raw content. The raw content does not include front matter. + +```go-html-template +{{ .RawContent }} +``` + +This is useful when rendering a page in a plain text [content format]. + +{{% note %}} +[Shortcodes] within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object. + +[shortcodes]: /getting-started/glossary/#shortcode +[`RenderShortcodes`]: /methods/page/rendershortcodes +{{% /note %}} + +[content format]: /templates/output-formats diff --git a/content/en/methods/page/ReadingTime.md b/content/en/methods/page/ReadingTime.md new file mode 100644 index 000000000..531824b9b --- /dev/null +++ b/content/en/methods/page/ReadingTime.md @@ -0,0 +1,49 @@ +--- +title: ReadingTime +description: Returns the estimated reading time, in minutes, for the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/WordCount + - methods/page/FuzzyWordCount + returnType: int + signatures: [PAGE.ReadingTime] +--- + +The estimated reading time is calculated by dividing the number of words in the content by the reading speed. + +By default, Hugo assumes a reading speed of 212 words per minute. For CJK languages, it assumes 500 words per minute. + +```go-html-template +{{ printf "Estimated reading time: %d minutes" .ReadingTime }} +``` + +Reading speed varies by language. Create language-specific estimated reading times on your multilingual site using site parameters. + +{{< code-toggle file=hugo >}} +[languages] + [languages.de] + contentDir = 'content/de' + languageCode = 'de-DE' + languageName = 'Deutsch' + weight = 2 + [languages.de.params] + reading_speed = 179 + [languages.en] + contentDir = 'content/en' + languageCode = 'en-US' + languageName = 'English' + weight = 1 + [languages.en.params] + reading_speed = 228 +{{< /code-toggle >}} + +Then in your template: + +```go-html-template +{{ $readingTime := div (float .WordCount) .Site.Params.reading_speed }} +{{ $readingTime = math.Ceil $readingTime }} +``` + +We cast the `.WordCount` to a float to obtain a float when we divide by the reading speed. Then round up to the nearest integer. diff --git a/content/en/methods/page/Ref.md b/content/en/methods/page/Ref.md new file mode 100644 index 000000000..2f52a74c1 --- /dev/null +++ b/content/en/methods/page/Ref.md @@ -0,0 +1,44 @@ +--- +title: Ref +description: Returns the absolute URL of the given page with the given path, language, and output format. +categories: [] +keywords: [] +action: + related: + - methods/page/RelRef + - functions/urls/RelRef + - functions/urls/Ref + returnType: string + signatures: [PAGE.Ref OPTIONS] +--- + +The map of option contains: + +path +: (`string`) The path to the page, relative to the content directory. Required. + +lang +: (`string`) The language (site) to search for the page. Default is the current language. Optional. + +outputFormat +: (`string`) The output format to search for the page. Default is the current output format. Optional. + +The examples below show the rendered output when visiting a page on the English language version of the site: + +```go-html-template +{{ $opts := dict "path" "/books/book-1" }} +{{ .Ref $opts }} → http://localhost:1314/en/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" }} +{{ .Ref $opts }} → http://localhost:1314/de/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }} +{{ .Ref $opts }} → http://localhost:1314/de/books/book-1/index.json +``` + +By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. + +{{< code-toggle file=hugo >}} +refLinksErrorLevel = 'warning' +refLinksNotFoundURL = '/some/other/url' +{{< /code-toggle >}} diff --git a/content/en/methods/page/RegularPages.md b/content/en/methods/page/RegularPages.md new file mode 100644 index 000000000..da433ec80 --- /dev/null +++ b/content/en/methods/page/RegularPages.md @@ -0,0 +1,87 @@ +--- +title: RegularPages +description: Returns a collection of regular pages within the current section. +categories: [] +keywords: [] +action: + related: + - methods/page/Pages + - methods/page/RegularPagesRecursive + returnType: page.Pages + signatures: [PAGE.RegularPages] +--- + +The `RegularPages` method on a `Page` object is available to these [page kinds]: `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection] in [context]. + +Range through the page collection in your template: + +```go-html-template +{{ range .RegularPages.ByTitle }} +

{{ .LinkTitle }}

+{{ end }} +``` + +Consider this content structure: + +```text +content/ +├── lessons/ +│ ├── lesson-1/ +│ │ ├── _index.md +│ │ ├── part-1.md +│ │ └── part-2.md +│ ├── lesson-2/ +│ │ ├── resources/ +│ │ │ ├── task-list.md +│ │ │ └── worksheet.md +│ │ ├── _index.md +│ │ ├── part-1.md +│ │ └── part-2.md +│ ├── _index.md +│ ├── grading-policy.md +│ └── lesson-plan.md +├── _index.md +├── contact.md +└── legal.md +``` + +When rendering the home page, the `RegularPages` method returns: + + contact.md + legal.md + +When rendering the lessons page, the `RegularPages` method returns: + + lessons/grading-policy.md + lessons/lesson-plan.md + +When rendering lesson-1, the `RegularPages` method returns: + + lessons/lesson-1/part-1.md + lessons/lesson-1/part-2.md + +When rendering lesson-2, the `RegularPages` method returns: + + lessons/lesson-2/part-1.md + lessons/lesson-2/part-2.md + lessons/lesson-2/resources/task-list.md + lessons/lesson-2/resources/worksheet.md + +In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section]---it does not contain an _index.md file. Its contents are part of the lesson-2 section. + +{{% note %}} +When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details]. + +[details]: /methods/site/regularpages +{{% /note %}} + +```go-html-template +{{ range .Site.RegularPages.ByTitle }} +

{{ .LinkTitle }}

+{{ end }} +``` + +[collection]: /getting-started/glossary/#collection +[context]: /getting-started/glossary/#context +[page kinds]: /getting-started/glossary/#page-kind +[section]: /getting-started/glossary/#section diff --git a/content/en/methods/page/RegularPagesRecursive.md b/content/en/methods/page/RegularPagesRecursive.md new file mode 100644 index 000000000..5a314cef3 --- /dev/null +++ b/content/en/methods/page/RegularPagesRecursive.md @@ -0,0 +1,90 @@ +--- +title: RegularPagesRecursive +description: Returns a collection of regular pages within the current section, and regular pages within all descendant sections. +categories: [] +keywords: [] +action: + related: + - methods/page/Pages + - methods/page/RegularPages + returnType: page.Pages + signatures: [PAGE.RegularPagesRecursive] +--- + +The `RegularPagesRecursive` method on a `Page` object is available to these [page kinds]: `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection] in [context]. + +Range through the page collection in your template: + +```go-html-template +{{ range .RegularPagesRecursive.ByTitle }} +

{{ .LinkTitle }}

+{{ end }} +``` + +Consider this content structure: + +```text +content/ +├── lessons/ +│ ├── lesson-1/ +│ │ ├── _index.md +│ │ ├── part-1.md +│ │ └── part-2.md +│ ├── lesson-2/ +│ │ ├── resources/ +│ │ │ ├── task-list.md +│ │ │ └── worksheet.md +│ │ ├── _index.md +│ │ ├── part-1.md +│ │ └── part-2.md +│ ├── _index.md +│ ├── grading-policy.md +│ └── lesson-plan.md +├── _index.md +├── contact.md +└── legal.md +``` + +When rendering the home page, the `RegularPagesRecursive` method returns: + + contact.md + lessons/grading-policy.md + legal.md + lessons/lesson-plan.md + lessons/lesson-2/part-1.md + lessons/lesson-1/part-1.md + lessons/lesson-2/part-2.md + lessons/lesson-1/part-2.md + lessons/lesson-2/resources/task-list.md + lessons/lesson-2/resources/worksheet.md + +When rendering the lessons page, the `RegularPagesRecursive` method returns: + + lessons/grading-policy.md + lessons/lesson-plan.md + lessons/lesson-2/part-1.md + lessons/lesson-1/part-1.md + lessons/lesson-2/part-2.md + lessons/lesson-1/part-2.md + lessons/lesson-2/resources/task-list.md + lessons/lesson-2/resources/worksheet.md + +When rendering lesson-1, the `RegularPagesRecursive` method returns: + + lessons/lesson-1/part-1.md + lessons/lesson-1/part-2.md + +When rendering lesson-2, the `RegularPagesRecursive` method returns: + + lessons/lesson-2/part-1.md + lessons/lesson-2/part-2.md + lessons/lesson-2/resources/task-list.md + lessons/lesson-2/resources/worksheet.md + +{{% note %}} +The `RegularPagesRecursive` method in not available on a `Site` object. +{{% /note %}} + +[collection]: /getting-started/glossary/#collection +[context]: /getting-started/glossary/#context +[page kinds]: /getting-started/glossary/#page-kind diff --git a/content/en/methods/page/RelPermalink.md b/content/en/methods/page/RelPermalink.md new file mode 100644 index 000000000..8a5972ccc --- /dev/null +++ b/content/en/methods/page/RelPermalink.md @@ -0,0 +1,25 @@ +--- +title: RelPermalink +description: Returns the relative permalink of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Permalink + returnType: string + signatures: [PAGE.RelPermalink] +--- + +Site configuration: + +{{< code-toggle file=hugo >}} +title = 'Documentation' +baseURL = 'https://example.org/docs/' +{{< /code-toggle >}} + +Template: + +```go-html-template +{{ $page := .Site.GetPage "/about" }} +{{ $page.Permalink }} → /docs/about/ +``` diff --git a/content/en/methods/page/RelRef.md b/content/en/methods/page/RelRef.md new file mode 100644 index 000000000..3d30bfbe9 --- /dev/null +++ b/content/en/methods/page/RelRef.md @@ -0,0 +1,44 @@ +--- +title: RelRef +description: Returns the relative URL of the given page with the given path, language, and output format. +categories: [] +keywords: [] +action: + related: + - methods/page/Ref + - functions/urls/Ref + - functions/urls/RelRef + returnType: string + signatures: [PAGE.RelRef OPTIONS] +--- + +The map of option contains: + +path +: (`string`) The path to the page, relative to the content directory. Required. + +lang +: (`string`) The language (site) to search for the page. Default is the current language. Optional. + +outputFormat +: (`string`) The output format to search for the page. Default is the current output format. Optional. + +The examples below show the rendered output when visiting a page on the English language version of the site: + +```go-html-template +{{ $opts := dict "path" "/books/book-1" }} +{{ .RelRef $opts }} → /en/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" }} +{{ .RelRef $opts }} → /de/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }} +{{ .RelRef $opts }} → /de/books/book-1/index.json +``` + +By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. + +{{< code-toggle file=hugo >}} +refLinksErrorLevel = 'warning' +refLinksNotFoundURL = '/some/other/url' +{{< /code-toggle >}} diff --git a/content/en/methods/page/Render.md b/content/en/methods/page/Render.md new file mode 100644 index 000000000..bc3f58352 --- /dev/null +++ b/content/en/methods/page/Render.md @@ -0,0 +1,75 @@ +--- +title: Render +description: Renders the given template with the given page as context. +categories: [] +keywords: [] +action: + related: + - functions/partials/Include + - functions/partials/IncludeCached + returnType: template.HTML + signatures: [PAGE.Render NAME] +aliases: [/functions/render] +--- + +Typically used when ranging over a page collection, the `Render` method on a `Page` object renders the given template, passing the given page as context. + +```go-html-template +{{ range site.RegularPages }} +

{{ .LinkTitle }}

+ {{ .Render "summary" }} +{{ end }} +``` + +In the example above, note that the template ("summary") is identified by its file name without directory or extension. + +Although similar to the [`partial`] function, there are key differences. + +`Render` method|`partial` function| +:--|:-- +The `Page` object is automatically passed to the given template. You cannot pass additional context.| You must specify the context, allowing you to pass a combination of objects, slices, maps, and scalars. +The path to the template is determined by the [content type].|You must specify the path to the template, relative to the layouts/partials directory. + +Consider this layout structure: + +```text +layouts/ +├── _default/ +│ ├── baseof.html +│ ├── home.html +│ ├── li.html <-- used for other content types +│ ├── list.html +│ ├── single.html +│ └── summary.html +└── books/ + ├── li.html <-- used when content type is "books" + └── summary.html +``` + +And this template: + +```go-html-template +
    + {{ range site.RegularPages.ByDate }} + {{ .Render "li" }} + {{ end }} +
+``` + +When rendering content of type "books" the `Render` method calls: + +```text +layouts/books/li.html +``` + +For all other content types the `Render` methods calls: + +```text +layouts/_default/li.html +``` + +See [content views] for more examples. + +[content views]: /templates/views +[`partial`]: /functions/partials/include +[content type]: /getting-started/glossary/#content-type diff --git a/content/en/methods/page/RenderShortcodes.md b/content/en/methods/page/RenderShortcodes.md new file mode 100644 index 000000000..a62893f52 --- /dev/null +++ b/content/en/methods/page/RenderShortcodes.md @@ -0,0 +1,76 @@ +--- +title: RenderShortcodes +description: Renders all shortcodes in the content of the given page, preserving the surrounding markup. +categories: [] +keywords: [] +action: + related: + - methods/page/RenderString + - methods/page/Content + - methods/page/RawContent + - methods/page/Plain + - methods/page/PlainWords + returnType: template.HTML + signatures: [PAGE.RenderShortcodes] +toc: true +--- + +Use this method in shortcode templates to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents. + +For example: + +{{< code file="layouts/shortcodes/include.html" >}} +{{ $p := site.GetPage (.Get 0) }} +{{ $p.RenderShortcodes }} +{{< /code >}} + +Then in your markdown: + +{{< code file="content/about.md" lang=md >}} +{{%/* include "/snippets/services.md" */%}} +{{%/* include "/snippets/values.md" */%}} +{{%/* include "/snippets/leadership.md" */%}} +{{< /code >}} + +Each of the included markdown files can contain calls to other shortcodes. + +## Shortcode notation + +In the example above it's important to understand the difference between the two delimiters used when calling a shortcode: + +- `{{}}` tells Hugo that the rendered shortcode does not need further processing. For example, the shortcode content is HTML. +- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is markdown. + +Use the latter for the "include" shortcode described above. + +## Further explanation + +To understand what is returned by the `RenderShortcodes` method, consider this content file + +{{< code file="content/about.md" lang=text >}} ++++ +title = 'About' +date = 2023-10-07T12:28:33-07:00 ++++ + +{{}} + +An *emphasized* word. +{{< /code >}} + +With this template code: + +```go-html-template +{{ $p := site.GetPage "/about" }} +{{ $p.RenderShortcodes }} +``` + +Hugo renders this:; + +```html +https://example.org/privacy/ + +An *emphasized* word. +``` + +Note that the shortcode within the content file was rendered, but the surrounding markdown was preserved. diff --git a/content/en/methods/page/RenderString.md b/content/en/methods/page/RenderString.md new file mode 100644 index 000000000..5782cd2b1 --- /dev/null +++ b/content/en/methods/page/RenderString.md @@ -0,0 +1,51 @@ +--- +title: RenderString +description: Renders markup to HTML. +categories: [] +keywords: [] +action: + related: + - methods/page/RenderShortcodes + - functions/transform/Markdownify + returnType: template.HTML + signatures: ['PAGE.RenderString [OPTIONS] MARKUP'] +aliases: [/functions/renderstring] +--- + +```go-html-template +{{ $s := "An *emphasized* word" }} +{{ $s | .RenderString }} → An emphasized word +``` + +This method takes an optional map of options: + +display +: (`string`) Specify either `inline` or `block`. If `inline`, removes surrounding `p` tags from short snippets. Default is `inline`. + +markup +: (`string`) Specify a [markup identifier] for the provided markup. Default is the `markup` front matter value, falling back to the value derived from the page's file extension. + +Render with the default markup renderer: + +```go-html-template +{{ $s := "An *emphasized* word" }} +{{ $s | .RenderString }} → An emphasized word + +{{ $opts := dict "display" "block" }} +{{ $s | .RenderString $opts }} →

An emphasized word

+``` + +Render with [Pandoc]: + +```go-html-template +{{ $s := "H~2~O" }} + +{{ $opts := dict "markup" "pandoc" }} +{{ $s | .RenderString $opts }} → H2O + +{{ $opts := dict "display" "block" "markup" "pandoc" }} +{{ .RenderString $opts $s }} →

H2O

+``` + +[markup identifier]: /content-management/formats/#list-of-content-formats +[pandoc]: https://www.pandoc.org/ diff --git a/content/en/methods/page/Resources.md b/content/en/methods/page/Resources.md new file mode 100644 index 000000000..a9fa3dab2 --- /dev/null +++ b/content/en/methods/page/Resources.md @@ -0,0 +1,81 @@ +--- +title: Resources +description: Returns a collection of page resources. +categories: [] +keywords: [] +action: + related: + - functions/resources/ByType + - functions/resources/Get + - functions/resources/GetMatch + - functions/resources/GetRemote + - functions/resources/Match + returnType: resource.Resources + signatures: [PAGE.Resources] +toc: true +--- + +The `Resources` method on a `Page` object returns a collection of page resources. A page resource is a file within a [page bundle]. + +To work with global or remote resources, see the [`resources`] functions. + +## Methods + +ByType +: (`resource.Resources`) Returns a collection of page resources of the given [media type], or nil if none found. The media type is typically one of `image`, `text`, `audio`, `video`, or `application`. + +```go-html-template +{{ range .Resources.ByType "image" }} + +{{ end }} +``` + +When working with global resources instead of page resources, use the [`resources.ByType`] function. + +Get +: (`resource.Resource`) Returns a page resource from the given path, or nil if none found. + +```go-html-template +{{ with .Resources.Get "images/a.jpg" }} + +{{ end }} +``` + +When working with global resources instead of page resources, use the [`resources.Get`] function. + +GetMatch +: (`resource.Resource`) Returns the first page resource from paths matching the given [glob pattern], or nil if none found. + +```go-html-template +{{ with .Resources.GetMatch "images/*.jpg" }} + +{{ end }} +``` + +When working with global resources instead of page resources, use the [`resources.GetMatch`] function. + +Match +: (`resource.Resources`) Returns a collection of page resources from paths matching the given [glob pattern], or nil if none found. + +```go-html-template +{{ range .Resources.Match "images/*.jpg" }} + +{{ end }} +``` + +When working with global resources instead of page resources, use the [`resources.Match`] function. + +## Pattern matching + +With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob pattern]. + +{{% include "functions/_common/glob-patterns.md" %}} + +[`resources.ByType`]: /functions/resources/ByType +[`resources.GetMatch`]: /functions/resources/ByType +[`resources.Get`]: /functions/resources/ByType +[`resources.Match`]: /functions/resources/ByType +[`resources`]: /functions/resources +[glob pattern]: https://github.com/gobwas/glob#example +[media type]: https://en.wikipedia.org/wiki/Media_type +[page bundle]: /getting-started/glossary/#page-bundle diff --git a/content/en/methods/page/Scratch.md b/content/en/methods/page/Scratch.md new file mode 100644 index 000000000..f9ce7f7fb --- /dev/null +++ b/content/en/methods/page/Scratch.md @@ -0,0 +1,23 @@ +--- +title: Scratch +description: Creates a "scratch pad" on the given page to store and manipulate data. +categories: [] +keywords: [] +action: + related: + - methods/page/Store + - functions/collections/NewScratch + returnType: maps.Scratch + signatures: [PAGE.Scratch] +aliases: [/extras/scratch/,/doc/scratch/,/functions/scratch] +--- + +The `Scratch` method on a `Page` object creates a [scratch pad] to store and manipulate data. To create a scratch pad that is not reset on server rebuilds, use the [`Store`] method instead. + +To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function. + +[`Store`]: /methods/page/store +[`newScratch`]: functions/collections/newscratch +[scratch pad]: /getting-started/glossary/#scratch-pad + +{{% include "methods/page/_common/scratch-methods.md" %}} diff --git a/content/en/methods/page/Section.md b/content/en/methods/page/Section.md new file mode 100644 index 000000000..30c8a9837 --- /dev/null +++ b/content/en/methods/page/Section.md @@ -0,0 +1,54 @@ +--- +title: Section +description: Returns the name of the top level section in which the given page resides. +categories: [] +keywords: [] +action: + related: + - methods/page/Type + returnType: string + signatures: [PAGE.Section] +--- + +With this content structure: + +```text +content/ +├── lessons/ +│ ├── math/ +│ │ ├── _index.md +│ │ ├── lesson-1.md +│ │ └── lesson-2.md +│ └── _index.md +└── _index.md +``` + +When rendering lesson-1.md: + +```go-html-template +{{ .Section }} → lessons +``` + +In the example above "lessons" is the top level section. + +The `Section` method is often used with the [`where`] function to build a page collection. + +```go-html-template +{{ range where .Site.RegularPages "Section" "lessons" }} +

{{ .LinkTitle }}

+{{ end }} +``` + +This is similar to using the [`Type`] method with the `where` function + +```go-html-template +{{ range where .Site.RegularPages "Type" "lessons" }} +

{{ .LinkTitle }}

+{{ end }} +``` + +However, if the `type` field in front matter has been defined on one or more pages, the page collection based on `Type` will be different than the page collection based on `Section`. + + +[`where`]: /functions/collections/where +[`Type`]: /methods/page/type diff --git a/content/en/methods/page/Sections.md b/content/en/methods/page/Sections.md new file mode 100644 index 000000000..68795c50e --- /dev/null +++ b/content/en/methods/page/Sections.md @@ -0,0 +1,69 @@ +--- +title: Sections +description: Returns a collection of section pages, one for each immediate descendant section of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Ancestors + - methods/page/CurrentSection + - methods/page/FirstSection + - methods/page/InSection + - methods/page/IsAncestor + - methods/page/IsDescendant + - methods/page/Parent + returnType: page.Pages + signatures: [PAGE.Sections] +--- + +{{% include "methods/page/_common/definition-of-section.md" %}} + +With this content structure: + +```text +content/ +├── auctions/ +│ ├── 2023-11/ <-- front matter: weight = 202311 +│ │ ├── _index.md +│ │ ├── auction-1.md +│ │ └── auction-2.md +│ ├── 2023-12/ +│ │ ├── _index.md <-- front matter: weight = 202312 +│ │ ├── auction-3.md +│ │ └── auction-4.md +│ ├── _index.md <-- front matter: weight = 30 +│ ├── bidding.md +│ └── payment.md +├── books/ +│ ├── _index.md <-- front matter: weight = 10 +│ ├── book-1.md +│ └── book-2.md +├── films/ +│ ├── _index.md <-- front matter: weight = 20 +│ ├── film-1.md +│ └── film-2.md +└── _index.md +``` + +And this template: + +```go-html-template +{{ range .Sections.ByWeight }} +

{{ .LinkTitle }}

+{{ end }} +``` + +On the home page, Hugo renders: + +```html +

Films

+

Books

+

Auctions

+``` + +On the auctions page, Hugo renders: + +```html +

Auctions in November 2023

+

Auctions in December 2023

+``` diff --git a/content/en/methods/page/Site.md b/content/en/methods/page/Site.md new file mode 100644 index 000000000..34748facd --- /dev/null +++ b/content/en/methods/page/Site.md @@ -0,0 +1,19 @@ +--- +title: Site +description: Returns the Site object. +categories: [] +keywords: [] +action: + related: + - methods/page/Sites + returnType: page.siteWrapper + signatures: [PAGE.Site] +--- + +See [Site methods]. + +[Site methods]: /methods/site + +```go-html-template +{{ .Site.Title }} +``` diff --git a/content/en/methods/page/Sitemap.md b/content/en/methods/page/Sitemap.md new file mode 100644 index 000000000..08ff3f5d0 --- /dev/null +++ b/content/en/methods/page/Sitemap.md @@ -0,0 +1,70 @@ +--- +title: Sitemap +description: Returns the sitemap settings for the given page as defined in front matter, falling back to the sitemap settings as defined in the site configuration. +categories: [] +keywords: [] +action: + related: [] + returnType: config.SitemapConfig + signatures: [PAGE.Sitemap] +toc: true +--- + +Access to the `Sitemap` method on a `Page` object is restricted to [sitemap templates]. + +## Methods + +ChangeFreq +: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is "" (change frequency omitted from rendered sitemap). + +```go-html-template +{{ .Sitemap.ChangeFreq }} +``` + +Priority +: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. Default is -1 (priority omitted from rendered sitemap). + +```go-html-template +{{ .Sitemap.Priority }} +``` + +## Example + +With this site configuration: + +{{< code-toggle file=hugo >}} +[sitemap] +changeFreq = 'monthly' +{{< /code-toggle >}} + +And this content: + +{{< code-toggle file=content/news.md fm=true >}} +title = 'News' +[sitemap] +changeFreq = 'hourly' +{{< /code-toggle >}} + +And this simplistic sitemap template: + +{{< code file=layouts/_default/sitemap.xml >}} +{{ printf "" | safeHTML }} + + {{ range .Pages }} + + {{ .Permalink }} + {{ if not .Lastmod.IsZero }} + {{ .Lastmod.Format "2006-01-02T15:04:05-07:00" | safeHTML }} + {{ end }} + {{ with .Sitemap.ChangeFreq }} + {{ . }} + {{ end }} + + {{ end }} + +{{< /code >}} + +The change frequency will be `hourly` for the news page, and `monthly` for other pages. + +[sitemap templates]: /templates/sitemap-template/ diff --git a/content/en/methods/page/Sites.md b/content/en/methods/page/Sites.md new file mode 100644 index 000000000..1fbdfcdcd --- /dev/null +++ b/content/en/methods/page/Sites.md @@ -0,0 +1,69 @@ +--- +title: Sites +description: Returns a collection of all Site objects, one for each language, ordered by language weight. +categories: [] +keywords: [] +action: + related: + - methods/page/Site + returnType: page.Sites + signatures: [PAGE.Sites] +--- + +This is a convenience method to access `.Site.Sites`. + +With this site configuration: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'de' +defaultContentLanguageInSubdir = false + +[languages.de] +languageCode = 'de-DE' +languageDirection = 'ltr' +languageName = 'Deutsch' +title = 'Projekt Dokumentation' +weight = 1 + +[languages.en] +languageCode = 'en-US' +languageDirection = 'ltr' +languageName = 'English' +title = 'Project Documentation' +weight = 2 +{{< /code-toggle >}} + +This template: + +```go-html-template + +``` + +Produces a list of links to each home page: + +```html + +``` + +To render a link to home page of the primary (first) language: + +```go-html-template +{{ with .Sites.First }} + {{ .Title }} +{{ end }} +``` + +This is equivalent to: + +```go-html-template +{{ with index .Sites 0 }} + {{ .Title }} +{{ end }} +``` diff --git a/content/en/methods/page/Slug.md b/content/en/methods/page/Slug.md new file mode 100644 index 000000000..9fdb09b57 --- /dev/null +++ b/content/en/methods/page/Slug.md @@ -0,0 +1,25 @@ +--- +title: Slug +description: Returns the URL slug of the given page as defined in front matter. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [PAGE.Slug] +--- + +{{< code-toggle file=content/recipes/spicy-tuna-hand-rolls.md fm=true >}} +title = 'How to make spicy tuna hand rolls' +slug = 'sushi' +{{< /code-toggle >}} + +This page will be served from: + + https://example.org/recipes/sushi + +To get the slug value within a template: + +```go-html-template +{{ .Slug }} → sushi +``` diff --git a/content/en/methods/page/Store.md b/content/en/methods/page/Store.md new file mode 100644 index 000000000..04e1d5256 --- /dev/null +++ b/content/en/methods/page/Store.md @@ -0,0 +1,97 @@ +--- +title: Store +description: Creates a persistent "scratch pad" on the given page to store and manipulate data. +categories: [] +keywords: [] +action: + related: + - methods/page/scratch + - functions/collections/NewScratch + returnType: maps.Scratch + signatures: [PAGE.Store] +aliases: [/functions/store] +--- + +The `Store` method on a `Page` object creates a persistent [scratch pad] to store and manipulate data. In contrast with the [`Scratch`] method, the scratch pad created by the `Store` method is not reset on server rebuilds. + +To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function. + +[`Scratch`]: /methods/page/scratch +[`newScratch`]: functions/collections/newscratch +[scratch pad]: /getting-started/glossary/#scratch-pad + +## 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.Set "greeting" "Hello" }} +{{ .Store.Add "greeting" "Welcome" }} +{{ .Store.Get "greeting" }} → HelloWelcome +``` + +```go-html-template +{{ .Store.Set "total" 3 }} +{{ .Store.Add "total" 7 }} +{{ .Store.Get "total" }} → 10 +``` + +```go-html-template +{{ .Store.Set "greetings" (slice "Hello") }} +{{ .Store.Add "greetings" (slice "Welcome" "Cheers") }} +{{ .Store.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 +{{ .Store.SetInMap "greetings" "english" "Hello" }} +{{ .Store.SetInMap "greetings" "french" "Bonjour" }} +{{ .Store.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 +{{ .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" }} +``` diff --git a/content/en/methods/page/Summary.md b/content/en/methods/page/Summary.md new file mode 100644 index 000000000..37ce86589 --- /dev/null +++ b/content/en/methods/page/Summary.md @@ -0,0 +1,29 @@ +--- +title: Summary +description: Returns the content summary of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Truncated + - methods/page/Description + returnType: template.HTML + signatures: [PAGE.Summary] +--- + +There are three ways to define the [content summary]: + +1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration. +2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary. +3. Create a `summary` field in front matter. + +To list the pages in a section with a summary beneath each link: + +```go-html-template +{{ range .Pages }} +

{{ .LinkTitle }}

+ {{ .Summary }} +{{ end }} +``` + +[content summary]: /content-management/summaries diff --git a/content/en/methods/page/TableOfContents.md b/content/en/methods/page/TableOfContents.md new file mode 100644 index 000000000..2ab182e8c --- /dev/null +++ b/content/en/methods/page/TableOfContents.md @@ -0,0 +1,47 @@ +--- +title: TableOfContents +description: Returns a table of contents for the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Fragments + returnType: template.HTML + signatures: [PAGE.TableOfContents] +--- + +The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the markdown [ATX] and [setext] headings within the page content. + +[atx]: https://spec.commonmark.org/0.30/#atx-headings +[setext]: https://spec.commonmark.org/0.30/#setext-headings + +This template code: + +```go-html-template +{{ .TableOfContents }} +``` + +Produces this HTML: + +```html + +``` + +By default, the `TableOfContents` method returns an unordered list of level 2 and level 3 headings. You can adjust this in your site configuration: + +{{< code-toggle file=hugo >}} +[markup.tableOfContents] +endLevel = 3 +ordered = false +startLevel = 2 +{{< /code-toggle >}} diff --git a/content/en/methods/page/Title.md b/content/en/methods/page/Title.md new file mode 100644 index 000000000..d21cc1110 --- /dev/null +++ b/content/en/methods/page/Title.md @@ -0,0 +1,23 @@ +--- +title: Title +description: Returns the title of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/LinkTitle + returnType: string + signatures: [PAGE.Title] +--- + +For pages backed by a file, the `Title` method returns the `title` field in front matter. For section pages that are automatically generated, the `Title` method returns the section name. + +{{< code-toggle file=content/about.md fm=true >}} +title = 'About us' +{{< /code-toggle >}} + +```go-html-template +{{ .Title }} → About us +``` + +With automatic section pages, the title is capitalized by default, using the `titleCaseStyle` defined in your site configuration. To disable this behavior, set `pluralizeListTitles` to `false` in your site configuration. diff --git a/content/en/methods/page/TranslationKey.md b/content/en/methods/page/TranslationKey.md new file mode 100644 index 000000000..f022612ae --- /dev/null +++ b/content/en/methods/page/TranslationKey.md @@ -0,0 +1,74 @@ +--- +title: TranslationKey +description: Returns the translation key of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Translations + - methods/page/AllTranslations + - methods/page/IsTranslated + returnType: string + signatures: [PAGE.TranslationKey] +--- + +The translation key creates a relationship between all translations of a given page. The translation key is derived from the file path, or from the `translationKey` parameter if defined in front matter. + +With this site configuration: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'en' + +[languages.en] +contentDir = 'content/en' +languageCode = 'en-US' +languageName = 'English' +weight = 1 + +[languages.de] +contentDir = 'content/de' +languageCode = 'de-DE' +languageName = 'Deutsch' +weight = 2 +{{< /code-toggle >}} + +And this content: + +```text +content/ +├── de/ +│ ├── books/ +│ │ ├── buch-1.md +│ │ └── book-2.md +│ └── _index.md +├── en/ +│ ├── books/ +│ │ ├── book-1.md +│ │ └── book-2.md +│ └── _index.md +└── _index.md +``` + +And this front matter: + +{{< code-toggle file="content/en/books/book-1.md" fm=true >}} +title = 'Book 1' +translationKey = 'foo' +{{< /code-toggle >}} + +{{< code-toggle file="content/de/books/buch-1.md" fm=true >}} +title = 'Buch 1' +translationKey = 'foo' +{{< /code-toggle >}} + +When rendering either either of the pages above: + +```go-html-template +{{ .TranslationKey }} → page/foo +``` + +If the front matter of Book 2, in both languages, does not include a translation key: + +```go-html-template +{{ .TranslationKey }} → page/books/book-2 +``` diff --git a/content/en/methods/page/Translations.md b/content/en/methods/page/Translations.md new file mode 100644 index 000000000..7aaee75ab --- /dev/null +++ b/content/en/methods/page/Translations.md @@ -0,0 +1,88 @@ +--- +title: Translations +description: Returns all translation of the given page, excluding the current language. +categories: [] +keywords: [] +action: + related: + - methods/page/AllTranslations + - methods/page/IsTranslated + - methods/page/TranslationKey + returnType: page.Pages + signatures: [PAGE.Translations] +--- + +With this site configuration: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'en' + +[languages.en] +contentDir = 'content/en' +languageCode = 'en-US' +languageName = 'English' +weight = 1 + +[languages.de] +contentDir = 'content/de' +languageCode = 'de-DE' +languageName = 'Deutsch' +weight = 2 + +[languages.fr] +contentDir = 'content/fr' +languageCode = 'fr-FR' +languageName = 'Français' +weight = 3 +{{< /code-toggle >}} + +And this content: + +```text +content/ +├── de/ +│ ├── books/ +│ │ ├── book-1.md +│ │ └── book-2.md +│ └── _index.md +├── en/ +│ ├── books/ +│ │ ├── book-1.md +│ │ └── book-2.md +│ └── _index.md +├── fr/ +│ ├── books/ +│ │ └── book-1.md +│ └── _index.md +└── _index.md +``` + +And this template: + +```go-html-template +{{ with .Translations }} + +{{ end }} +``` + +Hugo will render this list on the "Book 1" page of the English site: + +```html + +``` + +Hugo will render this list on the "Book 2" page of the English site: + +```html + +``` diff --git a/content/en/methods/page/Truncated.md b/content/en/methods/page/Truncated.md new file mode 100644 index 000000000..e6051f0cd --- /dev/null +++ b/content/en/methods/page/Truncated.md @@ -0,0 +1,35 @@ +--- +title: Truncated +description: Reports whether the content length exceeds the summary length. +categories: [] +keywords: [] +action: + related: + - methods/page/Summary + returnType: bool + signatures: [PAGE.Truncated] +--- + +There are three ways to define the [content summary]: + +1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration. +2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary. +3. Create a `summary` field in front matter. + +{{% note %}} +The `Truncated` method returns `false` if you define the summary in front matter. +{{% /note %}} + +The `Truncated` method returns `true` if the content length exceeds the summary length. This is useful for rendering a "read more" link: + +```go-html-template +{{ range .Pages }} +

{{ .LinkTitle }}

+ {{ .Summary }} + {{ if .Truncated }} + Read more... + {{ end }} +{{ end }} +``` + +[content summary]: /content-management/summaries diff --git a/content/en/methods/page/Type.md b/content/en/methods/page/Type.md new file mode 100644 index 000000000..d504bc8b8 --- /dev/null +++ b/content/en/methods/page/Type.md @@ -0,0 +1,56 @@ +--- +title: Type +description: Returns the content type of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Kind + - methods/page/Layout + - methods/page/Type + returnType: string + signatures: [PAGE.Type] +--- + +The `Type` method on a `Page` object returns the [content type] of the given page. The content type is defined by the `type` field in front matter, or inferred from the top-level directory name if the `type` field in front matter is not defined. + +With this content structure: + +```text +content/ +├── auction/ +│ ├── _index.md +│ ├── item-1.md +│ └── item-2.md <-- front matter: type = books +├── books/ +│ ├── _index.md +│ ├── book-1.md +│ └── book-2.md +├── films/ +│ ├── _index.md +│ ├── film-1.md +│ └── film-2.md +└── _index.md +``` + +To list the books, regardless of [section]: + +```go-html-template +{{ range where .Site.RegularPages.ByTitle "Type" "books" }} +

{{ .LinkTitle }}

+{{ end }} +``` + +Hugo renders this to; + +```html +

Book 1

+

Book 2

+

Item 2

+``` + +The `type` field in front matter is also useful for targeting a template. See [details]. + +[content type]: /getting-started/glossary/#content-type +[details]: /templates/lookup-order/#target-a-template +[section]: /getting-started/glossary/#section diff --git a/content/en/methods/page/Weight.md b/content/en/methods/page/Weight.md new file mode 100644 index 000000000..75c75db86 --- /dev/null +++ b/content/en/methods/page/Weight.md @@ -0,0 +1,27 @@ +--- +title: Weight +description: Returns the weight of the given page as defined in front matter. +categories: [] +keywords: [] +action: + related: [] + returnType: int + signatures: [PAGE.Weight] +--- + +The `Weight` method on a `Page` object returns the [weight] of the given page as defined in front matter. + +[weight]: /getting-started/glossary/#weight + +{{< code-toggle file=content/recipes/sushi.md fm=true >}} +title = 'How to make spicy tuna hand rolls' +weight = 42 +{{< /code-toggle >}} + +Page weight controls the position of a page within a collection that is sorted by weight. Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection. + +Although rarely used within a template, you can access the value with: + +```go-html-template +{{ .Weight }} → 42 +``` diff --git a/content/en/methods/page/WordCount.md b/content/en/methods/page/WordCount.md new file mode 100644 index 000000000..bb1fdcf94 --- /dev/null +++ b/content/en/methods/page/WordCount.md @@ -0,0 +1,20 @@ +--- +title: WordCount +description: Returns the number of words in the content of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/FuzzyWordCount + - methods/page/ReadingTime + returnType: int + signatures: [PAGE.WordCount] +--- + +```go-html-template +{{ .WordCount }} → 103 +``` + +To round up to nearest multiple of 100, use the [`FuzzyWordCount`] method. + +[`FuzzyWordCount`]: /methods/page/fuzzywordcount diff --git a/content/en/methods/page/_common/_index.md b/content/en/methods/page/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/methods/page/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + + diff --git a/content/en/methods/page/_common/definition-of-section.md b/content/en/methods/page/_common/definition-of-section.md new file mode 100644 index 000000000..7dc600789 --- /dev/null +++ b/content/en/methods/page/_common/definition-of-section.md @@ -0,0 +1,5 @@ +--- +# Do not remove front matter. +--- + +A _section_ is a top-level content directory, or any content directory with an _index.md file. diff --git a/content/en/methods/page/_common/output-format-definition.md b/content/en/methods/page/_common/output-format-definition.md new file mode 100644 index 000000000..25944464a --- /dev/null +++ b/content/en/methods/page/_common/output-format-definition.md @@ -0,0 +1,11 @@ +--- +# Do not remove front matter. +--- + +Hugo generates one or more files per page when building a site. For example, when rendering home, [section], [taxonomy], and [term] pages, Hugo generates an HTML file and an RSS file. Both HTML and RSS are built-in _output formats_. Create multiple output formats, and control generation based on [page kind], or by enabling one or more output formats for one or more pages. See [details]. + +[section]: /getting-started/glossary/#section +[taxonomy]: /getting-started/glossary/#taxonomy +[term]: /getting-started/glossary/#term +[page kind]: /getting-started/glossary/#page-kind +[details]: /templates/output-formats diff --git a/content/en/methods/page/_common/output-format-methods.md b/content/en/methods/page/_common/output-format-methods.md new file mode 100644 index 000000000..5e7111fe5 --- /dev/null +++ b/content/en/methods/page/_common/output-format-methods.md @@ -0,0 +1,27 @@ +--- +# Do not remove front matter. +--- + +Get IDENTIFIER +: (`any`) Returns the `OutputFormat` object with the given identifier. + +MediaType +: (`media.Type`) Returns the media type of the output format. + +MediaType.MainType +: (`string`) Returns the main type of the output format's media type. + +MediaType.SubType +: (`string`) Returns the subtype of the current format's media type. + +Name +: (`string`) Returns the output identifier of the output format. + +Permalink +: (`string`) Returns the permalink of the page generated by the current output format. + +Rel +: (`string`) Returns the `rel` value of the output format, either the default or as defined in the site configuration. + +RelPermalink +: (`string`) Returns the relative permalink of the page generated by the current output format. diff --git a/content/en/methods/page/_common/scratch-methods.md b/content/en/methods/page/_common/scratch-methods.md new file mode 100644 index 000000000..c09b4aadc --- /dev/null +++ b/content/en/methods/page/_common/scratch-methods.md @@ -0,0 +1,79 @@ +--- +# Do not remove front matter. +--- + +## Methods + +Set +: Sets the value of a given key. + +```go-html-template +{{ .Scratch.Set "greeting" "Hello" }} +``` + +Get +: Gets the value of a given key. + +```go-html-template +{{ .Scratch.Set "greeting" "Hello" }} +{{ .Scratch.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 +{{ .Scratch.Set "greeting" "Hello" }} +{{ .Scratch.Add "greeting" "Welcome" }} +{{ .Scratch.Get "greeting" }} → HelloWelcome +``` + +```go-html-template +{{ .Scratch.Set "total" 3 }} +{{ .Scratch.Add "total" 7 }} +{{ .Scratch.Get "total" }} → 10 +``` + +```go-html-template +{{ .Scratch.Set "greetings" (slice "Hello") }} +{{ .Scratch.Add "greetings" (slice "Welcome" "Cheers") }} +{{ .Scratch.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 +{{ .Scratch.SetInMap "greetings" "english" "Hello" }} +{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }} +{{ .Scratch.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 +{{ .Scratch.SetInMap "greetings" "english" "Hello" }} +{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }} +{{ .Scratch.DeleteInMap "greetings" "english" }} +{{ .Scratch.Get "greetings" }} → map[french:Bonjour] +``` + +GetSortedMapValues +: Returns 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 +: Removes the given key. + +```go-html-template +{{ .Scratch.Set "greeting" "Hello" }} +{{ .Scratch.Delete "greeting" }} +``` diff --git a/content/en/methods/page/_index.md b/content/en/methods/page/_index.md new file mode 100644 index 000000000..278541c5a --- /dev/null +++ b/content/en/methods/page/_index.md @@ -0,0 +1,12 @@ +--- +title: Page methods +linkTitle: Page +description: Use these methods with a Page object. +categories: [] +keywords: [] +menu: + docs: + parent: methods +--- + +Use these methods with a Page object. diff --git a/content/en/methods/pages/ByDate.md b/content/en/methods/pages/ByDate.md new file mode 100644 index 000000000..41d9b7da7 --- /dev/null +++ b/content/en/methods/pages/ByDate.md @@ -0,0 +1,31 @@ +--- +title: ByDate +description: Returns the given page collection sorted by date in ascending order. +categories: [] +keywords: [] +action: + related: + - methods/pages/ByExpiryDate + - methods/pages/ByLastMod + - methods/pages/ByPublishDate + returnType: page.Pages + signatures: [PAGES.ByDate] +--- + +When sorting by date, the value is determined by your [site configuration], defaulting to the `date` field in front matter. + +[site configuration]: /getting-started/configuration/#configure-dates + +```go-html-template +{{ range .Pages.ByDate }} +

{{ .Title }}

+{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByDate.Reverse }} +

{{ .Title }}

+{{ end }} +``` diff --git a/content/en/methods/pages/ByExpiryDate.md b/content/en/methods/pages/ByExpiryDate.md new file mode 100644 index 000000000..cec8f975c --- /dev/null +++ b/content/en/methods/pages/ByExpiryDate.md @@ -0,0 +1,31 @@ +--- +title: ByExpiryDate +description: Returns the given page collection sorted by expiration date in ascending order. +categories: [] +keywords: [] +action: + related: + - methods/pages/ByDate + - methods/pages/ByLastMod + - methods/pages/ByPublishDate + returnType: page.Pages + signatures: [PAGES.ByExpiryDate] +--- + +When sorting by expiration date, the value is determined by your [site configuration], defaulting to the `expiryDate` field in front matter. + +[site configuration]: /getting-started/configuration/#configure-dates + +```go-html-template +{{ range .Pages.ByExpiryDate }} +

{{ .Title }}

+{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByExpiryDate.Reverse }} +

{{ .Title }}

+{{ end }} +``` diff --git a/content/en/methods/pages/ByLanguage.md b/content/en/methods/pages/ByLanguage.md new file mode 100644 index 000000000..744a8efeb --- /dev/null +++ b/content/en/methods/pages/ByLanguage.md @@ -0,0 +1,24 @@ +--- +title: ByLanguage +description: Returns the given page collection sorted by language in ascending order. +categories: [] +keywords: [] +action: + related: [] + returnType: page.Pages + signatures: [PAGES.ByLanguage] +--- + +```go-html-template +{{ range .Site.AllPages.ByLanguage }} +

{{ .Title }}

+{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Site.AllPages.ByLanguage.Reverse }} +

{{ .Title }}

+{{ end }} +``` diff --git a/content/en/methods/pages/ByLastmod.md b/content/en/methods/pages/ByLastmod.md new file mode 100644 index 000000000..3c5a0347f --- /dev/null +++ b/content/en/methods/pages/ByLastmod.md @@ -0,0 +1,31 @@ +--- +title: ByLastmod +description: Returns the given page collection sorted by last modification date in ascending order. +categories: [] +keywords: [] +action: + related: + - methods/pages/ByDate + - methods/pages/ByExpiryDate + - methods/pages/ByPublishDate + returnType: page.Pages + signatures: [PAGES.ByLastmod] +--- + +When sorting by last modification date, the value is determined by your [site configuration], defaulting to the `lastmod` field in front matter. + +[site configuration]: /getting-started/configuration/#configure-dates + +```go-html-template +{{ range .Pages.ByLastmod }} +

{{ .Title }}

+{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByLastmod.Reverse }} +

{{ .Title }}

+{{ end }} +``` diff --git a/content/en/methods/pages/ByLength.md b/content/en/methods/pages/ByLength.md new file mode 100644 index 000000000..7d20d034e --- /dev/null +++ b/content/en/methods/pages/ByLength.md @@ -0,0 +1,24 @@ +--- +title: ByLength +description: Returns the given page collection sorted by content length in ascending order. +categories: [] +keywords: [] +action: + related: [] + returnType: page.Pages + signatures: [PAGES.ByLength] +--- + +```go-html-template +{{ range .Pages.ByLength }} +

{{ .Title }}

+{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByLength.Reverse }} +

{{ .Title }}

+{{ end }} +``` diff --git a/content/en/methods/pages/ByLinkTitle.md b/content/en/methods/pages/ByLinkTitle.md new file mode 100644 index 000000000..073b1e1ba --- /dev/null +++ b/content/en/methods/pages/ByLinkTitle.md @@ -0,0 +1,26 @@ +--- +title: ByLinkTitle +description: Returns the given page collection sorted by link title in ascending order, falling back to title if link title is not defined. +categories: [] +keywords: [] +action: + related: + - methods/pages/ByTitle + - methods/pages/ByParam + returnType: page.Pages + signatures: [PAGES.ByLinkTitle] +--- + +```go-html-template +{{ range .Pages.ByLinkTitle }} +

{{ .LinkTitle }}

+{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByLinkTitle.Reverse }} +

{{ .LinkTitle }}

+{{ end }} +``` diff --git a/content/en/methods/pages/ByParam.md b/content/en/methods/pages/ByParam.md new file mode 100644 index 000000000..0fb9b48c0 --- /dev/null +++ b/content/en/methods/pages/ByParam.md @@ -0,0 +1,36 @@ +--- +title: ByParam +description: Returns the given page collection sorted by the given parameter in ascending order. +categories: [] +keywords: [] +action: + related: + - methods/pages/ByTitle + - methods/pages/ByLinkTitle + returnType: page.Pages + signatures: [PAGES.ByParam PARAM] +--- + +If the given parameter is not present in front matter, Hugo will use the matching parameter in your site configuration if present. + +```go-html-template +{{ range .Pages.ByParam "author" }} +

{{ .Title }}

+{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range (.Pages.ByParam "author").Reverse }} +

{{ .Title }}

+{{ end }} +``` + +If the targeted parameter is nested, access the field using dot notation: + +```go-html-template +{{ range .Pages.ByParam "author.last_name" }} +

{{ .Title }}

+{{ end }} +``` diff --git a/content/en/methods/pages/ByPublishDate.md b/content/en/methods/pages/ByPublishDate.md new file mode 100644 index 000000000..b7d026f5f --- /dev/null +++ b/content/en/methods/pages/ByPublishDate.md @@ -0,0 +1,31 @@ +--- +title: ByPublishDate +description: Returns the given page collection sorted by publish date in ascending order. +categories: [] +keywords: [] +action: + related: + - methods/pages/ByDate + - methods/pages/ByExpiryDate + - methods/pages/ByLastMod + returnType: page.Pages + signatures: [PAGES.ByPublishDate] +--- + +When sorting by publish date, the value is determined by your [site configuration], defaulting to the `publishDate` field in front matter. + +[site configuration]: /getting-started/configuration/#configure-dates + +```go-html-template +{{ range .Pages.ByPublishDate }} +

{{ .Title }}

+{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByPublishDate.Reverse }} +

{{ .Title }}

+{{ end }} +``` diff --git a/content/en/methods/pages/ByTitle.md b/content/en/methods/pages/ByTitle.md new file mode 100644 index 000000000..ee54d5cda --- /dev/null +++ b/content/en/methods/pages/ByTitle.md @@ -0,0 +1,26 @@ +--- +title: ByTitle +description: Returns the given page collection sorted by title in ascending order. +categories: [] +keywords: [] +action: + related: + - methods/pages/ByLinkTitle + - methods/pages/ByParam + returnType: page.Pages + signatures: [PAGES.ByTitle] +--- + +```go-html-template +{{ range .Pages.ByTitle }} +

{{ .Title }}

+{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByTitle.Reverse }} +

{{ .Title }}

+{{ end }} +``` diff --git a/content/en/methods/pages/ByWeight.md b/content/en/methods/pages/ByWeight.md new file mode 100644 index 000000000..1e4de8e80 --- /dev/null +++ b/content/en/methods/pages/ByWeight.md @@ -0,0 +1,28 @@ +--- +title: ByWeight +description: Returns the given page collection sorted by weight in ascending order. +categories: [] +keywords: [] +action: + related: [] + returnType: page.Pages + signatures: [PAGES.ByWeight] +--- + +Assign a [weight] to a page using the `weight` field in front matter. The weight must be a non-zero integer. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted pages are placed at the end of the collection. + +[weight]: /getting-started/glossary/#weight + +```go-html-template +{{ range .Pages.ByWeight }} +

{{ .Title }}

+{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByWeight.Reverse }} +

{{ .Title }}

+{{ end }} +``` diff --git a/content/en/methods/pages/GroupBy.md b/content/en/methods/pages/GroupBy.md new file mode 100644 index 000000000..e4e905ade --- /dev/null +++ b/content/en/methods/pages/GroupBy.md @@ -0,0 +1,36 @@ +--- +title: GroupBy +description: Returns the given page collection grouped by the given field in ascending order. +categories: [] +keywords: [] +action: + related: [] + returnType: page.PagesGroup + signatures: ['PAGES.GroupBy FIELD [SORT]'] +--- + +{{% include "methods/pages/_common/group-sort-order.md" %}} + +```go-html-template +{{ range .Pages.GroupBy "Section" }} +

{{ .Key }}

+ +{{ end }} +``` + +To sort the groups in descending order: + +```go-html-template +{{ range .Pages.GroupBy "Section" "desc" }} +

{{ .Key }}

+ +{{ end }} +``` diff --git a/content/en/methods/pages/GroupByDate.md b/content/en/methods/pages/GroupByDate.md new file mode 100644 index 000000000..aa77f5881 --- /dev/null +++ b/content/en/methods/pages/GroupByDate.md @@ -0,0 +1,68 @@ +--- +title: GroupByDate +description: Returns the given page collection grouped by date in descending order. +categories: [] +keywords: [] +action: + related: + - methods/pages/GroupByExpiryDate + - methods/pages/GroupByLastMod + - methods/pages/GroupByParamDate + - methods/pages/GroupByPublishDate + returnType: page.PagesGroup + signatures: ['PAGES.GroupByDate LAYOUT [SORT]'] +--- + +When grouping by date, the value is determined by your [site configuration], defaulting to the `date` field in front matter. + +The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized] for language and region. + +[`time.Format`]: /functions/time/format/ +[layout string]: #layout-string +[localized]: /getting-started/glossary/#localization +[site configuration]: /getting-started/configuration/#configure-dates + +{{% include "methods/pages/_common/group-sort-order.md" %}} + +To group content by year and month: + +```go-html-template +{{ range .Pages.GroupByDate "January 2006" }} +

{{ .Key }}

+ +{{ end }} +``` + +To sort the groups in ascending order: + +```go-html-template +{{ range .Pages.GroupByDate "January 2006" "asc" }} +

{{ .Key }}

+ +{{ end }} +``` + +The pages within each group will also be sorted by date, either ascending or descending depending on the grouping option. To sort the pages within each group, use one of the sorting methods. For example, to sort the pages within each group by title: + +```go-html-template +{{ range .Pages.GroupByDate "January 2006" }} +

{{ .Key }}

+ +{{ end }} +``` + +## Layout string + +{{% include "functions/_common/time-layout-string.md" %}} diff --git a/content/en/methods/pages/GroupByExpiryDate.md b/content/en/methods/pages/GroupByExpiryDate.md new file mode 100644 index 000000000..d398be775 --- /dev/null +++ b/content/en/methods/pages/GroupByExpiryDate.md @@ -0,0 +1,68 @@ +--- +title: GroupByExpiryDate +description: Returns the given page collection grouped by expiration date in descending order. +categories: [] +keywords: [] +action: + related: + - methods/pages/GroupByDate + - methods/pages/GroupByLastMod + - methods/pages/GroupByParamDate + - methods/pages/GroupByPublishDate + returnType: page.PagesGroup + signatures: ['PAGES.GroupByExpiryDate LAYOUT [SORT]'] +--- + +When grouping by expiration date, the value is determined by your [site configuration], defaulting to the `expiryDate` field in front matter. + +The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized] for language and region. + +[`time.Format`]: /functions/time/format/ +[layout string]: #layout-string +[localized]: /getting-started/glossary/#localization +[site configuration]: /getting-started/configuration/#configure-dates + +{{% include "methods/pages/_common/group-sort-order.md" %}} + +To group content by year and month: + +```go-html-template +{{ range .Pages.GroupByExpiryDate "January 2006" }} +

{{ .Key }}

+ +{{ end }} +``` + +To sort the groups in ascending order: + +```go-html-template +{{ range .Pages.GroupByExpiryDate "January 2006" "asc" }} +

{{ .Key }}

+ +{{ end }} +``` + +The pages within each group will also be sorted by expiration date, either ascending or descending depending on your grouping option. To sort the pages within each group, use one of the sorting methods. For example, to sort the pages within each group by title: + +```go-html-template +{{ range .Pages.GroupByExpiryDate "January 2006" }} +

{{ .Key }}

+ +{{ end }} +``` + +## Layout string + +{{% include "functions/_common/time-layout-string.md" %}} diff --git a/content/en/methods/pages/GroupByLastmod.md b/content/en/methods/pages/GroupByLastmod.md new file mode 100644 index 000000000..30f1431f7 --- /dev/null +++ b/content/en/methods/pages/GroupByLastmod.md @@ -0,0 +1,68 @@ +--- +title: GroupByLastmod +description: Returns the given page collection grouped by last modification date in descending order. +categories: [] +keywords: [] +action: + related: + - methods/pages/GroupByDate + - methods/pages/GroupByExpiryDate + - methods/pages/GroupByParamDate + - methods/pages/GroupByPublishDate + returnType: page.PagesGroup + signatures: ['PAGES.GroupByLastmod LAYOUT [SORT]'] +--- + +When grouping by last modification date, the value is determined by your [site configuration], defaulting to the `lastmod` field in front matter. + +The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized] for language and region. + +[`time.Format`]: /functions/time/format/ +[layout string]: #layout-string +[localized]: /getting-started/glossary/#localization +[site configuration]: /getting-started/configuration/#configure-dates + +{{% include "methods/pages/_common/group-sort-order.md" %}} + +To group content by year and month: + +```go-html-template +{{ range .Pages.GroupByLastmod "January 2006" }} +

{{ .Key }}

+ +{{ end }} +``` + +To sort the groups in ascending order: + +```go-html-template +{{ range .Pages.GroupByLastmod "January 2006" "asc" }} +

{{ .Key }}

+ +{{ end }} +``` + +The pages within each group will also be sorted by last modification date, either ascending or descending depending on your grouping option. To sort the pages within each group, use one of the sorting methods. For example, to sort the pages within each group by title: + +```go-html-template +{{ range .Pages.GroupByLastmod "January 2006" }} +

{{ .Key }}

+ +{{ end }} +``` + +## Layout string + +{{% include "functions/_common/time-layout-string.md" %}} diff --git a/content/en/methods/pages/GroupByParam.md b/content/en/methods/pages/GroupByParam.md new file mode 100644 index 000000000..87570c0a5 --- /dev/null +++ b/content/en/methods/pages/GroupByParam.md @@ -0,0 +1,36 @@ +--- +title: GroupByParam +description: Returns the given page collection grouped by the given parameter in ascending order. +categories: [] +keywords: [] +action: + related: [] + returnType: page.PagesGroup + signatures: ['PAGES.GroupByParam PARAM [SORT]'] +--- + +{{% include "methods/pages/_common/group-sort-order.md" %}} + +```go-html-template +{{ range .Pages.GroupByParam "color" }} +

{{ .Key | title }}

+ +{{ end }} +``` + +To sort the groups in descending order: + +```go-html-template +{{ range .Pages.GroupByParam "color" "desc" }} +

{{ .Key | title }}

+ +{{ end }} +``` diff --git a/content/en/methods/pages/GroupByParamDate.md b/content/en/methods/pages/GroupByParamDate.md new file mode 100644 index 000000000..03642fcbe --- /dev/null +++ b/content/en/methods/pages/GroupByParamDate.md @@ -0,0 +1,65 @@ +--- +title: GroupByParamDate +description: Returns the given page collection grouped by the given date parameter in descending order. +categories: [] +keywords: [] +action: + related: + - methods/pages/GroupByDate + - methods/pages/GroupByExpiryDate + - methods/pages/GroupByLastMod + - methods/pages/GroupByPublishDate + returnType: page.PagesGroup + signatures: ['PAGES.GroupByParamDate PARAM LAYOUT [SORT]'] +--- + +The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized] for language and region. + +[`time.Format`]: /functions/time/format/ +[layout string]: #layout-string +[localized]: /getting-started/glossary/#localization + +{{% include "methods/pages/_common/group-sort-order.md" %}} + +To group content by year and month: + +```go-html-template +{{ range .Pages.GroupByParamDate "eventDate" "January 2006" }} +

{{ .Key }}

+ +{{ end }} +``` + +To sort the groups in ascending order: + +```go-html-template +{{ range .Pages.GroupByParamDate "eventDate" "January 2006" "asc" }} +

{{ .Key }}

+ +{{ end }} +``` + +The pages within each group will also be sorted by the parameter date, either ascending or descending depending on your grouping option. To sort the pages within each group, use one of the sorting methods. For example, to sort the pages within each group by title: + +```go-html-template +{{ range .Pages.GroupByParamDate "eventDate" "January 2006" }} +

{{ .Key }}

+ +{{ end }} +``` + +## Layout string + +{{% include "functions/_common/time-layout-string.md" %}} diff --git a/content/en/methods/pages/GroupByPublishDate.md b/content/en/methods/pages/GroupByPublishDate.md new file mode 100644 index 000000000..9264ecae2 --- /dev/null +++ b/content/en/methods/pages/GroupByPublishDate.md @@ -0,0 +1,68 @@ +--- +title: GroupByPublishDate +description: Returns the given page collection grouped by publish date in descending order. +categories: [] +keywords: [] +action: + related: + - methods/pages/GroupByDate + - methods/pages/GroupByExpiryDate + - methods/pages/GroupByLastMod + - methods/pages/GroupByParamDate + returnType: page.PagesGroup + signatures: ['PAGES.GroupByPublishDate LAYOUT [SORT]'] +--- + +When grouping by publish date, the value is determined by your [site configuration], defaulting to the `publishDate` field in front matter. + +The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized] for language and region. + +[`time.Format`]: /functions/time/format/ +[layout string]: #layout-string +[localized]: /getting-started/glossary/#localization +[site configuration]: /getting-started/configuration/#configure-dates + +{{% include "methods/pages/_common/group-sort-order.md" %}} + +To group content by year and month: + +```go-html-template +{{ range .Pages.GroupByPublishDate "January 2006" }} +

{{ .Key }}

+ +{{ end }} +``` + +To sort the groups in ascending order: + +```go-html-template +{{ range .Pages.GroupByPublishDate "January 2006" "asc" }} +

{{ .Key }}

+ +{{ end }} +``` + +The pages within each group will also be sorted by publish date, either ascending or descending depending on your grouping option. To sort the pages within each group, use one of the sorting methods. For example, to sort the pages within each group by title: + +```go-html-template +{{ range .Pages.GroupByPublishDate "January 2006" }} +

{{ .Key }}

+ +{{ end }} +``` + +## Layout string + +{{% include "functions/_common/time-layout-string.md" %}} diff --git a/content/en/methods/pages/Len.md b/content/en/methods/pages/Len.md new file mode 100644 index 000000000..0a5989a1a --- /dev/null +++ b/content/en/methods/pages/Len.md @@ -0,0 +1,14 @@ +--- +title: Len +description: Returns the number of pages in the given page collection. +categories: [] +keywords: [] +action: + related: [] + returnType: int + signatures: [PAGES.Len] +--- + +```go-html-template +{{ .Pages.Len }} → 42 +``` diff --git a/content/en/methods/pages/Limit.md b/content/en/methods/pages/Limit.md new file mode 100644 index 000000000..0939add9f --- /dev/null +++ b/content/en/methods/pages/Limit.md @@ -0,0 +1,16 @@ +--- +title: Limit +description: Returns the first N pages from the given page collection. +categories: [] +keywords: [] +action: + related: [] + returnType: page.Pages + signatures: [PAGES.Limit NUMBER] +--- + +```go-html-template +{{ range .Pages.Limit 3 }} +

{{ .Title }}

+{{ end }} +``` diff --git a/content/en/methods/pages/Next.md b/content/en/methods/pages/Next.md new file mode 100644 index 000000000..638822e5d --- /dev/null +++ b/content/en/methods/pages/Next.md @@ -0,0 +1,55 @@ +--- +title: Next +description: Returns the next page in a local page collection, relative to the given page. +categories: [] +keywords: [] +action: + related: + - methods/pages/Prev + - methods/page/Next + - methods/page/NextInSection + - methods/page/Prev + - methods/page/PrevInSection + returnType: hugolib.pageState + signatures: [PAGES.Next PAGE] +toc: true +--- + +The behavior of the `Prev` and `Next` methods on a `Pages` objects is probably the reverse of what you expect. + +With this content structure and the page collection sorted by weight in ascending order: + +```text +content/ +├── pages/ +│ ├── _index.md +│ ├── page-1.md <-- front matter: weight = 10 +│ ├── page-2.md <-- front matter: weight = 20 +│ └── page-3.md <-- front matter: weight = 30 +└── _index.md +``` + +When you visit page-2: + +- The `Prev` method points to page-3 +- The `Next` method points to page-1 + +{{% note %}} +Use the opposite label in your navigation links as shown in the example below. +{{% /note %}} + +```go-html-template +{{ $pages := where .Site.RegularPages.ByWeight "Section" "pages" }} + +{{ with $pages.Next . }} + Previous +{{ end }} + +{{ with $pages.Prev . }} + Next +{{ end }} +``` + +## Compare to Page methods + +{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}} diff --git a/content/en/methods/pages/Prev.md b/content/en/methods/pages/Prev.md new file mode 100644 index 000000000..3a4dcfd1d --- /dev/null +++ b/content/en/methods/pages/Prev.md @@ -0,0 +1,55 @@ +--- +title: Prev +description: Returns the previous page in a local page collection, relative to the given page. +categories: [] +keywords: [] +action: + related: + - methods/pages/Next + - methods/page/Next + - methods/page/NextInSection + - methods/page/Prev + - methods/page/PrevInSection + returnType: hugolib.pageStates + signatures: [PAGES.Prev PAGE] +toc: true +--- + +The behavior of the `Prev` and `Next` methods on a `Pages` objects is probably the reverse of what you expect. + +With this content structure and the page collection sorted by weight in ascending order: + +```text +content/ +├── pages/ +│ ├── _index.md +│ ├── page-1.md <-- front matter: weight = 10 +│ ├── page-2.md <-- front matter: weight = 20 +│ └── page-3.md <-- front matter: weight = 30 +└── _index.md +``` + +When you visit page-2: + +- The `Prev` method points to page-3 +- The `Next` method points to page-1 + +{{% note %}} +Use the opposite label in your navigation links as shown in the example below. +{{% /note %}} + +```go-html-template +{{ $pages := where .Site.RegularPages.ByWeight "Section" "pages" }} + +{{ with $pages.Next . }} + Previous +{{ end }} + +{{ with $pages.Prev . }} + Next +{{ end }} +``` + +## Compare to Page methods + +{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}} diff --git a/content/en/methods/pages/Related.md b/content/en/methods/pages/Related.md new file mode 100644 index 000000000..60ca4ca67 --- /dev/null +++ b/content/en/methods/pages/Related.md @@ -0,0 +1,77 @@ +--- +title: Related +description: Returns a collection of pages related to the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/HeadingsFiltered + - functions/collections/KeyVals + returnType: page.Pages + signatures: [PAGES.Related PAGE/OPTIONS] +--- + +Based on front matter, Hugo uses several factors to identify content related to the given page. Use the default [related content configuration], or tune the results to the desired indices and parameters. See [details]. + +The argument passed to the `Related` method may be a `Page` or an options map. For example, to pass the current page: + +{{< code file="layouts/_default/single.html" lang=go-html-template copy=false >}} +{{ with .Site.RegularPages.Related . | first 5 }} +

Related pages:

+ +{{ end }} +{{< /code >}} + +To pass an options map: + +{{< code file="layouts/_default/single.html" lang=go-html-template copy=false >}} +{{ $opts := dict + "document" . + "indices" (slice "tags" "keywords") +}} +{{ with .Site.RegularPages.Related $opts | first 5 }} +

Related pages:

+ +{{ end }} +{{< /code >}} + + +## Options + +indices +: (`slice`) The indices to search within. + +document +: (`page`) The page for which to find related content. Required when specifying an options map. + +namedSlices +: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function. + +[`keyVals`]: /functions/collections/keyvals/ + +fragments +: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment] identifiers of the documents. + +A contrived example using all of the above: + +```go-html-template +{{ $page := . }} +{{ $opts := dict + "indices" (slice "tags" "keywords") + "document" $page + "namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date)) + "fragments" (slice "heading-1" "heading-2") +}} +``` + +[details]: /content-management/related/ +[fragment]: /getting-started/glossary/#fragment +[related content configuration]: /content-management/related/ diff --git a/content/en/methods/pages/Reverse.md b/content/en/methods/pages/Reverse.md new file mode 100644 index 000000000..b54cf451e --- /dev/null +++ b/content/en/methods/pages/Reverse.md @@ -0,0 +1,16 @@ +--- +title: Reverse +description: Returns the given page collection in reverse order. +categories: [] +keywords: [] +action: + related: [] + returnType: page.Pages + signatures: [PAGES.Reverse] +--- + +```go-html-template +{{ range .Pages.ByDate.Reverse }} +

{{ .Title }}

+{{ end }} +``` diff --git a/content/en/methods/pages/_common/_index.md b/content/en/methods/pages/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/methods/pages/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + + diff --git a/content/en/methods/pages/_common/group-sort-order.md b/content/en/methods/pages/_common/group-sort-order.md new file mode 100644 index 000000000..bb5be82f6 --- /dev/null +++ b/content/en/methods/pages/_common/group-sort-order.md @@ -0,0 +1,5 @@ +--- +# Do not remove front matter. +--- + +For the optional sort order, specify either `asc` for ascending order, or `desc` for descending order. diff --git a/content/en/methods/pages/_index.md b/content/en/methods/pages/_index.md new file mode 100644 index 000000000..d8a64f5d5 --- /dev/null +++ b/content/en/methods/pages/_index.md @@ -0,0 +1,13 @@ +--- +title: Pages methods +linkTitle: Pages +description: Use these methods with a collection of Page objects. +categories: [] +keywords: [] +menu: + docs: + parent: methods +aliases: [/variables/pages] +--- + +Use these methods with a collection of Page objects. diff --git a/content/en/methods/resource/Colors.md b/content/en/methods/resource/Colors.md new file mode 100644 index 000000000..9eca058fe --- /dev/null +++ b/content/en/methods/resource/Colors.md @@ -0,0 +1,20 @@ +--- +title: Colors +description: Applicable to images, returns a slice of the most dominant colors using a simple histogram method. +categories: [] +keywords: [] +action: + related: [] + returnType: '[]string' + signatures: [RESOURCE.Colors] +--- + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .Colors }} → [#bebebd #514947 #768a9a #647789 #90725e #a48974] +{{ end }} +``` + +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 image. + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/Content.md b/content/en/methods/resource/Content.md new file mode 100644 index 000000000..f51abd327 --- /dev/null +++ b/content/en/methods/resource/Content.md @@ -0,0 +1,61 @@ +--- +title: Content +description: Returns the content of the given resource. +categories: [] +keywords: [] +action: + related: [] + returnType: any + signatures: [RESOURCE.Content] +toc: +--- + +The `Content` method on a `Resource` object returns `template.HTML` when the resource type is `page`, otherwise it returns a `string`. + +[resource type]: /methods/resource/resourcetype + +{{< code file="assets/quotations/kipling.txt" >}} +He travels the fastest who travels alone. +{{< /code >}} + +To get the content: + +```go-html-template +{{ with resources.Get "quotations/kipling.txt" }} + {{ .Content }} → He travels the fastest who travels alone. +{{ end }} +``` + +To get the size in bytes: + +```go-html-template +{{ with resources.Get "quotations/kipling.txt" }} + {{ .Content | len }} → 42 +{{ end }} +``` + +To create an inline image: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + +{{ end }} +``` + +To create inline CSS: + +```go-html-template +{{ with resources.Get "css/style.css" }} + +{{ end }} +``` + +To create inline JavaScript: + +```go-html-template +{{ with resources.Get "js/script.js" }} + +{{ end }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/Crop.md b/content/en/methods/resource/Crop.md new file mode 100644 index 000000000..711fc07b0 --- /dev/null +++ b/content/en/methods/resource/Crop.md @@ -0,0 +1,48 @@ +--- +title: Crop +description: Applicable to images, returns an image resource cropped to the given dimensions without resizing. +categories: [] +keywords: [] +action: + related: + - methods/resource/Fit + - methods/resource/Fill + - methods/resource/Resize + - methods/resource/Process + - functions/images/Process + returnType: images.ImageResource + signatures: [RESOURCE.Crop SPEC] +toc: true +--- + +Crop an image to match the given dimensions without resizing. You must provide both width and height. + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Crop "200x200" }} + + {{ end }} +{{ end }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} + +{{% include "/methods/resource/_common/processing-spec.md" %}} + +## Example + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Crop "200x200 topright webp q85 lanczos" }} + + {{ end }} +{{ end }} +``` + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Process" + filterArgs="crop 200x200 topright webp q85 lanczos" + example=true +>}} diff --git a/content/en/methods/resource/Data.md b/content/en/methods/resource/Data.md new file mode 100644 index 000000000..0fbaf6199 --- /dev/null +++ b/content/en/methods/resource/Data.md @@ -0,0 +1,53 @@ +--- +title: Data +description: Applicable to resources returned by the resources.GetRemote function, returns information from the HTTP response. +categories: [] +keywords: [] +action: + related: + - functions/resources/GetRemote + - methods/resource/Err + returnType: map + signatures: [RESOURCE.Data] +--- + +The `Data` method on a resource returned by the [`resources.GetRemote`] function returns information from the HTTP response. + +[`resources.GetRemote`]: functions/resources/getremote + +```go-html-template +{{ $url := "https://example.org/images/a.jpg" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ with .Data }} + {{ .ContentLength }} → 42764 + {{ .ContentType }} → image/jpeg + {{ .Status }} → 200 OK + {{ .StatusCode }} → 200 + {{ .TransferEncoding }} → [] + {{ end }} + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +ContentLength +: (`int`) The content length in bytes. + +ContentType +: (`string`) The content type. + +Status +: (`string`) The HTTP status text. + +StatusCode +: (`int`) The HTTP status code. + +TransferEncoding +: (`string`) The transfer encoding. + + +[`resources.GetRemote`]: functions/resources/getremote diff --git a/content/en/methods/resource/Err.md b/content/en/methods/resource/Err.md new file mode 100644 index 000000000..f4b410aa7 --- /dev/null +++ b/content/en/methods/resource/Err.md @@ -0,0 +1,56 @@ +--- +title: Err +description: Applicable to resources returned by the resources.GetRemote function, returns an error message if the HTTP request fails, else nil. +categories: [] +keywords: [] +action: + related: + - functions/resources/GetRemote + - methods/resource/Data + returnType: resource.resourceError + signatures: [RESOURCE.Err] +--- + +The `Err` method on a resource returned by the [`resources.GetRemote`] function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build. + +[`resources.GetRemote`]: functions/resources/getremote + +In this example we send an HTTP request to a nonexistent domain: + +```go-html-template +{{ $url := "https://broken-example.org/images/a.jpg" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +The code above captures the error from the HTTP request, then fails the build: + +```text +ERROR error calling resources.GetRemote: Get "https://broken-example.org/images/a.jpg": dial tcp: lookup broken-example.org on 127.0.0.53:53: no such host +``` + +To log an error as a warning instead of an error: + +```go-html-template +{{ $url := "https://broken-example.org/images/a.jpg" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ warnf "%s" . }} + {{ else }} + + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +{{% note %}} +An HTTP response with a 404 status code is not an HTTP request error. To handle 404 status codes, code defensively using the nested `with-else-end` construct as shown above. +{{% /note %}} diff --git a/content/en/methods/resource/Exif.md b/content/en/methods/resource/Exif.md new file mode 100644 index 000000000..bf18efd50 --- /dev/null +++ b/content/en/methods/resource/Exif.md @@ -0,0 +1,78 @@ +--- +title: Exif +description: Applicable to images, returns an EXIF object containing image metatdata. +categories: [] +keywords: [] +action: + related: [] + returnType: exif.ExifInfo + signatures: [RESOURCE.Exif] +toc: true +--- + +Applicable to images, the `Exif` method on an image `Resource` object returns an [EXIF] object containing image metatdata. + +## Methods + +Date +: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function. + +Lat +: (`float64`) Returns the GPS latitude in degrees. + +Long +: (`float64`) Returns the GPS longitude in degrees. + +Tags +: (`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration]. + +## Examples + +To list the creation date, location, and EXIF tags: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with .Exif }} +

Date: {{ .Date }}

+

Lat/Long: {{ .Lat }}/{{ .Long }}

+ {{ with .Tags }} +

Tags

+ + + + + + {{ range $k, $v := . }} + + {{ end }} + +
TagValue
{{ $k }}{{ $v }}
+ {{ end }} + {{ end }} +{{ end }} +``` + +To list specific values: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with .Exif }} +
    + {{ with .Date }}
  • Date: {{ .Format "January 02, 2006" }}
    • {{ end }} + {{ with .Tags.ApertureValue }}
  • Aperture: {{ lang.FormatNumber 2 . }}
    • {{ end }} + {{ with .Tags.BrightnessValue }}
  • Brightness: {{ lang.FormatNumber 2 . }}
    • {{ end }} + {{ with .Tags.ExposureTime }}
  • Exposure Time: {{ . }}
    • {{ end }} + {{ with .Tags.FNumber }}
  • F Number: {{ . }}
    • {{ end }} + {{ with .Tags.FocalLength }}
  • Focal Length: {{ . }}
    • {{ end }} + {{ with .Tags.ISOSpeedRatings }}
  • ISO Speed Ratings: {{ . }}
    • {{ end }} + {{ with .Tags.LensModel }}
  • Lens Model: {{ . }}
    • {{ end }} +
+ {{ end }} +{{ end }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} + +[exif]: https://en.wikipedia.org/wiki/Exif +[site configuration]: /content-management/image-processing/#exif-data +[`time.Format`]: /functions/time/format diff --git a/content/en/methods/resource/Fill.md b/content/en/methods/resource/Fill.md new file mode 100644 index 000000000..8bbaf93ee --- /dev/null +++ b/content/en/methods/resource/Fill.md @@ -0,0 +1,48 @@ +--- +title: Fill +description: Applicable to images, returns an image resource cropped and resized to the given dimensions. +categories: [] +keywords: [] +action: + related: + - methods/resource/Crop + - methods/resource/Fit + - methods/resource/Resize + - methods/resource/Process + - functions/images/Process + returnType: images.ImageResource + signatures: [RESOURCE.Fill SPEC] +toc: true +--- + +Crop and resize an image to match the given dimensions. You must provide both width and height. + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Fill "200x200" }} + + {{ end }} +{{ end }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} + +{{% include "/methods/resource/_common/processing-spec.md" %}} + +## Example + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Fill "200x200 top webp q85 lanczos" }} + + {{ end }} +{{ end }} +``` + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Process" + filterArgs="fill 200x200 top webp q85 lanczos" + example=true +>}} diff --git a/content/en/methods/resource/Filter.md b/content/en/methods/resource/Filter.md new file mode 100644 index 000000000..329168da7 --- /dev/null +++ b/content/en/methods/resource/Filter.md @@ -0,0 +1,68 @@ +--- +title: Filter +description: Applicable to images, applies one or more image filters to the given image resource. +categories: [] +keywords: [] +action: + related: + - functions/images/Filter + returnType: resources.resourceAdapter + signatures: [RESOURCE.Filter FILTER...] +toc: true +--- + +Apply one or more [image filters](#image-filters) to the given image. + +To apply a single filter: + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Filter images.Grayscale }} + + {{ end }} +{{ end }} +``` + +To apply two or more filters, executing from left to right: + +```go-html-template +{{ $filters := slice + images.Grayscale + (images.GaussianBlur 8) +}} +{{ with resources.Get "images/original.jpg" }} + {{ with .Filter $filters }} + + {{ end }} +{{ end }} +``` + +You can also apply image filters using the [`images.Filter`] function. + +[`images.Filter`]: /functions/images/filter + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} + +## Example + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Filter images.Grayscale }} + + {{ end }} +{{ end }} +``` + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Grayscale" + filterArgs="" + example=true +>}} + +## Image filters + +Use any of these filters with the `Filter` method. + +{{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}} diff --git a/content/en/methods/resource/Fit.md b/content/en/methods/resource/Fit.md new file mode 100644 index 000000000..13354fe5a --- /dev/null +++ b/content/en/methods/resource/Fit.md @@ -0,0 +1,48 @@ +--- +title: Fit +description: Applicable to images, returns an image resource downscaled to fit the given dimensions while maintaining aspect ratio. +categories: [] +keywords: [] +action: + related: + - methods/resource/Crop + - methods/resource/Fill + - methods/resource/Resize + - methods/resource/Process + - functions/images/Process + returnType: images.ImageResource + signatures: [RESOURCE.Fit SPEC] +toc: true +--- + +Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height. + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Fit "200x200" }} + + {{ end }} +{{ end }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} + +{{% include "/methods/resource/_common/processing-spec.md" %}} + +## Example + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Fit "300x175 webp q85 lanczos" }} + + {{ end }} +{{ end }} +``` + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Process" + filterArgs="fit 300x175 webp q85 lanczos" + example=true +>}} diff --git a/content/en/methods/resource/Height.md b/content/en/methods/resource/Height.md new file mode 100644 index 000000000..dcaf6c514 --- /dev/null +++ b/content/en/methods/resource/Height.md @@ -0,0 +1,27 @@ +--- +title: Height +description: Applicable to images, returns the height of the given resource. +categories: [] +keywords: [] +action: + related: + - methods/resource/Width + returnType: int + signatures: [RESOURCE.Height] +--- + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .Height }} → 400 +{{ end }} +``` + +Use the `Width` and `Height` methods together when rendering an `img` element: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + +{{ end }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/Key.md b/content/en/methods/resource/Key.md new file mode 100644 index 000000000..747df414c --- /dev/null +++ b/content/en/methods/resource/Key.md @@ -0,0 +1,45 @@ +--- +title: Key +description: Returns the unique key for the given resource, equivalent to its publishing path. +categories: [] +keywords: [] +action: + related: + - methods/resource/Permalink + - methods/resource/RelPermalink + - methods/resource/Publish + returnType: string + signatures: [RESOURCE.Key] +--- + +By way of example, consider this site configuration: + +{{< code-toggle file=hugo copy=false >}} +baseURL = 'https://example.org/docs/' +{{< /code-toggle >}} + +And this template: + +```go-html-template + {{ with resources.Get "images/a.jpg" }} + {{ with resources.Copy "foo/bar/b.jpg" . }} + {{ .Key }} → foo/bar/b.jpg + + {{ .Name }} → images/a.jpg + {{ .Title }} → images/a.jpg + + {{ .RelPermalink }} → /docs/foo/bar/b.jpg + {{ end }} + {{ end }} +``` + +We used the [`resources.Copy`] function to change the publishing path. The `Key` method returns the updated path, but note that it is different than the value returned by [`RelPermalink`]. The `RelPermalink` value includes the subdirectory segment of the `baseURL` in the site configuration. + +The `Key` method is useful if you need to get the resource's publishing path without publishing the resource. Unlike the `Permalink`, `RelPermalink`, or `Publish` methods, calling `Key` will not publish the resource. + + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} + +[`Permalink`]: /methods/resource/permalink +[`RelPermalink`]: /methods/resource/relpermalink +[`resources.Copy`]: /functions/resources/copy diff --git a/content/en/methods/resource/MediaType.md b/content/en/methods/resource/MediaType.md new file mode 100644 index 000000000..6dea8706c --- /dev/null +++ b/content/en/methods/resource/MediaType.md @@ -0,0 +1,52 @@ +--- +title: MediaType +description: Returns a media type object for the given resource. +categories: [] +keywords: [] +action: + related: [] + returnType: media.Type + signatures: [RESOURCE.MediaType] +--- + +The `MediaType` method on a `Resource` object returns an object with additional methods. + +## Methods + +Type +: (`string`) The resource's media type. + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .MediaType.Type }} → image/jpeg +{{ end }} +``` + +MainType +: (`string`) The main type of the resource’s media type. + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .MediaType.MainType }} → image +{{ end }} +``` + +SubType +: (`string`) The subtype of the resource’s media type. This may or may not correspond to the file suffix. + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .MediaType.SubType }} → jpeg +{{ end }} +``` + +Suffixes +: (`slice`) A slice of possible file suffixes for the resource’s media type. + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .MediaType.Suffixes }} → [jpg jpeg jpe jif jfif] +{{ end }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/Name.md b/content/en/methods/resource/Name.md new file mode 100644 index 000000000..1c584adad --- /dev/null +++ b/content/en/methods/resource/Name.md @@ -0,0 +1,82 @@ +--- +title: Name +description: Returns the name of the given resource as optionally defined in front matter, falling back to a relative path or hashed file name depending on resource type. +categories: [] +keywords: [] +action: + related: + - methods/resource/Title + returnType: string + signatures: [RESOURCE.Name] +toc: true +--- + +The value returned by the `Name` method on a `Resource` object depends on the resource type. + +## Global resource + +With a [global resource], the `Name` method returns the path to the resource, relative to the assets directory. + +```text +assets/ +└── images/ + └── a.jpg +``` + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .Name }} → images/a.jpg +{{ end }} +``` + +## Page resource + +With a [page resource], the `Name` method returns the path to the resource, relative to the page bundle. + +```text +content/ +├── posts/ +│ ├── post-1/ +│ │ ├── images/ +│ │ │ └── a.jpg +│ │ └── index.md +│ └── _index.md +└── _index.md +``` + +```go-html-template +{{ with .Resources.Get "images/a.jpg" }} + {{ .Name }} → images/a.jpg +{{ end }} +``` + +If you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter: + +{{< code-toggle file="content/posts/post-1.md" fm=true >}} +title = 'Post 1' +[[resources]] +src = 'images/a.jpg' +name = 'cat' +title = 'Felix the cat' +[resources.params] +temperament = 'malicious' +{{< /code-toggle >}} + +```go-html-template +{{ with .Resources.Get "cat" }} + {{ .Name }} → cat +{{ end }} +``` +## Remote resource + +With a [remote resource], the `Name` method returns a hashed file name. + +```go-html-template +{{ with resources.GetRemote "https://example.org/images/a.jpg" }} + {{ .Name }} → a_18432433023265451104.jpg +{{ end }} +``` + +[global resource]: /getting-started/glossary/#global-resource +[page resource]: /getting-started/glossary/#page-resource +[remote resource]: /getting-started/glossary/#remote-resource diff --git a/content/en/methods/resource/Params.md b/content/en/methods/resource/Params.md new file mode 100644 index 000000000..7a9ec89b3 --- /dev/null +++ b/content/en/methods/resource/Params.md @@ -0,0 +1,65 @@ +--- +title: Params +description: Returns a map of resource parameters as defined in front matter. +categories: [] +keywords: [] +action: + related: [] + returnType: map + signatures: [RESOURCE.Params] +--- + +Use the `Params` method with [page resources]. It is not applicable to either [global] or [remote] resources. + +[global]: /getting-started/glossary/#global-resource +[page resources]: /getting-started/glossary/#page-resource +[remote]: /getting-started/glossary/#remote-resource + +With this content structure: + +```text +content/ +├── posts/ +│ ├── cats/ +│ │ ├── images/ +│ │ │ └── a.jpg +│ │ └── index.md +│ └── _index.md +└── _index.md +``` + +And this front matter: + +{{< code-toggle file=content/posts/cats.md fm=true copy=false >}} +title = 'Cats' +[[resources]] + src = 'images/a.jpg' + title = 'Felix the cat' + [resources.params] + alt = 'Photograph of black cat' + temperament = 'vicious' +{{< /code-toggle >}} + +And this template: + +```go-html-template +{{ with .Resources.Get "images/a.jpg" }} +
+ {{ .Params.alt }} +
{{ .Title }} is {{ .Params.temperament }}
+
+{{ end }} +``` + +Hugo renders: + +```html +
+ Photograph of black cat +
Felix the cat is vicious
+
+``` + +See the [page resources] section for more information. + +[page resources]: /content-management/page-resources diff --git a/content/en/methods/resource/Permalink.md b/content/en/methods/resource/Permalink.md new file mode 100644 index 000000000..ab0ad41b0 --- /dev/null +++ b/content/en/methods/resource/Permalink.md @@ -0,0 +1,25 @@ +--- +title: Permalink +description: Publishes the given resource and returns its permalink. +categories: [] +keywords: [] +action: + related: + - methods/resource/RelPermalink + - methods/resource/Publish + - methods/resource/Key + returnType: string + signatures: [RESOURCE.Permalink] +--- + +The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [permalink]. + +[permalink]: /getting-started/glossary/#permalink + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .Permalink }} → https://example.org/images/a.jpg +{{ end }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/Process.md b/content/en/methods/resource/Process.md new file mode 100644 index 000000000..c3f86feee --- /dev/null +++ b/content/en/methods/resource/Process.md @@ -0,0 +1,66 @@ +--- +title: Process +description: Applicable to images, returns an image resource processed with the given specification. +categories: [] +keywords: [] +action: + related: + - methods/resource/Crop + - methods/resource/Fit + - methods/resource/Fill + - methods/resource/Resize + - functions/images/Process + returnType: images.ImageResource + signatures: [RESOURCE.Process SPEC] +toc: true +--- + +Process an 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 [`Crop`], [`Fill`], [`Fit`], or [`Resize`]. + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Process "crop 200x200" }} + + {{ end }} +{{ end }} +``` + +You can also use this method to apply simple transformations such as rotation and conversion: + +```go-html-template +{{/* Rotate 90 degrees counter-clockwise. */}} +{{ $image := $image.Process "r90" }} + +{{/* Convert to WebP. */}} +{{ $image := $image.Process "webp" }} +``` + +The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [`images.Process`]. + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} + +{{% include "/methods/resource/_common/processing-spec.md" %}} + +## Example + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Process "crop 200x200 topright webp q85 lanczos" }} + + {{ end }} +{{ end }} +``` + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Process" + filterArgs="crop 200x200 topright webp q85 lanczos" + example=true +>}} + +[`Crop`]: /methods/resource/crop +[`Fill`]: /methods/resource/fill +[`Fit`]: /methods/resource/fit +[`Resize`]: /methods/resource/resize +[`images.Process`]: /functions/images/process diff --git a/content/en/methods/resource/Publish.md b/content/en/methods/resource/Publish.md new file mode 100644 index 000000000..b090bfe5a --- /dev/null +++ b/content/en/methods/resource/Publish.md @@ -0,0 +1,35 @@ +--- +title: Publish +description: Publishes the given resource. +categories: [] +keywords: [] +action: + related: + - methods/resource/Permalink + - methods/resource/RelPermalink + - methods/resource/Key + returnType: nil + signatures: [RESOURCE.Publish] +--- + +The `Publish` method on a `Resource` object writes the resource to the publish directory, typically `public`. + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .Publish }} +{{ end }} +``` + +The `Permalink` and `RelPermalink` methods also publish a resource. `Publish` is a convenience method for publishing without a return value. For example, this: + +```go-html-template +{{ $resource.Publish }} +``` + +Instead of this: + +```go-html-template +{{ $noop := $resource.Permalink }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/RelPermalink.md b/content/en/methods/resource/RelPermalink.md new file mode 100644 index 000000000..2b96c35d7 --- /dev/null +++ b/content/en/methods/resource/RelPermalink.md @@ -0,0 +1,25 @@ +--- +title: RelPermalink +description: Publishes the given resource and returns its relative permalink. +categories: [] +keywords: [] +action: + related: + - methods/resource/Permalink + - methods/resource/Publish + - methods/resource/Key + returnType: string + signatures: [RESOURCE.RelPermalink] +--- + +The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [relative permalink]. + +[relative permalink]: /getting-started/glossary/#relative-permalink + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .RelPermalink }} → /images/a.jpg +{{ end }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/Resize.md b/content/en/methods/resource/Resize.md new file mode 100644 index 000000000..4ba054bb5 --- /dev/null +++ b/content/en/methods/resource/Resize.md @@ -0,0 +1,49 @@ +--- +title: Resize +description: Applicable to images, returns an image resource resized to the given width and/or height. +categories: [] +keywords: [] +action: + related: + - methods/resource/Crop + - methods/resource/Fit + - methods/resource/Fill + - methods/resource/Process + - functions/images/Process + returnType: images.ImageResource + signatures: [RESOURCE.Resize SPEC] +--- + +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. + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Resize "300x" }} + + {{ end }} +{{ end }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} + +{{% include "/methods/resource/_common/processing-spec.md" %}} + +## Example + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Resize "300x webp q85 lanczos" }} + + {{ end }} +{{ end }} +``` + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Process" + filterArgs="resize 300x webp q85 lanczos" + example=true +>}} diff --git a/content/en/methods/resource/ResourceType.md b/content/en/methods/resource/ResourceType.md new file mode 100644 index 000000000..1522b7d32 --- /dev/null +++ b/content/en/methods/resource/ResourceType.md @@ -0,0 +1,43 @@ +--- +title: ResourceType +description: Returns the main type of the given resource's media type. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [RESOURCE.ResourceType] +--- + +Common resource types include `audio`, `image`, `text`, and `video`. + +```go-html-template +{{ with resources.Get "image/a.jpg" }} + {{ .ResourceType }} → image + {{ .MediaType.MainType }} → image +{{ end }} +``` + +When working with content files, the resource type is `page`. + +```text +content/ +├── lessons/ +│ ├── lesson-1/ +│ │ ├── _objectives.md <-- resource type = page +│ │ ├── _topics.md <-- resource type = page +│ │ ├── _example.jpg <-- resource type = image +│ │ └── index.md +│ └── _index.md +└── _index.md +``` + +With the structure above, we can range through page resources of type `page` to build content: + +{{< code file="layouts/lessons/single.html" lang=go-html-template copy=false >}} +{{ range .Resources.ByType "page" }} + {{ .Content }} +{{ end }} +{{< /code >}} + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/Title.md b/content/en/methods/resource/Title.md new file mode 100644 index 000000000..78540b20a --- /dev/null +++ b/content/en/methods/resource/Title.md @@ -0,0 +1,95 @@ +--- +title: Title +description: Returns the title of the given resource as optionally defined in front matter, falling back to a relative path or hashed file name depending on resource type. +categories: [] +keywords: [] +action: + related: + - methods/resource/Name + returnType: string + signatures: [RESOURCE.Title] +toc: true +--- + +The value returned by the `Title` method on a `Resource` object depends on the resource type. + +## Global resource + +With a [global resource], the `Title` method returns the path to the resource, relative to the assets directory. + +```text +assets/ +└── images/ + └── a.jpg +``` + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .Title }} → images/a.jpg +{{ end }} +``` + +## Page resource + +With a [page resource], the `Title` method returns the path to the resource, relative to the page bundle. + +```text +content/ +├── posts/ +│ ├── post-1/ +│ │ ├── images/ +│ │ │ └── a.jpg +│ │ └── index.md +│ └── _index.md +└── _index.md +``` + +```go-html-template +{{ with .Resources.Get "images/a.jpg" }} + {{ .Title }} → images/a.jpg +{{ end }} +``` + +If you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter: + +{{< code-toggle file="content/posts/post-1.md" fm=true >}} +title = 'Post 1' +[[resources]] +src = 'images/a.jpg' +name = 'cat' +title = 'Felix the cat' +[resources.params] +temperament = 'malicious' +{{< /code-toggle >}} + +```go-html-template +{{ with .Resources.Get "cat" }} + {{ .Title }} → Felix the cat +{{ end }} +``` + +If the page resource is a content file, the `Title` methods return the `title` field as defined in front matter. + +```text +content/ +├── lessons/ +│ ├── lesson-1/ +│ │ ├── _objectives.md <-- resource type = page +│ │ └── index.md +│ └── _index.md +└── _index.md +``` + +## Remote resource + +With a [remote resource], the `Title` method returns a hashed file name. + +```go-html-template +{{ with resources.GetRemote "https://example.org/images/a.jpg" }} + {{ .Title }} → a_18432433023265451104.jpg +{{ end }} +``` + +[global resource]: /getting-started/glossary/#global-resource +[page resource]: /getting-started/glossary/#page-resource +[remote resource]: /getting-started/glossary/#remote-resource diff --git a/content/en/methods/resource/Width.md b/content/en/methods/resource/Width.md new file mode 100644 index 000000000..8b96c95e8 --- /dev/null +++ b/content/en/methods/resource/Width.md @@ -0,0 +1,27 @@ +--- +title: Width +description: Applicable to images, returns the width of the given resource. +categories: [] +keywords: [] +action: + related: + - methods/resource/Height + returnType: int + signatures: [RESOURCE.Width] +--- + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .Width }} → 600 +{{ end }} +``` + +Use the `Width` and `Height` methods together when rendering an `img` element: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + +{{ end }} +``` + +{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/content/en/methods/resource/_common/_index.md b/content/en/methods/resource/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/methods/resource/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + + diff --git a/content/en/methods/resource/_common/global-page-remote-resources.md b/content/en/methods/resource/_common/global-page-remote-resources.md new file mode 100644 index 000000000..4ea4d1b87 --- /dev/null +++ b/content/en/methods/resource/_common/global-page-remote-resources.md @@ -0,0 +1,13 @@ +--- +# Do not remove front matter. +--- + +{{% note %}} + +Use this method with [global], [page], or [remote] resources. + +[global]: /getting-started/glossary/#global-resource +[page]: /getting-started/glossary/#page-resource +[remote]: /getting-started/glossary/#remote-resource + +{{% /note %}} diff --git a/content/en/methods/resource/_common/processing-spec.md b/content/en/methods/resource/_common/processing-spec.md new file mode 100644 index 000000000..1a3ed887d --- /dev/null +++ b/content/en/methods/resource/_common/processing-spec.md @@ -0,0 +1,34 @@ +--- +# Do not remove front matter. +--- + +## Process specification + +The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence: + +action +: Applicable to the [`Process`](/methods/resource/process) method only. Specify zero or one of `resize`, `fit`, `fill`, or `crop`. If you specify an action you must also provide dimensions. + +dimensions +: Provide width _or_ height when using the [`Resize`](/methods/resource/resize) method, else provide both width _and_ height. See [details](/content-management/image-processing/#dimensions). + +anchor +: Use with the [`Crop`](/methods/resource/crop) and [`Fill`](/methods/resource/fill) methods. Specify zero or one of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. See [details](/content-management/image-processing/#anchor). + +rotation +: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See [details](/content-management/image-processing/#rotation). + +target format +: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See [details](/content-management/image-processing/#target-format). + +quality +: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See [details](/content-management/image-processing/#quality). + +hint +: Applicable to WebP images. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint). + +background color +: When converting a PNG or WebP with transparency to a format that does not support transparency, optionally specify a background color using a 3-digit or a 6-digit hexadecimal color code. Default is `#ffffff` (white). See [details](/content-management/image-processing/#background-color). + +resampling filter +: Typically specify zero or one of `Box`, `Lanczos`, `CatmullRom`, `MitchellNetravali`, `Linear`, or `NearestNeighbor`. Other resampling filters are available. See [details](/content-management/image-processing/#resampling-filter). diff --git a/content/en/methods/resource/_index.md b/content/en/methods/resource/_index.md new file mode 100644 index 000000000..e9426e1a5 --- /dev/null +++ b/content/en/methods/resource/_index.md @@ -0,0 +1,12 @@ +--- +title: Resource methods +linkTitle: Resource +description: Use these methods with global, page, and remote Resource objects. +categories: [] +keywords: [] +menu: + docs: + parent: methods +--- + +Use these methods with global, page, and remote Resource objects. diff --git a/content/en/methods/shortcode/Get.md b/content/en/methods/shortcode/Get.md new file mode 100644 index 000000000..2465023a6 --- /dev/null +++ b/content/en/methods/shortcode/Get.md @@ -0,0 +1,51 @@ +--- +title: Get +description: Returns the value of the given parameter. +categories: [] +keywords: [] +action: + related: + - methods/shortcode/IsNamedParams + - methods/shortcode/Params + returnType: any + signatures: [SHORTCODE.Get PARAM] +toc: true +--- + +Specify the parameter by position or by name. When calling a shortcode within markdown, use either positional or named parameters, but not both. + +{{% note %}} +Some shortcodes support positional parameters, some support named parameters, and others support both. Refer to the shortcode's documentation for usage details. +{{% /note %}} + +## Positional parameters + +This shortcode call uses positional parameters: + +{{< code file="content/about.md" lang=md copy=false >}} +{{}} +{{< /code >}} + +To retrieve parameters by position: + +{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}} +{{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world. +{{< /code >}} + +## Named parameters + +This shortcode call uses named parameters: + +{{< code file="content/about.md" lang=md copy=false >}} +{{}} +{{< /code >}} + +To retrieve parameters by name: + +{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}} +{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world. +{{< /code >}} + +{{% note %}} +Parameter names are case-sensitive. +{{% /note %}} diff --git a/content/en/methods/shortcode/Inner.md b/content/en/methods/shortcode/Inner.md new file mode 100644 index 000000000..98e97b5ea --- /dev/null +++ b/content/en/methods/shortcode/Inner.md @@ -0,0 +1,153 @@ +--- +title: Inner +description: Returns the content between opening and closing shortcode tags, applicable when the shortcode call includes a closing tag. +categories: [] +keywords: [] +action: + related: + - functions/strings/Trim + - methods/page/RenderString + - functions/transform/Markdownify + - methods/shortcode/InnerDeindent + returnType: template.HTML + signatures: [SHORTCODE.Inner] +--- + +This content: + +{{< code file="content/services.md" lang=md copy=false >}} +{{}} +We design the **best** widgets in the world. +{{}} +{{< /code >}} + +With this shortcode: + +{{< code file="layouts/shortcodes/card.html" lang=go-html-template copy=false >}} +
+ {{ with .Get "title" }} +
{{ . }}
+ {{ end }} +
+ {{ trim .Inner "\r\n" }} +
+
+{{< /code >}} + +Is rendered to: + +```html +
+
Product Design
+
+ We design the **best** widgets in the world. +
+
+``` + +{{% note %}} +Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the markdown. Use the [`trim`] function as shown above to remove both carriage returns and newlines. + +[`trim`]: /functions/strings/trim +{{% /note %}} + +{{% note %}} +In the example above, the value returned by `Inner` is markdown, but it was rendered as plain text. Use either of the following approaches to render markdown to HTML. +{{% /note %}} + + +## Use the RenderString method + +Let's modify the example above to pass the value returned by `Inner` through the [`RenderString`] method on the `Page` object: + +[`RenderString`]: /methods/page/renderstring + +{{< code file="layouts/shortcodes/card.html" lang=go-html-template copy=false >}} +
+ {{ with .Get "title" }} +
{{ . }}
+ {{ end }} +
+ {{ trim .Inner "\r\n" | .Page.RenderString }} +
+
+{{< /code >}} + +Hugo renders this to: + +```html +
+
Product design
+
+ We produce the best widgets in the world. +
+
+``` + +You can use the [`markdownify`] function instead of the `RenderString` method, but the latter is more flexible. See [details]. + +[details]: /methods/page/renderstring +[`markdownify`]: /functions/transform/markdownify + +## Use alternate notation + +Instead of calling the shortcode with the `{{}}` notation, use the `{{%/* */%}}` notation: + +{{< code file="content/services.md" lang=md copy=false >}} +{{%/* card title="Product Design" */%}} +We design the **best** widgets in the world. +{{%/* /card */%}} +{{< /code >}} + +When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as markdown, requiring the following changes. + +First, configure the renderer to allow raw HTML within markdown: + +{{< code-toggle file=hugo copy=false >}} +[markup.goldmark.renderer] +unsafe = true +{{< /code-toggle >}} + +This configuration is not unsafe if _you_ control the content. Read more about Hugo's [security model]. + +Second, because we are rendering the entire shortcode as markdown, we must adhere to the rules governing [indentation] and inclusion of [raw HTML blocks] as provided in the [CommonMark] specification. + +{{< code file="layouts/shortcodes/card.html" lang=go-html-template copy=false >}} +
+ {{ with .Get "title" }} +
{{ . }}
+ {{ end }} +
+ + {{ trim .Inner "\r\n" }} +
+
+{{< /code >}} + +The difference between this and the previous example is subtle but required. Note the change in indentation, the addition of a blank line, and removal of the `RenderString` method. + +```diff +--- layouts/shortcodes/a.html ++++ layouts/shortcodes/b.html +@@ -1,8 +1,9 @@ +
+ {{ with .Get "title" }} +-
{{ . }}
++
{{ . }}
+ {{ end }} +
+- {{ trim .Inner "\r\n" | .Page.RenderString }} ++ ++ {{ trim .Inner "\r\n" }} +
+
+``` + +{{% note %}} +When using the `{{%/* */%}}` notation, do not pass the value returned by `Inner` through the `RenderString` method or the `markdownify` function. +{{% /note %}} + +[commonmark]: https://commonmark.org/ +[indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks +[raw html blocks]: https://spec.commonmark.org/0.30/#html-blocks +[security model]: /about/security-model/ diff --git a/content/en/methods/shortcode/InnerDeindent.md b/content/en/methods/shortcode/InnerDeindent.md new file mode 100644 index 000000000..34191df1f --- /dev/null +++ b/content/en/methods/shortcode/InnerDeindent.md @@ -0,0 +1,99 @@ +--- +title: InnerDeindent +description: Returns the content between opening and closing shortcode tags, with indentation removed, applicable when the shortcode call includes a closing tag. +categories: [] +keywords: [] +action: + related: + - methods/shortcode/Inner + returnType: template.HTML + signatures: [SHORTCODE.InnerDeindent] +--- + +Similar to the [`Inner`] method, `InnerDeindent` returns the content between opening and closing shortcode tags. However, with `InnerDeindent`, indentation before the content is removed. + +This allows us to effectively bypass the rules governing [indentation] as provided in the [CommonMark] specification. + +Consider this markdown, an unordered list with a small gallery of thumbnail images within each list item: + +{{< code file="content/about.md" lang=md copy=false >}} +- Gallery one + + {{}} + ![kitten a](thumbnails/a.jpg) + ![kitten b](thumbnails/b.jpg) + {{}} + +- Gallery two + + {{}} + ![kitten c](thumbnails/c.jpg) + ![kitten d](thumbnails/d.jpg) + {{}} +{{< /code >}} + +In the example above, notice that the content between the opening and closing shortcode tags is indented by four spaces. Per the CommonMark specification, this is treated as an indented code block. + +With this shortcode, calling `Inner` instead of `InnerDeindent`: + +{{< code file="layouts/shortcodes/gallery.html" lang=go-html-template copy=false >}} +
+ {{ trim .Inner "\r\n" | .Page.RenderString }} +
+{{< /code >}} + +Hugo renders the markdown to: + +```html +
    +
  • +

    Gallery one

    +
    + 
    ![kitten a](images/a.jpg)
+      ![kitten b](images/b.jpg)
+
    +
    +
    • +
  • +

    Gallery two

    +
    + 
    ![kitten c](images/c.jpg)
+      ![kitten d](images/d.jpg)
+
    +
    +
    • +
+``` + +Although technically correct per the CommonMark specification, this is not what we want. If we remove the indentation using the `InnerDeindent` method: + +{{< code file="layouts/shortcodes/gallery.html" lang=go-html-template copy=false >}} +
+ {{ trim .InnerDeindent "\r\n" | .Page.RenderString }} +
+{{< /code >}} + +Hugo renders the markdown to: + +```html +
    +
  • +

    Gallery one

    +
    + kitten a + kitten b +
    +
    • +
  • +

    Gallery two

    +
    + kitten c + kitten d +
    +
    • +
+``` + +[commonmark]: https://commonmark.org/ +[indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks +[`Inner`]: /methods/shortcode/inner diff --git a/content/en/methods/shortcode/IsNamedParams.md b/content/en/methods/shortcode/IsNamedParams.md new file mode 100644 index 000000000..eac3fc812 --- /dev/null +++ b/content/en/methods/shortcode/IsNamedParams.md @@ -0,0 +1,30 @@ +--- +title: IsNamedParams +description: Reports whether the shortcode call specifies named or positional parameters. +categories: [] +keywords: [] +action: + related: + - methods/shortcode/Get + returnType: bool + signatures: [SHORTCODE.IsNamedParams] +--- + +To support both positional and named parameters when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called. + +With this shortcode template: + +{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}} +{{ if .IsNamedParams }} + {{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} +{{ else }} + {{ printf "%s %s." (.Get 0) (.Get 1) }} +{{ end }} +{{< /code >}} + +Both of these calls return the same value: + +{{< code file="content/about.md" lang=md copy=false >}} +{{}} +{{}} +{{< /code >}} diff --git a/content/en/methods/shortcode/Name.md b/content/en/methods/shortcode/Name.md new file mode 100644 index 000000000..011138e00 --- /dev/null +++ b/content/en/methods/shortcode/Name.md @@ -0,0 +1,29 @@ +--- +title: Name +description: Returns the shortcode file name, excluding the file extension. +categories: [] +keywords: [] +action: + related: + - methods/shortcode/Position + - functions/fmt/Errorf + returnType: string + signatures: [SHORTCODE.Name] +--- + +The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter: + +{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}} +{{ $greeting := "" }} +{{ with .Get "greeting" }} + {{ $greeting = . }} +{{ else }} + {{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }} +{{ end }} +{{< /code >}} + +In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build: + +```text +ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1" +``` diff --git a/content/en/methods/shortcode/Ordinal.md b/content/en/methods/shortcode/Ordinal.md new file mode 100644 index 000000000..50cd2b0d3 --- /dev/null +++ b/content/en/methods/shortcode/Ordinal.md @@ -0,0 +1,50 @@ +--- +title: Ordinal +description: Returns the zero-based ordinal of the shortcode in relation to its parent. +categories: [] +keywords: [] +action: + related: [] + returnType: int + signatures: [SHORTCODE.Ordinal] +--- + +The `Ordinal` method returns the zero-based ordinal of the shortcode in relation to its parent. If the parent is the page itself, the ordinal represents the position of this shortcode in the page content. + +This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example: + +{{< code file="content/about.md" lang=md copy=false >}} +{{}} + +{{}} +{{< /code >}} + +This shortcode performs error checking, then renders an HTML `img` element with a unique `id` attribute: + +{{< code file="layouts/shortcodes/img.html" lang=go-html-template copy=false >}} +{{ $src := "" }} +{{ with .Get "src" }} + {{ $src = . }} + {{ with resources.Get $src }} + {{ $id := printf "img-%03d" $.Ordinal }} + + {{ else }} + {{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $src $.Position }} + {{ end }} +{{ else }} + {{ errorf "The %q shortcode requires a 'src' parameter. See %s" .Name .Position }} +{{ end }} +{{< /code >}} + +Hugo renders the page to: + +```html + + +``` + +{{% note %}} +In the shortcode template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top level context passed into the template. + +[`with`]: /functions/go-template/with +{{% /note %}} diff --git a/content/en/methods/shortcode/Page.md b/content/en/methods/shortcode/Page.md new file mode 100644 index 000000000..83d414599 --- /dev/null +++ b/content/en/methods/shortcode/Page.md @@ -0,0 +1,36 @@ +--- +title: Page +description: Returns the Page object from which the shortcode was called. +categories: [] +keywords: [] +action: + related: [] + returnType: hugolib.pageForShortcode + signatures: [SHORTCODE.Page] +--- + +With this content: + +{{< code-toggle file=content/books/les-miserables.md copy=false fm=true >}} +title = 'Les Misérables' +author = 'Victor Hugo' +published = 1862 +isbn = '978-0451419439' +{{< /code-toggle >}} + +Calling this shortcode: + +```text +{{}} +``` + +We can access the front matter values using the `Page` method: + +{{< code file="layouts/shortcodes/book-details.html" lang=go-html-template copy=false >}} +
    +
  • Title: {{ .Page.Title }}
    • +
  • Author: {{ .Page.Params.author }}
    • +
  • Published: {{ .Page.Params.publication_year }}
    • +
  • ISBN: {{ .Page.Params.isbn }}
    • +
+{{< /code >}} diff --git a/content/en/methods/shortcode/Params.md b/content/en/methods/shortcode/Params.md new file mode 100644 index 000000000..e1ac23a3b --- /dev/null +++ b/content/en/methods/shortcode/Params.md @@ -0,0 +1,33 @@ +--- +title: Params +description: Returns a collection of the shortcode parameters. +categories: [] +keywords: [] +action: + related: + - methods/shortcode/Get + returnType: any + signatures: [SHORTCODE.Params] +--- + +When you call a shortcode using positional parameters, the `Params` method returns a slice. + +{{< code file="content/about.md" lang=md copy=false >}} +{{}} +{{< /code >}} + +{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}} +{{ index .Params 0 }} → Hello +{{ index .Params 1 }} → world +{{< /code >}} + +When you call a shortcode using named parameters, the `Params` method returns a map. + +{{< code file="content/about.md" lang=md copy=false >}} +{{}} +{{< /code >}} + +{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}} +{{ .Params.greeting }} → Hello +{{ .Params.name }} → world +{{< /code >}} diff --git a/content/en/methods/shortcode/Parent.md b/content/en/methods/shortcode/Parent.md new file mode 100644 index 000000000..f40148bc5 --- /dev/null +++ b/content/en/methods/shortcode/Parent.md @@ -0,0 +1,50 @@ +--- +title: Parent +description: Returns the parent shortcode context in nested shortcodes. +categories: [] +keywords: [] +action: + related: [] + returnType: hugolib.ShortcodeWithPage + signatures: [SHORTCODE.Parent] +--- + +This is useful for inheritance of common shortcode parameters from the root. + +In this contrived example, the "greeting" shortcode is the parent, and the "now" shortcode is child. + +{{< code file="content/welcome.md" lang=md copy=false >}} +{{}} +Welcome. Today is {{}}. +{{}} +{{< /code >}} + +{{< code file="layouts/shortcodes/greeting.html" lang=go-html-template copy=false >}} +
+ {{ trim .Inner "\r\n" | .Page.RenderString }} +
+{{< /code >}} + +{{< code file="layouts/shortcodes/now.html" lang=go-html-template copy=false >}} +{{- $dateFormat := "January 2, 2006 15:04:05" }} + +{{- with .Params }} + {{- with .dateFormat }} + {{- $dateFormat = . }} + {{- end }} +{{- else }} + {{- with .Parent.Params }} + {{- with .dateFormat }} + {{- $dateFormat = . }} + {{- end }} + {{- end }} +{{- end }} + +{{- now | time.Format $dateFormat -}} +{{< /code >}} + +The "now" shortcode formats the current time using: + +1. The `dateFormat` parameter passed to the "now" shortcode, if present +2. The `dateFormat` parameter passed to the "greeting" shortcode, if present +3. The default layout string defined at the top of the shortcode diff --git a/content/en/methods/shortcode/Position.md b/content/en/methods/shortcode/Position.md new file mode 100644 index 000000000..181a13e4d --- /dev/null +++ b/content/en/methods/shortcode/Position.md @@ -0,0 +1,33 @@ +--- +title: Position +description: Returns the filename and position from which the shortcode was called. +categories: [] +keywords: [] +action: + related: + - methods/shortcode/Name + - functions/fmt/Errorf + returnType: text.Position + signatures: [SHORTCODE.Position] +--- + +The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter: + +{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}} +{{ $greeting := "" }} +{{ with .Get "greeting" }} + {{ $greeting = . }} +{{ else }} + {{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }} +{{ end }} +{{< /code >}} + +In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build: + +```text +ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1" +``` + +{{% note %}} +The position can relatively expensive to calculate. Limit its use to error reporting. +{{% /note %}} diff --git a/content/en/methods/shortcode/Scratch.md b/content/en/methods/shortcode/Scratch.md new file mode 100644 index 000000000..76586abe2 --- /dev/null +++ b/content/en/methods/shortcode/Scratch.md @@ -0,0 +1,24 @@ +--- +title: Scratch +description: Creates a "scratch pad" scoped to the shortcode to store and manipulate data. +categories: [] +keywords: [] +action: + related: + - functions/collections/NewScratch + returnType: maps.Scratch + signatures: [SHORTCODE.Scratch] +--- + +The `Scratch` method within a shortcode creates a [scratch pad] to store and manipulate data. The scratch pad is scoped to the shortcode, and is reset on server rebuilds. + +{{% note %}} +With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Scratch` method within a shortcode is obsolete. + +[assign values to variables]: https://go.dev/doc/go1.11#text/template +[`newScratch`]: functions/collections/newscratch +{{% /note %}} + +[scratch pad]: /getting-started/glossary/#scratch-pad + +{{% include "methods/page/_common/scratch-methods.md" %}} diff --git a/content/en/methods/shortcode/_index.md b/content/en/methods/shortcode/_index.md new file mode 100644 index 000000000..d26366844 --- /dev/null +++ b/content/en/methods/shortcode/_index.md @@ -0,0 +1,12 @@ +--- +title: Shortcode methods +linkTitle: Shortcode +description: Use these methods in your shortcode templates. +categories: [] +keywords: [] +menu: + docs: + parent: methods +--- + +Use these methods in your shortcode templates. diff --git a/content/en/methods/site/AllPages.md b/content/en/methods/site/AllPages.md new file mode 100644 index 000000000..8df6348f9 --- /dev/null +++ b/content/en/methods/site/AllPages.md @@ -0,0 +1,26 @@ +--- +title: AllPages +description: Returns a collection of all pages in all languages. +categories: [] +keywords: [] +action: + related: + - methods/site/Pages + - methods/site/RegularPages + - methods/site/Sections + returnType: page.Pages + signatures: [SITE.AllPages] +--- + +This method returns all page [kinds] in all languages. That includes the home page, section pages, taxonomy pages, term pages, and regular pages. + +In most cases you should use the [`RegularPages`] method instead. + +[`RegularPages`]: methods/site/regularpages +[kinds]: /getting-started/glossary/#page-kind + +```go-html-template +{{ range .Site.AllPages }} +

{{ .LinkTitle }}

+{{ end }} +``` diff --git a/content/en/methods/site/BaseURL.md b/content/en/methods/site/BaseURL.md new file mode 100644 index 000000000..f9c43bca3 --- /dev/null +++ b/content/en/methods/site/BaseURL.md @@ -0,0 +1,37 @@ +--- +title: BaseURL +description: Returns the base URL as defined in the site configuration. +categories: [] +keywords: [] +action: + related: + - functions/urls/AbsURL + - functions/urls/AbsLangURL + - functions/urls/RelURL + - functions/urls/RelLangURL + returnType: string + signatures: [SITE.BaseURL] +--- + +Site configuration: + +{{< code-toggle file=hugo >}} +baseURL = 'https://example.org/docs/' +{{< /code-toggle >}} + +Template: + +```go-html-template +{{ .Site.BaseURL }} → https://example.org/docs/ +``` + +{{% note %}} +There is almost never a good reason to use this method in your templates. Its usage tends to be fragile due to misconfiguration. + +Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead. + +[`absURL`]: /functions/urls/absURL +[`absLangURL`]: /functions/urls/absLangURL +[`relURL`]: /functions/urls/relURL +[`relLangURL`]: /functions/urls/relLangURL +{{% /note %}} diff --git a/content/en/methods/site/BuildDrafts.md b/content/en/methods/site/BuildDrafts.md new file mode 100644 index 000000000..0d85c78fd --- /dev/null +++ b/content/en/methods/site/BuildDrafts.md @@ -0,0 +1,28 @@ +--- +title: BuildDrafts +description: Reports whether the current build includes draft pages. +categories: [] +keywords: [] +action: + related: [] + returnType: bool + signatures: [SITE.BuildDrafts] +--- + +By default, draft pages are not published when building a site. You can change this behavior with a command line flag: + +```sh +hugo --buildDrafts +``` + +Or by setting `buildDrafts` to `true` in your site configuration: + +{{< code-toggle file=hugo >}} +buildDrafts = true +{{< /code-toggle >}} + +Use the `BuildDrafts` method on a `Site` object to determine the current configuration: + +```go-html-template +{{ .Site.BuildDrafts }} → true +``` diff --git a/content/en/methods/site/Config.md b/content/en/methods/site/Config.md new file mode 100644 index 000000000..b18371d08 --- /dev/null +++ b/content/en/methods/site/Config.md @@ -0,0 +1,57 @@ +--- +title: Config +description: Returns a subset of the site configuration. +categories: [] +keywords: [] +action: + related: [] + returnType: page.SiteConfig + signatures: [SITE.Config] +toc: true +--- + +The `Config` method on a `Site` object provides access to a subset of the site configuration, specifically the `services` and `privacy` keys. + +## Services + +These are the default service settings, typically used by Hugo's built-in templates and shortcodes. + +{{< code-toggle config="services" />}} + +For example, to use Hugo's built-in Google Analytics template you must add a [Google tag ID]: + +[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en + +{{< code-toggle file=hugo >}} +[services.googleAnalytics] +id = 'G-XXXXXXXXX' +{{< /code-toggle >}} + +To access this value from a template: + +```go-html-template +{{ .Site.Config.Services.GoogleAnalytics.ID }} → G-XXXXXXXXX +``` + +You must capitalize each identifier as shown above. + +## Privacy + +These are the default privacy settings, typically used by Hugo's built-in templates and shortcodes: + +{{< code-toggle config="privacy" />}} + +For example, to disable usage of the built-in YouTube shortcode: + +{{< code-toggle file=hugo >}} +[privacy.youtube] +disable = true +{{< /code-toggle >}} + +To access this value from a template: + +```go-html-template +{{ .Site.Config.Privacy.YouTube.Disable }} → true +``` + +You must capitalize each identifier as shown above. diff --git a/content/en/methods/site/Copyright.md b/content/en/methods/site/Copyright.md new file mode 100644 index 000000000..e2ae7d2a5 --- /dev/null +++ b/content/en/methods/site/Copyright.md @@ -0,0 +1,22 @@ +--- +title: Copyright +description: Returns the copyright notice as defined in the site configuration. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [SITE.Copyright] +--- + +Site configuration: + +{{< code-toggle file=hugo >}} +copyright = '© 2023 ABC Widgets, Inc.' +{{< /code-toggle >}} + +Template: + +```go-html-template +{{ .Site.Copyright }} → © 2023 ABC Widgets, Inc. +``` diff --git a/content/en/methods/site/Data.md b/content/en/methods/site/Data.md new file mode 100644 index 000000000..f6b38b597 --- /dev/null +++ b/content/en/methods/site/Data.md @@ -0,0 +1,108 @@ +--- +title: Data +description: Returns a data structure composed from the files in the data directory. +categories: [] +keywords: [] +action: + related: + - functions/collections/IndexFunction + - functions/transform/Unmarshal + - functions/collections/Where + - functions/collections/Sort + returnType: map + signatures: [SITE.Data] +--- + +Use the `Data` method on a `Site` object to access data within the data directory, or within any directory [mounted] to the data directory. Supported data formats include JSON, TOML, YAML, and XML. + +[mounted]: /hugo-modules/configuration/#module-configuration-mounts + +{{% note %}} +Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the data directory. You cannot access data within CSV files using this method. + +[`transform.Unmarshal`]: /functions/transform/unmarshal +{{% /note %}} + +Consider this data directory: + +```text +data/ +├── books/ +│ ├── fiction.yaml +│ └── nonfiction.yaml +├── films.json +├── paintings.xml +└── sculptures.toml +``` + +And these data files: + +{{< code file="data/books/fiction.yaml" lang=yaml >}} +- title: The Hunchback of Notre Dame + author: Victor Hugo + isbn: 978-0140443530 +- title: Les Misérables + author: Victor Hugo + isbn: 978-0451419439 +{{< /code >}} + +{{< code file="data/books/nonfiction.yaml" lang=yaml >}} +- title: The Ancien Régime and the Revolution + author: Alexis de Tocqueville + isbn: 978-0141441641 +- title: Interpreting the French Revolution + author: François Furet + isbn: 978-0521280495 +{{< /code >}} + +Access the data by [chaining] the [identifiers]: + +```go-html-template +{{ range $category, $books := .Site.Data.books }} +

{{ $category | title }}

+
    + {{ range $books }} +
  • {{ .title }} ({{ .isbn }})
    • + {{ end }} +
+{{ end }} +``` + +Hugo renders this to: + +```html +

Fiction

+
    +
  • The Hunchback of Notre Dame (978-0140443530)
    • +
  • Les Misérables (978-0451419439)
    • +
+

Nonfiction

+
    +
  • The Ancien Régime and the Revolution (978-0141441641)
    • +
  • Interpreting the French Revolution (978-0521280495)
    • +
+``` + +To limit the listing to fiction, and sort by title: + +```go-html-template +
    + {{ range sort .Site.Data.books.fiction "title" }} +
  • {{ .title }} ({{ .author }})
    • + {{ end }} +
+``` + +To find a fiction book by ISBN: + +```go-html-template +{{ range where .Site.Data.books.fiction "isbn" "978-0140443530" }} +
  • {{ .title }} ({{ .author }})
    • +{{ end }} +``` + +In the template examples above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function: + +[`index`]: /functions/collections/indexfunction +[chaining]: /getting-started/glossary/#chain +[identifiers]: /getting-started/glossary/#identifier diff --git a/content/en/methods/site/GetPage.md b/content/en/methods/site/GetPage.md new file mode 100644 index 000000000..1e949f37c --- /dev/null +++ b/content/en/methods/site/GetPage.md @@ -0,0 +1,109 @@ +--- +title: GetPage +description: Returns a Page object from the given path. +categories: [] +keywords: [] +action: + related: + - methods/page/GetPage + returnType: hugolib.pageState + signatures: [SITE.GetPage PATH] +toc: true +--- + +The `GetPage` method is also available on `Page` objects, allowing you to specify a path relative to the current page. See [details]. + +[details]: /methods/page/getpage + +When using the `GetPage` method on a `Site` object, specify a path relative to the content directory. + +If Hugo cannot resolve the path to a page, the method returns nil. + +Consider this content structure: + +```text +content/ +├── works/ +│ ├── paintings/ +│ │ ├── _index.md +│ │ ├── starry-night.md +│ │ └── the-mona-lisa.md +│ ├── sculptures/ +│ │ ├── _index.md +│ │ ├── david.md +│ │ └── the-thinker.md +│ └── _index.md +└── _index.md +``` + +This home page template: + +```go-html-template +{{ with .Site.GetPage "/works/paintings" }} +
      + {{ range .Pages }} +
    • {{ .Title }} by {{ .Params.artist }}
      • + {{ end }} +
    +{{ end }} +``` + +Is rendered to: + +```html +
      +
    • Starry Night by Vincent van Gogh
      • +
    • The Mona Lisa by Leonardo da Vinci
      • +
    +``` + +To get a regular page instead of a section page: + +```go-html-template +{{ with .Site.GetPage "/works/paintings/starry-night" }} + {{ .Title }} → Starry Night + {{ .Params.artist }} → Vincent van Gogh +{{ end }} +``` + +## Multilingual projects + +With multilingual projects, the `GetPage` method on a `Site` object resolves the given path to a page in the current language. + +To get a page from a different language, query the `Sites` object: + +```go-html-template +{{ with where .Site.Sites "Language.Lang" "eq" "de" }} + {{ with index . 0 }} + {{ with .GetPage "/works/paintings/starry-night" }} + {{ .Title }} → Sternenklare Nacht + {{ end }} + {{ end }} +{{ end }} +``` + +## Page bundles + +Consider this content structure: + +```text +content/ +├── headless/ +│ ├── a.jpg +│ ├── b.jpg +│ ├── c.jpg +│ └── index.md <-- front matter: headless = true +└── _index.md +``` + +In the home page template, use the `GetPage` method on a `Site` object to render all the images in the headless [page bundle]: + +```go-html-template +{{ with .Site.GetPage "/headless" }} + {{ range .Resources.ByType "image" }} + + {{ end }} +{{ end }} +``` + +[page bundle]: /getting-started/glossary/#page-bundle diff --git a/content/en/methods/site/Home.md b/content/en/methods/site/Home.md new file mode 100644 index 000000000..52612dd12 --- /dev/null +++ b/content/en/methods/site/Home.md @@ -0,0 +1,25 @@ +--- +title: Home +description: Returns the home Page object for the given site. +categories: [] +keywords: [] +action: + related: [] + returnType: hugolib.pageState + signatures: [SITE.Home] +--- + +This method is useful for obtaining a link to the home page. + +Site configuration: + +{{< code-toggle file=hugo >}} +baseURL = 'https://example.org/docs/' +{{< /code-toggle >}} + +Template: + +```go-html-template +{{ .Site.Home.Permalink }} → https://example.org/docs/ +{{ .Site.Home.RelPermalink }} → /docs/ +``` diff --git a/content/en/methods/site/IsMultiLingual.md b/content/en/methods/site/IsMultiLingual.md new file mode 100644 index 000000000..61cc5e462 --- /dev/null +++ b/content/en/methods/site/IsMultiLingual.md @@ -0,0 +1,34 @@ +--- +title: IsMultiLingual +description: Reports whether the site is multilingual. +categories: [] +keywords: [] +action: + related: [] + returnType: bool + signatures: [SITE.IsMultiLingual] +--- + +Site configuration: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'de' +defaultContentLanguageInSubdir = true +[languages] + [languages.de] + languageCode = 'de-DE' + languageName = 'Deutsch' + title = 'Projekt Dokumentation' + weight = 1 + [languages.en] + languageCode = 'en-US' + languageName = 'English' + title = 'Project Documentation' + weight = 2 +{{< /code-toggle >}} + +Template: + +```go-html-template +{{ .Site.IsMultiLingual }} → true +``` diff --git a/content/en/methods/site/Language.md b/content/en/methods/site/Language.md new file mode 100644 index 000000000..1babc099b --- /dev/null +++ b/content/en/methods/site/Language.md @@ -0,0 +1,83 @@ +--- +title: Language +description: Returns the language object for the given site. +categories: [] +keywords: [] +action: + related: + - methods/page/language + returnType: langs.Language + signatures: [SITE.Language] +toc: true +--- + +The `Language` method on a `Site` object returns the language object for the given site. The language object points to the language definition in the site configuration. + +You can also use the `Language` method on a `Page` object. See [details]. + +## Methods + +The examples below assume the following in your site configuration: + +{{< code-toggle file=hugo >}} +[languages.de] +languageCode = 'de-DE' +languageDirection = 'ltr' +languageName = 'Deutsch' +weight = 1 +{{< /code-toggle >}} + +Lang +: (`string`) The language tag as defined by [RFC 5646]. + +```go-html-template +{{ .Site.Language.Lang }} → de +``` + +LanguageCode +: (`string`) The language code from the site configuration. + +```go-html-template +{{ .Site.Language.LanguageCode }} → de-DE +``` + +LanguageDirection +: (`string`) The language direction from the site configuration, either `ltr` or `rtl`. + +```go-html-template +{{ .Site.Language.LanguageDirection }} → ltr +``` + +LanguageName +: (`string`) The language name from the site configuration. + +```go-html-template +{{ .Site.Language.LanguageName }} → Deutsch +``` + +Weight +: (`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object. + +```go-html-template +{{ .Site.Language.Weight }} → 1 +``` + +## Example + +Some of the methods above are commonly used in a base template as attributes for the `html` element. + +```go-html-template +{{ jsonify (dict "indent" " ") .Site.Languages }} +``` + +With this site configuration: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'de' +defaultContentLanguageInSubdir = false + +[languages.de] +languageCode = 'de-DE' +languageDirection = 'ltr' +languageName = 'Deutsch' +title = 'Projekt Dokumentation' +weight = 1 + +[languages.en] +languageCode = 'en-US' +languageDirection = 'ltr' +languageName = 'English' +title = 'Project Documentation' +weight = 2 +{{< /code-toggle >}} + +This template: + +```go-html-template +
      + {{ range .Site.Languages }} +
    • {{ .Title }} ({{ .LanguageName }})
      • + {{ end }} +
    +``` + +Is rendered to: + +```html +
      +
    • Projekt Dokumentation (Deutsch)
      • +
    • Project Documentation (English)
      • +
    +``` diff --git a/content/en/methods/site/LastChange.md b/content/en/methods/site/LastChange.md new file mode 100644 index 000000000..aceee691d --- /dev/null +++ b/content/en/methods/site/LastChange.md @@ -0,0 +1,21 @@ +--- +title: LastChange +description: Returns the last modification date of site content. +categories: [] +keywords: [] +action: + related: [] + returnType: time.Time + signatures: [SITE.LastChange] +--- + +The `LastChange` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example: + +```go-html-template +{{ .Site.LastChange | time.Format ":date_long" }} → October 16, 2023 + +``` + +[`time.Time`]: https://pkg.go.dev/time#Time +[functions]: /functions/time +[methods]: /methods/time diff --git a/content/en/methods/site/MainSections.md b/content/en/methods/site/MainSections.md new file mode 100644 index 000000000..251fe1a97 --- /dev/null +++ b/content/en/methods/site/MainSections.md @@ -0,0 +1,55 @@ +--- +title: MainSections +description: Returns a slice of the main section names as defined in the site configuration, falling back to the top level section with the most pages. +categories: [] +keywords: [] +action: + related: [] + returnType: '[]string' + signatures: [SITE.MainSections] +--- + +Site configuration: + +{{< code-toggle file=hugo >}} +[params] +mainSections = ['books','films'] +{{< /code-toggle >}} + +Template: + +```go-html-template +{{ .Site.MainSections }} → [books films] +``` + +If `params.mainSections` is not defined in the site configuration, this method returns a slice with one element---the top level section with the most pages. + +With this content structure, the "films" section has the most pages: + +```text +content/ +├── books/ +│ ├── book-1.md +│ └── book-2.md +├── films/ +│ ├── film-1.md +│ ├── film-2.md +│ └── film-3.md +└── _index.md +``` + +Template: + +```go-html-template +{{ .Site.MainSections }} → [films] +``` + +When creating a theme, instead of hardcoding section names when listing the most relevant pages on the front page, instruct site authors to set `params.mainSections` in their site configuration. + +Then your home page template can do something like this: + +```go-html-template +{{ range where .Site.RegularPages "Section" "in" .Site.MainSections }} +

    {{ .LinkTitle }}

    +{{ end }} +``` diff --git a/content/en/methods/site/Menus.md b/content/en/methods/site/Menus.md new file mode 100644 index 000000000..1967a9211 --- /dev/null +++ b/content/en/methods/site/Menus.md @@ -0,0 +1,94 @@ +--- +title: Menus +description: Returns a collection of menu objects for the given site. +categories: [] +keywords: [] +action: + related: + - methods/page/IsMenuCurrent + - methods/page/HasMenuCurrent + returnType: navigation.Menus + signatures: [SITE.Menus] +--- + +The `Menus` method on a `Site` object returns a collection of menus, where each menu contains one or more entries, either flat or nested. Each entry points to a page within the site, or to an external resource. + +{{% note %}} +Menus can be defined and localized in several ways. Please see the [menus] section for a complete explanation and examples. + +[menus]: /content-management/menus/ +{{% /note %}} + +A site can have multiple menus. For example, a main menu and a footer menu: + +{{< code-toggle file=hugo >}} +[[menu.main]] +name = 'Home' +pageRef = '/' +weight = 10 + +[[menu.main]] +name = 'Books' +pageRef = '/books' +weight = 20 + +[[menu.main]] +name = 'Films' +pageRef = '/films' +weight = 30 + +[[menu.footer]] +name = 'Legal' +pageRef = '/legal' +weight = 10 + +[[menu.footer]] +name = 'Privacy' +pageRef = '/privacy' +weight = 20 +{{< /code-toggle >}} + +This template renders the main menu: + +```go-html-template +{{ with site.Menus.main }} + +{{ end }} +``` + +When viewing the home page, the result is: + +```html + +``` + +When viewing the "books" page, the result is: + +```html + +``` + +You will typically render a menu using a partial template. As the active menu entry will be different on each page, use the [`partial`] function to call the template. Do not use the [`partialCached`] function. + +The example above is simplistic. Please see the [menu templates] section for more information. + +[menu templates]: /templates/menu-templates + +[`partial`]: /functions/partials/include +[`partialCached`]: /functions/partials/includecached diff --git a/content/en/methods/site/Pages.md b/content/en/methods/site/Pages.md new file mode 100644 index 000000000..583e98c11 --- /dev/null +++ b/content/en/methods/site/Pages.md @@ -0,0 +1,26 @@ +--- +title: Pages +description: Returns a collection of all pages. +categories: [] +keywords: [] +action: + related: + - methods/site/AllPages + - methods/site/RegularPages + - methods/site/Sections + returnType: page.Pages + signatures: [SITE.Pages] +--- + +This method returns all page [kinds] in the current language. That includes the home page, section pages, taxonomy pages, term pages, and regular pages. + +In most cases you should use the [`RegularPages`] method instead. + +[`RegularPages`]: methods/site/regularpages +[kinds]: /getting-started/glossary/#page-kind + +```go-html-template +{{ range .Site.Pages }} +

    {{ .LinkTitle }}

    +{{ end }} +``` diff --git a/content/en/methods/site/Params.md b/content/en/methods/site/Params.md new file mode 100644 index 000000000..518d93bf3 --- /dev/null +++ b/content/en/methods/site/Params.md @@ -0,0 +1,47 @@ +--- +title: Params +description: Returns a map of custom parameters as defined in the site configuration. +categories: [] +keywords: [] +action: + related: + - functions/collections/indexFunction + - methods/page/Params + - methods/page/Param + returnType: maps.Params + signatures: [SITE.Params] +--- + +With this site configuration: + +{{< code-toggle file=hugo >}} +[params] + subtitle = 'The Best Widgets on Earth' + copyright-year = '2023' + [params.author] + email = 'jsmith@example.org' + name = 'John Smith' + [params.layouts] + rfc_1123 = 'Mon, 02 Jan 2006 15:04:05 MST' + rfc_3339 = '2006-01-02T15:04:05-07:00' +{{< /code-toggle >}} + +Access the custom parameters by [chaining] the [identifiers]: + +```go-html-template +{{ .Site.Params.subtitle }} → The Best Widgets on Earth +{{ .Site.Params.author.name }} → John Smith + +{{ $layout := .Site.Params.layouts.rfc_1123 }} +{{ .Site.LastChange.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT +``` + +In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function: + +```go-html-template +{{ index .Site.Params "copyright-year" }} → 2023 +``` + +[`index`]: /functions/collections/indexfunction +[chaining]: /getting-started/glossary/#chain +[identifiers]: /getting-started/glossary/#identifier diff --git a/content/en/methods/site/RegularPages.md b/content/en/methods/site/RegularPages.md new file mode 100644 index 000000000..744eb8a13 --- /dev/null +++ b/content/en/methods/site/RegularPages.md @@ -0,0 +1,38 @@ +--- +title: RegularPages +description: Returns a collection of all regular pages. +categories: [] +keywords: [] +action: + related: + - methods/site/AllPages + - methods/site/RegularPages + - methods/site/Sections + returnType: page.Pages + signatures: [SITE.RegularPages] +--- + +```go-html-template +{{ range .Site.RegularPages }} +

    {{ .LinkTitle }}

    +{{ end }} +``` + +By default, Hugo sorts page collections by: + +1. The page `weight` as defined in front matter +1. The page `date` as defined in front matter +1. The page `linkTitle` as defined in front matter +1. The file path + +If the `linkTitle` is not defined, Hugo evaluates the `title` instead. + +To change the sort order, use any of the `Pages` [sorting methods]. For example: + +```go-html-template +{{ range .Site.RegularPages.ByTitle }} +

    {{ .LinkTitle }}

    +{{ end }} +``` + +[sorting methods]: /methods/pages/ diff --git a/content/en/methods/site/Sections.md b/content/en/methods/site/Sections.md new file mode 100644 index 000000000..a397c5926 --- /dev/null +++ b/content/en/methods/site/Sections.md @@ -0,0 +1,41 @@ +--- +title: Sections +description: Returns a collection of first level section pages. +categories: [] +keywords: [] +action: + related: + - methods/site/AllPages + - methods/site/Pages + - methods/site/RegularPages + returnType: page.Pages + signatures: [SITE.Sections] +--- + +Given this content structure: + +```text +content/ +├── books/ +│ ├── book-1.md +│ └── book-2.md +├── films/ +│ ├── film-1.md +│ └── film-2.md +└── _index.md +``` + +This template: + +```go-html-template +{{ range .Site.Sections }} +

    {{ .LinkTitle }}

    +{{ end }} +``` + +Is rendered to: + +```html +

    Books

    +

    Films

    +``` diff --git a/content/en/methods/site/Sites.md b/content/en/methods/site/Sites.md new file mode 100644 index 000000000..f7bafd3ed --- /dev/null +++ b/content/en/methods/site/Sites.md @@ -0,0 +1,66 @@ +--- +title: Sites +description: Returns a collection of all Site objects, one for each language, ordered by language weight. +categories: [] +keywords: [] +action: + related: [] + returnType: page.Sites + signatures: [SITE.Sites] +--- + +With this site configuration: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'de' +defaultContentLanguageInSubdir = false + +[languages.de] +languageCode = 'de-DE' +languageDirection = 'ltr' +languageName = 'Deutsch' +title = 'Projekt Dokumentation' +weight = 1 + +[languages.en] +languageCode = 'en-US' +languageDirection = 'ltr' +languageName = 'English' +title = 'Project Documentation' +weight = 2 +{{< /code-toggle >}} + +This template: + +```go-html-template + +``` + +Produces a list of links to each home page: + +```html + +``` + +To render a link to home page of the primary (first) language: + +```go-html-template +{{ with .Site.Sites.First }} + {{ .Title }} +{{ end }} +``` + +This is equivalent to: + +```go-html-template +{{ with index .Site.Sites 0 }} + {{ .Title }} +{{ end }} +``` diff --git a/content/en/methods/site/Taxonomies.md b/content/en/methods/site/Taxonomies.md new file mode 100644 index 000000000..72bfc75d5 --- /dev/null +++ b/content/en/methods/site/Taxonomies.md @@ -0,0 +1,99 @@ +--- +title: Taxonomies +description: Returns a data structure containing the site's taxonomy objects, the terms within each taxonomy object, and the pages to which the terms are assigned. +categories: [] +keywords: [] +action: + related: [] + returnType: page.TaxonomyList + signatures: [SITE.Taxonomies] +--- + +Conceptually, the `Taxonomies` method on a `Site` object returns a data structure such as: + +{{< code-toggle >}} +taxonomy a: + - term 1: + - page 1 + - page 2 + - term 2: + - page 1 +taxonomy b: + - term 1: + - page 2 + - term 2: + - page 1 + - page 2 +{{< /code-toggle >}} + +For example, on a book review site you might create two taxonomies; one for genres and another for authors. + +With this site configuration: + +{{< code-toggle file=hugo >}} +[taxonomies] +genre = 'genres' +author = 'authors' +{{< /code-toggle >}} + +And this content structure: + +```text +content/ +├── books/ +│ ├── and-then-there-were-none.md --> genres: suspense +│ ├── death-on-the-nile.md --> genres: suspense +│ └── jamaica-inn.md --> genres: suspense, romance +│ └── pride-and-prejudice.md --> genres: romance +└── _index.md +``` + +Conceptually, the taxonomies data structure looks like: + +{{< code-toggle >}} +genres: + - suspense: + - And Then There Were None + - Death on the Nile + - Jamaica Inn + - romance: + - Jamaica Inn + - Pride and Prejudice +authors: + - achristie: + - And Then There Were None + - Death on the Nile + - ddmaurier: + - Jamaica Inn + - jausten: + - Pride and Prejudice +{{< /code-toggle >}} + + +To list the "suspense" books: + +```go-html-template +
      + {{ range .Site.Taxonomies.genres.suspense }} +
    • {{ .LinkTitle }}
      • + {{ end }} +
    +``` + +Hugo renders this to: + +```html + +``` + +{{% note %}} +Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages. + +Please see the [taxonomies] section for a complete explanation and examples. + +[taxonomies]: content-management/taxonomies/ +{{% /note %}} diff --git a/content/en/methods/site/Title.md b/content/en/methods/site/Title.md new file mode 100644 index 000000000..a357286c1 --- /dev/null +++ b/content/en/methods/site/Title.md @@ -0,0 +1,22 @@ +--- +title: Title +description: Returns the title as defined in the site configuration. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [SITE.Title] +--- + +Site configuration: + +{{< code-toggle file=hugo >}} +title = 'My Documentation Site' +{{< /code-toggle >}} + +Template: + +```go-html-template +{{ .Site.Title }} → My Documentation Site +``` diff --git a/content/en/methods/site/_index.md b/content/en/methods/site/_index.md new file mode 100644 index 000000000..39f66f308 --- /dev/null +++ b/content/en/methods/site/_index.md @@ -0,0 +1,12 @@ +--- +title: Site methods +linkTitle: Site +description: Use these methods with Site objects. +categories: [] +keywords: [] +menu: + docs: + parent: methods +--- + +Use these methods with Site objects. A multilingual project will have two or more sites, one for each language. diff --git a/content/en/methods/taxonomy/Alphabetical.md b/content/en/methods/taxonomy/Alphabetical.md new file mode 100644 index 000000000..2c07fbef4 --- /dev/null +++ b/content/en/methods/taxonomy/Alphabetical.md @@ -0,0 +1,78 @@ +--- +title: Alphabetical +description: Returns an ordered taxonomy, sorted alphabetically by term. +categories: [] +keywords: [] +action: + related: + - methods/taxonomy/ByCount + returnType: page.OrderedTaxonomy + signatures: [TAXONOMY.Alphabetical] +toc: true +--- + +The `Alphabetical` method on a `Taxonomy` object returns an [ordered taxonomy], sorted alphabetically by [term]. + +While a `Taxonomy` object is a [map], an ordered taxonomy is a [slice], where each element is an object that contains the term and a slice of its [weighted pages]. + +{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} + +## Get the ordered taxonomy + +Now that we have captured the “genres” Taxonomy object, let’s get the ordered taxonomy sorted alphabetically by term: + +```go-html-template +{{ $taxonomyObject.Alphabetical }} +``` + +To reverse the sort order: + +```go-html-template +{{ $taxonomyObject.Alphabetical.Reverse }} +``` + +To inspect the data structure: + +```go-html-template +
    {{ jsonify (dict "indent" "  ") $taxonomyObject.Alphabetical }}
    +``` + +{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}} + +## Example + +With this template: + +```go-html-template +{{ range $taxonomyObject.Alphabetical }} +

    {{ .Page.LinkTitle }} ({{ .Count }})

    + +{{ end }} +``` + +Hugo renders: + +```html +

    romance (2)

    + +

    suspense (3)

    + +``` + +[ordered taxonomy]: /getting-started/glossary/#ordered-taxonomy +[term]: /getting-started/glossary/#term +[map]: /getting-started/glossary/#map +[slice]: /getting-started/glossary/#slice +[term]: /getting-started/glossary/#term +[weighted pages]: /getting-started/glossary/#weighted-page diff --git a/content/en/methods/taxonomy/ByCount.md b/content/en/methods/taxonomy/ByCount.md new file mode 100644 index 000000000..d0caa7d2c --- /dev/null +++ b/content/en/methods/taxonomy/ByCount.md @@ -0,0 +1,78 @@ +--- +title: ByCount +description: Returns an ordered taxonomy, sorted by the number of pages associated with each term. +categories: [] +keywords: [] +action: + related: + - methods/taxonomy/Alphabetical + returnType: page.OrderedTaxonomy + signatures: [TAXONOMY.ByCount] +toc: true +--- + +The `ByCount` method on a `Taxonomy` object returns an [ordered taxonomy], sorted by the number of pages associated with each [term]. + +While a `Taxonomy` object is a [map], an ordered taxonomy is a [slice], where each element is an object that contains the term and a slice of its [weighted pages]. + +{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} + +## Get the ordered taxonomy + +Now that we have captured the “genres” Taxonomy object, let’s get the ordered taxonomy sorted by the number of pages associated with each term: + +```go-html-template +{{ $taxonomyObject.ByCount }} +``` + +To reverse the sort order: + +```go-html-template +{{ $taxonomyObject.ByCount.Reverse }} +``` + +To inspect the data structure: + +```go-html-template +
    {{ jsonify (dict "indent" "  ") $taxonomyObject.ByCount }}
    +``` + +{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}} + +## Example + +With this template: + +```go-html-template +{{ range $taxonomyObject.ByCount }} +

    {{ .Page.LinkTitle }} ({{ .Count }})

    + +{{ end }} +``` + +Hugo renders: + +```html +

    suspense (3)

    + +

    romance (2)

    + +``` + +[ordered taxonomy]: /getting-started/glossary/#ordered-taxonomy +[term]: /getting-started/glossary/#term +[map]: /getting-started/glossary/#map +[slice]: /getting-started/glossary/#slice +[term]: /getting-started/glossary/#term +[weighted pages]: /getting-started/glossary/#weighted-page diff --git a/content/en/methods/taxonomy/Count.md b/content/en/methods/taxonomy/Count.md new file mode 100644 index 000000000..50f705ec9 --- /dev/null +++ b/content/en/methods/taxonomy/Count.md @@ -0,0 +1,26 @@ +--- +title: Count +description: Returns the number of number of weighted pages to which the given term has been assigned. +categories: [] +keywords: [] +action: + related: [] + returnType: int + signatures: [TAXONOMY.Count TERM] +toc: true +--- + +The `Count` method on a `Taxonomy` object returns the number of number of [weighted pages] to which the given [term] has been assigned. + +{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} + +## Count the weighted pages + +Now that we have captured the "genres" `Taxonomy` object, let's count the number of weighted pages to which the "suspense" term has been assigned: + +```go-html-template +{{ $taxonomyObject.Count "suspense" }} → 3 +``` + +[weighted pages]: /getting-started/glossary/#weighted-page +[term]: /getting-started/glossary/#term diff --git a/content/en/methods/taxonomy/Get.md b/content/en/methods/taxonomy/Get.md new file mode 100644 index 000000000..3bac86f08 --- /dev/null +++ b/content/en/methods/taxonomy/Get.md @@ -0,0 +1,72 @@ +--- +title: Get +description: Returns a slice of weighted pages to which the given term has been assigned. +categories: [] +keywords: [] +action: + related: [] + returnType: page.WeightedPages + signatures: [TAXONOMY.Get TERM] +toc: true +--- + +The `Get` method on a `Taxonomy` object returns a slice of [weighted pages] to which the given [term] has been assigned. + +{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} + +## Get the weighted pages + +Now that we have captured the "genres" `Taxonomy` object, let's get the weighted pages to which the "suspense" term has been assigned: + +```go-html-template +{{ $weightedPages := $taxonomyObject.Get "suspense" }} +``` + +The above is equivalent to: + +```go-html-template +{{ $weightedPages := $taxonomyObject.suspense }} +``` + +But, if the term is not a valid [identifier], you cannot use the [chaining] syntax. For example, this will throw an error because the identifier contains a hyphen: + +```go-html-template +{{ $weightedPages := $taxonomyObject.my-genre }} +``` + +You could also use the [`index`] function, but the syntax is more verbose: + +```go-html-template +{{ $weightedPages := index $taxonomyObject "my-genre" }} +``` + +To inspect the data structure: + +```go-html-template +
    {{ jsonify (dict "indent" "  ") $weightedPages }}
    +``` + +## Example + +With this template: + +```go-html-template +{{ $weightedPages := $taxonomyObject.Get "suspense" }} +{{ range $weightedPages }} +

    {{ .LinkTitle }}

    +{{ end }} +``` + +Hugo renders: + +```html +

    Jamaica inn

    +

    Death on the nile

    +

    And then there were none

    +``` + +[chaining]: /getting-started/glossary/#chain +[`index`]: /functions/collections/indexfunction +[identifier]: /getting-started/glossary/#identifier +[term]: /getting-started/glossary/#term +[weighted pages]: /getting-started/glossary/#weighted-page diff --git a/content/en/methods/taxonomy/_common/_index.md b/content/en/methods/taxonomy/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/methods/taxonomy/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + + diff --git a/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md b/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md new file mode 100644 index 000000000..d9bd14364 --- /dev/null +++ b/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md @@ -0,0 +1,68 @@ +--- +# Do not remove front matter. +--- + +Before we can use a `Taxonomy` method, we need to capture a `Taxonomy` object. + +## Capture a taxonomy object + +Consider this site configuration: + +{{< code-toggle file=hugo >}} +[taxonomies] +genre = 'genres' +author = 'authors' +{{< /code-toggle >}} + +And this content structure: + +```text +content/ +├── books/ +│ ├── and-then-there-were-none.md --> genres: suspense +│ ├── death-on-the-nile.md --> genres: suspense +│ └── jamaica-inn.md --> genres: suspense, romance +│ └── pride-and-prejudice.md --> genres: romance +└── _index.md +``` + +To capture the "genres" taxonomy object from within any template, use the [`Taxonomies`] method on a `Site` object. + +```go-html-template +{{ $taxonomyObject := .Site.Taxonomies.genres }} +``` + +To capture the "genres" taxonomy object when rendering its page with a taxonomy template, use the [`Terms`] method on the page's [`Data`] object: + +{{< code file="layouts/_default/taxonomy.html" lang=go-html-template >}} +{{ $taxonomyObject := .Data.Terms }} +{{< /code >}} + +To inspect the data structure: + +```go-html-template +
    {{ jsonify (dict "indent" "  ") $taxonomyObject }}
    +``` + +Although the [`Alphabetical`] and [`ByCount`] methods provide a better data structure for ranging through the taxonomy, you can render the weighted pages by term directly from the `Taxonomy` object: + +```go-html-template +{{ range $term, $weightedPages := $taxonomyObject }} +

    {{ .Page.LinkTitle }}

    + +{{ end }} +``` + +In the example above, the first anchor element is a link to the term page. + + +[`Alphabetical`]: /methods/taxonomy/alphabetical +[`ByCount`]: /methods/taxonomy/bycount + +[`data`]: /methods/page/data +[`terms`]: /methods/page/data/#in-a-taxonomy-template +[`taxonomies`]: /methods/site/taxonomies diff --git a/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md b/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md new file mode 100644 index 000000000..57c9e8e29 --- /dev/null +++ b/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md @@ -0,0 +1,25 @@ +--- +# Do not remove front matter. +--- + +An ordered taxonomy is a slice, where each element is an object that contains the term and a slice of its weighted pages. + +Each element of the slice provides these methods: + +Count +: (`int`) Returns the number of pages to which the term is assigned. + +Page +: (`hugolib.pageState`) Returns the term's `Page` object, useful for linking to the term page. + +Pages +: (`page.Pages`) Returns a `Pages` object containing the `Page` objects to which the term is assigned, sorted by [taxonomic weight]. To sort or group, use any of the [methods] available to the `Pages` object. For example, sort by the last modification date. + +Term +: (`string`) Returns the term name. + +WeightedPages +: (`page.WeightedPages`) Returns a slice of weighted pages to which the term is assigned, sorted by [taxonomic weight]. The `Pages` method above is more flexible, allowing you to sort and group. + +[methods]: /methods/pages +[taxonomic weight]: /getting-started/glossary/#taxonomic-weight diff --git a/content/en/methods/taxonomy/_index.md b/content/en/methods/taxonomy/_index.md new file mode 100644 index 000000000..e7eb57834 --- /dev/null +++ b/content/en/methods/taxonomy/_index.md @@ -0,0 +1,12 @@ +--- +title: Taxonomy methods +linkTitle: Taxonomy +description: Use these methods with Taxonomy objects. +keywords: [] +menu: + docs: + identifier: + parent: methods +--- + +Use these methods with Taxonomy objects. diff --git a/content/en/methods/time/Add.md b/content/en/methods/time/Add.md new file mode 100644 index 000000000..8fd755244 --- /dev/null +++ b/content/en/methods/time/Add.md @@ -0,0 +1,23 @@ +--- +title: Add +description: Returns the given time plus the given duration. +categories: [] +keywords: [] +action: + related: + - functions/time/AsTime + - functions/time/Duration + - functions/time/ParseDuration + returnType: time.Time + signatures: [TIME.Add DURATION] +--- + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} + +{{ $d1 = time.ParseDuration "3h20m10s" }} +{{ $d2 = time.ParseDuration "-3h20m10s" }} + +{{ $t.Add $d1 }} → 2023-01-28 03:05:08 -0800 PST +{{ $t.Add $d2 }} → 2023-01-27 20:24:48 -0800 PST +``` diff --git a/content/en/functions/AddDate.md b/content/en/methods/time/AddDate.md similarity index 88% rename from content/en/functions/AddDate.md rename to content/en/methods/time/AddDate.md index 7f5b39b16..8537d6e25 100644 --- a/content/en/functions/AddDate.md +++ b/content/en/methods/time/AddDate.md @@ -1,16 +1,14 @@ --- -title: .AddDate +title: AddDate description: Returns the time corresponding to adding the given number of years, months, and days to the given time.Time value. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: [] returnType: time.Time - signatures: [.AddDate YEARS MONTHS DAYS] -relatedFunctions: [] + signatures: [TIME.AddDate YEARS MONTHS DAYS] +aliases: [/functions/adddate] --- ```go-html-template diff --git a/content/en/methods/time/After.md b/content/en/methods/time/After.md new file mode 100644 index 000000000..0aeeb38d8 --- /dev/null +++ b/content/en/methods/time/After.md @@ -0,0 +1,20 @@ +--- +title: After +description: Reports whether TIME1 is after TIME2. +categories: [] +keywords: [] +action: + related: + - methods/time/Before + - methods/time/After + - functions/time/AsTime + returnType: bool + signatures: [TIME1.After TIME2] +--- + +```go-html-template +{{ $t1 := time.AsTime "2023-01-01T17:00:00-08:00" }} +{{ $t2 := time.AsTime "2010-01-01T17:00:00-08:00" }} + +{{ $t1.After $t2 }} → true +``` diff --git a/content/en/methods/time/Before.md b/content/en/methods/time/Before.md new file mode 100644 index 000000000..c3d582860 --- /dev/null +++ b/content/en/methods/time/Before.md @@ -0,0 +1,19 @@ +--- +title: Before +description: Reports whether TIME1 is before TIME2. +categories: [] +keywords: [] +action: + related: + - methods/time/After + - methods/time/Equal + - functions/time/AsTime + returnType: bool + signatures: [TIME1.Before TIME2] +--- + +```go-html-template +{{ $t1 := time.AsTime "2023-01-01T17:00:00-08:00" }} +{{ $t2 := time.AsTime "2030-01-01T17:00:00-08:00" }} + +{{ $t1.Before $t2 }} → true diff --git a/content/en/methods/time/Day.md b/content/en/methods/time/Day.md new file mode 100644 index 000000000..1173b8489 --- /dev/null +++ b/content/en/methods/time/Day.md @@ -0,0 +1,21 @@ +--- +title: Day +description: Returns the day of the month of the given time.Time value. +categories: [] +keywords: [] +action: + related: + - methods/time/Year + - methods/time/Month + - methods/time/Hour + - methods/time/Minute + - methods/time/Second + - functions/time/AsTime + returnType: int + signatures: [TIME.Day] +--- + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.Day }} → 27 +``` diff --git a/content/en/methods/time/Equal.md b/content/en/methods/time/Equal.md new file mode 100644 index 000000000..4d45a3ada --- /dev/null +++ b/content/en/methods/time/Equal.md @@ -0,0 +1,20 @@ +--- +title: Equal +description: Reports whether TIME1 is equal to TIME2. +categories: [] +keywords: [] +action: + related: + - methods/time/After + - methods/time/Before + - functions/time/AsTime + returnType: bool + signatures: [TIME1.Equal TIME2] +--- + +```go-html-template +{{ $t1 := time.AsTime "2023-01-01T17:00:00-08:00" }} +{{ $t2 := time.AsTime "2023-01-01T20:00:00-05:00" }} + +{{ $t1.Equal $t2 }} → true +``` diff --git a/content/en/functions/Format.md b/content/en/methods/time/Format.md similarity index 83% rename from content/en/functions/Format.md rename to content/en/methods/time/Format.md index e679cb2c4..c784c14aa 100644 --- a/content/en/functions/Format.md +++ b/content/en/methods/time/Format.md @@ -1,17 +1,18 @@ --- -title: .Format +title: Format description: Returns a formatted time.Time value. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/time/AsTime + - methods/time/UTC + - methods/time/Local returnType: string - signatures: [.Format LAYOUT] -relatedFunctions: [] + signatures: [TIME.Format LAYOUT] toc: true +aliases: [/methods/time/format] --- ```go-template @@ -28,7 +29,7 @@ To return a formatted and localized `time.Time` value, use the [`time.Format`] f [`time.Format`]: /functions/time/format {{% /note %}} -Use the `.Format` method with any `time.Time` value, including the four predefined front matter dates: +Use the `Format` method with any `time.Time` value, including the four predefined front matter dates: ```go-html-template {{ $format := "2 Jan 2006" }} @@ -41,13 +42,13 @@ Use the `.Format` method with any `time.Time` value, including the four predefin ## Layout string -{{% readfile file="/functions/_common/time-layout-string.md" %}} +{{% include "functions/_common/time-layout-string.md" %}} ## Examples Given this front matter: -{{< code-toggle fm=true copy=false >}} +{{< code-toggle fm=true >}} title = "About time" date = 2023-01-27T23:44:58-08:00 {{< /code-toggle >}} diff --git a/content/en/methods/time/Hour.md b/content/en/methods/time/Hour.md new file mode 100644 index 000000000..58ed00260 --- /dev/null +++ b/content/en/methods/time/Hour.md @@ -0,0 +1,21 @@ +--- +title: Hour +description: Returns the hour within the day of the given time.Time value, in the range [0, 23]. +categories: [] +keywords: [] +action: + related: + - methods/time/Year + - methods/time/Month + - methods/time/Day + - methods/time/Minute + - methods/time/Second + - functions/time/AsTime + returnType: int + signatures: [TIME.Hour] +--- + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.Hour }} → 23 +``` diff --git a/content/en/methods/time/IsDST.md b/content/en/methods/time/IsDST.md new file mode 100644 index 000000000..df2b84cae --- /dev/null +++ b/content/en/methods/time/IsDST.md @@ -0,0 +1,19 @@ +--- +title: IsDST +description: Reports whether the given time.Time value is in Daylight Savings Time. +categories: [] +keywords: [] +action: + related: + - functions/time/AsTime + returnType: bool + signatures: [TIME.IsDST] +--- + +```go-html-template +{{ $t1 := time.AsTime "2023-01-01T00:00:00-08:00" }} +{{ $t2 := time.AsTime "2023-07-01T00:00:00-07:00" }} + +{{ $t1.IsDST }} → false +{{ $t2.IsDST }} → true +``` diff --git a/content/en/methods/time/IsZero.md b/content/en/methods/time/IsZero.md new file mode 100644 index 000000000..2026f3b2e --- /dev/null +++ b/content/en/methods/time/IsZero.md @@ -0,0 +1,19 @@ +--- +title: IsZero +description: Reports whether the given time.Time value represents the zero time instant, January 1, year 1, 00:00:00 UTC. +categories: [] +keywords: [] +action: + related: + - functions/time/AsTime + returnType: bool + signatures: [TIME.IsZero] +--- + +````go-html-template +{{ $t1 := time.AsTime "2023-01-01T00:00:00-08:00" }} +{{ $t2 := time.AsTime "0001-01-01T00:00:00-00:00" }} + +{{ $t1.IsZero }} → false +{{ $t2.IsZero }} → true +``` diff --git a/content/en/methods/time/Local.md b/content/en/methods/time/Local.md new file mode 100644 index 000000000..bd40e3a44 --- /dev/null +++ b/content/en/methods/time/Local.md @@ -0,0 +1,17 @@ +--- +title: Local +description: Returns the given time.Time value with the location set to local time. +categories: [] +keywords: [] +action: + related: + - methods/time/UTC + - functions/time/AsTime + returnType: time.Time + signatures: [TIME.Local] +--- + +```go-html-template +{{ $t := time.AsTime "2023-01-28T07:44:58+00:00" }} +{{ $t.Local }} → 2023-01-27 23:44:58 -0800 PST +``` diff --git a/content/en/methods/time/Minute.md b/content/en/methods/time/Minute.md new file mode 100644 index 000000000..d482fab5d --- /dev/null +++ b/content/en/methods/time/Minute.md @@ -0,0 +1,21 @@ +--- +title: Minute +description: Returns the minute offset within the hour of the given time.Time value, in the range [0, 59]. +categories: [] +keywords: [] +action: + related: + - methods/time/Year + - methods/time/Month + - methods/time/Day + - methods/time/Hour + - methods/time/Second + - functions/time/AsTime + returnType: int + signatures: [TIME.Minute] +--- + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.Minute }} → 44 +``` diff --git a/content/en/methods/time/Month.md b/content/en/methods/time/Month.md new file mode 100644 index 000000000..08815afbd --- /dev/null +++ b/content/en/methods/time/Month.md @@ -0,0 +1,30 @@ +--- +title: Month +description: Returns the month of the year of the given time.Time value. +categories: [] +keywords: [] +action: + related: + - methods/time/Year + - methods/time/Day + - methods/time/Hour + - methods/time/Minute + - methods/time/Second + - functions/time/AsTime + returnType: time.Month + signatures: [TIME.Month] +--- + +To convert the time.Month value to a string: + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.Month.String }} → January +``` + +To convert the time.Month value to an integer. + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.Month | int }} → 1 +``` diff --git a/content/en/methods/time/Nanosecond.md b/content/en/methods/time/Nanosecond.md new file mode 100644 index 000000000..606143139 --- /dev/null +++ b/content/en/methods/time/Nanosecond.md @@ -0,0 +1,16 @@ +--- +title: Nanosecond +description: Returns the nanosecond offset within the second of the given time.Time value, in the range [0, 999999999]. +categories: [] +keywords: [] +action: + related: + - functions/time/AsTime + returnType: int + signatures: [TIME.Nanosecond] +--- + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.Nanosecond }} → 0 +``` diff --git a/content/en/methods/time/Second.md b/content/en/methods/time/Second.md new file mode 100644 index 000000000..e326c64bc --- /dev/null +++ b/content/en/methods/time/Second.md @@ -0,0 +1,21 @@ +--- +title: Second +description: Returns the second offset within the minute of the given time.Time value, in the range [0, 59]. +categories: [] +keywords: [] +action: + related: + - methods/time/Year + - methods/time/Month + - methods/time/Day + - methods/time/Hour + - methods/time/Minute + - functions/time/AsTime + returnType: int + signatures: [TIME.Second] +--- + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.Second }} → 58 +``` diff --git a/content/en/methods/time/Sub.md b/content/en/methods/time/Sub.md new file mode 100644 index 000000000..9678365eb --- /dev/null +++ b/content/en/methods/time/Sub.md @@ -0,0 +1,18 @@ +--- +title: Sub +description: Returns the duration computed by subtracting TIME2 from TIME1. +categories: [] +keywords: [] +action: + related: + - functions/time/AsTime + returnType: time.Duration + signatures: [TIME1.Sub TIME2] +--- + +```go-html-template +{{ $t1 := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t2 := time.AsTime "2023-01-26T22:34:38-08:00" }} + +{{ $t1.Sub $t2 }} → 25h10m20s +``` diff --git a/content/en/methods/time/UTC.md b/content/en/methods/time/UTC.md new file mode 100644 index 000000000..6fd7b526d --- /dev/null +++ b/content/en/methods/time/UTC.md @@ -0,0 +1,16 @@ +--- +title: UTC +description: Returns the given time.Time value with the location set to UTC. +categories: [] +keywords: [] +action: + related: + - methods/time/Local + - functions/time/AsTime + returnType: time.Time + signatures: [TIME.UTC] +--- + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.UTC }} → 2023-01-28 07:44:58 +0000 UTC diff --git a/content/en/methods/time/Unix.md b/content/en/methods/time/Unix.md new file mode 100644 index 000000000..fcfc661fe --- /dev/null +++ b/content/en/methods/time/Unix.md @@ -0,0 +1,21 @@ +--- +title: Unix +description: Returns the given time.Time value expressed as the number of seconds elapsed since January 1, 1970 UTC. +categories: [] +action: + related: + - methods/time/UnixMilli + - methods/time/UnixMicro + - methods/time/UnixNano + - functions/time/AsTime + returnType: int64 + signatures: [TIME.Unix] +aliases: [/functions/unix] +--- + +See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.Unix }} → 1674891898 +``` diff --git a/content/en/methods/time/UnixMicro.md b/content/en/methods/time/UnixMicro.md new file mode 100644 index 000000000..150497cd3 --- /dev/null +++ b/content/en/methods/time/UnixMicro.md @@ -0,0 +1,21 @@ +--- +title: UnixMicro +description: Returns the given time.Time value expressed as the number of microseconds elapsed since January 1, 1970 UTC. +categories: [] +keywords: [] +action: + related: + - methods/time/Unix + - methods/time/UnixMilli + - methods/time/UnixNano + - functions/time/AsTime + returnType: int64 + signatures: [TIME.UnixMicro] +--- + +See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.UnixMicro }} → 1674891898000000 +``` diff --git a/content/en/methods/time/UnixMilli.md b/content/en/methods/time/UnixMilli.md new file mode 100644 index 000000000..e5e90ba25 --- /dev/null +++ b/content/en/methods/time/UnixMilli.md @@ -0,0 +1,21 @@ +--- +title: UnixMilli +description: Returns the given time.Time value expressed as the number of milliseconds elapsed since January 1, 1970 UTC. +categories: [] +keywords: [] +action: + related: + - methods/time/Unix + - methods/time/UnixMicro + - methods/time/UnixNano + - functions/time/AsTime + returnType: int64 + signatures: [TIME.UnixMilli] +--- + +See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.UnixMilli }} → 1674891898000 +``` diff --git a/content/en/methods/time/UnixNano.md b/content/en/methods/time/UnixNano.md new file mode 100644 index 000000000..63db320a3 --- /dev/null +++ b/content/en/methods/time/UnixNano.md @@ -0,0 +1,21 @@ +--- +title: UnixNano +description: Returns the given time.Time value expressed as the number of nanoseconds elapsed since January 1, 1970 UTC. +categories: [] +keywords: [] +action: + related: + - methods/time/Unix + - methods/time/UnixMilli + - methods/time/UnixMicro + - functions/time/AsTime + returnType: int64 + signatures: [TIME.UnixNano] +--- + +See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.UnixNano }} → 1674891898000000000 +``` diff --git a/content/en/methods/time/Weekday.md b/content/en/methods/time/Weekday.md new file mode 100644 index 000000000..9e2349c80 --- /dev/null +++ b/content/en/methods/time/Weekday.md @@ -0,0 +1,24 @@ +--- +title: Weekday +description: Returns the day of the week of the given time.Time value. +categories: [] +keywords: [] +action: + related: + - functions/time/AsTime + returnType: time.Weekday + signatures: [TIME.Weekday] +--- + +To convert the time.Weekday value to a string: + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.Weekday.String }} → Friday +``` + +To convert the time.Weekday value to an integer. + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.Weekday | int }} → 5 diff --git a/content/en/methods/time/Year.md b/content/en/methods/time/Year.md new file mode 100644 index 000000000..b046896f4 --- /dev/null +++ b/content/en/methods/time/Year.md @@ -0,0 +1,21 @@ +--- +title: Year +description: Returns the year of the given time.Time value. +categories: [] +keywords: [] +action: + related: + - methods/time/Month + - methods/time/Day + - methods/time/Hour + - methods/time/Minute + - methods/time/Second + - functions/time/AsTime + returnType: int + signatures: [TIME.Year] +--- + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.Year }} → 2023 +``` diff --git a/content/en/methods/time/YearDay.md b/content/en/methods/time/YearDay.md new file mode 100644 index 000000000..40d7d6aab --- /dev/null +++ b/content/en/methods/time/YearDay.md @@ -0,0 +1,15 @@ +--- +title: YearDay +description: Returns the day of the year of the given time.Time value, in the range [1, 365] for non-leap years, and [1,366] in leap years. +categories: [] +keywords: [] +action: + related: [] + returnType: int + signatures: [TIME.YearDay] +--- + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $t.YearDay }} → 27 +``` diff --git a/content/en/methods/time/_index.md b/content/en/methods/time/_index.md new file mode 100644 index 000000000..81d4690e0 --- /dev/null +++ b/content/en/methods/time/_index.md @@ -0,0 +1,13 @@ +--- +title: Time methods +linkTitle: Time +description: Use these methods with time.Time values. +categories: [] +keywords: [] +menu: + docs: + identifier: time-methods + parent: methods +--- + +Use these methods with time.Time values. diff --git a/content/en/myshowcase/bio.md b/content/en/myshowcase/bio.md index 7d1b30895..6b8f7e1a9 100644 --- a/content/en/myshowcase/bio.md +++ b/content/en/myshowcase/bio.md @@ -3,6 +3,5 @@ Add some **general info** about Myshowcase 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) diff --git a/content/en/quick-reference/_index.md b/content/en/quick-reference/_index.md new file mode 100644 index 000000000..ad7f8437a --- /dev/null +++ b/content/en/quick-reference/_index.md @@ -0,0 +1,16 @@ +--- +title: Quick reference +linkTitle: Overview +description: Quick reference guides to Hugo's features, functions, and methods. +categories: [] +keywords: [] +menu: + docs: + identifier: quick-reference-overview + parent: quick-reference + weight: 10 +weight: 10 +showSectionMenu: false +--- + +Quick reference guides to Hugo's features, functions, and methods. diff --git a/content/en/quick-reference/emojis.md b/content/en/quick-reference/emojis.md new file mode 100644 index 000000000..df05eade0 --- /dev/null +++ b/content/en/quick-reference/emojis.md @@ -0,0 +1,1619 @@ +--- +title: Emojis +description: Include emoji shortcodes in your markdown, or use the emojify function in your templates. +categories: [] +keywords: [emoji] +menu: + docs: + parent: quick-reference + weight: 20 +weight: 20 +toc: true +--- + +With emoji processing enabled, this markdown: + +```md +Hello! :wave: +``` + +Is rendered to: + +```html +Hello! 👋 +``` + +And in your browser... Hello! :wave: + +To enable this capability in your site configuration: + +{{< code-toggle file=hugo >}} +enableEmoji = true +{{< /code-toggle >}} + +To process an emoji shortcode from within a template, use the [`emojify`] function. + +[`emojify`]: /functions/transform/emojify + +## Introduction + +This quick reference guide was automatically generated from [GitHub Emoji API] and [Unicode Full Emoji List]. Specials thanks to [@ikatyang] for making [this list] available to the open source community. + +GitHub [custom emoji] are not supported. + +[custom emoji]: #github-custom-emoji +[@ikatyang]: https://github.com/ikatyang +[github emoji api]: https://api.github.com/emojis +[unicode full emoji list]: https://unicode.org/emoji/charts/full-emoji-list.html +[this list]: https://github.com/ikatyang/emoji-cheat-sheet/#readme + +## Smileys & Emotion + +- [Face Smiling](#face-smiling) +- [Face Affection](#face-affection) +- [Face Tongue](#face-tongue) +- [Face Hand](#face-hand) +- [Face Neutral Skeptical](#face-neutral-skeptical) +- [Face Sleepy](#face-sleepy) +- [Face Unwell](#face-unwell) +- [Face Hat](#face-hat) +- [Face Glasses](#face-glasses) +- [Face Concerned](#face-concerned) +- [Face Negative](#face-negative) +- [Face Costume](#face-costume) +- [Cat Face](#cat-face) +- [Monkey Face](#monkey-face) +- [Heart](#heart) +- [Emotion](#emotion) + +### Face Smiling + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :grinning: | `:grinning:` | :smiley: | `:smiley:` | [top](#introduction) | +| [top](#introduction) | :smile: | `:smile:` | :grin: | `:grin:` | [top](#introduction) | +| [top](#introduction) | :laughing: | `:laughing:`
    `:satisfied:` | :sweat_smile: | `:sweat_smile:` | [top](#introduction) | +| [top](#introduction) | :rofl: | `:rofl:` | :joy: | `:joy:` | [top](#introduction) | +| [top](#introduction) | :slightly_smiling_face: | `:slightly_smiling_face:` | :upside_down_face: | `:upside_down_face:` | [top](#introduction) | +| [top](#introduction) | :wink: | `:wink:` | :blush: | `:blush:` | [top](#introduction) | +| [top](#introduction) | :innocent: | `:innocent:` | | | [top](#introduction) | + +### Face Affection + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :smiling_face_with_three_hearts: | `:smiling_face_with_three_hearts:` | :heart_eyes: | `:heart_eyes:` | [top](#introduction) | +| [top](#introduction) | :star_struck: | `:star_struck:` | :kissing_heart: | `:kissing_heart:` | [top](#introduction) | +| [top](#introduction) | :kissing: | `:kissing:` | :relaxed: | `:relaxed:` | [top](#introduction) | +| [top](#introduction) | :kissing_closed_eyes: | `:kissing_closed_eyes:` | :kissing_smiling_eyes: | `:kissing_smiling_eyes:` | [top](#introduction) | +| [top](#introduction) | :smiling_face_with_tear: | `:smiling_face_with_tear:` | | | [top](#introduction) | + +### Face Tongue + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :yum: | `:yum:` | :stuck_out_tongue: | `:stuck_out_tongue:` | [top](#introduction) | +| [top](#introduction) | :stuck_out_tongue_winking_eye: | `:stuck_out_tongue_winking_eye:` | :zany_face: | `:zany_face:` | [top](#introduction) | +| [top](#introduction) | :stuck_out_tongue_closed_eyes: | `:stuck_out_tongue_closed_eyes:` | :money_mouth_face: | `:money_mouth_face:` | [top](#introduction) | + +### Face Hand + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :hugs: | `:hugs:` | :hand_over_mouth: | `:hand_over_mouth:` | [top](#introduction) | +| [top](#introduction) | :shushing_face: | `:shushing_face:` | :thinking: | `:thinking:` | [top](#introduction) | + +### Face Neutral Skeptical + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :zipper_mouth_face: | `:zipper_mouth_face:` | :raised_eyebrow: | `:raised_eyebrow:` | [top](#introduction) | +| [top](#introduction) | :neutral_face: | `:neutral_face:` | :expressionless: | `:expressionless:` | [top](#introduction) | +| [top](#introduction) | :no_mouth: | `:no_mouth:` | :face_in_clouds: | `:face_in_clouds:` | [top](#introduction) | +| [top](#introduction) | :smirk: | `:smirk:` | :unamused: | `:unamused:` | [top](#introduction) | +| [top](#introduction) | :roll_eyes: | `:roll_eyes:` | :grimacing: | `:grimacing:` | [top](#introduction) | +| [top](#introduction) | :face_exhaling: | `:face_exhaling:` | :lying_face: | `:lying_face:` | [top](#introduction) | + +### Face Sleepy + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :relieved: | `:relieved:` | :pensive: | `:pensive:` | [top](#introduction) | +| [top](#introduction) | :sleepy: | `:sleepy:` | :drooling_face: | `:drooling_face:` | [top](#introduction) | +| [top](#introduction) | :sleeping: | `:sleeping:` | | | [top](#introduction) | + +### Face Unwell + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :mask: | `:mask:` | :face_with_thermometer: | `:face_with_thermometer:` | [top](#introduction) | +| [top](#introduction) | :face_with_head_bandage: | `:face_with_head_bandage:` | :nauseated_face: | `:nauseated_face:` | [top](#introduction) | +| [top](#introduction) | :vomiting_face: | `:vomiting_face:` | :sneezing_face: | `:sneezing_face:` | [top](#introduction) | +| [top](#introduction) | :hot_face: | `:hot_face:` | :cold_face: | `:cold_face:` | [top](#introduction) | +| [top](#introduction) | :woozy_face: | `:woozy_face:` | :dizzy_face: | `:dizzy_face:` | [top](#introduction) | +| [top](#introduction) | :face_with_spiral_eyes: | `:face_with_spiral_eyes:` | :exploding_head: | `:exploding_head:` | [top](#introduction) | + +### Face Hat + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :cowboy_hat_face: | `:cowboy_hat_face:` | :partying_face: | `:partying_face:` | [top](#introduction) | +| [top](#introduction) | :disguised_face: | `:disguised_face:` | | | [top](#introduction) | + +### Face Glasses + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :sunglasses: | `:sunglasses:` | :nerd_face: | `:nerd_face:` | [top](#introduction) | +| [top](#introduction) | :monocle_face: | `:monocle_face:` | | | [top](#introduction) | + +### Face Concerned + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :confused: | `:confused:` | :worried: | `:worried:` | [top](#introduction) | +| [top](#introduction) | :slightly_frowning_face: | `:slightly_frowning_face:` | :frowning_face: | `:frowning_face:` | [top](#introduction) | +| [top](#introduction) | :open_mouth: | `:open_mouth:` | :hushed: | `:hushed:` | [top](#introduction) | +| [top](#introduction) | :astonished: | `:astonished:` | :flushed: | `:flushed:` | [top](#introduction) | +| [top](#introduction) | :pleading_face: | `:pleading_face:` | :frowning: | `:frowning:` | [top](#introduction) | +| [top](#introduction) | :anguished: | `:anguished:` | :fearful: | `:fearful:` | [top](#introduction) | +| [top](#introduction) | :cold_sweat: | `:cold_sweat:` | :disappointed_relieved: | `:disappointed_relieved:` | [top](#introduction) | +| [top](#introduction) | :cry: | `:cry:` | :sob: | `:sob:` | [top](#introduction) | +| [top](#introduction) | :scream: | `:scream:` | :confounded: | `:confounded:` | [top](#introduction) | +| [top](#introduction) | :persevere: | `:persevere:` | :disappointed: | `:disappointed:` | [top](#introduction) | +| [top](#introduction) | :sweat: | `:sweat:` | :weary: | `:weary:` | [top](#introduction) | +| [top](#introduction) | :tired_face: | `:tired_face:` | :yawning_face: | `:yawning_face:` | [top](#introduction) | + +### Face Negative + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :triumph: | `:triumph:` | :pout: | `:pout:`
    `:rage:` | [top](#introduction) | +| [top](#introduction) | :angry: | `:angry:` | :cursing_face: | `:cursing_face:` | [top](#introduction) | +| [top](#introduction) | :smiling_imp: | `:smiling_imp:` | :imp: | `:imp:` | [top](#introduction) | +| [top](#introduction) | :skull: | `:skull:` | :skull_and_crossbones: | `:skull_and_crossbones:` | [top](#introduction) | + +### Face Costume + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :hankey: | `:hankey:`
    `:poop:`
    `:shit:` | :clown_face: | `:clown_face:` | [top](#introduction) | +| [top](#introduction) | :japanese_ogre: | `:japanese_ogre:` | :japanese_goblin: | `:japanese_goblin:` | [top](#introduction) | +| [top](#introduction) | :ghost: | `:ghost:` | :alien: | `:alien:` | [top](#introduction) | +| [top](#introduction) | :space_invader: | `:space_invader:` | :robot: | `:robot:` | [top](#introduction) | + +### Cat Face + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :smiley_cat: | `:smiley_cat:` | :smile_cat: | `:smile_cat:` | [top](#introduction) | +| [top](#introduction) | :joy_cat: | `:joy_cat:` | :heart_eyes_cat: | `:heart_eyes_cat:` | [top](#introduction) | +| [top](#introduction) | :smirk_cat: | `:smirk_cat:` | :kissing_cat: | `:kissing_cat:` | [top](#introduction) | +| [top](#introduction) | :scream_cat: | `:scream_cat:` | :crying_cat_face: | `:crying_cat_face:` | [top](#introduction) | +| [top](#introduction) | :pouting_cat: | `:pouting_cat:` | | | [top](#introduction) | + +### Monkey Face + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :see_no_evil: | `:see_no_evil:` | :hear_no_evil: | `:hear_no_evil:` | [top](#introduction) | +| [top](#introduction) | :speak_no_evil: | `:speak_no_evil:` | | | [top](#introduction) | + +### Heart + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :love_letter: | `:love_letter:` | :cupid: | `:cupid:` | [top](#introduction) | +| [top](#introduction) | :gift_heart: | `:gift_heart:` | :sparkling_heart: | `:sparkling_heart:` | [top](#introduction) | +| [top](#introduction) | :heartpulse: | `:heartpulse:` | :heartbeat: | `:heartbeat:` | [top](#introduction) | +| [top](#introduction) | :revolving_hearts: | `:revolving_hearts:` | :two_hearts: | `:two_hearts:` | [top](#introduction) | +| [top](#introduction) | :heart_decoration: | `:heart_decoration:` | :heavy_heart_exclamation: | `:heavy_heart_exclamation:` | [top](#introduction) | +| [top](#introduction) | :broken_heart: | `:broken_heart:` | :heart_on_fire: | `:heart_on_fire:` | [top](#introduction) | +| [top](#introduction) | :mending_heart: | `:mending_heart:` | :heart: | `:heart:` | [top](#introduction) | +| [top](#introduction) | :orange_heart: | `:orange_heart:` | :yellow_heart: | `:yellow_heart:` | [top](#introduction) | +| [top](#introduction) | :green_heart: | `:green_heart:` | :blue_heart: | `:blue_heart:` | [top](#introduction) | +| [top](#introduction) | :purple_heart: | `:purple_heart:` | :brown_heart: | `:brown_heart:` | [top](#introduction) | +| [top](#introduction) | :black_heart: | `:black_heart:` | :white_heart: | `:white_heart:` | [top](#introduction) | + +### Emotion + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#introduction) | :kiss: | `:kiss:` | :100: | `:100:` | [top](#introduction) | +| [top](#introduction) | :anger: | `:anger:` | :boom: | `:boom:`
    `:collision:` | [top](#introduction) | +| [top](#introduction) | :dizzy: | `:dizzy:` | :sweat_drops: | `:sweat_drops:` | [top](#introduction) | +| [top](#introduction) | :dash: | `:dash:` | :hole: | `:hole:` | [top](#introduction) | +| [top](#introduction) | :speech_balloon: | `:speech_balloon:` | :eye_speech_bubble: | `:eye_speech_bubble:` | [top](#introduction) | +| [top](#introduction) | :left_speech_bubble: | `:left_speech_bubble:` | :right_anger_bubble: | `:right_anger_bubble:` | [top](#introduction) | +| [top](#introduction) | :thought_balloon: | `:thought_balloon:` | :zzz: | `:zzz:` | [top](#introduction) | + +## People & Body + +- [Hand Fingers Open](#hand-fingers-open) +- [Hand Fingers Partial](#hand-fingers-partial) +- [Hand Single Finger](#hand-single-finger) +- [Hand Fingers Closed](#hand-fingers-closed) +- [Hands](#hands) +- [Hand Prop](#hand-prop) +- [Body Parts](#body-parts) +- [Person](#person) +- [Person Gesture](#person-gesture) +- [Person Role](#person-role) +- [Person Fantasy](#person-fantasy) +- [Person Activity](#person-activity) +- [Person Sport](#person-sport) +- [Person Resting](#person-resting) +- [Family](#family) +- [Person Symbol](#person-symbol) + +### Hand Fingers Open + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :wave: | `:wave:` | :raised_back_of_hand: | `:raised_back_of_hand:` | [top](#introduction) | +| [top](#people--body) | :raised_hand_with_fingers_splayed: | `:raised_hand_with_fingers_splayed:` | :hand: | `:hand:`
    `:raised_hand:` | [top](#introduction) | +| [top](#people--body) | :vulcan_salute: | `:vulcan_salute:` | | | [top](#introduction) | + +### Hand Fingers Partial + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :ok_hand: | `:ok_hand:` | :pinched_fingers: | `:pinched_fingers:` | [top](#introduction) | +| [top](#people--body) | :pinching_hand: | `:pinching_hand:` | :v: | `:v:` | [top](#introduction) | +| [top](#people--body) | :crossed_fingers: | `:crossed_fingers:` | :love_you_gesture: | `:love_you_gesture:` | [top](#introduction) | +| [top](#people--body) | :metal: | `:metal:` | :call_me_hand: | `:call_me_hand:` | [top](#introduction) | + +### Hand Single Finger + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :point_left: | `:point_left:` | :point_right: | `:point_right:` | [top](#introduction) | +| [top](#people--body) | :point_up_2: | `:point_up_2:` | :fu: | `:fu:`
    `:middle_finger:` | [top](#introduction) | +| [top](#people--body) | :point_down: | `:point_down:` | :point_up: | `:point_up:` | [top](#introduction) | + +### Hand Fingers Closed + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :+1: | `:+1:`
    `:thumbsup:` | :-1: | `:-1:`
    `:thumbsdown:` | [top](#introduction) | +| [top](#people--body) | :fist: | `:fist:`
    `:fist_raised:` | :facepunch: | `:facepunch:`
    `:fist_oncoming:`
    `:punch:` | [top](#introduction) | +| [top](#people--body) | :fist_left: | `:fist_left:` | :fist_right: | `:fist_right:` | [top](#introduction) | + +### Hands + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :clap: | `:clap:` | :raised_hands: | `:raised_hands:` | [top](#introduction) | +| [top](#people--body) | :open_hands: | `:open_hands:` | :palms_up_together: | `:palms_up_together:` | [top](#introduction) | +| [top](#people--body) | :handshake: | `:handshake:` | :pray: | `:pray:` | [top](#introduction) | + +### Hand Prop + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :writing_hand: | `:writing_hand:` | :nail_care: | `:nail_care:` | [top](#introduction) | +| [top](#people--body) | :selfie: | `:selfie:` | | | [top](#introduction) | + +### Body Parts + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :muscle: | `:muscle:` | :mechanical_arm: | `:mechanical_arm:` | [top](#introduction) | +| [top](#people--body) | :mechanical_leg: | `:mechanical_leg:` | :leg: | `:leg:` | [top](#introduction) | +| [top](#people--body) | :foot: | `:foot:` | :ear: | `:ear:` | [top](#introduction) | +| [top](#people--body) | :ear_with_hearing_aid: | `:ear_with_hearing_aid:` | :nose: | `:nose:` | [top](#introduction) | +| [top](#people--body) | :brain: | `:brain:` | :anatomical_heart: | `:anatomical_heart:` | [top](#introduction) | +| [top](#people--body) | :lungs: | `:lungs:` | :tooth: | `:tooth:` | [top](#introduction) | +| [top](#people--body) | :bone: | `:bone:` | :eyes: | `:eyes:` | [top](#introduction) | +| [top](#people--body) | :eye: | `:eye:` | :tongue: | `:tongue:` | [top](#introduction) | +| [top](#people--body) | :lips: | `:lips:` | | | [top](#introduction) | + +### Person + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :baby: | `:baby:` | :child: | `:child:` | [top](#introduction) | +| [top](#people--body) | :boy: | `:boy:` | :girl: | `:girl:` | [top](#introduction) | +| [top](#people--body) | :adult: | `:adult:` | :blond_haired_person: | `:blond_haired_person:` | [top](#introduction) | +| [top](#people--body) | :man: | `:man:` | :bearded_person: | `:bearded_person:` | [top](#introduction) | +| [top](#people--body) | :man_beard: | `:man_beard:` | :woman_beard: | `:woman_beard:` | [top](#introduction) | +| [top](#people--body) | :red_haired_man: | `:red_haired_man:` | :curly_haired_man: | `:curly_haired_man:` | [top](#introduction) | +| [top](#people--body) | :white_haired_man: | `:white_haired_man:` | :bald_man: | `:bald_man:` | [top](#introduction) | +| [top](#people--body) | :woman: | `:woman:` | :red_haired_woman: | `:red_haired_woman:` | [top](#introduction) | +| [top](#people--body) | :person_red_hair: | `:person_red_hair:` | :curly_haired_woman: | `:curly_haired_woman:` | [top](#introduction) | +| [top](#people--body) | :person_curly_hair: | `:person_curly_hair:` | :white_haired_woman: | `:white_haired_woman:` | [top](#introduction) | +| [top](#people--body) | :person_white_hair: | `:person_white_hair:` | :bald_woman: | `:bald_woman:` | [top](#introduction) | +| [top](#people--body) | :person_bald: | `:person_bald:` | :blond_haired_woman: | `:blond_haired_woman:`
    `:blonde_woman:` | [top](#introduction) | +| [top](#people--body) | :blond_haired_man: | `:blond_haired_man:` | :older_adult: | `:older_adult:` | [top](#introduction) | +| [top](#people--body) | :older_man: | `:older_man:` | :older_woman: | `:older_woman:` | [top](#introduction) | + +### Person Gesture + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :frowning_person: | `:frowning_person:` | :frowning_man: | `:frowning_man:` | [top](#introduction) | +| [top](#people--body) | :frowning_woman: | `:frowning_woman:` | :pouting_face: | `:pouting_face:` | [top](#introduction) | +| [top](#people--body) | :pouting_man: | `:pouting_man:` | :pouting_woman: | `:pouting_woman:` | [top](#introduction) | +| [top](#people--body) | :no_good: | `:no_good:` | :ng_man: | `:ng_man:`
    `:no_good_man:` | [top](#introduction) | +| [top](#people--body) | :ng_woman: | `:ng_woman:`
    `:no_good_woman:` | :ok_person: | `:ok_person:` | [top](#introduction) | +| [top](#people--body) | :ok_man: | `:ok_man:` | :ok_woman: | `:ok_woman:` | [top](#introduction) | +| [top](#people--body) | :information_desk_person: | `:information_desk_person:`
    `:tipping_hand_person:` | :sassy_man: | `:sassy_man:`
    `:tipping_hand_man:` | [top](#introduction) | +| [top](#people--body) | :sassy_woman: | `:sassy_woman:`
    `:tipping_hand_woman:` | :raising_hand: | `:raising_hand:` | [top](#introduction) | +| [top](#people--body) | :raising_hand_man: | `:raising_hand_man:` | :raising_hand_woman: | `:raising_hand_woman:` | [top](#introduction) | +| [top](#people--body) | :deaf_person: | `:deaf_person:` | :deaf_man: | `:deaf_man:` | [top](#introduction) | +| [top](#people--body) | :deaf_woman: | `:deaf_woman:` | :bow: | `:bow:` | [top](#introduction) | +| [top](#people--body) | :bowing_man: | `:bowing_man:` | :bowing_woman: | `:bowing_woman:` | [top](#introduction) | +| [top](#people--body) | :facepalm: | `:facepalm:` | :man_facepalming: | `:man_facepalming:` | [top](#introduction) | +| [top](#people--body) | :woman_facepalming: | `:woman_facepalming:` | :shrug: | `:shrug:` | [top](#introduction) | +| [top](#people--body) | :man_shrugging: | `:man_shrugging:` | :woman_shrugging: | `:woman_shrugging:` | [top](#introduction) | + +### Person Role + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :health_worker: | `:health_worker:` | :man_health_worker: | `:man_health_worker:` | [top](#introduction) | +| [top](#people--body) | :woman_health_worker: | `:woman_health_worker:` | :student: | `:student:` | [top](#introduction) | +| [top](#people--body) | :man_student: | `:man_student:` | :woman_student: | `:woman_student:` | [top](#introduction) | +| [top](#people--body) | :teacher: | `:teacher:` | :man_teacher: | `:man_teacher:` | [top](#introduction) | +| [top](#people--body) | :woman_teacher: | `:woman_teacher:` | :judge: | `:judge:` | [top](#introduction) | +| [top](#people--body) | :man_judge: | `:man_judge:` | :woman_judge: | `:woman_judge:` | [top](#introduction) | +| [top](#people--body) | :farmer: | `:farmer:` | :man_farmer: | `:man_farmer:` | [top](#introduction) | +| [top](#people--body) | :woman_farmer: | `:woman_farmer:` | :cook: | `:cook:` | [top](#introduction) | +| [top](#people--body) | :man_cook: | `:man_cook:` | :woman_cook: | `:woman_cook:` | [top](#introduction) | +| [top](#people--body) | :mechanic: | `:mechanic:` | :man_mechanic: | `:man_mechanic:` | [top](#introduction) | +| [top](#people--body) | :woman_mechanic: | `:woman_mechanic:` | :factory_worker: | `:factory_worker:` | [top](#introduction) | +| [top](#people--body) | :man_factory_worker: | `:man_factory_worker:` | :woman_factory_worker: | `:woman_factory_worker:` | [top](#introduction) | +| [top](#people--body) | :office_worker: | `:office_worker:` | :man_office_worker: | `:man_office_worker:` | [top](#introduction) | +| [top](#people--body) | :woman_office_worker: | `:woman_office_worker:` | :scientist: | `:scientist:` | [top](#introduction) | +| [top](#people--body) | :man_scientist: | `:man_scientist:` | :woman_scientist: | `:woman_scientist:` | [top](#introduction) | +| [top](#people--body) | :technologist: | `:technologist:` | :man_technologist: | `:man_technologist:` | [top](#introduction) | +| [top](#people--body) | :woman_technologist: | `:woman_technologist:` | :singer: | `:singer:` | [top](#introduction) | +| [top](#people--body) | :man_singer: | `:man_singer:` | :woman_singer: | `:woman_singer:` | [top](#introduction) | +| [top](#people--body) | :artist: | `:artist:` | :man_artist: | `:man_artist:` | [top](#introduction) | +| [top](#people--body) | :woman_artist: | `:woman_artist:` | :pilot: | `:pilot:` | [top](#introduction) | +| [top](#people--body) | :man_pilot: | `:man_pilot:` | :woman_pilot: | `:woman_pilot:` | [top](#introduction) | +| [top](#people--body) | :astronaut: | `:astronaut:` | :man_astronaut: | `:man_astronaut:` | [top](#introduction) | +| [top](#people--body) | :woman_astronaut: | `:woman_astronaut:` | :firefighter: | `:firefighter:` | [top](#introduction) | +| [top](#people--body) | :man_firefighter: | `:man_firefighter:` | :woman_firefighter: | `:woman_firefighter:` | [top](#introduction) | +| [top](#people--body) | :cop: | `:cop:`
    `:police_officer:` | :policeman: | `:policeman:` | [top](#introduction) | +| [top](#people--body) | :policewoman: | `:policewoman:` | :detective: | `:detective:` | [top](#introduction) | +| [top](#people--body) | :male_detective: | `:male_detective:` | :female_detective: | `:female_detective:` | [top](#introduction) | +| [top](#people--body) | :guard: | `:guard:` | :guardsman: | `:guardsman:` | [top](#introduction) | +| [top](#people--body) | :guardswoman: | `:guardswoman:` | :ninja: | `:ninja:` | [top](#introduction) | +| [top](#people--body) | :construction_worker: | `:construction_worker:` | :construction_worker_man: | `:construction_worker_man:` | [top](#introduction) | +| [top](#people--body) | :construction_worker_woman: | `:construction_worker_woman:` | :prince: | `:prince:` | [top](#introduction) | +| [top](#people--body) | :princess: | `:princess:` | :person_with_turban: | `:person_with_turban:` | [top](#introduction) | +| [top](#people--body) | :man_with_turban: | `:man_with_turban:` | :woman_with_turban: | `:woman_with_turban:` | [top](#introduction) | +| [top](#people--body) | :man_with_gua_pi_mao: | `:man_with_gua_pi_mao:` | :woman_with_headscarf: | `:woman_with_headscarf:` | [top](#introduction) | +| [top](#people--body) | :person_in_tuxedo: | `:person_in_tuxedo:` | :man_in_tuxedo: | `:man_in_tuxedo:` | [top](#introduction) | +| [top](#people--body) | :woman_in_tuxedo: | `:woman_in_tuxedo:` | :person_with_veil: | `:person_with_veil:` | [top](#introduction) | +| [top](#people--body) | :man_with_veil: | `:man_with_veil:` | :bride_with_veil: | `:bride_with_veil:`
    `:woman_with_veil:` | [top](#introduction) | +| [top](#people--body) | :pregnant_woman: | `:pregnant_woman:` | :breast_feeding: | `:breast_feeding:` | [top](#introduction) | +| [top](#people--body) | :woman_feeding_baby: | `:woman_feeding_baby:` | :man_feeding_baby: | `:man_feeding_baby:` | [top](#introduction) | +| [top](#people--body) | :person_feeding_baby: | `:person_feeding_baby:` | | | [top](#introduction) | + +### Person Fantasy + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :angel: | `:angel:` | :santa: | `:santa:` | [top](#introduction) | +| [top](#people--body) | :mrs_claus: | `:mrs_claus:` | :mx_claus: | `:mx_claus:` | [top](#introduction) | +| [top](#people--body) | :superhero: | `:superhero:` | :superhero_man: | `:superhero_man:` | [top](#introduction) | +| [top](#people--body) | :superhero_woman: | `:superhero_woman:` | :supervillain: | `:supervillain:` | [top](#introduction) | +| [top](#people--body) | :supervillain_man: | `:supervillain_man:` | :supervillain_woman: | `:supervillain_woman:` | [top](#introduction) | +| [top](#people--body) | :mage: | `:mage:` | :mage_man: | `:mage_man:` | [top](#introduction) | +| [top](#people--body) | :mage_woman: | `:mage_woman:` | :fairy: | `:fairy:` | [top](#introduction) | +| [top](#people--body) | :fairy_man: | `:fairy_man:` | :fairy_woman: | `:fairy_woman:` | [top](#introduction) | +| [top](#people--body) | :vampire: | `:vampire:` | :vampire_man: | `:vampire_man:` | [top](#introduction) | +| [top](#people--body) | :vampire_woman: | `:vampire_woman:` | :merperson: | `:merperson:` | [top](#introduction) | +| [top](#people--body) | :merman: | `:merman:` | :mermaid: | `:mermaid:` | [top](#introduction) | +| [top](#people--body) | :elf: | `:elf:` | :elf_man: | `:elf_man:` | [top](#introduction) | +| [top](#people--body) | :elf_woman: | `:elf_woman:` | :genie: | `:genie:` | [top](#introduction) | +| [top](#people--body) | :genie_man: | `:genie_man:` | :genie_woman: | `:genie_woman:` | [top](#introduction) | +| [top](#people--body) | :zombie: | `:zombie:` | :zombie_man: | `:zombie_man:` | [top](#introduction) | +| [top](#people--body) | :zombie_woman: | `:zombie_woman:` | | | [top](#introduction) | + +### Person Activity + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :massage: | `:massage:` | :massage_man: | `:massage_man:` | [top](#introduction) | +| [top](#people--body) | :massage_woman: | `:massage_woman:` | :haircut: | `:haircut:` | [top](#introduction) | +| [top](#people--body) | :haircut_man: | `:haircut_man:` | :haircut_woman: | `:haircut_woman:` | [top](#introduction) | +| [top](#people--body) | :walking: | `:walking:` | :walking_man: | `:walking_man:` | [top](#introduction) | +| [top](#people--body) | :walking_woman: | `:walking_woman:` | :standing_person: | `:standing_person:` | [top](#introduction) | +| [top](#people--body) | :standing_man: | `:standing_man:` | :standing_woman: | `:standing_woman:` | [top](#introduction) | +| [top](#people--body) | :kneeling_person: | `:kneeling_person:` | :kneeling_man: | `:kneeling_man:` | [top](#introduction) | +| [top](#people--body) | :kneeling_woman: | `:kneeling_woman:` | :person_with_probing_cane: | `:person_with_probing_cane:` | [top](#introduction) | +| [top](#people--body) | :man_with_probing_cane: | `:man_with_probing_cane:` | :woman_with_probing_cane: | `:woman_with_probing_cane:` | [top](#introduction) | +| [top](#people--body) | :person_in_motorized_wheelchair: | `:person_in_motorized_wheelchair:` | :man_in_motorized_wheelchair: | `:man_in_motorized_wheelchair:` | [top](#introduction) | +| [top](#people--body) | :woman_in_motorized_wheelchair: | `:woman_in_motorized_wheelchair:` | :person_in_manual_wheelchair: | `:person_in_manual_wheelchair:` | [top](#introduction) | +| [top](#people--body) | :man_in_manual_wheelchair: | `:man_in_manual_wheelchair:` | :woman_in_manual_wheelchair: | `:woman_in_manual_wheelchair:` | [top](#introduction) | +| [top](#people--body) | :runner: | `:runner:`
    `:running:` | :running_man: | `:running_man:` | [top](#introduction) | +| [top](#people--body) | :running_woman: | `:running_woman:` | :dancer: | `:dancer:`
    `:woman_dancing:` | [top](#introduction) | +| [top](#people--body) | :man_dancing: | `:man_dancing:` | :business_suit_levitating: | `:business_suit_levitating:` | [top](#introduction) | +| [top](#people--body) | :dancers: | `:dancers:` | :dancing_men: | `:dancing_men:` | [top](#introduction) | +| [top](#people--body) | :dancing_women: | `:dancing_women:` | :sauna_person: | `:sauna_person:` | [top](#introduction) | +| [top](#people--body) | :sauna_man: | `:sauna_man:` | :sauna_woman: | `:sauna_woman:` | [top](#introduction) | +| [top](#people--body) | :climbing: | `:climbing:` | :climbing_man: | `:climbing_man:` | [top](#introduction) | +| [top](#people--body) | :climbing_woman: | `:climbing_woman:` | | | [top](#introduction) | + +### Person Sport + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :person_fencing: | `:person_fencing:` | :horse_racing: | `:horse_racing:` | [top](#introduction) | +| [top](#people--body) | :skier: | `:skier:` | :snowboarder: | `:snowboarder:` | [top](#introduction) | +| [top](#people--body) | :golfing: | `:golfing:` | :golfing_man: | `:golfing_man:` | [top](#introduction) | +| [top](#people--body) | :golfing_woman: | `:golfing_woman:` | :surfer: | `:surfer:` | [top](#introduction) | +| [top](#people--body) | :surfing_man: | `:surfing_man:` | :surfing_woman: | `:surfing_woman:` | [top](#introduction) | +| [top](#people--body) | :rowboat: | `:rowboat:` | :rowing_man: | `:rowing_man:` | [top](#introduction) | +| [top](#people--body) | :rowing_woman: | `:rowing_woman:` | :swimmer: | `:swimmer:` | [top](#introduction) | +| [top](#people--body) | :swimming_man: | `:swimming_man:` | :swimming_woman: | `:swimming_woman:` | [top](#introduction) | +| [top](#people--body) | :bouncing_ball_person: | `:bouncing_ball_person:` | :basketball_man: | `:basketball_man:`
    `:bouncing_ball_man:` | [top](#introduction) | +| [top](#people--body) | :basketball_woman: | `:basketball_woman:`
    `:bouncing_ball_woman:` | :weight_lifting: | `:weight_lifting:` | [top](#introduction) | +| [top](#people--body) | :weight_lifting_man: | `:weight_lifting_man:` | :weight_lifting_woman: | `:weight_lifting_woman:` | [top](#introduction) | +| [top](#people--body) | :bicyclist: | `:bicyclist:` | :biking_man: | `:biking_man:` | [top](#introduction) | +| [top](#people--body) | :biking_woman: | `:biking_woman:` | :mountain_bicyclist: | `:mountain_bicyclist:` | [top](#introduction) | +| [top](#people--body) | :mountain_biking_man: | `:mountain_biking_man:` | :mountain_biking_woman: | `:mountain_biking_woman:` | [top](#introduction) | +| [top](#people--body) | :cartwheeling: | `:cartwheeling:` | :man_cartwheeling: | `:man_cartwheeling:` | [top](#introduction) | +| [top](#people--body) | :woman_cartwheeling: | `:woman_cartwheeling:` | :wrestling: | `:wrestling:` | [top](#introduction) | +| [top](#people--body) | :men_wrestling: | `:men_wrestling:` | :women_wrestling: | `:women_wrestling:` | [top](#introduction) | +| [top](#people--body) | :water_polo: | `:water_polo:` | :man_playing_water_polo: | `:man_playing_water_polo:` | [top](#introduction) | +| [top](#people--body) | :woman_playing_water_polo: | `:woman_playing_water_polo:` | :handball_person: | `:handball_person:` | [top](#introduction) | +| [top](#people--body) | :man_playing_handball: | `:man_playing_handball:` | :woman_playing_handball: | `:woman_playing_handball:` | [top](#introduction) | +| [top](#people--body) | :juggling_person: | `:juggling_person:` | :man_juggling: | `:man_juggling:` | [top](#introduction) | +| [top](#people--body) | :woman_juggling: | `:woman_juggling:` | | | [top](#introduction) | + +### Person Resting + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :lotus_position: | `:lotus_position:` | :lotus_position_man: | `:lotus_position_man:` | [top](#introduction) | +| [top](#people--body) | :lotus_position_woman: | `:lotus_position_woman:` | :bath: | `:bath:` | [top](#introduction) | +| [top](#people--body) | :sleeping_bed: | `:sleeping_bed:` | | | [top](#introduction) | + +### Family + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :people_holding_hands: | `:people_holding_hands:` | :two_women_holding_hands: | `:two_women_holding_hands:` | [top](#introduction) | +| [top](#people--body) | :couple: | `:couple:` | :two_men_holding_hands: | `:two_men_holding_hands:` | [top](#introduction) | +| [top](#people--body) | :couplekiss: | `:couplekiss:` | :couplekiss_man_woman: | `:couplekiss_man_woman:` | [top](#introduction) | +| [top](#people--body) | :couplekiss_man_man: | `:couplekiss_man_man:` | :couplekiss_woman_woman: | `:couplekiss_woman_woman:` | [top](#introduction) | +| [top](#people--body) | :couple_with_heart: | `:couple_with_heart:` | :couple_with_heart_woman_man: | `:couple_with_heart_woman_man:` | [top](#introduction) | +| [top](#people--body) | :couple_with_heart_man_man: | `:couple_with_heart_man_man:` | :couple_with_heart_woman_woman: | `:couple_with_heart_woman_woman:` | [top](#introduction) | +| [top](#people--body) | :family_man_woman_boy: | `:family_man_woman_boy:` | :family_man_woman_girl: | `:family_man_woman_girl:` | [top](#introduction) | +| [top](#people--body) | :family_man_woman_girl_boy: | `:family_man_woman_girl_boy:` | :family_man_woman_boy_boy: | `:family_man_woman_boy_boy:` | [top](#introduction) | +| [top](#people--body) | :family_man_woman_girl_girl: | `:family_man_woman_girl_girl:` | :family_man_man_boy: | `:family_man_man_boy:` | [top](#introduction) | +| [top](#people--body) | :family_man_man_girl: | `:family_man_man_girl:` | :family_man_man_girl_boy: | `:family_man_man_girl_boy:` | [top](#introduction) | +| [top](#people--body) | :family_man_man_boy_boy: | `:family_man_man_boy_boy:` | :family_man_man_girl_girl: | `:family_man_man_girl_girl:` | [top](#introduction) | +| [top](#people--body) | :family_woman_woman_boy: | `:family_woman_woman_boy:` | :family_woman_woman_girl: | `:family_woman_woman_girl:` | [top](#introduction) | +| [top](#people--body) | :family_woman_woman_girl_boy: | `:family_woman_woman_girl_boy:` | :family_woman_woman_boy_boy: | `:family_woman_woman_boy_boy:` | [top](#introduction) | +| [top](#people--body) | :family_woman_woman_girl_girl: | `:family_woman_woman_girl_girl:` | :family_man_boy: | `:family_man_boy:` | [top](#introduction) | +| [top](#people--body) | :family_man_boy_boy: | `:family_man_boy_boy:` | :family_man_girl: | `:family_man_girl:` | [top](#introduction) | +| [top](#people--body) | :family_man_girl_boy: | `:family_man_girl_boy:` | :family_man_girl_girl: | `:family_man_girl_girl:` | [top](#introduction) | +| [top](#people--body) | :family_woman_boy: | `:family_woman_boy:` | :family_woman_boy_boy: | `:family_woman_boy_boy:` | [top](#introduction) | +| [top](#people--body) | :family_woman_girl: | `:family_woman_girl:` | :family_woman_girl_boy: | `:family_woman_girl_boy:` | [top](#introduction) | +| [top](#people--body) | :family_woman_girl_girl: | `:family_woman_girl_girl:` | | | [top](#introduction) | + +### Person Symbol + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#people--body) | :speaking_head: | `:speaking_head:` | :bust_in_silhouette: | `:bust_in_silhouette:` | [top](#introduction) | +| [top](#people--body) | :busts_in_silhouette: | `:busts_in_silhouette:` | :people_hugging: | `:people_hugging:` | [top](#introduction) | +| [top](#people--body) | :family: | `:family:` | :footprints: | `:footprints:` | [top](#introduction) | + +## Animals & Nature + +- [Animal Mammal](#animal-mammal) +- [Animal Bird](#animal-bird) +- [Animal Amphibian](#animal-amphibian) +- [Animal Reptile](#animal-reptile) +- [Animal Marine](#animal-marine) +- [Animal Bug](#animal-bug) +- [Plant Flower](#plant-flower) +- [Plant Other](#plant-other) + +### Animal Mammal + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#animals--nature) | :monkey_face: | `:monkey_face:` | :monkey: | `:monkey:` | [top](#introduction) | +| [top](#animals--nature) | :gorilla: | `:gorilla:` | :orangutan: | `:orangutan:` | [top](#introduction) | +| [top](#animals--nature) | :dog: | `:dog:` | :dog2: | `:dog2:` | [top](#introduction) | +| [top](#animals--nature) | :guide_dog: | `:guide_dog:` | :service_dog: | `:service_dog:` | [top](#introduction) | +| [top](#animals--nature) | :poodle: | `:poodle:` | :wolf: | `:wolf:` | [top](#introduction) | +| [top](#animals--nature) | :fox_face: | `:fox_face:` | :raccoon: | `:raccoon:` | [top](#introduction) | +| [top](#animals--nature) | :cat: | `:cat:` | :cat2: | `:cat2:` | [top](#introduction) | +| [top](#animals--nature) | :black_cat: | `:black_cat:` | :lion: | `:lion:` | [top](#introduction) | +| [top](#animals--nature) | :tiger: | `:tiger:` | :tiger2: | `:tiger2:` | [top](#introduction) | +| [top](#animals--nature) | :leopard: | `:leopard:` | :horse: | `:horse:` | [top](#introduction) | +| [top](#animals--nature) | :racehorse: | `:racehorse:` | :unicorn: | `:unicorn:` | [top](#introduction) | +| [top](#animals--nature) | :zebra: | `:zebra:` | :deer: | `:deer:` | [top](#introduction) | +| [top](#animals--nature) | :bison: | `:bison:` | :cow: | `:cow:` | [top](#introduction) | +| [top](#animals--nature) | :ox: | `:ox:` | :water_buffalo: | `:water_buffalo:` | [top](#introduction) | +| [top](#animals--nature) | :cow2: | `:cow2:` | :pig: | `:pig:` | [top](#introduction) | +| [top](#animals--nature) | :pig2: | `:pig2:` | :boar: | `:boar:` | [top](#introduction) | +| [top](#animals--nature) | :pig_nose: | `:pig_nose:` | :ram: | `:ram:` | [top](#introduction) | +| [top](#animals--nature) | :sheep: | `:sheep:` | :goat: | `:goat:` | [top](#introduction) | +| [top](#animals--nature) | :dromedary_camel: | `:dromedary_camel:` | :camel: | `:camel:` | [top](#introduction) | +| [top](#animals--nature) | :llama: | `:llama:` | :giraffe: | `:giraffe:` | [top](#introduction) | +| [top](#animals--nature) | :elephant: | `:elephant:` | :mammoth: | `:mammoth:` | [top](#introduction) | +| [top](#animals--nature) | :rhinoceros: | `:rhinoceros:` | :hippopotamus: | `:hippopotamus:` | [top](#introduction) | +| [top](#animals--nature) | :mouse: | `:mouse:` | :mouse2: | `:mouse2:` | [top](#introduction) | +| [top](#animals--nature) | :rat: | `:rat:` | :hamster: | `:hamster:` | [top](#introduction) | +| [top](#animals--nature) | :rabbit: | `:rabbit:` | :rabbit2: | `:rabbit2:` | [top](#introduction) | +| [top](#animals--nature) | :chipmunk: | `:chipmunk:` | :beaver: | `:beaver:` | [top](#introduction) | +| [top](#animals--nature) | :hedgehog: | `:hedgehog:` | :bat: | `:bat:` | [top](#introduction) | +| [top](#animals--nature) | :bear: | `:bear:` | :polar_bear: | `:polar_bear:` | [top](#introduction) | +| [top](#animals--nature) | :koala: | `:koala:` | :panda_face: | `:panda_face:` | [top](#introduction) | +| [top](#animals--nature) | :sloth: | `:sloth:` | :otter: | `:otter:` | [top](#introduction) | +| [top](#animals--nature) | :skunk: | `:skunk:` | :kangaroo: | `:kangaroo:` | [top](#introduction) | +| [top](#animals--nature) | :badger: | `:badger:` | :feet: | `:feet:`
    `:paw_prints:` | [top](#introduction) | + +### Animal Bird + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#animals--nature) | :turkey: | `:turkey:` | :chicken: | `:chicken:` | [top](#introduction) | +| [top](#animals--nature) | :rooster: | `:rooster:` | :hatching_chick: | `:hatching_chick:` | [top](#introduction) | +| [top](#animals--nature) | :baby_chick: | `:baby_chick:` | :hatched_chick: | `:hatched_chick:` | [top](#introduction) | +| [top](#animals--nature) | :bird: | `:bird:` | :penguin: | `:penguin:` | [top](#introduction) | +| [top](#animals--nature) | :dove: | `:dove:` | :eagle: | `:eagle:` | [top](#introduction) | +| [top](#animals--nature) | :duck: | `:duck:` | :swan: | `:swan:` | [top](#introduction) | +| [top](#animals--nature) | :owl: | `:owl:` | :dodo: | `:dodo:` | [top](#introduction) | +| [top](#animals--nature) | :feather: | `:feather:` | :flamingo: | `:flamingo:` | [top](#introduction) | +| [top](#animals--nature) | :peacock: | `:peacock:` | :parrot: | `:parrot:` | [top](#introduction) | + +### Animal Amphibian + +| | ico | shortcode | | +| - | :-: | - | - | +| [top](#animals--nature) | :frog: | `:frog:` | [top](#introduction) | + +### Animal Reptile + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#animals--nature) | :crocodile: | `:crocodile:` | :turtle: | `:turtle:` | [top](#introduction) | +| [top](#animals--nature) | :lizard: | `:lizard:` | :snake: | `:snake:` | [top](#introduction) | +| [top](#animals--nature) | :dragon_face: | `:dragon_face:` | :dragon: | `:dragon:` | [top](#introduction) | +| [top](#animals--nature) | :sauropod: | `:sauropod:` | :t-rex: | `:t-rex:` | [top](#introduction) | + +### Animal Marine + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#animals--nature) | :whale: | `:whale:` | :whale2: | `:whale2:` | [top](#introduction) | +| [top](#animals--nature) | :dolphin: | `:dolphin:`
    `:flipper:` | :seal: | `:seal:` | [top](#introduction) | +| [top](#animals--nature) | :fish: | `:fish:` | :tropical_fish: | `:tropical_fish:` | [top](#introduction) | +| [top](#animals--nature) | :blowfish: | `:blowfish:` | :shark: | `:shark:` | [top](#introduction) | +| [top](#animals--nature) | :octopus: | `:octopus:` | :shell: | `:shell:` | [top](#introduction) | + +### Animal Bug + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#animals--nature) | :snail: | `:snail:` | :butterfly: | `:butterfly:` | [top](#introduction) | +| [top](#animals--nature) | :bug: | `:bug:` | :ant: | `:ant:` | [top](#introduction) | +| [top](#animals--nature) | :bee: | `:bee:`
    `:honeybee:` | :beetle: | `:beetle:` | [top](#introduction) | +| [top](#animals--nature) | :lady_beetle: | `:lady_beetle:` | :cricket: | `:cricket:` | [top](#introduction) | +| [top](#animals--nature) | :cockroach: | `:cockroach:` | :spider: | `:spider:` | [top](#introduction) | +| [top](#animals--nature) | :spider_web: | `:spider_web:` | :scorpion: | `:scorpion:` | [top](#introduction) | +| [top](#animals--nature) | :mosquito: | `:mosquito:` | :fly: | `:fly:` | [top](#introduction) | +| [top](#animals--nature) | :worm: | `:worm:` | :microbe: | `:microbe:` | [top](#introduction) | + +### Plant Flower + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#animals--nature) | :bouquet: | `:bouquet:` | :cherry_blossom: | `:cherry_blossom:` | [top](#introduction) | +| [top](#animals--nature) | :white_flower: | `:white_flower:` | :rosette: | `:rosette:` | [top](#introduction) | +| [top](#animals--nature) | :rose: | `:rose:` | :wilted_flower: | `:wilted_flower:` | [top](#introduction) | +| [top](#animals--nature) | :hibiscus: | `:hibiscus:` | :sunflower: | `:sunflower:` | [top](#introduction) | +| [top](#animals--nature) | :blossom: | `:blossom:` | :tulip: | `:tulip:` | [top](#introduction) | + +### Plant Other + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#animals--nature) | :seedling: | `:seedling:` | :potted_plant: | `:potted_plant:` | [top](#introduction) | +| [top](#animals--nature) | :evergreen_tree: | `:evergreen_tree:` | :deciduous_tree: | `:deciduous_tree:` | [top](#introduction) | +| [top](#animals--nature) | :palm_tree: | `:palm_tree:` | :cactus: | `:cactus:` | [top](#introduction) | +| [top](#animals--nature) | :ear_of_rice: | `:ear_of_rice:` | :herb: | `:herb:` | [top](#introduction) | +| [top](#animals--nature) | :shamrock: | `:shamrock:` | :four_leaf_clover: | `:four_leaf_clover:` | [top](#introduction) | +| [top](#animals--nature) | :maple_leaf: | `:maple_leaf:` | :fallen_leaf: | `:fallen_leaf:` | [top](#introduction) | +| [top](#animals--nature) | :leaves: | `:leaves:` | :mushroom: | `:mushroom:` | [top](#introduction) | + +## Food & Drink + +- [Food Fruit](#food-fruit) +- [Food Vegetable](#food-vegetable) +- [Food Prepared](#food-prepared) +- [Food Asian](#food-asian) +- [Food Marine](#food-marine) +- [Food Sweet](#food-sweet) +- [Drink](#drink) +- [Dishware](#dishware) + +### Food Fruit + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#food--drink) | :grapes: | `:grapes:` | :melon: | `:melon:` | [top](#introduction) | +| [top](#food--drink) | :watermelon: | `:watermelon:` | :mandarin: | `:mandarin:`
    `:orange:`
    `:tangerine:` | [top](#introduction) | +| [top](#food--drink) | :lemon: | `:lemon:` | :banana: | `:banana:` | [top](#introduction) | +| [top](#food--drink) | :pineapple: | `:pineapple:` | :mango: | `:mango:` | [top](#introduction) | +| [top](#food--drink) | :apple: | `:apple:` | :green_apple: | `:green_apple:` | [top](#introduction) | +| [top](#food--drink) | :pear: | `:pear:` | :peach: | `:peach:` | [top](#introduction) | +| [top](#food--drink) | :cherries: | `:cherries:` | :strawberry: | `:strawberry:` | [top](#introduction) | +| [top](#food--drink) | :blueberries: | `:blueberries:` | :kiwi_fruit: | `:kiwi_fruit:` | [top](#introduction) | +| [top](#food--drink) | :tomato: | `:tomato:` | :olive: | `:olive:` | [top](#introduction) | +| [top](#food--drink) | :coconut: | `:coconut:` | | | [top](#introduction) | + +### Food Vegetable + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#food--drink) | :avocado: | `:avocado:` | :eggplant: | `:eggplant:` | [top](#introduction) | +| [top](#food--drink) | :potato: | `:potato:` | :carrot: | `:carrot:` | [top](#introduction) | +| [top](#food--drink) | :corn: | `:corn:` | :hot_pepper: | `:hot_pepper:` | [top](#introduction) | +| [top](#food--drink) | :bell_pepper: | `:bell_pepper:` | :cucumber: | `:cucumber:` | [top](#introduction) | +| [top](#food--drink) | :leafy_green: | `:leafy_green:` | :broccoli: | `:broccoli:` | [top](#introduction) | +| [top](#food--drink) | :garlic: | `:garlic:` | :onion: | `:onion:` | [top](#introduction) | +| [top](#food--drink) | :peanuts: | `:peanuts:` | :chestnut: | `:chestnut:` | [top](#introduction) | + +### Food Prepared + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#food--drink) | :bread: | `:bread:` | :croissant: | `:croissant:` | [top](#introduction) | +| [top](#food--drink) | :baguette_bread: | `:baguette_bread:` | :flatbread: | `:flatbread:` | [top](#introduction) | +| [top](#food--drink) | :pretzel: | `:pretzel:` | :bagel: | `:bagel:` | [top](#introduction) | +| [top](#food--drink) | :pancakes: | `:pancakes:` | :waffle: | `:waffle:` | [top](#introduction) | +| [top](#food--drink) | :cheese: | `:cheese:` | :meat_on_bone: | `:meat_on_bone:` | [top](#introduction) | +| [top](#food--drink) | :poultry_leg: | `:poultry_leg:` | :cut_of_meat: | `:cut_of_meat:` | [top](#introduction) | +| [top](#food--drink) | :bacon: | `:bacon:` | :hamburger: | `:hamburger:` | [top](#introduction) | +| [top](#food--drink) | :fries: | `:fries:` | :pizza: | `:pizza:` | [top](#introduction) | +| [top](#food--drink) | :hotdog: | `:hotdog:` | :sandwich: | `:sandwich:` | [top](#introduction) | +| [top](#food--drink) | :taco: | `:taco:` | :burrito: | `:burrito:` | [top](#introduction) | +| [top](#food--drink) | :tamale: | `:tamale:` | :stuffed_flatbread: | `:stuffed_flatbread:` | [top](#introduction) | +| [top](#food--drink) | :falafel: | `:falafel:` | :egg: | `:egg:` | [top](#introduction) | +| [top](#food--drink) | :fried_egg: | `:fried_egg:` | :shallow_pan_of_food: | `:shallow_pan_of_food:` | [top](#introduction) | +| [top](#food--drink) | :stew: | `:stew:` | :fondue: | `:fondue:` | [top](#introduction) | +| [top](#food--drink) | :bowl_with_spoon: | `:bowl_with_spoon:` | :green_salad: | `:green_salad:` | [top](#introduction) | +| [top](#food--drink) | :popcorn: | `:popcorn:` | :butter: | `:butter:` | [top](#introduction) | +| [top](#food--drink) | :salt: | `:salt:` | :canned_food: | `:canned_food:` | [top](#introduction) | + +### Food Asian + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#food--drink) | :bento: | `:bento:` | :rice_cracker: | `:rice_cracker:` | [top](#introduction) | +| [top](#food--drink) | :rice_ball: | `:rice_ball:` | :rice: | `:rice:` | [top](#introduction) | +| [top](#food--drink) | :curry: | `:curry:` | :ramen: | `:ramen:` | [top](#introduction) | +| [top](#food--drink) | :spaghetti: | `:spaghetti:` | :sweet_potato: | `:sweet_potato:` | [top](#introduction) | +| [top](#food--drink) | :oden: | `:oden:` | :sushi: | `:sushi:` | [top](#introduction) | +| [top](#food--drink) | :fried_shrimp: | `:fried_shrimp:` | :fish_cake: | `:fish_cake:` | [top](#introduction) | +| [top](#food--drink) | :moon_cake: | `:moon_cake:` | :dango: | `:dango:` | [top](#introduction) | +| [top](#food--drink) | :dumpling: | `:dumpling:` | :fortune_cookie: | `:fortune_cookie:` | [top](#introduction) | +| [top](#food--drink) | :takeout_box: | `:takeout_box:` | | | [top](#introduction) | + +### Food Marine + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#food--drink) | :crab: | `:crab:` | :lobster: | `:lobster:` | [top](#introduction) | +| [top](#food--drink) | :shrimp: | `:shrimp:` | :squid: | `:squid:` | [top](#introduction) | +| [top](#food--drink) | :oyster: | `:oyster:` | | | [top](#introduction) | + +### Food Sweet + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#food--drink) | :icecream: | `:icecream:` | :shaved_ice: | `:shaved_ice:` | [top](#introduction) | +| [top](#food--drink) | :ice_cream: | `:ice_cream:` | :doughnut: | `:doughnut:` | [top](#introduction) | +| [top](#food--drink) | :cookie: | `:cookie:` | :birthday: | `:birthday:` | [top](#introduction) | +| [top](#food--drink) | :cake: | `:cake:` | :cupcake: | `:cupcake:` | [top](#introduction) | +| [top](#food--drink) | :pie: | `:pie:` | :chocolate_bar: | `:chocolate_bar:` | [top](#introduction) | +| [top](#food--drink) | :candy: | `:candy:` | :lollipop: | `:lollipop:` | [top](#introduction) | +| [top](#food--drink) | :custard: | `:custard:` | :honey_pot: | `:honey_pot:` | [top](#introduction) | + +### Drink + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#food--drink) | :baby_bottle: | `:baby_bottle:` | :milk_glass: | `:milk_glass:` | [top](#introduction) | +| [top](#food--drink) | :coffee: | `:coffee:` | :teapot: | `:teapot:` | [top](#introduction) | +| [top](#food--drink) | :tea: | `:tea:` | :sake: | `:sake:` | [top](#introduction) | +| [top](#food--drink) | :champagne: | `:champagne:` | :wine_glass: | `:wine_glass:` | [top](#introduction) | +| [top](#food--drink) | :cocktail: | `:cocktail:` | :tropical_drink: | `:tropical_drink:` | [top](#introduction) | +| [top](#food--drink) | :beer: | `:beer:` | :beers: | `:beers:` | [top](#introduction) | +| [top](#food--drink) | :clinking_glasses: | `:clinking_glasses:` | :tumbler_glass: | `:tumbler_glass:` | [top](#introduction) | +| [top](#food--drink) | :cup_with_straw: | `:cup_with_straw:` | :bubble_tea: | `:bubble_tea:` | [top](#introduction) | +| [top](#food--drink) | :beverage_box: | `:beverage_box:` | :mate: | `:mate:` | [top](#introduction) | +| [top](#food--drink) | :ice_cube: | `:ice_cube:` | | | [top](#introduction) | + +### Dishware + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#food--drink) | :chopsticks: | `:chopsticks:` | :plate_with_cutlery: | `:plate_with_cutlery:` | [top](#introduction) | +| [top](#food--drink) | :fork_and_knife: | `:fork_and_knife:` | :spoon: | `:spoon:` | [top](#introduction) | +| [top](#food--drink) | :hocho: | `:hocho:`
    `:knife:` | :amphora: | `:amphora:` | [top](#introduction) | + +## Travel & Places + +- [Place Map](#place-map) +- [Place Geographic](#place-geographic) +- [Place Building](#place-building) +- [Place Religious](#place-religious) +- [Place Other](#place-other) +- [Transport Ground](#transport-ground) +- [Transport Water](#transport-water) +- [Transport Air](#transport-air) +- [Hotel](#hotel) +- [Time](#time) +- [Sky & Weather](#sky--weather) + +### Place Map + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#travel--places) | :earth_africa: | `:earth_africa:` | :earth_americas: | `:earth_americas:` | [top](#introduction) | +| [top](#travel--places) | :earth_asia: | `:earth_asia:` | :globe_with_meridians: | `:globe_with_meridians:` | [top](#introduction) | +| [top](#travel--places) | :world_map: | `:world_map:` | :japan: | `:japan:` | [top](#introduction) | +| [top](#travel--places) | :compass: | `:compass:` | | | [top](#introduction) | + +### Place Geographic + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#travel--places) | :mountain_snow: | `:mountain_snow:` | :mountain: | `:mountain:` | [top](#introduction) | +| [top](#travel--places) | :volcano: | `:volcano:` | :mount_fuji: | `:mount_fuji:` | [top](#introduction) | +| [top](#travel--places) | :camping: | `:camping:` | :beach_umbrella: | `:beach_umbrella:` | [top](#introduction) | +| [top](#travel--places) | :desert: | `:desert:` | :desert_island: | `:desert_island:` | [top](#introduction) | +| [top](#travel--places) | :national_park: | `:national_park:` | | | [top](#introduction) | + +### Place Building + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#travel--places) | :stadium: | `:stadium:` | :classical_building: | `:classical_building:` | [top](#introduction) | +| [top](#travel--places) | :building_construction: | `:building_construction:` | :bricks: | `:bricks:` | [top](#introduction) | +| [top](#travel--places) | :rock: | `:rock:` | :wood: | `:wood:` | [top](#introduction) | +| [top](#travel--places) | :hut: | `:hut:` | :houses: | `:houses:` | [top](#introduction) | +| [top](#travel--places) | :derelict_house: | `:derelict_house:` | :house: | `:house:` | [top](#introduction) | +| [top](#travel--places) | :house_with_garden: | `:house_with_garden:` | :office: | `:office:` | [top](#introduction) | +| [top](#travel--places) | :post_office: | `:post_office:` | :european_post_office: | `:european_post_office:` | [top](#introduction) | +| [top](#travel--places) | :hospital: | `:hospital:` | :bank: | `:bank:` | [top](#introduction) | +| [top](#travel--places) | :hotel: | `:hotel:` | :love_hotel: | `:love_hotel:` | [top](#introduction) | +| [top](#travel--places) | :convenience_store: | `:convenience_store:` | :school: | `:school:` | [top](#introduction) | +| [top](#travel--places) | :department_store: | `:department_store:` | :factory: | `:factory:` | [top](#introduction) | +| [top](#travel--places) | :japanese_castle: | `:japanese_castle:` | :european_castle: | `:european_castle:` | [top](#introduction) | +| [top](#travel--places) | :wedding: | `:wedding:` | :tokyo_tower: | `:tokyo_tower:` | [top](#introduction) | +| [top](#travel--places) | :statue_of_liberty: | `:statue_of_liberty:` | | | [top](#introduction) | + +### Place Religious + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#travel--places) | :church: | `:church:` | :mosque: | `:mosque:` | [top](#introduction) | +| [top](#travel--places) | :hindu_temple: | `:hindu_temple:` | :synagogue: | `:synagogue:` | [top](#introduction) | +| [top](#travel--places) | :shinto_shrine: | `:shinto_shrine:` | :kaaba: | `:kaaba:` | [top](#introduction) | + +### Place Other + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#travel--places) | :fountain: | `:fountain:` | :tent: | `:tent:` | [top](#introduction) | +| [top](#travel--places) | :foggy: | `:foggy:` | :night_with_stars: | `:night_with_stars:` | [top](#introduction) | +| [top](#travel--places) | :cityscape: | `:cityscape:` | :sunrise_over_mountains: | `:sunrise_over_mountains:` | [top](#introduction) | +| [top](#travel--places) | :sunrise: | `:sunrise:` | :city_sunset: | `:city_sunset:` | [top](#introduction) | +| [top](#travel--places) | :city_sunrise: | `:city_sunrise:` | :bridge_at_night: | `:bridge_at_night:` | [top](#introduction) | +| [top](#travel--places) | :hotsprings: | `:hotsprings:` | :carousel_horse: | `:carousel_horse:` | [top](#introduction) | +| [top](#travel--places) | :ferris_wheel: | `:ferris_wheel:` | :roller_coaster: | `:roller_coaster:` | [top](#introduction) | +| [top](#travel--places) | :barber: | `:barber:` | :circus_tent: | `:circus_tent:` | [top](#introduction) | + +### Transport Ground + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#travel--places) | :steam_locomotive: | `:steam_locomotive:` | :railway_car: | `:railway_car:` | [top](#introduction) | +| [top](#travel--places) | :bullettrain_side: | `:bullettrain_side:` | :bullettrain_front: | `:bullettrain_front:` | [top](#introduction) | +| [top](#travel--places) | :train2: | `:train2:` | :metro: | `:metro:` | [top](#introduction) | +| [top](#travel--places) | :light_rail: | `:light_rail:` | :station: | `:station:` | [top](#introduction) | +| [top](#travel--places) | :tram: | `:tram:` | :monorail: | `:monorail:` | [top](#introduction) | +| [top](#travel--places) | :mountain_railway: | `:mountain_railway:` | :train: | `:train:` | [top](#introduction) | +| [top](#travel--places) | :bus: | `:bus:` | :oncoming_bus: | `:oncoming_bus:` | [top](#introduction) | +| [top](#travel--places) | :trolleybus: | `:trolleybus:` | :minibus: | `:minibus:` | [top](#introduction) | +| [top](#travel--places) | :ambulance: | `:ambulance:` | :fire_engine: | `:fire_engine:` | [top](#introduction) | +| [top](#travel--places) | :police_car: | `:police_car:` | :oncoming_police_car: | `:oncoming_police_car:` | [top](#introduction) | +| [top](#travel--places) | :taxi: | `:taxi:` | :oncoming_taxi: | `:oncoming_taxi:` | [top](#introduction) | +| [top](#travel--places) | :car: | `:car:`
    `:red_car:` | :oncoming_automobile: | `:oncoming_automobile:` | [top](#introduction) | +| [top](#travel--places) | :blue_car: | `:blue_car:` | :pickup_truck: | `:pickup_truck:` | [top](#introduction) | +| [top](#travel--places) | :truck: | `:truck:` | :articulated_lorry: | `:articulated_lorry:` | [top](#introduction) | +| [top](#travel--places) | :tractor: | `:tractor:` | :racing_car: | `:racing_car:` | [top](#introduction) | +| [top](#travel--places) | :motorcycle: | `:motorcycle:` | :motor_scooter: | `:motor_scooter:` | [top](#introduction) | +| [top](#travel--places) | :manual_wheelchair: | `:manual_wheelchair:` | :motorized_wheelchair: | `:motorized_wheelchair:` | [top](#introduction) | +| [top](#travel--places) | :auto_rickshaw: | `:auto_rickshaw:` | :bike: | `:bike:` | [top](#introduction) | +| [top](#travel--places) | :kick_scooter: | `:kick_scooter:` | :skateboard: | `:skateboard:` | [top](#introduction) | +| [top](#travel--places) | :roller_skate: | `:roller_skate:` | :busstop: | `:busstop:` | [top](#introduction) | +| [top](#travel--places) | :motorway: | `:motorway:` | :railway_track: | `:railway_track:` | [top](#introduction) | +| [top](#travel--places) | :oil_drum: | `:oil_drum:` | :fuelpump: | `:fuelpump:` | [top](#introduction) | +| [top](#travel--places) | :rotating_light: | `:rotating_light:` | :traffic_light: | `:traffic_light:` | [top](#introduction) | +| [top](#travel--places) | :vertical_traffic_light: | `:vertical_traffic_light:` | :stop_sign: | `:stop_sign:` | [top](#introduction) | +| [top](#travel--places) | :construction: | `:construction:` | | | [top](#introduction) | + +### Transport Water + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#travel--places) | :anchor: | `:anchor:` | :boat: | `:boat:`
    `:sailboat:` | [top](#introduction) | +| [top](#travel--places) | :canoe: | `:canoe:` | :speedboat: | `:speedboat:` | [top](#introduction) | +| [top](#travel--places) | :passenger_ship: | `:passenger_ship:` | :ferry: | `:ferry:` | [top](#introduction) | +| [top](#travel--places) | :motor_boat: | `:motor_boat:` | :ship: | `:ship:` | [top](#introduction) | + +### Transport Air + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#travel--places) | :airplane: | `:airplane:` | :small_airplane: | `:small_airplane:` | [top](#introduction) | +| [top](#travel--places) | :flight_departure: | `:flight_departure:` | :flight_arrival: | `:flight_arrival:` | [top](#introduction) | +| [top](#travel--places) | :parachute: | `:parachute:` | :seat: | `:seat:` | [top](#introduction) | +| [top](#travel--places) | :helicopter: | `:helicopter:` | :suspension_railway: | `:suspension_railway:` | [top](#introduction) | +| [top](#travel--places) | :mountain_cableway: | `:mountain_cableway:` | :aerial_tramway: | `:aerial_tramway:` | [top](#introduction) | +| [top](#travel--places) | :artificial_satellite: | `:artificial_satellite:` | :rocket: | `:rocket:` | [top](#introduction) | +| [top](#travel--places) | :flying_saucer: | `:flying_saucer:` | | | [top](#introduction) | + +### Hotel + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#travel--places) | :bellhop_bell: | `:bellhop_bell:` | :luggage: | `:luggage:` | [top](#introduction) | + +### Time + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#travel--places) | :hourglass: | `:hourglass:` | :hourglass_flowing_sand: | `:hourglass_flowing_sand:` | [top](#introduction) | +| [top](#travel--places) | :watch: | `:watch:` | :alarm_clock: | `:alarm_clock:` | [top](#introduction) | +| [top](#travel--places) | :stopwatch: | `:stopwatch:` | :timer_clock: | `:timer_clock:` | [top](#introduction) | +| [top](#travel--places) | :mantelpiece_clock: | `:mantelpiece_clock:` | :clock12: | `:clock12:` | [top](#introduction) | +| [top](#travel--places) | :clock1230: | `:clock1230:` | :clock1: | `:clock1:` | [top](#introduction) | +| [top](#travel--places) | :clock130: | `:clock130:` | :clock2: | `:clock2:` | [top](#introduction) | +| [top](#travel--places) | :clock230: | `:clock230:` | :clock3: | `:clock3:` | [top](#introduction) | +| [top](#travel--places) | :clock330: | `:clock330:` | :clock4: | `:clock4:` | [top](#introduction) | +| [top](#travel--places) | :clock430: | `:clock430:` | :clock5: | `:clock5:` | [top](#introduction) | +| [top](#travel--places) | :clock530: | `:clock530:` | :clock6: | `:clock6:` | [top](#introduction) | +| [top](#travel--places) | :clock630: | `:clock630:` | :clock7: | `:clock7:` | [top](#introduction) | +| [top](#travel--places) | :clock730: | `:clock730:` | :clock8: | `:clock8:` | [top](#introduction) | +| [top](#travel--places) | :clock830: | `:clock830:` | :clock9: | `:clock9:` | [top](#introduction) | +| [top](#travel--places) | :clock930: | `:clock930:` | :clock10: | `:clock10:` | [top](#introduction) | +| [top](#travel--places) | :clock1030: | `:clock1030:` | :clock11: | `:clock11:` | [top](#introduction) | +| [top](#travel--places) | :clock1130: | `:clock1130:` | | | [top](#introduction) | + +### Sky & Weather + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#travel--places) | :new_moon: | `:new_moon:` | :waxing_crescent_moon: | `:waxing_crescent_moon:` | [top](#introduction) | +| [top](#travel--places) | :first_quarter_moon: | `:first_quarter_moon:` | :moon: | `:moon:`
    `:waxing_gibbous_moon:` | [top](#introduction) | +| [top](#travel--places) | :full_moon: | `:full_moon:` | :waning_gibbous_moon: | `:waning_gibbous_moon:` | [top](#introduction) | +| [top](#travel--places) | :last_quarter_moon: | `:last_quarter_moon:` | :waning_crescent_moon: | `:waning_crescent_moon:` | [top](#introduction) | +| [top](#travel--places) | :crescent_moon: | `:crescent_moon:` | :new_moon_with_face: | `:new_moon_with_face:` | [top](#introduction) | +| [top](#travel--places) | :first_quarter_moon_with_face: | `:first_quarter_moon_with_face:` | :last_quarter_moon_with_face: | `:last_quarter_moon_with_face:` | [top](#introduction) | +| [top](#travel--places) | :thermometer: | `:thermometer:` | :sunny: | `:sunny:` | [top](#introduction) | +| [top](#travel--places) | :full_moon_with_face: | `:full_moon_with_face:` | :sun_with_face: | `:sun_with_face:` | [top](#introduction) | +| [top](#travel--places) | :ringed_planet: | `:ringed_planet:` | :star: | `:star:` | [top](#introduction) | +| [top](#travel--places) | :star2: | `:star2:` | :stars: | `:stars:` | [top](#introduction) | +| [top](#travel--places) | :milky_way: | `:milky_way:` | :cloud: | `:cloud:` | [top](#introduction) | +| [top](#travel--places) | :partly_sunny: | `:partly_sunny:` | :cloud_with_lightning_and_rain: | `:cloud_with_lightning_and_rain:` | [top](#introduction) | +| [top](#travel--places) | :sun_behind_small_cloud: | `:sun_behind_small_cloud:` | :sun_behind_large_cloud: | `:sun_behind_large_cloud:` | [top](#introduction) | +| [top](#travel--places) | :sun_behind_rain_cloud: | `:sun_behind_rain_cloud:` | :cloud_with_rain: | `:cloud_with_rain:` | [top](#introduction) | +| [top](#travel--places) | :cloud_with_snow: | `:cloud_with_snow:` | :cloud_with_lightning: | `:cloud_with_lightning:` | [top](#introduction) | +| [top](#travel--places) | :tornado: | `:tornado:` | :fog: | `:fog:` | [top](#introduction) | +| [top](#travel--places) | :wind_face: | `:wind_face:` | :cyclone: | `:cyclone:` | [top](#introduction) | +| [top](#travel--places) | :rainbow: | `:rainbow:` | :closed_umbrella: | `:closed_umbrella:` | [top](#introduction) | +| [top](#travel--places) | :open_umbrella: | `:open_umbrella:` | :umbrella: | `:umbrella:` | [top](#introduction) | +| [top](#travel--places) | :parasol_on_ground: | `:parasol_on_ground:` | :zap: | `:zap:` | [top](#introduction) | +| [top](#travel--places) | :snowflake: | `:snowflake:` | :snowman_with_snow: | `:snowman_with_snow:` | [top](#introduction) | +| [top](#travel--places) | :snowman: | `:snowman:` | :comet: | `:comet:` | [top](#introduction) | +| [top](#travel--places) | :fire: | `:fire:` | :droplet: | `:droplet:` | [top](#introduction) | +| [top](#travel--places) | :ocean: | `:ocean:` | | | [top](#introduction) | + +## Activities + +- [Event](#event) +- [Award Medal](#award-medal) +- [Sport](#sport) +- [Game](#game) +- [Arts & Crafts](#arts--crafts) + +### Event + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#activities) | :jack_o_lantern: | `:jack_o_lantern:` | :christmas_tree: | `:christmas_tree:` | [top](#introduction) | +| [top](#activities) | :fireworks: | `:fireworks:` | :sparkler: | `:sparkler:` | [top](#introduction) | +| [top](#activities) | :firecracker: | `:firecracker:` | :sparkles: | `:sparkles:` | [top](#introduction) | +| [top](#activities) | :balloon: | `:balloon:` | :tada: | `:tada:` | [top](#introduction) | +| [top](#activities) | :confetti_ball: | `:confetti_ball:` | :tanabata_tree: | `:tanabata_tree:` | [top](#introduction) | +| [top](#activities) | :bamboo: | `:bamboo:` | :dolls: | `:dolls:` | [top](#introduction) | +| [top](#activities) | :flags: | `:flags:` | :wind_chime: | `:wind_chime:` | [top](#introduction) | +| [top](#activities) | :rice_scene: | `:rice_scene:` | :red_envelope: | `:red_envelope:` | [top](#introduction) | +| [top](#activities) | :ribbon: | `:ribbon:` | :gift: | `:gift:` | [top](#introduction) | +| [top](#activities) | :reminder_ribbon: | `:reminder_ribbon:` | :tickets: | `:tickets:` | [top](#introduction) | +| [top](#activities) | :ticket: | `:ticket:` | | | [top](#introduction) | + +### Award Medal + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#activities) | :medal_military: | `:medal_military:` | :trophy: | `:trophy:` | [top](#introduction) | +| [top](#activities) | :medal_sports: | `:medal_sports:` | :1st_place_medal: | `:1st_place_medal:` | [top](#introduction) | +| [top](#activities) | :2nd_place_medal: | `:2nd_place_medal:` | :3rd_place_medal: | `:3rd_place_medal:` | [top](#introduction) | + +### Sport + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#activities) | :soccer: | `:soccer:` | :baseball: | `:baseball:` | [top](#introduction) | +| [top](#activities) | :softball: | `:softball:` | :basketball: | `:basketball:` | [top](#introduction) | +| [top](#activities) | :volleyball: | `:volleyball:` | :football: | `:football:` | [top](#introduction) | +| [top](#activities) | :rugby_football: | `:rugby_football:` | :tennis: | `:tennis:` | [top](#introduction) | +| [top](#activities) | :flying_disc: | `:flying_disc:` | :bowling: | `:bowling:` | [top](#introduction) | +| [top](#activities) | :cricket_game: | `:cricket_game:` | :field_hockey: | `:field_hockey:` | [top](#introduction) | +| [top](#activities) | :ice_hockey: | `:ice_hockey:` | :lacrosse: | `:lacrosse:` | [top](#introduction) | +| [top](#activities) | :ping_pong: | `:ping_pong:` | :badminton: | `:badminton:` | [top](#introduction) | +| [top](#activities) | :boxing_glove: | `:boxing_glove:` | :martial_arts_uniform: | `:martial_arts_uniform:` | [top](#introduction) | +| [top](#activities) | :goal_net: | `:goal_net:` | :golf: | `:golf:` | [top](#introduction) | +| [top](#activities) | :ice_skate: | `:ice_skate:` | :fishing_pole_and_fish: | `:fishing_pole_and_fish:` | [top](#introduction) | +| [top](#activities) | :diving_mask: | `:diving_mask:` | :running_shirt_with_sash: | `:running_shirt_with_sash:` | [top](#introduction) | +| [top](#activities) | :ski: | `:ski:` | :sled: | `:sled:` | [top](#introduction) | +| [top](#activities) | :curling_stone: | `:curling_stone:` | | | [top](#introduction) | + +### Game + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#activities) | :dart: | `:dart:` | :yo_yo: | `:yo_yo:` | [top](#introduction) | +| [top](#activities) | :kite: | `:kite:` | :gun: | `:gun:` | [top](#introduction) | +| [top](#activities) | :8ball: | `:8ball:` | :crystal_ball: | `:crystal_ball:` | [top](#introduction) | +| [top](#activities) | :magic_wand: | `:magic_wand:` | :video_game: | `:video_game:` | [top](#introduction) | +| [top](#activities) | :joystick: | `:joystick:` | :slot_machine: | `:slot_machine:` | [top](#introduction) | +| [top](#activities) | :game_die: | `:game_die:` | :jigsaw: | `:jigsaw:` | [top](#introduction) | +| [top](#activities) | :teddy_bear: | `:teddy_bear:` | :pinata: | `:pinata:` | [top](#introduction) | +| [top](#activities) | :nesting_dolls: | `:nesting_dolls:` | :spades: | `:spades:` | [top](#introduction) | +| [top](#activities) | :hearts: | `:hearts:` | :diamonds: | `:diamonds:` | [top](#introduction) | +| [top](#activities) | :clubs: | `:clubs:` | :chess_pawn: | `:chess_pawn:` | [top](#introduction) | +| [top](#activities) | :black_joker: | `:black_joker:` | :mahjong: | `:mahjong:` | [top](#introduction) | +| [top](#activities) | :flower_playing_cards: | `:flower_playing_cards:` | | | [top](#introduction) | + +### Arts & Crafts + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#activities) | :performing_arts: | `:performing_arts:` | :framed_picture: | `:framed_picture:` | [top](#introduction) | +| [top](#activities) | :art: | `:art:` | :thread: | `:thread:` | [top](#introduction) | +| [top](#activities) | :sewing_needle: | `:sewing_needle:` | :yarn: | `:yarn:` | [top](#introduction) | +| [top](#activities) | :knot: | `:knot:` | | | [top](#introduction) | + +## Objects + +- [Clothing](#clothing) +- [Sound](#sound) +- [Music](#music) +- [Musical Instrument](#musical-instrument) +- [Phone](#phone) +- [Computer](#computer) +- [Light & Video](#light--video) +- [Book Paper](#book-paper) +- [Money](#money) +- [Mail](#mail) +- [Writing](#writing) +- [Office](#office) +- [Lock](#lock) +- [Tool](#tool) +- [Science](#science) +- [Medical](#medical) +- [Household](#household) +- [Other Object](#other-object) + +### Clothing + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :eyeglasses: | `:eyeglasses:` | :dark_sunglasses: | `:dark_sunglasses:` | [top](#introduction) | +| [top](#objects) | :goggles: | `:goggles:` | :lab_coat: | `:lab_coat:` | [top](#introduction) | +| [top](#objects) | :safety_vest: | `:safety_vest:` | :necktie: | `:necktie:` | [top](#introduction) | +| [top](#objects) | :shirt: | `:shirt:`
    `:tshirt:` | :jeans: | `:jeans:` | [top](#introduction) | +| [top](#objects) | :scarf: | `:scarf:` | :gloves: | `:gloves:` | [top](#introduction) | +| [top](#objects) | :coat: | `:coat:` | :socks: | `:socks:` | [top](#introduction) | +| [top](#objects) | :dress: | `:dress:` | :kimono: | `:kimono:` | [top](#introduction) | +| [top](#objects) | :sari: | `:sari:` | :one_piece_swimsuit: | `:one_piece_swimsuit:` | [top](#introduction) | +| [top](#objects) | :swim_brief: | `:swim_brief:` | :shorts: | `:shorts:` | [top](#introduction) | +| [top](#objects) | :bikini: | `:bikini:` | :womans_clothes: | `:womans_clothes:` | [top](#introduction) | +| [top](#objects) | :purse: | `:purse:` | :handbag: | `:handbag:` | [top](#introduction) | +| [top](#objects) | :pouch: | `:pouch:` | :shopping: | `:shopping:` | [top](#introduction) | +| [top](#objects) | :school_satchel: | `:school_satchel:` | :thong_sandal: | `:thong_sandal:` | [top](#introduction) | +| [top](#objects) | :mans_shoe: | `:mans_shoe:`
    `:shoe:` | :athletic_shoe: | `:athletic_shoe:` | [top](#introduction) | +| [top](#objects) | :hiking_boot: | `:hiking_boot:` | :flat_shoe: | `:flat_shoe:` | [top](#introduction) | +| [top](#objects) | :high_heel: | `:high_heel:` | :sandal: | `:sandal:` | [top](#introduction) | +| [top](#objects) | :ballet_shoes: | `:ballet_shoes:` | :boot: | `:boot:` | [top](#introduction) | +| [top](#objects) | :crown: | `:crown:` | :womans_hat: | `:womans_hat:` | [top](#introduction) | +| [top](#objects) | :tophat: | `:tophat:` | :mortar_board: | `:mortar_board:` | [top](#introduction) | +| [top](#objects) | :billed_cap: | `:billed_cap:` | :military_helmet: | `:military_helmet:` | [top](#introduction) | +| [top](#objects) | :rescue_worker_helmet: | `:rescue_worker_helmet:` | :prayer_beads: | `:prayer_beads:` | [top](#introduction) | +| [top](#objects) | :lipstick: | `:lipstick:` | :ring: | `:ring:` | [top](#introduction) | +| [top](#objects) | :gem: | `:gem:` | | | [top](#introduction) | + +### Sound + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :mute: | `:mute:` | :speaker: | `:speaker:` | [top](#introduction) | +| [top](#objects) | :sound: | `:sound:` | :loud_sound: | `:loud_sound:` | [top](#introduction) | +| [top](#objects) | :loudspeaker: | `:loudspeaker:` | :mega: | `:mega:` | [top](#introduction) | +| [top](#objects) | :postal_horn: | `:postal_horn:` | :bell: | `:bell:` | [top](#introduction) | +| [top](#objects) | :no_bell: | `:no_bell:` | | | [top](#introduction) | + +### Music + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :musical_score: | `:musical_score:` | :musical_note: | `:musical_note:` | [top](#introduction) | +| [top](#objects) | :notes: | `:notes:` | :studio_microphone: | `:studio_microphone:` | [top](#introduction) | +| [top](#objects) | :level_slider: | `:level_slider:` | :control_knobs: | `:control_knobs:` | [top](#introduction) | +| [top](#objects) | :microphone: | `:microphone:` | :headphones: | `:headphones:` | [top](#introduction) | +| [top](#objects) | :radio: | `:radio:` | | | [top](#introduction) | + +### Musical Instrument + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :saxophone: | `:saxophone:` | :accordion: | `:accordion:` | [top](#introduction) | +| [top](#objects) | :guitar: | `:guitar:` | :musical_keyboard: | `:musical_keyboard:` | [top](#introduction) | +| [top](#objects) | :trumpet: | `:trumpet:` | :violin: | `:violin:` | [top](#introduction) | +| [top](#objects) | :banjo: | `:banjo:` | :drum: | `:drum:` | [top](#introduction) | +| [top](#objects) | :long_drum: | `:long_drum:` | | | [top](#introduction) | + +### Phone + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :iphone: | `:iphone:` | :calling: | `:calling:` | [top](#introduction) | +| [top](#objects) | :phone: | `:phone:`
    `:telephone:` | :telephone_receiver: | `:telephone_receiver:` | [top](#introduction) | +| [top](#objects) | :pager: | `:pager:` | :fax: | `:fax:` | [top](#introduction) | + +### Computer + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :battery: | `:battery:` | :electric_plug: | `:electric_plug:` | [top](#introduction) | +| [top](#objects) | :computer: | `:computer:` | :desktop_computer: | `:desktop_computer:` | [top](#introduction) | +| [top](#objects) | :printer: | `:printer:` | :keyboard: | `:keyboard:` | [top](#introduction) | +| [top](#objects) | :computer_mouse: | `:computer_mouse:` | :trackball: | `:trackball:` | [top](#introduction) | +| [top](#objects) | :minidisc: | `:minidisc:` | :floppy_disk: | `:floppy_disk:` | [top](#introduction) | +| [top](#objects) | :cd: | `:cd:` | :dvd: | `:dvd:` | [top](#introduction) | +| [top](#objects) | :abacus: | `:abacus:` | | | [top](#introduction) | + +### Light & Video + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :movie_camera: | `:movie_camera:` | :film_strip: | `:film_strip:` | [top](#introduction) | +| [top](#objects) | :film_projector: | `:film_projector:` | :clapper: | `:clapper:` | [top](#introduction) | +| [top](#objects) | :tv: | `:tv:` | :camera: | `:camera:` | [top](#introduction) | +| [top](#objects) | :camera_flash: | `:camera_flash:` | :video_camera: | `:video_camera:` | [top](#introduction) | +| [top](#objects) | :vhs: | `:vhs:` | :mag: | `:mag:` | [top](#introduction) | +| [top](#objects) | :mag_right: | `:mag_right:` | :candle: | `:candle:` | [top](#introduction) | +| [top](#objects) | :bulb: | `:bulb:` | :flashlight: | `:flashlight:` | [top](#introduction) | +| [top](#objects) | :izakaya_lantern: | `:izakaya_lantern:`
    `:lantern:` | :diya_lamp: | `:diya_lamp:` | [top](#introduction) | + +### Book Paper + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :notebook_with_decorative_cover: | `:notebook_with_decorative_cover:` | :closed_book: | `:closed_book:` | [top](#introduction) | +| [top](#objects) | :book: | `:book:`
    `:open_book:` | :green_book: | `:green_book:` | [top](#introduction) | +| [top](#objects) | :blue_book: | `:blue_book:` | :orange_book: | `:orange_book:` | [top](#introduction) | +| [top](#objects) | :books: | `:books:` | :notebook: | `:notebook:` | [top](#introduction) | +| [top](#objects) | :ledger: | `:ledger:` | :page_with_curl: | `:page_with_curl:` | [top](#introduction) | +| [top](#objects) | :scroll: | `:scroll:` | :page_facing_up: | `:page_facing_up:` | [top](#introduction) | +| [top](#objects) | :newspaper: | `:newspaper:` | :newspaper_roll: | `:newspaper_roll:` | [top](#introduction) | +| [top](#objects) | :bookmark_tabs: | `:bookmark_tabs:` | :bookmark: | `:bookmark:` | [top](#introduction) | +| [top](#objects) | :label: | `:label:` | | | [top](#introduction) | + +### Money + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :moneybag: | `:moneybag:` | :coin: | `:coin:` | [top](#introduction) | +| [top](#objects) | :yen: | `:yen:` | :dollar: | `:dollar:` | [top](#introduction) | +| [top](#objects) | :euro: | `:euro:` | :pound: | `:pound:` | [top](#introduction) | +| [top](#objects) | :money_with_wings: | `:money_with_wings:` | :credit_card: | `:credit_card:` | [top](#introduction) | +| [top](#objects) | :receipt: | `:receipt:` | :chart: | `:chart:` | [top](#introduction) | + +### Mail + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :envelope: | `:envelope:` | :e-mail: | `:e-mail:`
    `:email:` | [top](#introduction) | +| [top](#objects) | :incoming_envelope: | `:incoming_envelope:` | :envelope_with_arrow: | `:envelope_with_arrow:` | [top](#introduction) | +| [top](#objects) | :outbox_tray: | `:outbox_tray:` | :inbox_tray: | `:inbox_tray:` | [top](#introduction) | +| [top](#objects) | :package: | `:package:` | :mailbox: | `:mailbox:` | [top](#introduction) | +| [top](#objects) | :mailbox_closed: | `:mailbox_closed:` | :mailbox_with_mail: | `:mailbox_with_mail:` | [top](#introduction) | +| [top](#objects) | :mailbox_with_no_mail: | `:mailbox_with_no_mail:` | :postbox: | `:postbox:` | [top](#introduction) | +| [top](#objects) | :ballot_box: | `:ballot_box:` | | | [top](#introduction) | + +### Writing + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :pencil2: | `:pencil2:` | :black_nib: | `:black_nib:` | [top](#introduction) | +| [top](#objects) | :fountain_pen: | `:fountain_pen:` | :pen: | `:pen:` | [top](#introduction) | +| [top](#objects) | :paintbrush: | `:paintbrush:` | :crayon: | `:crayon:` | [top](#introduction) | +| [top](#objects) | :memo: | `:memo:`
    `:pencil:` | | | [top](#introduction) | + +### Office + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :briefcase: | `:briefcase:` | :file_folder: | `:file_folder:` | [top](#introduction) | +| [top](#objects) | :open_file_folder: | `:open_file_folder:` | :card_index_dividers: | `:card_index_dividers:` | [top](#introduction) | +| [top](#objects) | :date: | `:date:` | :calendar: | `:calendar:` | [top](#introduction) | +| [top](#objects) | :spiral_notepad: | `:spiral_notepad:` | :spiral_calendar: | `:spiral_calendar:` | [top](#introduction) | +| [top](#objects) | :card_index: | `:card_index:` | :chart_with_upwards_trend: | `:chart_with_upwards_trend:` | [top](#introduction) | +| [top](#objects) | :chart_with_downwards_trend: | `:chart_with_downwards_trend:` | :bar_chart: | `:bar_chart:` | [top](#introduction) | +| [top](#objects) | :clipboard: | `:clipboard:` | :pushpin: | `:pushpin:` | [top](#introduction) | +| [top](#objects) | :round_pushpin: | `:round_pushpin:` | :paperclip: | `:paperclip:` | [top](#introduction) | +| [top](#objects) | :paperclips: | `:paperclips:` | :straight_ruler: | `:straight_ruler:` | [top](#introduction) | +| [top](#objects) | :triangular_ruler: | `:triangular_ruler:` | :scissors: | `:scissors:` | [top](#introduction) | +| [top](#objects) | :card_file_box: | `:card_file_box:` | :file_cabinet: | `:file_cabinet:` | [top](#introduction) | +| [top](#objects) | :wastebasket: | `:wastebasket:` | | | [top](#introduction) | + +### Lock + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :lock: | `:lock:` | :unlock: | `:unlock:` | [top](#introduction) | +| [top](#objects) | :lock_with_ink_pen: | `:lock_with_ink_pen:` | :closed_lock_with_key: | `:closed_lock_with_key:` | [top](#introduction) | +| [top](#objects) | :key: | `:key:` | :old_key: | `:old_key:` | [top](#introduction) | + +### Tool + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :hammer: | `:hammer:` | :axe: | `:axe:` | [top](#introduction) | +| [top](#objects) | :pick: | `:pick:` | :hammer_and_pick: | `:hammer_and_pick:` | [top](#introduction) | +| [top](#objects) | :hammer_and_wrench: | `:hammer_and_wrench:` | :dagger: | `:dagger:` | [top](#introduction) | +| [top](#objects) | :crossed_swords: | `:crossed_swords:` | :bomb: | `:bomb:` | [top](#introduction) | +| [top](#objects) | :boomerang: | `:boomerang:` | :bow_and_arrow: | `:bow_and_arrow:` | [top](#introduction) | +| [top](#objects) | :shield: | `:shield:` | :carpentry_saw: | `:carpentry_saw:` | [top](#introduction) | +| [top](#objects) | :wrench: | `:wrench:` | :screwdriver: | `:screwdriver:` | [top](#introduction) | +| [top](#objects) | :nut_and_bolt: | `:nut_and_bolt:` | :gear: | `:gear:` | [top](#introduction) | +| [top](#objects) | :clamp: | `:clamp:` | :balance_scale: | `:balance_scale:` | [top](#introduction) | +| [top](#objects) | :probing_cane: | `:probing_cane:` | :link: | `:link:` | [top](#introduction) | +| [top](#objects) | :chains: | `:chains:` | :hook: | `:hook:` | [top](#introduction) | +| [top](#objects) | :toolbox: | `:toolbox:` | :magnet: | `:magnet:` | [top](#introduction) | +| [top](#objects) | :ladder: | `:ladder:` | | | [top](#introduction) | + +### Science + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :alembic: | `:alembic:` | :test_tube: | `:test_tube:` | [top](#introduction) | +| [top](#objects) | :petri_dish: | `:petri_dish:` | :dna: | `:dna:` | [top](#introduction) | +| [top](#objects) | :microscope: | `:microscope:` | :telescope: | `:telescope:` | [top](#introduction) | +| [top](#objects) | :satellite: | `:satellite:` | | | [top](#introduction) | + +### Medical + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :syringe: | `:syringe:` | :drop_of_blood: | `:drop_of_blood:` | [top](#introduction) | +| [top](#objects) | :pill: | `:pill:` | :adhesive_bandage: | `:adhesive_bandage:` | [top](#introduction) | +| [top](#objects) | :stethoscope: | `:stethoscope:` | | | [top](#introduction) | + +### Household + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :door: | `:door:` | :elevator: | `:elevator:` | [top](#introduction) | +| [top](#objects) | :mirror: | `:mirror:` | :window: | `:window:` | [top](#introduction) | +| [top](#objects) | :bed: | `:bed:` | :couch_and_lamp: | `:couch_and_lamp:` | [top](#introduction) | +| [top](#objects) | :chair: | `:chair:` | :toilet: | `:toilet:` | [top](#introduction) | +| [top](#objects) | :plunger: | `:plunger:` | :shower: | `:shower:` | [top](#introduction) | +| [top](#objects) | :bathtub: | `:bathtub:` | :mouse_trap: | `:mouse_trap:` | [top](#introduction) | +| [top](#objects) | :razor: | `:razor:` | :lotion_bottle: | `:lotion_bottle:` | [top](#introduction) | +| [top](#objects) | :safety_pin: | `:safety_pin:` | :broom: | `:broom:` | [top](#introduction) | +| [top](#objects) | :basket: | `:basket:` | :roll_of_paper: | `:roll_of_paper:` | [top](#introduction) | +| [top](#objects) | :bucket: | `:bucket:` | :soap: | `:soap:` | [top](#introduction) | +| [top](#objects) | :toothbrush: | `:toothbrush:` | :sponge: | `:sponge:` | [top](#introduction) | +| [top](#objects) | :fire_extinguisher: | `:fire_extinguisher:` | :shopping_cart: | `:shopping_cart:` | [top](#introduction) | + +### Other Object + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#objects) | :smoking: | `:smoking:` | :coffin: | `:coffin:` | [top](#introduction) | +| [top](#objects) | :headstone: | `:headstone:` | :funeral_urn: | `:funeral_urn:` | [top](#introduction) | +| [top](#objects) | :nazar_amulet: | `:nazar_amulet:` | :moyai: | `:moyai:` | [top](#introduction) | +| [top](#objects) | :placard: | `:placard:` | | | [top](#introduction) | + +## Symbols + +- [Transport Sign](#transport-sign) +- [Warning](#warning) +- [Arrow](#arrow) +- [Religion](#religion) +- [Zodiac](#zodiac) +- [Av Symbol](#av-symbol) +- [Gender](#gender) +- [Math](#math) +- [Punctuation](#punctuation) +- [Currency](#currency) +- [Other Symbol](#other-symbol) +- [Keycap](#keycap) +- [Alphanum](#alphanum) +- [Geometric](#geometric) + +### Transport Sign + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :atm: | `:atm:` | :put_litter_in_its_place: | `:put_litter_in_its_place:` | [top](#introduction) | +| [top](#symbols) | :potable_water: | `:potable_water:` | :wheelchair: | `:wheelchair:` | [top](#introduction) | +| [top](#symbols) | :mens: | `:mens:` | :womens: | `:womens:` | [top](#introduction) | +| [top](#symbols) | :restroom: | `:restroom:` | :baby_symbol: | `:baby_symbol:` | [top](#introduction) | +| [top](#symbols) | :wc: | `:wc:` | :passport_control: | `:passport_control:` | [top](#introduction) | +| [top](#symbols) | :customs: | `:customs:` | :baggage_claim: | `:baggage_claim:` | [top](#introduction) | +| [top](#symbols) | :left_luggage: | `:left_luggage:` | | | [top](#introduction) | + +### Warning + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :warning: | `:warning:` | :children_crossing: | `:children_crossing:` | [top](#introduction) | +| [top](#symbols) | :no_entry: | `:no_entry:` | :no_entry_sign: | `:no_entry_sign:` | [top](#introduction) | +| [top](#symbols) | :no_bicycles: | `:no_bicycles:` | :no_smoking: | `:no_smoking:` | [top](#introduction) | +| [top](#symbols) | :do_not_litter: | `:do_not_litter:` | :non-potable_water: | `:non-potable_water:` | [top](#introduction) | +| [top](#symbols) | :no_pedestrians: | `:no_pedestrians:` | :no_mobile_phones: | `:no_mobile_phones:` | [top](#introduction) | +| [top](#symbols) | :underage: | `:underage:` | :radioactive: | `:radioactive:` | [top](#introduction) | +| [top](#symbols) | :biohazard: | `:biohazard:` | | | [top](#introduction) | + +### Arrow + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :arrow_up: | `:arrow_up:` | :arrow_upper_right: | `:arrow_upper_right:` | [top](#introduction) | +| [top](#symbols) | :arrow_right: | `:arrow_right:` | :arrow_lower_right: | `:arrow_lower_right:` | [top](#introduction) | +| [top](#symbols) | :arrow_down: | `:arrow_down:` | :arrow_lower_left: | `:arrow_lower_left:` | [top](#introduction) | +| [top](#symbols) | :arrow_left: | `:arrow_left:` | :arrow_upper_left: | `:arrow_upper_left:` | [top](#introduction) | +| [top](#symbols) | :arrow_up_down: | `:arrow_up_down:` | :left_right_arrow: | `:left_right_arrow:` | [top](#introduction) | +| [top](#symbols) | :leftwards_arrow_with_hook: | `:leftwards_arrow_with_hook:` | :arrow_right_hook: | `:arrow_right_hook:` | [top](#introduction) | +| [top](#symbols) | :arrow_heading_up: | `:arrow_heading_up:` | :arrow_heading_down: | `:arrow_heading_down:` | [top](#introduction) | +| [top](#symbols) | :arrows_clockwise: | `:arrows_clockwise:` | :arrows_counterclockwise: | `:arrows_counterclockwise:` | [top](#introduction) | +| [top](#symbols) | :back: | `:back:` | :end: | `:end:` | [top](#introduction) | +| [top](#symbols) | :on: | `:on:` | :soon: | `:soon:` | [top](#introduction) | +| [top](#symbols) | :top: | `:top:` | | | [top](#introduction) | + +### Religion + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :place_of_worship: | `:place_of_worship:` | :atom_symbol: | `:atom_symbol:` | [top](#introduction) | +| [top](#symbols) | :om: | `:om:` | :star_of_david: | `:star_of_david:` | [top](#introduction) | +| [top](#symbols) | :wheel_of_dharma: | `:wheel_of_dharma:` | :yin_yang: | `:yin_yang:` | [top](#introduction) | +| [top](#symbols) | :latin_cross: | `:latin_cross:` | :orthodox_cross: | `:orthodox_cross:` | [top](#introduction) | +| [top](#symbols) | :star_and_crescent: | `:star_and_crescent:` | :peace_symbol: | `:peace_symbol:` | [top](#introduction) | +| [top](#symbols) | :menorah: | `:menorah:` | :six_pointed_star: | `:six_pointed_star:` | [top](#introduction) | + +### Zodiac + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :aries: | `:aries:` | :taurus: | `:taurus:` | [top](#introduction) | +| [top](#symbols) | :gemini: | `:gemini:` | :cancer: | `:cancer:` | [top](#introduction) | +| [top](#symbols) | :leo: | `:leo:` | :virgo: | `:virgo:` | [top](#introduction) | +| [top](#symbols) | :libra: | `:libra:` | :scorpius: | `:scorpius:` | [top](#introduction) | +| [top](#symbols) | :sagittarius: | `:sagittarius:` | :capricorn: | `:capricorn:` | [top](#introduction) | +| [top](#symbols) | :aquarius: | `:aquarius:` | :pisces: | `:pisces:` | [top](#introduction) | +| [top](#symbols) | :ophiuchus: | `:ophiuchus:` | | | [top](#introduction) | + +### Av Symbol + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :twisted_rightwards_arrows: | `:twisted_rightwards_arrows:` | :repeat: | `:repeat:` | [top](#introduction) | +| [top](#symbols) | :repeat_one: | `:repeat_one:` | :arrow_forward: | `:arrow_forward:` | [top](#introduction) | +| [top](#symbols) | :fast_forward: | `:fast_forward:` | :next_track_button: | `:next_track_button:` | [top](#introduction) | +| [top](#symbols) | :play_or_pause_button: | `:play_or_pause_button:` | :arrow_backward: | `:arrow_backward:` | [top](#introduction) | +| [top](#symbols) | :rewind: | `:rewind:` | :previous_track_button: | `:previous_track_button:` | [top](#introduction) | +| [top](#symbols) | :arrow_up_small: | `:arrow_up_small:` | :arrow_double_up: | `:arrow_double_up:` | [top](#introduction) | +| [top](#symbols) | :arrow_down_small: | `:arrow_down_small:` | :arrow_double_down: | `:arrow_double_down:` | [top](#introduction) | +| [top](#symbols) | :pause_button: | `:pause_button:` | :stop_button: | `:stop_button:` | [top](#introduction) | +| [top](#symbols) | :record_button: | `:record_button:` | :eject_button: | `:eject_button:` | [top](#introduction) | +| [top](#symbols) | :cinema: | `:cinema:` | :low_brightness: | `:low_brightness:` | [top](#introduction) | +| [top](#symbols) | :high_brightness: | `:high_brightness:` | :signal_strength: | `:signal_strength:` | [top](#introduction) | +| [top](#symbols) | :vibration_mode: | `:vibration_mode:` | :mobile_phone_off: | `:mobile_phone_off:` | [top](#introduction) | + +### Gender + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :female_sign: | `:female_sign:` | :male_sign: | `:male_sign:` | [top](#introduction) | +| [top](#symbols) | :transgender_symbol: | `:transgender_symbol:` | | | [top](#introduction) | + +### Math + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :heavy_multiplication_x: | `:heavy_multiplication_x:` | :heavy_plus_sign: | `:heavy_plus_sign:` | [top](#introduction) | +| [top](#symbols) | :heavy_minus_sign: | `:heavy_minus_sign:` | :heavy_division_sign: | `:heavy_division_sign:` | [top](#introduction) | +| [top](#symbols) | :infinity: | `:infinity:` | | | [top](#introduction) | + +### Punctuation + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :bangbang: | `:bangbang:` | :interrobang: | `:interrobang:` | [top](#introduction) | +| [top](#symbols) | :question: | `:question:` | :grey_question: | `:grey_question:` | [top](#introduction) | +| [top](#symbols) | :grey_exclamation: | `:grey_exclamation:` | :exclamation: | `:exclamation:`
    `:heavy_exclamation_mark:` | [top](#introduction) | +| [top](#symbols) | :wavy_dash: | `:wavy_dash:` | | | [top](#introduction) | + +### Currency + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :currency_exchange: | `:currency_exchange:` | :heavy_dollar_sign: | `:heavy_dollar_sign:` | [top](#introduction) | + +### Other Symbol + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :medical_symbol: | `:medical_symbol:` | :recycle: | `:recycle:` | [top](#introduction) | +| [top](#symbols) | :fleur_de_lis: | `:fleur_de_lis:` | :trident: | `:trident:` | [top](#introduction) | +| [top](#symbols) | :name_badge: | `:name_badge:` | :beginner: | `:beginner:` | [top](#introduction) | +| [top](#symbols) | :o: | `:o:` | :white_check_mark: | `:white_check_mark:` | [top](#introduction) | +| [top](#symbols) | :ballot_box_with_check: | `:ballot_box_with_check:` | :heavy_check_mark: | `:heavy_check_mark:` | [top](#introduction) | +| [top](#symbols) | :x: | `:x:` | :negative_squared_cross_mark: | `:negative_squared_cross_mark:` | [top](#introduction) | +| [top](#symbols) | :curly_loop: | `:curly_loop:` | :loop: | `:loop:` | [top](#introduction) | +| [top](#symbols) | :part_alternation_mark: | `:part_alternation_mark:` | :eight_spoked_asterisk: | `:eight_spoked_asterisk:` | [top](#introduction) | +| [top](#symbols) | :eight_pointed_black_star: | `:eight_pointed_black_star:` | :sparkle: | `:sparkle:` | [top](#introduction) | +| [top](#symbols) | :copyright: | `:copyright:` | :registered: | `:registered:` | [top](#introduction) | +| [top](#symbols) | :tm: | `:tm:` | | | [top](#introduction) | + +### Keycap + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :hash: | `:hash:` | :asterisk: | `:asterisk:` | [top](#introduction) | +| [top](#symbols) | :zero: | `:zero:` | :one: | `:one:` | [top](#introduction) | +| [top](#symbols) | :two: | `:two:` | :three: | `:three:` | [top](#introduction) | +| [top](#symbols) | :four: | `:four:` | :five: | `:five:` | [top](#introduction) | +| [top](#symbols) | :six: | `:six:` | :seven: | `:seven:` | [top](#introduction) | +| [top](#symbols) | :eight: | `:eight:` | :nine: | `:nine:` | [top](#introduction) | +| [top](#symbols) | :keycap_ten: | `:keycap_ten:` | | | [top](#introduction) | + +### Alphanum + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :capital_abcd: | `:capital_abcd:` | :abcd: | `:abcd:` | [top](#introduction) | +| [top](#symbols) | :1234: | `:1234:` | :symbols: | `:symbols:` | [top](#introduction) | +| [top](#symbols) | :abc: | `:abc:` | :a: | `:a:` | [top](#introduction) | +| [top](#symbols) | :ab: | `:ab:` | :b: | `:b:` | [top](#introduction) | +| [top](#symbols) | :cl: | `:cl:` | :cool: | `:cool:` | [top](#introduction) | +| [top](#symbols) | :free: | `:free:` | :information_source: | `:information_source:` | [top](#introduction) | +| [top](#symbols) | :id: | `:id:` | :m: | `:m:` | [top](#introduction) | +| [top](#symbols) | :new: | `:new:` | :ng: | `:ng:` | [top](#introduction) | +| [top](#symbols) | :o2: | `:o2:` | :ok: | `:ok:` | [top](#introduction) | +| [top](#symbols) | :parking: | `:parking:` | :sos: | `:sos:` | [top](#introduction) | +| [top](#symbols) | :up: | `:up:` | :vs: | `:vs:` | [top](#introduction) | +| [top](#symbols) | :koko: | `:koko:` | :sa: | `:sa:` | [top](#introduction) | +| [top](#symbols) | :u6708: | `:u6708:` | :u6709: | `:u6709:` | [top](#introduction) | +| [top](#symbols) | :u6307: | `:u6307:` | :ideograph_advantage: | `:ideograph_advantage:` | [top](#introduction) | +| [top](#symbols) | :u5272: | `:u5272:` | :u7121: | `:u7121:` | [top](#introduction) | +| [top](#symbols) | :u7981: | `:u7981:` | :accept: | `:accept:` | [top](#introduction) | +| [top](#symbols) | :u7533: | `:u7533:` | :u5408: | `:u5408:` | [top](#introduction) | +| [top](#symbols) | :u7a7a: | `:u7a7a:` | :congratulations: | `:congratulations:` | [top](#introduction) | +| [top](#symbols) | :secret: | `:secret:` | :u55b6: | `:u55b6:` | [top](#introduction) | +| [top](#symbols) | :u6e80: | `:u6e80:` | | | [top](#introduction) | + +### Geometric + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#symbols) | :red_circle: | `:red_circle:` | :orange_circle: | `:orange_circle:` | [top](#introduction) | +| [top](#symbols) | :yellow_circle: | `:yellow_circle:` | :green_circle: | `:green_circle:` | [top](#introduction) | +| [top](#symbols) | :large_blue_circle: | `:large_blue_circle:` | :purple_circle: | `:purple_circle:` | [top](#introduction) | +| [top](#symbols) | :brown_circle: | `:brown_circle:` | :black_circle: | `:black_circle:` | [top](#introduction) | +| [top](#symbols) | :white_circle: | `:white_circle:` | :red_square: | `:red_square:` | [top](#introduction) | +| [top](#symbols) | :orange_square: | `:orange_square:` | :yellow_square: | `:yellow_square:` | [top](#introduction) | +| [top](#symbols) | :green_square: | `:green_square:` | :blue_square: | `:blue_square:` | [top](#introduction) | +| [top](#symbols) | :purple_square: | `:purple_square:` | :brown_square: | `:brown_square:` | [top](#introduction) | +| [top](#symbols) | :black_large_square: | `:black_large_square:` | :white_large_square: | `:white_large_square:` | [top](#introduction) | +| [top](#symbols) | :black_medium_square: | `:black_medium_square:` | :white_medium_square: | `:white_medium_square:` | [top](#introduction) | +| [top](#symbols) | :black_medium_small_square: | `:black_medium_small_square:` | :white_medium_small_square: | `:white_medium_small_square:` | [top](#introduction) | +| [top](#symbols) | :black_small_square: | `:black_small_square:` | :white_small_square: | `:white_small_square:` | [top](#introduction) | +| [top](#symbols) | :large_orange_diamond: | `:large_orange_diamond:` | :large_blue_diamond: | `:large_blue_diamond:` | [top](#introduction) | +| [top](#symbols) | :small_orange_diamond: | `:small_orange_diamond:` | :small_blue_diamond: | `:small_blue_diamond:` | [top](#introduction) | +| [top](#symbols) | :small_red_triangle: | `:small_red_triangle:` | :small_red_triangle_down: | `:small_red_triangle_down:` | [top](#introduction) | +| [top](#symbols) | :diamond_shape_with_a_dot_inside: | `:diamond_shape_with_a_dot_inside:` | :radio_button: | `:radio_button:` | [top](#introduction) | +| [top](#symbols) | :white_square_button: | `:white_square_button:` | :black_square_button: | `:black_square_button:` | [top](#introduction) | + +## Flags + +- [Flag](#flag) +- [Country Flag](#country-flag) +- [Subdivision Flag](#subdivision-flag) + +### Flag + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#flags) | :checkered_flag: | `:checkered_flag:` | :triangular_flag_on_post: | `:triangular_flag_on_post:` | [top](#introduction) | +| [top](#flags) | :crossed_flags: | `:crossed_flags:` | :black_flag: | `:black_flag:` | [top](#introduction) | +| [top](#flags) | :white_flag: | `:white_flag:` | :rainbow_flag: | `:rainbow_flag:` | [top](#introduction) | +| [top](#flags) | :transgender_flag: | `:transgender_flag:` | :pirate_flag: | `:pirate_flag:` | [top](#introduction) | + +### Country Flag + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#flags) | :ascension_island: | `:ascension_island:` | :andorra: | `:andorra:` | [top](#introduction) | +| [top](#flags) | :united_arab_emirates: | `:united_arab_emirates:` | :afghanistan: | `:afghanistan:` | [top](#introduction) | +| [top](#flags) | :antigua_barbuda: | `:antigua_barbuda:` | :anguilla: | `:anguilla:` | [top](#introduction) | +| [top](#flags) | :albania: | `:albania:` | :armenia: | `:armenia:` | [top](#introduction) | +| [top](#flags) | :angola: | `:angola:` | :antarctica: | `:antarctica:` | [top](#introduction) | +| [top](#flags) | :argentina: | `:argentina:` | :american_samoa: | `:american_samoa:` | [top](#introduction) | +| [top](#flags) | :austria: | `:austria:` | :australia: | `:australia:` | [top](#introduction) | +| [top](#flags) | :aruba: | `:aruba:` | :aland_islands: | `:aland_islands:` | [top](#introduction) | +| [top](#flags) | :azerbaijan: | `:azerbaijan:` | :bosnia_herzegovina: | `:bosnia_herzegovina:` | [top](#introduction) | +| [top](#flags) | :barbados: | `:barbados:` | :bangladesh: | `:bangladesh:` | [top](#introduction) | +| [top](#flags) | :belgium: | `:belgium:` | :burkina_faso: | `:burkina_faso:` | [top](#introduction) | +| [top](#flags) | :bulgaria: | `:bulgaria:` | :bahrain: | `:bahrain:` | [top](#introduction) | +| [top](#flags) | :burundi: | `:burundi:` | :benin: | `:benin:` | [top](#introduction) | +| [top](#flags) | :st_barthelemy: | `:st_barthelemy:` | :bermuda: | `:bermuda:` | [top](#introduction) | +| [top](#flags) | :brunei: | `:brunei:` | :bolivia: | `:bolivia:` | [top](#introduction) | +| [top](#flags) | :caribbean_netherlands: | `:caribbean_netherlands:` | :brazil: | `:brazil:` | [top](#introduction) | +| [top](#flags) | :bahamas: | `:bahamas:` | :bhutan: | `:bhutan:` | [top](#introduction) | +| [top](#flags) | :bouvet_island: | `:bouvet_island:` | :botswana: | `:botswana:` | [top](#introduction) | +| [top](#flags) | :belarus: | `:belarus:` | :belize: | `:belize:` | [top](#introduction) | +| [top](#flags) | :canada: | `:canada:` | :cocos_islands: | `:cocos_islands:` | [top](#introduction) | +| [top](#flags) | :congo_kinshasa: | `:congo_kinshasa:` | :central_african_republic: | `:central_african_republic:` | [top](#introduction) | +| [top](#flags) | :congo_brazzaville: | `:congo_brazzaville:` | :switzerland: | `:switzerland:` | [top](#introduction) | +| [top](#flags) | :cote_divoire: | `:cote_divoire:` | :cook_islands: | `:cook_islands:` | [top](#introduction) | +| [top](#flags) | :chile: | `:chile:` | :cameroon: | `:cameroon:` | [top](#introduction) | +| [top](#flags) | :cn: | `:cn:` | :colombia: | `:colombia:` | [top](#introduction) | +| [top](#flags) | :clipperton_island: | `:clipperton_island:` | :costa_rica: | `:costa_rica:` | [top](#introduction) | +| [top](#flags) | :cuba: | `:cuba:` | :cape_verde: | `:cape_verde:` | [top](#introduction) | +| [top](#flags) | :curacao: | `:curacao:` | :christmas_island: | `:christmas_island:` | [top](#introduction) | +| [top](#flags) | :cyprus: | `:cyprus:` | :czech_republic: | `:czech_republic:` | [top](#introduction) | +| [top](#flags) | :de: | `:de:` | :diego_garcia: | `:diego_garcia:` | [top](#introduction) | +| [top](#flags) | :djibouti: | `:djibouti:` | :denmark: | `:denmark:` | [top](#introduction) | +| [top](#flags) | :dominica: | `:dominica:` | :dominican_republic: | `:dominican_republic:` | [top](#introduction) | +| [top](#flags) | :algeria: | `:algeria:` | :ceuta_melilla: | `:ceuta_melilla:` | [top](#introduction) | +| [top](#flags) | :ecuador: | `:ecuador:` | :estonia: | `:estonia:` | [top](#introduction) | +| [top](#flags) | :egypt: | `:egypt:` | :western_sahara: | `:western_sahara:` | [top](#introduction) | +| [top](#flags) | :eritrea: | `:eritrea:` | :es: | `:es:` | [top](#introduction) | +| [top](#flags) | :ethiopia: | `:ethiopia:` | :eu: | `:eu:`
    `:european_union:` | [top](#introduction) | +| [top](#flags) | :finland: | `:finland:` | :fiji: | `:fiji:` | [top](#introduction) | +| [top](#flags) | :falkland_islands: | `:falkland_islands:` | :micronesia: | `:micronesia:` | [top](#introduction) | +| [top](#flags) | :faroe_islands: | `:faroe_islands:` | :fr: | `:fr:` | [top](#introduction) | +| [top](#flags) | :gabon: | `:gabon:` | :gb: | `:gb:`
    `:uk:` | [top](#introduction) | +| [top](#flags) | :grenada: | `:grenada:` | :georgia: | `:georgia:` | [top](#introduction) | +| [top](#flags) | :french_guiana: | `:french_guiana:` | :guernsey: | `:guernsey:` | [top](#introduction) | +| [top](#flags) | :ghana: | `:ghana:` | :gibraltar: | `:gibraltar:` | [top](#introduction) | +| [top](#flags) | :greenland: | `:greenland:` | :gambia: | `:gambia:` | [top](#introduction) | +| [top](#flags) | :guinea: | `:guinea:` | :guadeloupe: | `:guadeloupe:` | [top](#introduction) | +| [top](#flags) | :equatorial_guinea: | `:equatorial_guinea:` | :greece: | `:greece:` | [top](#introduction) | +| [top](#flags) | :south_georgia_south_sandwich_islands: | `:south_georgia_south_sandwich_islands:` | :guatemala: | `:guatemala:` | [top](#introduction) | +| [top](#flags) | :guam: | `:guam:` | :guinea_bissau: | `:guinea_bissau:` | [top](#introduction) | +| [top](#flags) | :guyana: | `:guyana:` | :hong_kong: | `:hong_kong:` | [top](#introduction) | +| [top](#flags) | :heard_mcdonald_islands: | `:heard_mcdonald_islands:` | :honduras: | `:honduras:` | [top](#introduction) | +| [top](#flags) | :croatia: | `:croatia:` | :haiti: | `:haiti:` | [top](#introduction) | +| [top](#flags) | :hungary: | `:hungary:` | :canary_islands: | `:canary_islands:` | [top](#introduction) | +| [top](#flags) | :indonesia: | `:indonesia:` | :ireland: | `:ireland:` | [top](#introduction) | +| [top](#flags) | :israel: | `:israel:` | :isle_of_man: | `:isle_of_man:` | [top](#introduction) | +| [top](#flags) | :india: | `:india:` | :british_indian_ocean_territory: | `:british_indian_ocean_territory:` | [top](#introduction) | +| [top](#flags) | :iraq: | `:iraq:` | :iran: | `:iran:` | [top](#introduction) | +| [top](#flags) | :iceland: | `:iceland:` | :it: | `:it:` | [top](#introduction) | +| [top](#flags) | :jersey: | `:jersey:` | :jamaica: | `:jamaica:` | [top](#introduction) | +| [top](#flags) | :jordan: | `:jordan:` | :jp: | `:jp:` | [top](#introduction) | +| [top](#flags) | :kenya: | `:kenya:` | :kyrgyzstan: | `:kyrgyzstan:` | [top](#introduction) | +| [top](#flags) | :cambodia: | `:cambodia:` | :kiribati: | `:kiribati:` | [top](#introduction) | +| [top](#flags) | :comoros: | `:comoros:` | :st_kitts_nevis: | `:st_kitts_nevis:` | [top](#introduction) | +| [top](#flags) | :north_korea: | `:north_korea:` | :kr: | `:kr:` | [top](#introduction) | +| [top](#flags) | :kuwait: | `:kuwait:` | :cayman_islands: | `:cayman_islands:` | [top](#introduction) | +| [top](#flags) | :kazakhstan: | `:kazakhstan:` | :laos: | `:laos:` | [top](#introduction) | +| [top](#flags) | :lebanon: | `:lebanon:` | :st_lucia: | `:st_lucia:` | [top](#introduction) | +| [top](#flags) | :liechtenstein: | `:liechtenstein:` | :sri_lanka: | `:sri_lanka:` | [top](#introduction) | +| [top](#flags) | :liberia: | `:liberia:` | :lesotho: | `:lesotho:` | [top](#introduction) | +| [top](#flags) | :lithuania: | `:lithuania:` | :luxembourg: | `:luxembourg:` | [top](#introduction) | +| [top](#flags) | :latvia: | `:latvia:` | :libya: | `:libya:` | [top](#introduction) | +| [top](#flags) | :morocco: | `:morocco:` | :monaco: | `:monaco:` | [top](#introduction) | +| [top](#flags) | :moldova: | `:moldova:` | :montenegro: | `:montenegro:` | [top](#introduction) | +| [top](#flags) | :st_martin: | `:st_martin:` | :madagascar: | `:madagascar:` | [top](#introduction) | +| [top](#flags) | :marshall_islands: | `:marshall_islands:` | :macedonia: | `:macedonia:` | [top](#introduction) | +| [top](#flags) | :mali: | `:mali:` | :myanmar: | `:myanmar:` | [top](#introduction) | +| [top](#flags) | :mongolia: | `:mongolia:` | :macau: | `:macau:` | [top](#introduction) | +| [top](#flags) | :northern_mariana_islands: | `:northern_mariana_islands:` | :martinique: | `:martinique:` | [top](#introduction) | +| [top](#flags) | :mauritania: | `:mauritania:` | :montserrat: | `:montserrat:` | [top](#introduction) | +| [top](#flags) | :malta: | `:malta:` | :mauritius: | `:mauritius:` | [top](#introduction) | +| [top](#flags) | :maldives: | `:maldives:` | :malawi: | `:malawi:` | [top](#introduction) | +| [top](#flags) | :mexico: | `:mexico:` | :malaysia: | `:malaysia:` | [top](#introduction) | +| [top](#flags) | :mozambique: | `:mozambique:` | :namibia: | `:namibia:` | [top](#introduction) | +| [top](#flags) | :new_caledonia: | `:new_caledonia:` | :niger: | `:niger:` | [top](#introduction) | +| [top](#flags) | :norfolk_island: | `:norfolk_island:` | :nigeria: | `:nigeria:` | [top](#introduction) | +| [top](#flags) | :nicaragua: | `:nicaragua:` | :netherlands: | `:netherlands:` | [top](#introduction) | +| [top](#flags) | :norway: | `:norway:` | :nepal: | `:nepal:` | [top](#introduction) | +| [top](#flags) | :nauru: | `:nauru:` | :niue: | `:niue:` | [top](#introduction) | +| [top](#flags) | :new_zealand: | `:new_zealand:` | :oman: | `:oman:` | [top](#introduction) | +| [top](#flags) | :panama: | `:panama:` | :peru: | `:peru:` | [top](#introduction) | +| [top](#flags) | :french_polynesia: | `:french_polynesia:` | :papua_new_guinea: | `:papua_new_guinea:` | [top](#introduction) | +| [top](#flags) | :philippines: | `:philippines:` | :pakistan: | `:pakistan:` | [top](#introduction) | +| [top](#flags) | :poland: | `:poland:` | :st_pierre_miquelon: | `:st_pierre_miquelon:` | [top](#introduction) | +| [top](#flags) | :pitcairn_islands: | `:pitcairn_islands:` | :puerto_rico: | `:puerto_rico:` | [top](#introduction) | +| [top](#flags) | :palestinian_territories: | `:palestinian_territories:` | :portugal: | `:portugal:` | [top](#introduction) | +| [top](#flags) | :palau: | `:palau:` | :paraguay: | `:paraguay:` | [top](#introduction) | +| [top](#flags) | :qatar: | `:qatar:` | :reunion: | `:reunion:` | [top](#introduction) | +| [top](#flags) | :romania: | `:romania:` | :serbia: | `:serbia:` | [top](#introduction) | +| [top](#flags) | :ru: | `:ru:` | :rwanda: | `:rwanda:` | [top](#introduction) | +| [top](#flags) | :saudi_arabia: | `:saudi_arabia:` | :solomon_islands: | `:solomon_islands:` | [top](#introduction) | +| [top](#flags) | :seychelles: | `:seychelles:` | :sudan: | `:sudan:` | [top](#introduction) | +| [top](#flags) | :sweden: | `:sweden:` | :singapore: | `:singapore:` | [top](#introduction) | +| [top](#flags) | :st_helena: | `:st_helena:` | :slovenia: | `:slovenia:` | [top](#introduction) | +| [top](#flags) | :svalbard_jan_mayen: | `:svalbard_jan_mayen:` | :slovakia: | `:slovakia:` | [top](#introduction) | +| [top](#flags) | :sierra_leone: | `:sierra_leone:` | :san_marino: | `:san_marino:` | [top](#introduction) | +| [top](#flags) | :senegal: | `:senegal:` | :somalia: | `:somalia:` | [top](#introduction) | +| [top](#flags) | :suriname: | `:suriname:` | :south_sudan: | `:south_sudan:` | [top](#introduction) | +| [top](#flags) | :sao_tome_principe: | `:sao_tome_principe:` | :el_salvador: | `:el_salvador:` | [top](#introduction) | +| [top](#flags) | :sint_maarten: | `:sint_maarten:` | :syria: | `:syria:` | [top](#introduction) | +| [top](#flags) | :swaziland: | `:swaziland:` | :tristan_da_cunha: | `:tristan_da_cunha:` | [top](#introduction) | +| [top](#flags) | :turks_caicos_islands: | `:turks_caicos_islands:` | :chad: | `:chad:` | [top](#introduction) | +| [top](#flags) | :french_southern_territories: | `:french_southern_territories:` | :togo: | `:togo:` | [top](#introduction) | +| [top](#flags) | :thailand: | `:thailand:` | :tajikistan: | `:tajikistan:` | [top](#introduction) | +| [top](#flags) | :tokelau: | `:tokelau:` | :timor_leste: | `:timor_leste:` | [top](#introduction) | +| [top](#flags) | :turkmenistan: | `:turkmenistan:` | :tunisia: | `:tunisia:` | [top](#introduction) | +| [top](#flags) | :tonga: | `:tonga:` | :tr: | `:tr:` | [top](#introduction) | +| [top](#flags) | :trinidad_tobago: | `:trinidad_tobago:` | :tuvalu: | `:tuvalu:` | [top](#introduction) | +| [top](#flags) | :taiwan: | `:taiwan:` | :tanzania: | `:tanzania:` | [top](#introduction) | +| [top](#flags) | :ukraine: | `:ukraine:` | :uganda: | `:uganda:` | [top](#introduction) | +| [top](#flags) | :us_outlying_islands: | `:us_outlying_islands:` | :united_nations: | `:united_nations:` | [top](#introduction) | +| [top](#flags) | :us: | `:us:` | :uruguay: | `:uruguay:` | [top](#introduction) | +| [top](#flags) | :uzbekistan: | `:uzbekistan:` | :vatican_city: | `:vatican_city:` | [top](#introduction) | +| [top](#flags) | :st_vincent_grenadines: | `:st_vincent_grenadines:` | :venezuela: | `:venezuela:` | [top](#introduction) | +| [top](#flags) | :british_virgin_islands: | `:british_virgin_islands:` | :us_virgin_islands: | `:us_virgin_islands:` | [top](#introduction) | +| [top](#flags) | :vietnam: | `:vietnam:` | :vanuatu: | `:vanuatu:` | [top](#introduction) | +| [top](#flags) | :wallis_futuna: | `:wallis_futuna:` | :samoa: | `:samoa:` | [top](#introduction) | +| [top](#flags) | :kosovo: | `:kosovo:` | :yemen: | `:yemen:` | [top](#introduction) | +| [top](#flags) | :mayotte: | `:mayotte:` | :south_africa: | `:south_africa:` | [top](#introduction) | +| [top](#flags) | :zambia: | `:zambia:` | :zimbabwe: | `:zimbabwe:` | [top](#introduction) | + +### Subdivision Flag + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#flags) | :england: | `:england:` | :scotland: | `:scotland:` | [top](#introduction) | +| [top](#flags) | :wales: | `:wales:` | | | [top](#introduction) | + +## GitHub Custom Emoji + +| | ico | shortcode | ico | shortcode | | +| - | :-: | - | :-: | - | - | +| [top](#github-custom-emoji) | :accessibility: | `:accessibility:` | :atom: | `:atom:` | [top](#introduction) | +| [top](#github-custom-emoji) | :basecamp: | `:basecamp:` | :basecampy: | `:basecampy:` | [top](#introduction) | +| [top](#github-custom-emoji) | :bowtie: | `:bowtie:` | :dependabot: | `:dependabot:` | [top](#introduction) | +| [top](#github-custom-emoji) | :electron: | `:electron:` | :feelsgood: | `:feelsgood:` | [top](#introduction) | +| [top](#github-custom-emoji) | :finnadie: | `:finnadie:` | :fishsticks: | `:fishsticks:` | [top](#introduction) | +| [top](#github-custom-emoji) | :goberserk: | `:goberserk:` | :godmode: | `:godmode:` | [top](#introduction) | +| [top](#github-custom-emoji) | :hurtrealbad: | `:hurtrealbad:` | :neckbeard: | `:neckbeard:` | [top](#introduction) | +| [top](#github-custom-emoji) | :octocat: | `:octocat:` | :rage1: | `:rage1:` | [top](#introduction) | +| [top](#github-custom-emoji) | :rage2: | `:rage2:` | :rage3: | `:rage3:` | [top](#introduction) | +| [top](#github-custom-emoji) | :rage4: | `:rage4:` | :shipit: | `:shipit:` | [top](#introduction) | +| [top](#github-custom-emoji) | :suspect: | `:suspect:` | :trollface: | `:trollface:` | [top](#introduction) | diff --git a/content/en/quick-reference/functions.md b/content/en/quick-reference/functions.md new file mode 100644 index 000000000..24368a866 --- /dev/null +++ b/content/en/quick-reference/functions.md @@ -0,0 +1,14 @@ +--- +title: Functions +description: A quick reference guide to Hugo's functions, grouped by namespace. Aliases, if any, appear in parentheses to the right of the function name. +categories: [] +keywords: [] +menu: + docs: + parent: quick-reference + weight: 30 +weight: 30 +toc: true +--- + +{{% quick-reference section="functions" %}} diff --git a/content/en/quick-reference/methods.md b/content/en/quick-reference/methods.md new file mode 100644 index 000000000..d89fce2d4 --- /dev/null +++ b/content/en/quick-reference/methods.md @@ -0,0 +1,14 @@ +--- +title: Methods +description: A quick reference guide to Hugo's methods, grouped by object. +categories: [] +keywords: [] +menu: + docs: + parent: quick-reference + weight: 40 +weight: 40 +toc: true +--- + +{{% quick-reference section="methods" %}} diff --git a/content/en/showcase/1password-support/bio.md b/content/en/showcase/1password-support/bio.md index 9187908d9..3e15adc9f 100644 --- a/content/en/showcase/1password-support/bio.md +++ b/content/en/showcase/1password-support/bio.md @@ -1,5 +1,4 @@ **1Password** is a password manager that keeps you safe online. It protects your secure information behind the one password only you know. - The [1Password Support](https://support.1password.com/) website was built from scratch with **Hugo** and enhanced with **React** and **Elasticsearch** to give us the best of both worlds: The simplicity and performance of a static site, with the richness of a hosted web app. diff --git a/content/en/showcase/1password-support/index.md b/content/en/showcase/1password-support/index.md index 2bcbff3fd..ed44053c8 100644 --- a/content/en/showcase/1password-support/index.md +++ b/content/en/showcase/1password-support/index.md @@ -34,6 +34,6 @@ Finding a tool that will make your customers, writers, designers, _and_ DevOps t * [1Password Support](https://support.1password.com) uses Hugo with a custom theme. It shares styles and some template code with [1Password.com](https://1password.com), which we also moved to Hugo in 2016. * Code and articles live in a private GitHub repository, which is deployed to a static content server using Git hooks. * Writers build and preview the site on their computers and contribute content using pull requests. - * We use Hugo's [multilingual support](/content-management/multilingual/) to build the site in English, Spanish, French, Italian, German, and Russian. With the help of Hugo, 1Password Support became our very first site in multiple languages. +* We use Hugo's [multilingual support](/content-management/multilingual/) to build the site in English, Spanish, French, Italian, German, and Russian. With the help of Hugo, 1Password Support became our very first site in multiple languages. * Our [contact form](https://support.1password.com/contact) is a single-page React app. We were able to integrate it with Hugo seamlessly thanks to its support for static files. * The one part of the support site which is not static is our search engine, which we developed with Elasticsearch and host on AWS. diff --git a/content/en/showcase/alora-labs/bio.md b/content/en/showcase/alora-labs/bio.md index d304cf191..f14a90b75 100644 --- a/content/en/showcase/alora-labs/bio.md +++ b/content/en/showcase/alora-labs/bio.md @@ -1,3 +1,3 @@ -**Alora Labs** is a product development consultancy headquartered in Toronto, Canada. +**Alora Labs** is a product development consultancy headquartered in Toronto, Canada. We help companies build software and IoT products and were recently recognized as one of the [**top IoT development firms**](https://aloralabs.com/insights/alora-labs-receives-clutch-2021-top-iot-agency-award) in Toronto. diff --git a/content/en/showcase/alora-labs/index.md b/content/en/showcase/alora-labs/index.md index 5e6e18131..79a3c5416 100644 --- a/content/en/showcase/alora-labs/index.md +++ b/content/en/showcase/alora-labs/index.md @@ -9,10 +9,10 @@ aliases: [/showcase/aloralabs/] At Alora Labs we always have an eye open for new tools and technology that we can utilize to the benefit of our customers or internal projects like our website. -The previous iteration of our site was built with Jekyll, which served us well at first. However as time went on, we became frustrated with the number of dependencies we had to rely on, that would often break at the most inconvenient times. +The previous iteration of our site was built with Jekyll, which served us well at first. However as time went on, we became frustrated with the number of dependencies we had to rely on, that would often break at the most inconvenient times. Hugo was a breath of fresh air in this regard, a single binary that works equally well on Windows as it did on macOS or Linux. We no longer need additional tools for image optimization, Sass compilation or JavaScript bundling. Everything just works, and with a substantial performance boost too. -Hugo has become a favorite tool in the toolbelt and the foundation for many client projects. We couldn't be happier with the switch and we are optimistic about recommending Hugo for many years to come. +Hugo has become a favorite tool in the toolbelt and the foundation for many client projects. We couldn't be happier with the switch and we are optimistic about recommending Hugo for many years to come. -Thank you to the vibrant community and talented development team for all the hard work in making Hugo a success. As excellent as Hugo is now, we cannot wait to see what the release notes have in store for us next. \ No newline at end of file +Thank you to the vibrant community and talented development team for all the hard work in making Hugo a success. As excellent as Hugo is now, we cannot wait to see what the release notes have in store for us next. diff --git a/content/en/showcase/ampio-help/index.md b/content/en/showcase/ampio-help/index.md index 3d21192b8..9b6850385 100644 --- a/content/en/showcase/ampio-help/index.md +++ b/content/en/showcase/ampio-help/index.md @@ -47,7 +47,7 @@ We even implemented a simple REST API generated by Hugo! We have yet to find som When talking about Hugo, we cannot forget about the speed. At the beginning we were not considering it a killer feature, but as our document base grew bigger, we appreciated it more and more. Dry-runs are not so common---most of the time we are working on one of the documents with cache already built during one of the previous Hugo runs. In such a scenario, Hugo rebuilds the site in about a second and we consider it a very good result. -``` +```text | EN | PL -------------------+-----+------ Pages | 483 | 486 diff --git a/content/en/showcase/bypasscensorship/bio.md b/content/en/showcase/bypasscensorship/bio.md index 6563e13ca..0a847df1e 100644 --- a/content/en/showcase/bypasscensorship/bio.md +++ b/content/en/showcase/bypasscensorship/bio.md @@ -3,4 +3,4 @@ Bypass Censorship find and promote tools that provide Internet access to everyon The site is built by: * [Leyla Avsar](https://www.leylaavsar.com/) (designer) -* [Fredrik Jonsson](https://xdeb.net/) (dev) \ No newline at end of file +* [Fredrik Jonsson](https://xdeb.net/) (dev) diff --git a/content/en/showcase/bypasscensorship/index.md b/content/en/showcase/bypasscensorship/index.md index a266797ea..8cbda9aa6 100644 --- a/content/en/showcase/bypasscensorship/index.md +++ b/content/en/showcase/bypasscensorship/index.md @@ -21,4 +21,4 @@ It's a simply site, basically one page in seven languages. I had no problems get Thanks to the design by [Leyla Avsar](https://www.leylaavsar.com/) the site also looks good. I used the [Hugo Zen theme](https://github.com/frjo/hugo-theme-zen) with a few custom templates and the needed CSS. -The editors can maintain content via [Forestry.io CMS](https://forestry.io/) or directly via Git. Forestry does unfortunately not have multilingual support. All the language versions are in one pile making it harder to find the right file to edit, but it works. \ No newline at end of file +The editors can maintain content via [Forestry.io CMS](https://forestry.io/) or directly via Git. Forestry does unfortunately not have multilingual support. All the language versions are in one pile making it harder to find the right file to edit, but it works. diff --git a/content/en/showcase/digitalgov/index.md b/content/en/showcase/digitalgov/index.md index c0a927edb..4376bbf03 100644 --- a/content/en/showcase/digitalgov/index.md +++ b/content/en/showcase/digitalgov/index.md @@ -12,11 +12,11 @@ Through collaboration in our communities of practice, Digital.gov is a window in Digital.gov is built using the [U.S. Web Design System](https://designsystem.digital.gov/) (USWDS) and have followed the [design principles](https://designsystem.digital.gov/maturity-model/) in building out our new site: -- **Start with real user needs** — We used human-centered design methods to inform our product decisions (like qualitative user research), and gathered feedback from real users. We also continually test our assumptions with small experiments. -- **Earn trust** —We recognize that trust has to be earned every time. We are including all [required links and content](https://digital.gov/resources/required-web-content-and-links/) on our site, clearly identifying as a government site, building with modern best practices, and using HTTPS. -- **Embrace accessibility** — [Accessibility](https://digital.gov/resources/intro-accessibility/) affects everybody, and we built it into every decision. We’re continually working to conform to Section 508 requirements, use user experience best practices, and support a wide range of devices. -- **Promote continuity** — We started from shared solutions like USWDS and [Federalist](https://federalist.18f.gov/). We designed our site to clearly identify as a government site by including USWDS’s .gov banner, common colors and patterns, and built with modern best practices. -- **Listen** — We actively collect user feedback and web metrics. We use the [Digital Analytics Program](https://digital.gov/services/dap/) (DAP) and analyze the data to discover actionable insights. We make small, incremental changes to continuously improve our website by listening to readers and learning from what we hear. +- **Start with real user needs** — We used human-centered design methods to inform our product decisions (like qualitative user research), and gathered feedback from real users. We also continually test our assumptions with small experiments. +- **Earn trust** —We recognize that trust has to be earned every time. We are including all [required links and content](https://digital.gov/resources/required-web-content-and-links/) on our site, clearly identifying as a government site, building with modern best practices, and using HTTPS. +- **Embrace accessibility** — [Accessibility](https://digital.gov/resources/intro-accessibility/) affects everybody, and we built it into every decision. We’re continually working to conform to Section 508 requirements, use user experience best practices, and support a wide range of devices. +- **Promote continuity** — We started from shared solutions like USWDS and [Federalist](https://federalist.18f.gov/). We designed our site to clearly identify as a government site by including USWDS’s .gov banner, common colors and patterns, and built with modern best practices. +- **Listen** — We actively collect user feedback and web metrics. We use the [Digital Analytics Program](https://digital.gov/services/dap/) (DAP) and analyze the data to discover actionable insights. We make small, incremental changes to continuously improve our website by listening to readers and learning from what we hear. _More on the [USWDS maturity model »](https://designsystem.digital.gov/maturity-model/)_ @@ -34,7 +34,7 @@ At the moment, it takes around `32 seconds` to build close to `~10,000` pages! Take a look: -```bash +```text | EN -------------------+------- @@ -48,19 +48,17 @@ Take a look: Cleaned | 0 Built in 32.427 seconds - ``` In addition to Hugo, we are proudly using a number of other tools and services, all built by government are free to use: -- [Federalist](https://federalist.18f.gov/) -- [Search.gov](https://www.search.gov/) — A free, hosted search platform for federal websites. -- [Cloud.gov](https://www.cloud.gov/) — helps teams build, run, and authorize cloud-ready or legacy government systems quickly and cheaply. -- [Federal CrowdSource Mobile Testing Program](https://digital.gov/services/mobile-application-testing-program/) — Free mobile compatibility testing by feds, for feds. -- [Digital Analytics Program](https://digital.gov/services/dap/) (DAP) — A free analytics tool for measuring digital services in the federal government -- [Section508.gov](https://www.section508.gov/) and [PlainLanguage.gov](https://www.plainlanguage.gov/) resources -- [API.data.gov](https://api.data.gov/) — a free API management service for federal agencies -- [U.S. Digital Registry](https://digital.gov/services/u-s-digital-registry/) — A resource for confirming the official status of government social media accounts, mobile apps, and mobile websites. - +- [Federalist](https://federalist.18f.gov/) +- [Search.gov](https://www.search.gov/) — A free, hosted search platform for federal websites. +- [Cloud.gov](https://www.cloud.gov/) — helps teams build, run, and authorize cloud-ready or legacy government systems quickly and cheaply. +- [Federal CrowdSource Mobile Testing Program](https://digital.gov/services/mobile-application-testing-program/) — Free mobile compatibility testing by feds, for feds. +- [Digital Analytics Program](https://digital.gov/services/dap/) (DAP) — A free analytics tool for measuring digital services in the federal government +- [Section508.gov](https://www.section508.gov/) and [PlainLanguage.gov](https://www.plainlanguage.gov/) resources +- [API.data.gov](https://api.data.gov/) — a free API management service for federal agencies +- [U.S. Digital Registry](https://digital.gov/services/u-s-digital-registry/) — A resource for confirming the official status of government social media accounts, mobile apps, and mobile websites. **Questions or feedback?** [Submit an issue](https://github.com/GSA/digitalgov.gov/issues) or send us an email to [digitalgov@gsa.gov](mailto:digitalgov@gsa.gov) :heart: diff --git a/content/en/showcase/forestry/index.md b/content/en/showcase/forestry/index.md index fbfe9b961..32a932a7a 100644 --- a/content/en/showcase/forestry/index.md +++ b/content/en/showcase/forestry/index.md @@ -14,7 +14,7 @@ In our early research we looked at Ionic’s [site](https://github.com/ionic-tea We knew Hugo was fast but we did [some additional benchmarking](https://forestry.io/blog/hugo-vs-jekyll-benchmark/) before making our decision. Seeing Hugo in action is a whole different world of awesome. Hugo takes less than one second to build our 150-page site! Take a look: -```bash +```text | EN +------------------+-----+ Pages | 141 @@ -41,7 +41,7 @@ Lastly, we want to take the opportunity to give some love to other amazing tools * Chris can’t think of modern web development without [**Gulp**](https://gulpjs.com/) & [**Webpack**](https://webpack.js.org/). We used them to add additional build steps such as Browsersync, CSS, JS and SVG optimization. * Speaking about adding steps to our build, our lives would be much harder without [**CircleCI**](https://circleci.com/) for continuous deployment and automated testing purposes. * We can’t stop raving about [**Algolia**](https://www.algolia.com/). Chris loves it and even wrote a tutorial on [how to implement Algolia](https://forestry.io/blog/search-with-algolia-in-hugo/) into static sites using Hugo’s [Custom Outputs](/templates/output-formats/). -* [**Cloudinary**](https://cloudinary.com/) is probably one of the easiest ways to get responsive images into your website. +* [**Cloudinary**](https://cloudinary.com/) is probably one of the easiest ways to get responsive images into your website. * We might be a little biased on this one - We think [**Forestry.io**](https://forestry.io/) is a great way to add a content management system with a clean UI on top of your site without interrupting your experience as a developer. * For hosting purposes we use the almighty [**AWS**](https://aws.amazon.com/). * [**Formspree.io**](https://formspree.io/) is managing our support and enterprise requests. diff --git a/content/en/showcase/godot-tutorials/index.md b/content/en/showcase/godot-tutorials/index.md index 56a8dfc4d..3b71fd8bc 100644 --- a/content/en/showcase/godot-tutorials/index.md +++ b/content/en/showcase/godot-tutorials/index.md @@ -13,7 +13,6 @@ byline: "[Godot Tutorials](https://godottutorials.com), Web Developer & Game Pro --- - [Godot Tutorials](https://godottutorials.com) started as a way to teach beginners game programming and game development. As I created videos, I ran into a problem; if I made a mistake with a YouTube video, it was difficult to correct errors. @@ -22,4 +21,4 @@ I discovered that blogging episodes and having articles that teach on top of my As I researched blogging platforms, I came across two solutions; however, I chose [Hugo](https://gohugo.io) because it's built with Markdown in mind and simplified my workflow. In a sense, with [Hugo](https://gohugo.io) programmed the right way, I can focus **more time on planning, creating, and editing** -my videos and **less time maintaining and fixing** my website. \ No newline at end of file +my videos and **less time maintaining and fixing** my website. diff --git a/content/en/showcase/letsencrypt/index.md b/content/en/showcase/letsencrypt/index.md index 18221ed68..6ad4b7840 100644 --- a/content/en/showcase/letsencrypt/index.md +++ b/content/en/showcase/letsencrypt/index.md @@ -17,5 +17,4 @@ That site is bookmarked in many browsers, so preserving the URLs was a must. Hug The lessons learned from this also lead to [disableLanguages](/content-management/multilingual/#disable-a-language) in Hugo `0.34` (a way to turn off languages during translation). And I also registered [this issue](https://github.com/gohugoio/hugo/issues/4463). Once fixed it will make it easier to handle partially translated sites. - [^1]: The work on getting the content translated is in progress. diff --git a/content/en/showcase/pharmaseal/index.md b/content/en/showcase/pharmaseal/index.md index 64e9960a3..2110b4396 100644 --- a/content/en/showcase/pharmaseal/index.md +++ b/content/en/showcase/pharmaseal/index.md @@ -11,13 +11,11 @@ siteURL: https://pharmaseal.co/ # Link to the site's Hugo source code if public and you can/want to share. # Remove or leave blank if not needed/wanted. - # Add credit to the article author. Leave blank or remove if not needed/wanted. byline: "[Roboto Studio](https://roboto.studio), Jonathan Alford" --- - We wanted to shake the status quo with PHARMASEAL, opting for a fast and scalable website built with Hugo instead of slower monolithic systems the competitors were using. We had two goals: @@ -34,4 +32,4 @@ We're big fans of simplicity, and that's what we delivered with the Forestry bui PHARMASEAL have found Forestry CMS combined with HUGO to be so effective at producing fast, purpose driven pages, that we have worked with them to add even more blocks in a scalable, modular fashion. -**TLDR:** We're blown away with HUGO, the sheer speed, scalability and deployment possibilities with Netlify is the 💣 \ No newline at end of file +**TLDR:** We're blown away with HUGO, the sheer speed, scalability and deployment possibilities with Netlify is the 💣 diff --git a/content/en/showcase/quiply-employee-communications-app/bio.md b/content/en/showcase/quiply-employee-communications-app/bio.md index f72a62554..f79677a1a 100644 --- a/content/en/showcase/quiply-employee-communications-app/bio.md +++ b/content/en/showcase/quiply-employee-communications-app/bio.md @@ -1,4 +1,4 @@ **Quiply** is an employee communications app enabling mobile collaboration across an entire organization. -Our customers get their own branded app enabling them to communicate fast and effectively with all employees, also non-desk and shift workers. +Our customers get their own branded app enabling them to communicate fast and effectively with all employees, also non-desk and shift workers. As the Quiply app's build process is based on **Gulp**, we have started to build our company and product website using **Gulp + Hugo** which is super-fast and gives us exactly the flexibility we need. diff --git a/content/en/showcase/template/bio.md b/content/en/showcase/template/bio.md index 597163340..de9287898 100644 --- a/content/en/showcase/template/bio.md +++ b/content/en/showcase/template/bio.md @@ -3,6 +3,5 @@ Add some **general info** about the site 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) diff --git a/content/en/templates/data-templates.md b/content/en/templates/data-templates.md index cf835af44..97da22db5 100644 --- a/content/en/templates/data-templates.md +++ b/content/en/templates/data-templates.md @@ -12,20 +12,18 @@ aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/] toc: true --- - - Hugo supports loading data from YAML, JSON, XML, and TOML files located in the `data` directory at the root of your Hugo project. {{< youtube FyPgSuwIMWQ >}} -## The data folder +## The data directory -The `data` folder should store additional data for Hugo to use when generating your site. +The `data` directory should store additional data for Hugo to use when generating your site. Data files are not for generating standalone pages. They should supplement content files by: -- extending the content when the front matter fields grow out of control, or -- showing a larger dataset in a template (see the example below). +- Extending the content when the front matter fields grow out of control, or +- Showing a larger dataset in a template (see the example below). In both cases, it's a good idea to outsource the data in their (own) files. @@ -58,7 +56,9 @@ The keys in the map created with data templates from data files will be a dot-ch This is best explained with an example: -## Example: Jaco Pastorius' Solo Discography +## Examples + +### Jaco Pastorius' Solo Discography [Jaco Pastorius](https://en.wikipedia.org/wiki/Jaco_Pastorius_discography) was a great bass player, but his solo discography is short enough to use as an example. [John Patitucci](https://en.wikipedia.org/wiki/John_Patitucci) is another bass giant. @@ -111,7 +111,7 @@ And then in the `partials/artist.html`: Discover a new favorite bass player? Just add another `.toml` file in the same directory. -## Example: accessing named values in a data file +### Accessing named values in a data file Assume you have the following data structure in your `User0123.[yml|toml|xml|json]` data file located directly in `data/`: @@ -132,109 +132,19 @@ You can use the following code to render the `Short Description` in your layout: Note the use of the [`markdownify`] function. This will send the description through the Markdown rendering engine. -## Get remote data +## Remote data -Use `getJSON` or `getCSV` to get remote data: +Retrieve remote data using these template functions: -```go-html-template -{{ $dataJ := getJSON "url" }} -{{ $dataC := getCSV "separator" "url" }} -``` - -If you use a prefix or postfix for the URL, the functions accept [variadic arguments][variadic]: - -```go-html-template -{{ $dataJ := getJSON "url prefix" "arg1" "arg2" "arg n" }} -{{ $dataC := getCSV "separator" "url prefix" "arg1" "arg2" "arg n" }} -``` - -The separator for `getCSV` must be put in the first position and can only be one character long. - -All passed arguments will be joined to the final URL: - -```go-html-template -{{ $urlPre := "https://api.github.com" }} -{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} -``` - -This will resolve internally to the following: - -```go-html-template -{{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }} -``` - -### Add HTTP headers - -Both `getJSON` and `getCSV` takes an optional map as the last argument, e.g.: - -```go-html-template -{{ $data := getJSON "https://example.org/api" (dict "Authorization" "Bearer abcd") }} -``` - -If you need multiple values for the same header key, use a slice: - -```go-html-template -{{ $data := getJSON "https://example.org/api" (dict "X-List" (slice "a" "b" "c")) }} -``` - -### Example for CSV files - -For `getCSV`, the one-character-long separator must be placed in the first position followed by the URL. The following is an example of creating an HTML table in a [partial template][partials] from a published CSV: - -{{< code file="layouts/partials/get-csv.html" >}} - - - - - - - - - - {{ $url := "https://example.com/finance/employee-salaries.csv" }} - {{ $sep := "," }} - {{ range $i, $r := getCSV $sep $url }} - - - - - - {{ end }} - -
    NamePositionSalary
    {{ index $r 0 }}{{ index $r 1 }}{{ index $r 2 }}
    -{{< /code >}} - -The expression `{{ index $r number }}` must be used to output the nth-column from the current row. - -### Cache URLs - -Each downloaded URL will be cached in the default folder `$TMPDIR/hugo_cache_$USER/`. The variable `$TMPDIR` will be resolved to your system-dependent temporary directory. - -With the command-line flag `--cacheDir`, you can specify any folder on your system as a caching directory. - -You can also set `cacheDir` in the [main configuration file][config]. - -If you don't like caching at all, you can fully disable caching with the command-line flag `--ignoreCache`. - -### Authentication when using REST URLs - -Currently, you can only use those authentication methods that can be put into an URL. [OAuth] and other authentication methods are not implemented. - -## Load local files - -To load local files with `getJSON` and `getCSV`, the source files must reside within Hugo's working directory. The file extension does not matter, but the content does. - -It applies the same output logic as above in [Get Remote Data](#get-remote-data). - -{{% note %}} -The local CSV files to be loaded using `getCSV` must be located **outside** the `data` directory. -{{% /note %}} +- [`resources.GetRemote`](/functions/resources/getremote) (recommended) +- [`data.GetCSV`](/functions/data/getcsv) +- [`data.GetJSON`](/functions/data/getjson) ## LiveReload with data files There is no chance to trigger a [LiveReload] when the content of a URL changes. However, when a *local* file changes (i.e., `data/*` and `themes//data/*`), a LiveReload will be triggered. Symlinks are not supported. Note too that because downloading data takes a while, Hugo stops processing your Markdown files until the data download has been completed. -{{% warning "URL Data and LiveReload" %}} +{{% note %}} If you change any local file and the LiveReload is triggered, Hugo will read the data-driven (URL) content from the cache. If you have disabled the cache (i.e., by running the server with `hugo server --ignoreCache`), Hugo will re-download the content every time LiveReload triggers. This can create *huge* traffic. You may reach API limits quickly. {{% /note %}} diff --git a/content/en/templates/internal.md b/content/en/templates/internal.md index a73ecde4c..6610f6e47 100644 --- a/content/en/templates/internal.md +++ b/content/en/templates/internal.md @@ -31,9 +31,10 @@ Hugo ships with an internal template supporting [Google Analytics 4][GA4] (GA4). Provide your tracking ID in your configuration file: **Google Analytics 4 (gtag.js)** -{{< code-toggle file="hugo" >}} + +{{< code-toggle file=hugo >}} [services.googleAnalytics] -ID = "G-MEASUREMENT_ID" +googleAnalytics = "G-MEASUREMENT_ID" {{}} ### Use the Google Analytics template @@ -54,7 +55,7 @@ Hugo also ships with an internal template for [Disqus comments][disqus], a popul To use Hugo's Disqus template, first set up a single configuration value: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [services.disqus] shortname = 'your-disqus-shortname' {{}} @@ -122,7 +123,7 @@ This format is used for Facebook and some other sites. Hugo's Open Graph template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages. -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [params] title = "My cool site" images = ["site-feature-image.jpg"] @@ -172,7 +173,7 @@ metadata used to attach rich media to Tweets linking to your site. Hugo's Twitter Card template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages. -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [params] images = ["site-feature-image.jpg"] description = "Text about my cool site" @@ -192,7 +193,7 @@ Hugo uses the page title and description for the card's title and description fi Set the value of `twitter:site` in your site configuration: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [params.social] twitter = "GoHugoIO" {{}} diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md index 2eb436f82..549466992 100644 --- a/content/en/templates/introduction.md +++ b/content/en/templates/introduction.md @@ -29,7 +29,6 @@ A _predefined variable_ could be a variable already existing in the current scope (like the `.Title` example in the [Variables](#variables) section below) or a custom variable (like the `$address` example in that same section). - ```go-html-template {{ .Title }} {{ $address }} @@ -276,7 +275,6 @@ It skips the block if the variable is absent, or if it evaluates to Below snippet uses the "description" front-matter parameter's value if set, else uses the default `.Summary` [Page variable][pagevars]: - ```go-html-template {{ with .Param "description" }} {{ . }} @@ -350,7 +348,6 @@ The following two examples are functionally the same: {{ shuffle (seq 1 5) }} ``` - ```go-html-template {{ (seq 1 5) | shuffle }} ``` @@ -429,7 +426,7 @@ Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` {{< /code >}} -{{% warning "Don't Redefine the Dot" %}} +{{% note %}} The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value. {{% /note %}} @@ -535,7 +532,7 @@ An example of this is used in the Hugo docs. Most of the pages benefit from havi Here is the example front matter: -{{< code-toggle file="content/example.md" fm=true copy=false >}} +{{< code-toggle file="content/example.md" fm=true >}} title: Example notoc: true {{< /code-toggle >}} @@ -564,7 +561,7 @@ You can arbitrarily define as many site-level parameters as you want in your [si For instance, you might declare the following: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} params: copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved." twitteruser: "spf13" @@ -617,7 +614,7 @@ content/ └── event-3.md ``` -{{< code-toggle file="content/events/event-1.md" copy=false >}} +{{< code-toggle file="content/events/event-1.md" >}} title = 'Event 1' date = 2021-12-06T10:37:16-08:00 draft = false @@ -634,7 +631,7 @@ This [partial template][partials] renders future events: {{ if gt (.Params.start_date | time.AsTime) now }} {{ $startDate := .Params.start_date | time.Format ":date_medium" }}
  • - {{ .LinkTitle }} - {{ $startDate }} + {{ .Title }} - {{ $startDate }}
    • {{ end }} {{ end }} @@ -649,7 +646,7 @@ If you restrict front matter to the TOML format, and omit quotation marks surrou {{ range where (where site.RegularPages "Type" "events") "Params.start_date" "gt" now }} {{ $startDate := .Params.start_date | time.Format ":date_medium" }}
  • - {{ .LinkTitle }} - {{ $startDate }} + {{ .Title }} - {{ $startDate }}
    • {{ end }} @@ -666,9 +663,9 @@ If you restrict front matter to the TOML format, and omit quotation marks surrou [internal templates]: /templates/internal [math]: /functions/math [pagevars]: /variables/page -[param]: /functions/param +[param]: /methods/page/param [partials]: /templates/partials -[relpermalink]: /variables/page#page-variables +[relpermalink]: /variables/page [`safehtml`]: /functions/safe/html [sitevars]: /variables/site [variables]: /variables diff --git a/content/en/templates/lists/index.md b/content/en/templates/lists/index.md index b48969e96..7e95cc5bc 100644 --- a/content/en/templates/lists/index.md +++ b/content/en/templates/lists/index.md @@ -110,7 +110,7 @@ You can now access this `_index.md`'s' content in your list template: This above will output the following HTML: -{{< code file="example.com/posts/index.html" copy=false >}} +{{< code file="example.com/posts/index.html" >}}
    @@ -134,7 +134,7 @@ You do *not* have to create an `_index.md` file for every list page (i.e. sectio Using this same `layouts/_default/list.html` template and applying it to the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from: -{{< code file="example.com/quote/index.html" copy=false >}} +{{< code file="example.com/quote/index.html" >}}
    @@ -144,8 +144,8 @@ Using this same `layouts/_default/list.html` template and applying it to the `qu
    @@ -194,374 +194,29 @@ This list template has been modified slightly from a template originally used in {{ end }} {{< /code >}} -## Order content +## Sort content -Hugo lists render the content based on metadata you provide in [front matter]. In addition to sane defaults, Hugo also ships with multiple methods to make quick work of ordering content inside list templates: +By default, Hugo sorts page collections by: -### Default: Weight > Date > LinkTitle > FilePath +1. Page [weight] +2. Page [date] (descending) +3. Page [linkTitle], falling back to page [title] +4. Page file path if the page is backed by a file -{{< code file="layouts/partials/default-order.html" >}} -
      - {{ range .Pages }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} +[date]: /methods/page/date +[weight]: /methods/page/weight +[linkTitle]: /methods/page/linktitle +[title]: /methods/page/title -### By weight +Change the sort order using any of the methods below. -Lower weight gets higher precedence. So content with lower weight will come first. - -{{< code file="layouts/partials/by-weight.html" >}} -
      - {{ range .Pages.ByWeight }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By date - -{{< code file="layouts/partials/by-date.html" >}} -
      - - {{ range .Pages.ByDate }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By publish date - -{{< code file="layouts/partials/by-publish-date.html" >}} -
      - - {{ range .Pages.ByPublishDate }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By expiration date - -{{< code file="layouts/partials/by-expiry-date.html" >}} -
      - {{ range .Pages.ByExpiryDate }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By last modified date - -{{< code file="layouts/partials/by-last-mod.html" >}} -
      - - {{ range .Pages.ByLastmod }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By length - -{{< code file="layouts/partials/by-length.html" >}} -
      - - {{ range .Pages.ByLength }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By title - -{{< code file="layouts/partials/by-title.html" >}} -
      - - {{ range .Pages.ByTitle }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By link title - -{{< code file="layouts/partials/by-link-title.html" >}} -
      - - {{ range .Pages.ByLinkTitle }} -
    • -

      {{ .LinkTitle }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By page parameter - -Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering. - -{{< code file="layouts/partials/by-rating.html" >}} - -{{ range (.Pages.ByParam "rating") }} - -{{ end }} -{{< /code >}} - -If the targeted front matter field is nested beneath another field, you can access the field using dot notation. - -{{< code file="layouts/partials/by-nested-param.html" >}} -{{ range (.Pages.ByParam "author.last_name") }} - -{{ end }} -{{< /code >}} - -### Reverse order - -Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example: - -{{< code file="layouts/partials/by-date-reverse.html" >}} -
      - {{ range .Pages.ByDate.Reverse }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} +{{< list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. omitElementIDs=true >}} ## Group content -Hugo provides some functions for grouping pages by Section, Type, Date, etc. +Group your content by field, parameter, or date using any of the methods below. -### By page field - -{{< code file="layouts/partials/by-page-field.html" >}} - -{{ range .Pages.GroupBy "Section" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -In the above example, you may want `{{ .Title }}` to point the `title` field you have added to your `_index.md` file instead. You can access this value using the [`.GetPage` function][getpage]: - -{{< code file="layouts/partials/by-page-field.html" >}} - -{{ range .Pages.GroupBy "Section" }} - - {{ with $.Site.GetPage "section" .Key }} -

    {{ .Title }}

    - {{ else }} - -

    {{ .Key | title }}

    - {{ end }} -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -### By date - -{{< code file="layouts/partials/by-page-date.html" >}} - -{{ range .Pages.GroupByDate "2006-01" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [`time.Format`] and the `.Key` in the result will be localized for the current language. - -### By publish date - -{{< code file="layouts/partials/by-page-publish-date.html" >}} - -{{ range .Pages.GroupByPublishDate "2006-01" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .PublishDate.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [`time.Format`] and the `.Key` in the result will be localized for the current language. - -### By expiration date - -{{< code file="layouts/partials/by-page-expiry-date.html" >}} - -{{ range .Pages.GroupByExpiryDate "2006-01" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [`time.Format`] and the `.Key` in the result will be localized for the current language. - -### By last modified date - -{{< code file="layouts/partials/by-page-lastmod.html" >}} - -{{ range .Pages.GroupByLastmod "2006-01" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Lastmod.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [`time.Format`] and the `.Key` in the result will be localized for the current language. - -### By page parameter - -{{< code file="layouts/partials/by-page-param.html" >}} - -{{ range .Pages.GroupByParam "param_key" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    - {{ end }} -{{< /code >}} - -### By page parameter in date format - -The following template takes grouping by `date` a step further and uses Go's layout string. See the [`Format` function] for more examples of how to use Go's layout string to format dates in Hugo. - -{{< code file="layouts/partials/by-page-param-as-date.html" >}} - -{{ range .Pages.GroupByParamDate "param_key" "2006-01" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -### Reverse key order - -Ordering of groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (i.e., with the newest first) for dates. - -While these are logical defaults, they are not always the desired order. There are two different syntaxes to change Hugo's default ordering for groups, both of which work the same way. - -#### 1. Adding the reverse method - -```go-html-template -{{ range (.Pages.GroupBy "Section").Reverse }} -``` - -```go-html-template -{{ range (.Pages.GroupByDate "2006-01").Reverse }} -``` - -#### 2. Providing the alternate direction - -```go-html-template -{{ range .Pages.GroupByDate "2006-01" "asc" }} -``` - -```go-html-template -{{ range .Pages.GroupBy "Section" "desc" }} -``` - -### Order within groups - -Because Grouping returns a `{{ .Key }}` and a slice of pages, all the ordering methods listed above are available. - -Here is the ordering for the example that follows: - -1. Content is grouped by month according to the `date` field in front matter. -2. Groups are listed in ascending order (i.e., the oldest groups first) -3. Pages within each respective group are ordered alphabetically according to the `title`. - -{{< code file="layouts/partials/by-group-by-page.html" >}} -{{ range .Pages.GroupByDate "2006-01" "asc" }} -

    {{ .Key }}

    -
      - {{ range .Pages.ByTitle }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} +{{< list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. omitElementIDs=true >}} ## Filtering and limiting lists @@ -575,9 +230,9 @@ See the documentation on [`where`] and [base]: /templates/base/ [bepsays]: https://bepsays.com/en/2016/12/19/hugo-018/ [directorystructure]: /getting-started/directory-structure/ -[`Format` function]: /functions/format/ +[`Format` function]: /methods/time/format/ [front matter]: /content-management/front-matter/ -[getpage]: /functions/getpage/ +[getpage]: /methods/page/getpage/ [homepage]: /templates/homepage/ [mentalmodel]: https://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html [pagevars]: /variables/page/ @@ -592,6 +247,6 @@ See the documentation on [`where`] and [taxvars]: /variables/taxonomy/ [views]: /templates/views/ [`where`]: /functions/collections/where -[`first`]: /functions/first/ +[`first`]: /functions/collections/first/ [main sections]: /functions/collections/where#mainsections [`time.Format`]: /functions/time/format diff --git a/content/en/templates/lookup-order.md b/content/en/templates/lookup-order.md index c36956cb9..b49c79524 100644 --- a/content/en/templates/lookup-order.md +++ b/content/en/templates/lookup-order.md @@ -63,7 +63,7 @@ layouts/ But the contact page probably has a form and requires a different template. In the front matter specify `layout`: -{{< code-toggle file=content/contact.md copy=false >}} +{{< code-toggle file=content/contact.md >}} title = 'Contact' layout = 'contact' {{< /code-toggle >}} @@ -79,12 +79,12 @@ layouts/ As a content type, the word `page` is vague. Perhaps `miscellaneous` would be better. Add `type` to the front matter of each page: -{{< code-toggle file=content/about.md copy=false >}} +{{< code-toggle file=content/about.md >}} title = 'About' type = 'miscellaneous' {{< /code-toggle >}} -{{< code-toggle file=content/contact.md copy=false >}} +{{< code-toggle file=content/contact.md >}} title = 'Contact' type = 'miscellaneous' layout = 'contact' @@ -117,7 +117,7 @@ A section page is a list of pages within a given section. A taxonomy page is a list of terms within a given taxonomy. The examples below assume the following site configuration: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} [taxonomies] category = 'categories' {{< /code-toggle >}} @@ -128,7 +128,7 @@ category = 'categories' A term page is a list of pages associated with a given term. The examples below assume the following site configuration: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} [taxonomies] category = 'categories' {{< /code-toggle >}} diff --git a/content/en/templates/menu-templates.md b/content/en/templates/menu-templates.md index e2d141f06..6b7532e29 100644 --- a/content/en/templates/menu-templates.md +++ b/content/en/templates/menu-templates.md @@ -28,7 +28,7 @@ The example below handles every combination. This partial template recursively "walks" a menu structure, rendering a localized, accessible nested list. -{{< code file="layouts/partials/menu.html" >}} +{{< code file="layouts/partials/menu.html" copy=true >}} {{- $page := .page }} {{- $menuID := .menuID }} @@ -128,5 +128,5 @@ Hugo provides two methods to localize your menu entries. See [multilingual]. [localize the menu entries]: /content-management/multilingual/#menus [menu entry defined in front matter]: /content-management/menus/#example-front-matter [menu entry defined in site configuration]: /content-management/menus/#example-site-configuration -[menu variables and methods]: /variables/menus/ +[menu variables and methods]: /variables/menu-entry/ [multilingual]: /content-management/multilingual/#menus diff --git a/content/en/templates/output-formats.md b/content/en/templates/output-formats.md index 5f2abdc2a..0fad84da4 100644 --- a/content/en/templates/output-formats.md +++ b/content/en/templates/output-formats.md @@ -31,7 +31,7 @@ This is the full set of built-in media types in Hugo: To add or modify a media type, define it in a `mediaTypes` section in your [site configuration], either for all sites or for a given language. -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [mediaTypes] [mediaTypes."text/enriched"] suffixes = ["enr"] @@ -43,7 +43,7 @@ The above example adds one new media type, `text/enriched`, and changes the suff **Note:** these media types are configured for **your output formats**. If you want to redefine one of Hugo's default output formats (e.g. `HTML`), you also need to redefine the media type. So, if you want to change the suffix of the `HTML` output format from `html` (default) to `htm`: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [mediaTypes] [mediaTypes."text/html"] suffixes = ["htm"] @@ -69,7 +69,7 @@ This is the full set of Hugo's built-in output formats: To add or modify an output format, define it in an `outputFormats` section in your site's [configuration file](/getting-started/configuration/), either for all sites or for a given language. -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [outputFormats.MyEnrichedFormat] mediaType = "text/enriched" baseName = "myindex" @@ -139,7 +139,7 @@ per language). Example from site configuration file: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [outputs] home = ["html", "amp", "rss"] page = ["html"] @@ -153,7 +153,7 @@ Note that in the above examples, the _output formats_ for `section`, The following is an example of front matter in a content file that defines output formats for the rendered `Page`: -{{< code-toggle file="content/example.md" fm=true copy=false >}} +{{< code-toggle file="content/example.md" fm=true >}} title: Example outputs: - html diff --git a/content/en/templates/partials.md b/content/en/templates/partials.md index 97cf93f71..d5fe5aade 100644 --- a/content/en/templates/partials.md +++ b/content/en/templates/partials.md @@ -128,7 +128,7 @@ Value: {{ partial "my-inline-partial.html" . }} ## Cached partials -The `partialCached` template function provides significant performance gains for complex templates that don't need to be re-rendered on every invocation. See [details][partialcached]. +The `partialCached` template function provides significant performance gains for complex templates that don't need to be re-rendered on every invocation. See [details][partialcached]. ## Examples diff --git a/content/en/templates/render-hooks.md b/content/en/templates/render-hooks.md index 13106b7f7..9ced3f62b 100644 --- a/content/en/templates/render-hooks.md +++ b/content/en/templates/render-hooks.md @@ -97,7 +97,6 @@ IsBlock {{< new-in "0.108.0" >}} Ordinal {{< new-in "0.108.0" >}} : Zero-based ordinal for all the images in the current document. - ### Link with title markdown example ```md diff --git a/content/en/templates/robots.md b/content/en/templates/robots.md index b9cdb76dd..eea639426 100644 --- a/content/en/templates/robots.md +++ b/content/en/templates/robots.md @@ -14,7 +14,7 @@ aliases: [/extras/robots-txt/] To generate a robots.txt file from a template, change the [site configuration]: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} enableRobotsTXT = true {{< /code-toggle >}} diff --git a/content/en/templates/rss.md b/content/en/templates/rss.md index b72861117..df97c437c 100644 --- a/content/en/templates/rss.md +++ b/content/en/templates/rss.md @@ -15,7 +15,7 @@ toc: true By default, when you build your site, Hugo generates RSS feeds for home, section, taxonomy, and term pages. Control feed generation in your site configuration. For example, to generate feeds for home and section pages, but not for taxonomy and term pages: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} [outputs] home = ['html', 'rss'] section = ['html', 'rss'] @@ -25,13 +25,13 @@ term = ['html'] To disable feed generation for all [page kinds]: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} disableKinds = ['rss'] {{< /code-toggle >}} By default, the number of items in each feed is unlimited. Change this as needed in your site configuration: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} [services.rss] limit = 42 {{< /code-toggle >}} @@ -40,7 +40,7 @@ Set `limit` to `-1` to generate an unlimited number of items per feed. The built-in RSS template will render the following values, if present, from your site configuration: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} copyright = '© 2023 ABC Widgets, Inc.' [params.author] name = 'John Doe' diff --git a/content/en/templates/section-templates.md b/content/en/templates/section-templates.md index b35009a2f..ed12b30a3 100644 --- a/content/en/templates/section-templates.md +++ b/content/en/templates/section-templates.md @@ -25,7 +25,7 @@ See [Template Lookup](/templates/lookup-order/). Every `Page` in Hugo has a `.Kind` attribute. -{{% page-kinds %}} +{{% include "content-management/_common/page-kinds.md" %}} ## `.Site.GetPage` with sections @@ -69,10 +69,10 @@ The `.Site.GetPage` example that follows assumes the following project directory . └── content ├── blog - │   ├── _index.md # "title: My Hugo Blog" in the front matter - │   ├── post-1.md - │   ├── post-2.md - │   └── post-3.md + │ ├── _index.md # "title: My Hugo Blog" in the front matter + │ ├── post-1.md + │ ├── post-2.md + │ └── post-3.md └── events #Note there is no _index.md file in "events" ├── event-1.md └── event-2.md @@ -103,7 +103,7 @@ Which then returns the following: ``` [contentorg]: /content-management/organization/ -[getpage]: /functions/getpage/ +[getpage]: /methods/page/getpage [lists]: /templates/lists/ [lookup]: /templates/lookup-order/ [`where`]: /functions/collections/where diff --git a/content/en/templates/shortcode-templates.md b/content/en/templates/shortcode-templates.md index 41b52641c..e90ab685a 100644 --- a/content/en/templates/shortcode-templates.md +++ b/content/en/templates/shortcode-templates.md @@ -10,6 +10,7 @@ menu: weight: 130 weight: 130 toc: true +aliases: [/functions/get] --- Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside your content. @@ -28,7 +29,7 @@ Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, H To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{}}` or `{{%/* myshortcode /*/%}}`. -You can organize your shortcodes in subfolders, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g: +You can organize your shortcodes in subdirectories, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g: ```go-html-template {{}} @@ -193,7 +194,7 @@ Would load the template at `/layouts/shortcodes/youtube.html`: {{< /code >}} -{{< code file="youtube-embed.html" copy=false >}} +{{< code file="youtube-embed.html" >}}
    @@ -297,7 +298,7 @@ The template for the `highlight` shortcode uses the following code, which is alr The rendered output of the HTML example code block will be as follows: -{{< code file="syntax-highlighted.html" copy=false >}} +{{< code file="syntax-highlighted.html" >}} 
    <html>
     <body> This HTML </body>
 </html>
@@ -349,9 +350,9 @@ This will output the following HTML. Note how the first two `img` shortcodes inh
 
 ## Error handling in shortcodes
 
-Use the [errorf](/functions/fmt/errorf) template func and [.Position](/variables/shortcodes/) variable to get useful error messages in shortcodes:
+Use the [errorf](/functions/fmt/errorf) template func and [.Position](/variables/shortcode/) variable to get useful error messages in shortcodes:
 
-```bash
+```sh
 {{ with .Get "name" }}
 {{ else }}
 {{ errorf "missing value for parameter 'name': %s" .Position }}
@@ -360,7 +361,7 @@ Use the [errorf](/functions/fmt/errorf) template func and [.Position](/variables
 
 When the above fails, you will see an `ERROR` log similar to the below:
 
-```bash
+```sh
 ERROR 2018/11/07 10:05:55 missing value for parameter name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1"
 ```
 
@@ -374,7 +375,7 @@ You can also implement your shortcodes inline -- e.g. where you use them in the
 
 This feature is disabled by default, but can be enabled in your site configuration:
 
-{{< code-toggle file="hugo" >}}
+{{< code-toggle file=hugo >}}
 enableInlineShortcodes = true
 {{< /code-toggle >}}
 
@@ -382,7 +383,7 @@ It is disabled by default for security reasons. The security model used by Hugo'
 
 And once enabled, you can do this in your content files:
 
- ```go-text-template
+ ```go-html-template
  {{}}{{ now }}{{}}
  ```
 
@@ -394,7 +395,7 @@ This means that the current page can be accessed via `.Page.Title` etc. This als
 
 The same inline shortcode can be reused later in the same content file, with different parameters if needed, using the self-closing syntax:
 
- ```go-text-template
+ ```go-html-template
 {{}}
 ```
 
@@ -408,8 +409,8 @@ The same inline shortcode can be reused later in the same content file, with dif
 [hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
 [lookup order]: /templates/lookup-order/
 [pagevars]: /variables/page/
-[parent]: /variables/shortcodes/
-[shortcodesvars]: /variables/shortcodes/
+[parent]: /variables/shortcode/
+[shortcodesvars]: /variables/shortcode/
 [spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes
 [vimeoexample]: #single-flexible-example-vimeo
 [youtubeshortcode]: /content-management/shortcodes/#youtube
diff --git a/content/en/templates/single-page-templates.md b/content/en/templates/single-page-templates.md
index a32e8231c..54efddc6e 100644
--- a/content/en/templates/single-page-templates.md
+++ b/content/en/templates/single-page-templates.md
@@ -43,14 +43,14 @@ This single page template makes use of Hugo [base templates], the [`.Format` fun
       {{ with .GetTerms "topics" }}
         
       {{ end }}
       {{ with .GetTerms "tags" }}
         
       {{ end }}
@@ -74,7 +74,7 @@ To easily generate new instances of a content type (e.g., new `.md` files in a s
 [content type]: /content-management/types/
 [directory structure]: /getting-started/directory-structure/
 [dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
-[`.format` function]: /functions/format/
+[`.format` function]: /methods/time/format/
 [front matter]: /content-management/front-matter/
 [pagetaxonomy]: /templates/taxonomy-templates/#list-terms-assigned-to-a-page
 [pagevars]: /variables/page/
diff --git a/content/en/templates/sitemap-template.md b/content/en/templates/sitemap-template.md
index 4f86380f1..bccd37812 100644
--- a/content/en/templates/sitemap-template.md
+++ b/content/en/templates/sitemap-template.md
@@ -67,7 +67,7 @@ To override the built-in sitemapindex.xml template, create a new file in either
 
 You may disable sitemap generation in your site configuration:
 
-{{< code-toggle file="hugo" >}}
+{{< code-toggle file=hugo >}}
 disableKinds = ['sitemap']
 {{}}
 
diff --git a/content/en/templates/taxonomy-templates.md b/content/en/templates/taxonomy-templates.md
index 1b15bd4ef..ca96c6185 100644
--- a/content/en/templates/taxonomy-templates.md
+++ b/content/en/templates/taxonomy-templates.md
@@ -152,7 +152,7 @@ Weights of zero are thus treated specially: if two pages have unequal weights, a
 
 Content can be assigned weight for each taxonomy that it's assigned to.
 
-{{< code-toggle file="content/example.md" fm=true copy=false >}}
+{{< code-toggle file="content/example.md" fm=true >}}
 tags = [ "a", "b", "c" ]
 tags_weight = 22
 categories = ["d"]
@@ -205,7 +205,7 @@ To render an unordered list:
   
    {{ (site.GetPage $taxonomy).LinkTitle }}:
    
   
 {{ end }}
@@ -220,7 +220,7 @@ To render a comma-delimited list:
     {{ (site.GetPage $taxonomy).LinkTitle }}:
     {{ range $k, $_ := . -}}
       {{ if $k }}, {{ end }}
-      {{ .LinkTitle }}
+      {{ .Title }}
     {{- end }}
   
    
 {{ end }}
@@ -253,7 +253,7 @@ This would be very useful in a sidebar as “featured content”. You could even
       
  • {{ $key }}
    • 
       
     {{ end }}
@@ -288,7 +288,7 @@ This example will list all taxonomies and their terms, as well as all the conten
   {{ range $taxonomy, $terms := site.Taxonomies }}
     
  • 
       {{ with site.GetPage $taxonomy }}
-        {{ .LinkTitle }}
+        {{ .Title }}
       {{ end }}
       
      
         {{ range $term, $weightedPages := $terms }}
@@ -296,7 +296,7 @@ This example will list all taxonomies and their terms, as well as all the conten
             {{ .Page.LinkTitle }}
             
           
@@ -322,8 +322,7 @@ Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to
 
    
 {{< /code >}}
 
-[delimit]: /functions/collections/delimit/
-[getpage]: /functions/getpage/
+[getpage]: /methods/page/getpage
 [lists]: /templates/lists/
 [renderlists]: /templates/lists/
 [single page template]: /templates/single-page-templates/
diff --git a/content/en/templates/views.md b/content/en/templates/views.md
index 3d00a4ed6..595e3071b 100644
--- a/content/en/templates/views.md
+++ b/content/en/templates/views.md
@@ -36,7 +36,6 @@ To create a new view, create a template in each of your different content type d
 
 Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
 
-
 ```txt
 ▾ layouts/
   ▾ _default/
@@ -104,7 +103,7 @@ Continuing on the previous example, we can change our render function to use a s
 [lists]: /templates/lists/
 [lookup]: /templates/lookup-order/
 [pagevars]: /variables/page/
-[render]: /functions/render/
+[render]: /methods/page/render/
 [single]: /templates/single-page-templates/
 [spf]: https://spf13.com
 [spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
diff --git a/content/en/tools/editors.md b/content/en/tools/editors.md
index ea83f37c6..8ff632e0c 100644
--- a/content/en/tools/editors.md
+++ b/content/en/tools/editors.md
@@ -1,46 +1,66 @@
 ---
-title: Editor plugins for Hugo
+title: Editor plugins
 linkTitle: Editor plugins
-description: The Hugo community uses a wide range of preferred tools and has developed plug-ins for some of the most popular text editors to help automate parts of your workflow.
+description: The Hugo community uses a wide range of tools and has developed plugins for some of the most popular text editors to help automate parts of your workflow.
 categories: [developer tools]
-keywords: [editor, plug-ins]
+keywords: [editor, plugin]
 menu:
   docs:
     parent: developer-tools
     weight: 20
 weight: 20
+toc: true
 ---
 
-## Sublime Text
-
-* [Hugofy](https://github.com/akmittal/Hugofy). Hugofy is a plugin for Sublime Text 3 to make life easier to use Hugo static site generator.
-* [Hugo Snippets](https://packagecontrol.io/packages/Hugo%20Snippets). Hugo Snippets is a useful plugin for adding automatic snippets to Sublime Text 3.
-
 ## Visual Studio Code
 
-* [Front Matter](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-front-matter). Once you go for a static site, you need to think about how you are going to manage your articles. Front matter is a tool that helps you maintain the metadata/front matter of your articles like: creation date, modified date, slug, tile, SEO check, and many more...
-* [Hugo Helper](https://marketplace.visualstudio.com/items?itemName=rusnasonov.vscode-hugo). Hugo Helper is a plugin for Visual Studio Code that has some useful commands for Hugo. The source code can be found [here](https://github.com/rusnasonov/vscode-hugo).
-* [Hugo Language and Syntax Support](https://marketplace.visualstudio.com/items?itemName=budparr.language-hugo-vscode). Hugo Language and Syntax Support is a Visual Studio Code plugin for Hugo syntax highlighting and snippets. The source code can be found [here](https://github.com/budparr/language-hugo-vscode).
-* [Hugo Themer](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-hugo-themer). Hugo Themer is an extension to help you while developing themes. It allows you to easily navigate through your theme files.
-* [Hugofy](https://marketplace.visualstudio.com/items?itemName=akmittal.hugofy). Hugofy is a plugin for Visual Studio Code to "make life easier" when developing with Hugo. The source code can be found [here](https://github.com/akmittal/hugofy-vscode).
-* [Prettier Plugin for Go Templates](https://github.com/NiklasPor/prettier-plugin-go-template). Format Hugo templates using this [Prettier](https://prettier.io/) plugin. See [installation instructions](https://discourse.gohugo.io/t/38403).
-* [Syntax Highlighting for Hugo Shortcodes](https://marketplace.visualstudio.com/items?itemName=kaellarkin.hugo-shortcode-syntax). This extension adds some syntax highlighting for Shortcodes, making visual identification of individual pieces easier.
+[Front Matter](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-front-matter)
+: Once you go for a static site, you need to think about how you are going to manage your articles. Front matter is a tool that helps you maintain the metadata/front matter of your articles like: creation date, modified date, slug, tile, SEO check, and more.
 
-Front Matter
-Hugo Helper
-Hugo Language and Syntax Support
-Hugo Themer
-Hugofy
-Syntax Highlighting for Hugo Shortcodes
+[Hugo Helper](https://marketplace.visualstudio.com/items?itemName=rusnasonov.vscode-hugo)
+: Hugo Helper is a plugin for Visual Studio Code that has some useful commands for Hugo. The source code can be found [here](https://github.com/rusnasonov/vscode-hugo).
+
+[Hugo Language and Syntax Support](https://marketplace.visualstudio.com/items?itemName=budparr.language-hugo-vscode)
+: Hugo Language and Syntax Support is a Visual Studio Code plugin for Hugo syntax highlighting and snippets. The source code can be found [here](https://github.com/budparr/language-hugo-vscode).
+
+[Hugo Themer](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-hugo-themer)
+: Hugo Themer is an extension to help you while developing themes. It allows you to easily navigate through your theme files.
+
+[Hugofy](https://marketplace.visualstudio.com/items?itemName=akmittal.hugofy)
+: Hugofy is a plugin for Visual Studio Code to "make life easier" when developing with Hugo. The source code can be found [here](https://github.com/akmittal/hugofy-vscode).
+
+[Prettier Plugin for Go Templates](https://github.com/NiklasPor/prettier-plugin-go-template)
+: Format Hugo templates using this [Prettier](https://prettier.io/) plugin. See [installation instructions](https://discourse.gohugo.io/t/38403).
+
+[Syntax Highlighting for Hugo Shortcodes](https://marketplace.visualstudio.com/items?itemName=kaellarkin.hugo-shortcode-syntax)
+: This extension adds some syntax highlighting for Shortcodes, making visual identification of individual pieces easier.
 
 ## Emacs
 
-* [emacs-easy-hugo](https://github.com/masasam/emacs-easy-hugo). Emacs major mode for managing hugo blogs. Note that Hugo also supports [Org-mode][formats].
-* [ox-hugo.el](https://ox-hugo.scripter.co). Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org subtrees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [*Why ox-hugo?*](https://ox-hugo.scripter.co/doc/why-ox-hugo/) for more.
+[emacs-easy-hugo](https://github.com/masasam/emacs-easy-hugo)
+: Emacs major mode for managing hugo blogs. Note that Hugo also supports [Org-mode][formats].
+
+[ox-hugo.el](https://ox-hugo.scripter.co)
+: Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org subtrees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [*Why ox-hugo?*](https://ox-hugo.scripter.co/doc/why-ox-hugo/) for more.
+
+## Sublime Text
+
+[Hugofy](https://github.com/akmittal/Hugofy)
+: Hugofy is a plugin for Sublime Text 3 to make life easier to use Hugo static site generator.
+
+[Hugo Snippets](https://packagecontrol.io/packages/Hugo%20Snippets)
+: Hugo Snippets is a useful plugin for adding automatic snippets to Sublime Text 3.
 
 ## Vim
 
-* [Vim Hugo Helper](https://github.com/robertbasic/vim-hugo-helper). A small Vim plugin that facilitates authoring pages and blog posts with Hugo.
-* [vim-hugo](https://github.com/phelipetls/vim-hugo). A Vim plugin with syntax highlighting for templates and a few other features.
+[Vim Hugo Helper]: https://github.com/robertbasic/vim-hugo-helper
+
+[Vim Hugo Helper]
+: A small Vim plugin that facilitates authoring pages and blog posts with Hugo.
+
+[xxx]: xxx
+
+[vim-hugo](https://github.com/phelipetls/vim-hugo)
+: A Vim plugin with syntax highlighting for templates and a few other features.
 
 [formats]: /content-management/formats/
diff --git a/content/en/tools/frontends.md b/content/en/tools/frontends.md
index bc4df22b5..2ecac6f05 100644
--- a/content/en/tools/frontends.md
+++ b/content/en/tools/frontends.md
@@ -1,5 +1,5 @@
 ---
-title: Frontend interfaces with Hugo
+title: Frontend interfaces
 linkTitle: Frontends
 description: Do you prefer a graphical user interface over a text editor? Give these frontends a try.
 categories: [developer tools]
@@ -9,14 +9,18 @@ menu:
     parent: developer-tools
     weight: 30
 weight: 30
+toc: true
 ---
 
-- [enwrite](https://github.com/zzamboni/enwrite). Enwrite enables evernote-powered, statically generated blogs and websites. Now posting to your blog or updating your website is as easy as writing a new note in Evernote!
-- [Lipi](https://github.com/SohanChy/Lipi). Lipi is a native GUI frontend written in Java to manage your Hugo websites.
-- [Decap CMS (formerly Netlify CMS)](https://decapcms.org/). Decap CMS is an open source, serverless solution for managing Git based content in static sites, and it works on any platform that can host static sites. A [Hugo/Decap CMS starter](https://github.com/decaporg/one-click-hugo-cms) is available to get new projects running quickly.
-- [Hokus CMS](https://github.com/julianoappelklein/hokus). Hokus CMS is an open source, multi-platform, easy to use, desktop application for Hugo. Build from simple to complex user interfaces for Hugo websites by choosing from a dozen ready-to-use components — all for free, with no vendor lock-in.
+## Commercial
 
-## Commercial services
+[CloudCannon](https://cloudcannon.com/hugo-cms/)
+: The intuitive Git-based CMS for your Hugo website. CloudCannon syncs changes from your Git repository and pushes content changes back, so your development and content teams are always in sync. Edit all of your content on the page with visual editing, build entire pages with reusable custom components and then publish confidently.
 
-- [DATOCMS](https://www.datocms.com) DatoCMS is a fully customizable administrative area for your static websites. Use your favorite website generator, let your clients publish new content independently, and the host the site anywhere you like.
-- [CloudCannon](https://cloudcannon.com/hugo-cms/). The intuitive Git-based CMS for your Hugo website. CloudCannon syncs changes from your Git repository and pushes content changes back, so your development and content teams are always in sync. Edit all of your content on the page with visual editing, build entire pages with reusable custom components and then publish confidently.
+[DATOCMS](https://www.datocms.com)
+: DatoCMS is a fully customizable administrative area for your static websites. Use your favorite website generator, let your clients publish new content independently, and the host the site anywhere you like.
+
+## Open source
+
+[Decap CMS](https://decapcms.org/)
+: Decap CMS is an open source, serverless solution for managing Git based content in static sites, and it works on any platform that can host static sites. A [Hugo/Decap CMS starter](https://github.com/decaporg/one-click-hugo-cms) is available to get new projects running quickly.
diff --git a/content/en/tools/migrations.md b/content/en/tools/migrations.md
index 8ba01f927..a23c19319 100644
--- a/content/en/tools/migrations.md
+++ b/content/en/tools/migrations.md
@@ -14,63 +14,88 @@ toc: true
 
 This section highlights some projects around Hugo that are independently developed. These tools try to extend the functionality of our static site generator or help you to get started.
 
-{{% note %}}
-Do you know or maintain a similar project around Hugo? Feel free to open a [pull request](https://github.com/gohugoio/hugoDocs/pulls) on GitHub if you think it should be added.
-{{% /note %}}
-
 Take a look at this list of migration tools if you currently use other blogging tools like Jekyll or WordPress but intend to switch to Hugo instead. They'll take care to export your content into Hugo-friendly formats.
 
 ## Jekyll
 
-Alternatively, you can use the new [Jekyll import command](/commands/hugo_import_jekyll/).
+Alternatively, you can use the [Jekyll import command](/commands/hugo_import_jekyll/).
 
-- [JekyllToHugo](https://github.com/fredrikloch/JekyllToHugo) - A Small script for converting Jekyll blog posts to a Hugo site.
-- [ConvertToHugo](https://github.com/coderzh/ConvertToHugo) - Convert your blog from Jekyll to Hugo.
+[JekyllToHugo](https://github.com/fredrikloch/JekyllToHugo)
+: A Small script for converting Jekyll blog posts to a Hugo site.
+
+[ConvertToHugo](https://github.com/coderzh/ConvertToHugo)
+: Convert your blog from Jekyll to Hugo.
 
 ## Octopress
 
-- [octohug](https://github.com/codebrane/octohug) - Octopress to Hugo migrator.
+[octohug](https://github.com/codebrane/octohug)
+: Octopress to Hugo migrator.
 
 ## DokuWiki
 
-- [dokuwiki-to-hugo](https://github.com/wgroeneveld/dokuwiki-to-hugo) - Migrates your DokuWiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extra's like the TODO plugin. Written with extensibility in mind using python 3. Also generates a TOML header for each page. Designed to copypaste the wiki directory into your /content directory.
+[dokuwiki-to-hugo](https://github.com/wgroeneveld/dokuwiki-to-hugo)
+: Migrates your DokuWiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extra's like the TODO plugin. Written with extensibility in mind using python 3. Also generates a TOML header for each page. Designed to copypaste the wiki directory into your /content directory.
 
 ## WordPress
 
-- [wordpress-to-hugo-exporter](https://github.com/SchumacherFM/wordpress-to-hugo-exporter) - A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you can [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.)
-- [blog2md](https://github.com/palaniraja/blog2md) - Works with [exported xml](https://en.support.wordpress.com/export/) file of your free YOUR-TLD.wordpress.com website. It also saves approved comments to `YOUR-POST-NAME-comments.md` file along with posts.
-- [wordhugopress](https://github.com/nantipov/wordhugopress) - A small utility written in Java, exports the entire WordPress site from the database and resource (e.g. images) files stored locally or remotely. Therefore, migration from the backup files is possible. Supports merging of the multiple WordPress sites into a single Hugo one.
+[wordpress-to-hugo-exporter](https://github.com/SchumacherFM/wordpress-to-hugo-exporter)
+: A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you  - \s-\scan [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.)
+
+[blog2md](https://github.com/palaniraja/blog2md)
+: Works with [exported xml](https://en.support.wordpress.com/export/) file of your free YOUR-TLD.wordpress.com website. It also saves approved comments to `YOUR-POST-NAME-comments.md` file along with posts.
+
+[wordhugopress](https://github.com/nantipov/wordhugopress)
+: A small utility written in Java, exports the entire WordPress site from the database and resource (e.g. images) files stored locally or remotely. Therefore, migration from the backup files is possible. Supports merging of the multiple WordPress sites into a single Hugo one.
 
 ## Medium
 
-- [medium2md](https://github.com/gautamdhameja/medium-2-md) - A simple Medium to Hugo exporter able to import stories in one command, including front matter.
-- [medium-to-hugo](https://github.com/bgadrian/medium-to-hugo) - CLI tool written in Go to export medium posts into a Hugo compatible Markdown format. Tags and images are included. All images will be downloaded locally and linked appropriately.
+[medium2md](https://github.com/gautamdhameja/medium-2-md)
+: A simple Medium to Hugo exporter able to import stories in one command, including front matter.
+
+[medium-to-hugo](https://github.com/bgadrian/medium-to-hugo)
+: CLI tool written in Go to export medium posts into a Hugo compatible Markdown format. Tags and images are included. All images will be downloaded locally and linked appropriately.
 
 ## Tumblr
 
-- [tumblr-importr](https://github.com/carlmjohnson/tumblr-importr) - An importer that uses the Tumblr API to create a Hugo static site.
-- [tumblr2hugomarkdown](https://github.com/Wysie/tumblr2hugomarkdown) - Export all your Tumblr content to Hugo Markdown files with preserved original formatting.
-- [Tumblr to Hugo](https://github.com/jipiboily/tumblr-to-hugo) - A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. Furthermore, "Tumblr to Hugo" creates a CSV file with the original URL and the new path on Hugo, to help you setup the redirections.
+[tumblr-importr](https://github.com/carlmjohnson/tumblr-importr)
+: An importer that uses the Tumblr API to create a Hugo static site.
+
+[tumblr2hugomarkdown](https://github.com/Wysie/tumblr2hugomarkdown)
+: Export all your Tumblr content to Hugo Markdown files with preserved original formatting.
+
+[Tumblr to Hugo](https://github.com/jipiboily/tumblr-to-hugo)
+: A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. Furthermore, "Tumblr to Hugo" creates a CSV file with the original URL and the new path on Hugo, to help you setup the redirections.
 
 ## Drupal
 
-- [drupal2hugo](https://github.com/danapsimer/drupal2hugo) - Convert a Drupal site to Hugo.
+[drupal2hugo](https://github.com/danapsimer/drupal2hugo)
+: Convert a Drupal site to Hugo.
 
 ## Joomla
 
-- [hugojoomla](https://github.com/davetcc/hugojoomla) - This utility written in Java takes a Joomla database and converts all the content into Markdown files. It changes any URLs that are in Joomla's internal format and converts them to a suitable form.
+[hugojoomla](https://github.com/davetcc/hugojoomla)
+: This utility written in Java takes a Joomla database and converts all the content into Markdown files. It changes any URLs that are in Joomla's internal format and converts them to a suitable form.
 
 ## Blogger
 
-- [blogimport](https://github.com/natefinch/blogimport) - A tool to import from Blogger posts to Hugo.
-- [blogger-to-hugo](https://pypi.org/project/blogger-to-hugo/) - Another tool to import Blogger posts to Hugo. It also downloads embedded images so they will be stored locally.
-- [blog2md](https://github.com/palaniraja/blog2md) - Works with [exported xml](https://support.google.com/blogger/answer/41387?hl=en) file of your YOUR-TLD.blogspot.com website. It also saves comments to `YOUR-POST-NAME-comments.md` file along with posts.
-- [BloggerToHugo](https://github.com/huanlin/blogger-to-hugo) - Yet another tool to import Blogger posts to Hugo. For Windows platform only, and .NET Framework 4.5 is required. See README.md before using this tool.
+[blogimport](https://github.com/natefinch/blogimport)
+: A tool to import from Blogger posts to Hugo.
+
+[blogger-to-hugo](https://pypi.org/project/blogger-to-hugo/)
+: Another tool to import Blogger posts to Hugo. It also downloads embedded images so they will be stored locally.
+
+[blog2md](https://github.com/palaniraja/blog2md)
+: Works with [exported xml](https://support.google.com/blogger/answer/41387?hl=en) file of your YOUR-TLD.blogspot.com website. It also saves comments to `YOUR-POST-NAME-comments.md` file along with posts.
+
+[BloggerToHugo](https://github.com/huanlin/blogger-to-hugo)
+: Yet another tool to import Blogger posts to Hugo. For Windows platform only, and .NET Framework 4.5 is required. See README.md before using this tool.
 
 ## Contentful
 
-- [contentful-hugo](https://github.com/ModiiMedia/contentful-hugo) - A tool to create content-files for Hugo from content on [Contentful](https://www.contentful.com/).
+[contentful-hugo](https://github.com/ModiiMedia/contentful-hugo)
+: A tool to create content-files for Hugo from content on [Contentful](https://www.contentful.com/).
 
 ## BlogML
 
-- [BlogML2Hugo](https://github.com/jijiechen/BlogML2Hugo) - A tool that helps you convert BlogML xml file to Hugo Markdown files. Users need to take care of links to attachments and images by themselves. This helps the blogs that export BlogML files (e.g. BlogEngine.NET) transform to hugo sites easily.
+[BlogML2Hugo](https://github.com/jijiechen/BlogML2Hugo)
+: A tool that helps you convert BlogML xml file to Hugo Markdown files. Users need to take care of links to attachments and images by themselves. This helps the blogs that export BlogML files (e.g. BlogEngine.NET) transform to hugo sites easily.
diff --git a/content/en/tools/other.md b/content/en/tools/other.md
index 272827911..7b1489862 100644
--- a/content/en/tools/other.md
+++ b/content/en/tools/other.md
@@ -17,7 +17,7 @@ And for all the other small things around Hugo:
 - [flickr-hugo-embed](https://github.com/nikhilm/flickr-hugo-embed) prints shortcodes to embed a set of images from an album on Flickr into Hugo.
 - [hugo-openapispec-shortcode](https://github.com/tenfourty/hugo-openapispec-shortcode) A shortcode that allows you to include [Open API Spec](https://openapis.org) (formerly known as Swagger Spec) in a page.
 - [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) makes it easy to create image galleries using PhotoSwipe.
-- [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) Syncs the local build of your Hugo website with your remote webserver via SFTP.
+- [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) Syncs the local build of your Hugo website with your remote web server via SFTP.
 - [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) Emacs package for writing blog posts in markdown or org-mode and building your site with Hugo.
 - [JAMStack Themes](https://jamstackthemes.dev/ssg/hugo/). JAMStack themes is a collection of site themes filterable by static site generator and supported CMS to help build CMS-connected sites using Hugo (linking to Hugo-specific themes).
 - [plausible-hugo](https://github.com/divinerites/plausible-hugo). Easy Hugo integration for Plausible Analytics, a simple, open-source, lightweight and privacy-friendly web analytics alternative to Google Analytics.
diff --git a/content/en/tools/search.md b/content/en/tools/search.md
index 620ba4862..b7facc186 100644
--- a/content/en/tools/search.md
+++ b/content/en/tools/search.md
@@ -1,5 +1,5 @@
 ---
-title: Search for your Hugo website
+title: Search tools
 linkTitle: Search
 description: See some of the open-source and commercial search options for your newly created Hugo website.
 menu:
@@ -12,19 +12,42 @@ toc: true
 
 A static website with a dynamic search function? Yes, Hugo provides an alternative to embeddable scripts from Google or other search engines for static websites. Hugo allows you to provide your visitors with a custom search function by indexing your content files directly.
 
-* [GitHub Gist for Hugo Workflow](https://gist.github.com/sebz/efddfc8fdcb6b480f567). This gist contains a simple workflow to create a search index for your static website. It uses a simple Grunt script to index all your content files and [lunr.js](https://lunrjs.com/) to serve the search results.
+## Open source
 
-* [hugo-lunr](https://www.npmjs.com/package/hugo-lunr). A simple way to add site search to your static Hugo site using [lunr.js](https://lunrjs.com/). Hugo-lunr will create an index file of any HTML and Markdown documents in your Hugo project.
-* [hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh). A bit like Hugo-lunr, but Hugo-lunr-zh can help you separate the Chinese keywords.
-* [GitHub Gist for Fuse.js integration](https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1cb41ae). This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](https://fusejs.io/) on the client-side. Although this gist uses Fuse.js for fuzzy matching, any client-side search tool capable of reading JSON indexes will work. Does not require npm, grunt or other build-time tools except Hugo!
-* [hugo-search-index](https://www.npmjs.com/package/hugo-search-index). A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project markdown files.
-* [hugofastsearch](https://gist.github.com/cmod/5410eae147e4318164258742dd053993). A usability and speed update to "GitHub Gist for Fuse.js integration" — global, keyboard-optimized search.
-* [JS & Fuse.js tutorial](https://makewithhugo.com/add-search-to-a-hugo-site/) A simple client-side search solution, using FuseJS (does not require jQuery).
-* [Pagefind](https://github.com/cloudcannon/pagefind). A fully static search library that aims to perform well on large sites, while using as little of your users' bandwidth as possible.
-* [Hugo Lyra](https://github.com/paolomainardi/hugo-lyra). Hugo-Lyra is a JavaScript module to integrate [Lyra](https://github.com/LyraSearch/lyra) into a Hugo website. It contains the server-side part to generate the index and the client-side library (optional) to bootstrap the search engine easily.
+[Pagefind](https://github.com/cloudcannon/pagefind)
+: A fully static search library that aims to perform well on large sites, while using as little of your users' bandwidth as possible.
 
-## Commercial search services
+[GitHub Gist for Hugo Workflow](https://gist.github.com/sebz/efddfc8fdcb6b480f567)
+: This gist contains a simple workflow to create a search index for your static website. It uses a simple Grunt script to index all your content files and [lunr.js](https://lunrjs.com/) to serve the search results.
 
-* [Algolia](https://www.algolia.com/)'s Search API makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search.
-* [Bonsai](https://www.bonsai.io) is a fully-managed hosted Elasticsearch service that is fast, reliable, and simple to set up. Easily ingest your docs from Hugo into Elasticsearch following [this guide from the docs](https://docs.bonsai.io/hc/en-us/articles/13929190788756-Hugo).
-* [ExpertRec](https://www.expertrec.com/) is a hosted search-as-a-service solution that is fast and scalable. Set-up and integration is extremely easy and takes only a few minutes. The search settings can be modified without coding using a dashboard.
+[hugo-lunr](https://www.npmjs.com/package/hugo-lunr)
+: A simple way to add site search to your static Hugo site using [lunr.js](https://lunrjs.com/). Hugo-lunr will create an index file of any HTML and Markdown documents in your Hugo project.
+
+[hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh)
+: A bit like Hugo-lunr, but Hugo-lunr-zh can help you separate the Chinese keywords.
+
+[GitHub Gist for Fuse.js integration](https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1cb41ae)
+: This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](https://fusejs.io/) on the client-side. Although this gist uses Fuse.js for fuzzy matching, any client-side search tool capable of reading JSON indexes will work. Does not require npm, grunt or other build-time tools except Hugo!
+
+[hugo-search-index](https://www.npmjs.com/package/hugo-search-index)
+: A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project markdown files.
+
+[hugofastsearch](https://gist.github.com/cmod/5410eae147e4318164258742dd053993)
+: A usability and speed update to "GitHub Gist for Fuse.js integration" — global, keyboard-optimized search.
+
+[JS & Fuse.js tutorial](https://makewithhugo.com/add-search-to-a-hugo-site/)
+: A simple client-side search solution, using FuseJS (does not require jQuery).
+
+[Hugo Lyra](https://github.com/paolomainardi/hugo-lyra)
+: Hugo-Lyra is a JavaScript module to integrate [Lyra](https://github.com/LyraSearch/lyra) into a Hugo website. It contains the server-side part to generate the index and the client-side library (optional) to bootstrap the search engine easily.
+
+## Commercial
+
+[Algolia](https://www.algolia.com/)
+: Algolia's Search API makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search.
+
+[Bonsai](https://www.bonsai.io)
+: Bonsai is a fully-managed hosted Elasticsearch service that is fast, reliable, and simple to set up. Easily ingest your docs from Hugo into Elasticsearch following [this guide from the docs](https://docs.bonsai.io/hc/en-us/articles/13929190788756-Hugo).
+
+[ExpertRec](https://www.expertrec.com/)
+: ExpertRec is a hosted search-as-a-service solution that is fast and scalable. Set-up and integration is extremely easy and takes only a few minutes. The search settings can be modified without coding using a dashboard.
diff --git a/content/en/troubleshooting/faq.md b/content/en/troubleshooting/faq.md
index bc29bfba1..15ca8d36e 100644
--- a/content/en/troubleshooting/faq.md
+++ b/content/en/troubleshooting/faq.md
@@ -53,7 +53,7 @@ Also see this Twitter thread:
 
 If you process `SCSS` or `Sass` to `CSS` in your Hugo project with `libsass` as the transpiler or if you convert images to the `webp` format, you need the Hugo `extended` version, or else you may see an error message similar to the below:
 
-```bash
+```sh
 error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version
 ```
 
diff --git a/content/en/variables/_common/_index.md b/content/en/variables/_common/_index.md
new file mode 100644
index 000000000..47d5812fb
--- /dev/null
+++ b/content/en/variables/_common/_index.md
@@ -0,0 +1,13 @@
+---
+cascade:
+  _build:
+    list: never
+    publishResources: false
+    render: never
+---
+
+
diff --git a/content/en/variables/_common/consistent-terminology.md b/content/en/variables/_common/consistent-terminology.md
new file mode 100644
index 000000000..164dc23a8
--- /dev/null
+++ b/content/en/variables/_common/consistent-terminology.md
@@ -0,0 +1,20 @@
+---
+# Do not remove front matter.
+---
+
+{{% note %}}
+We are making an effort to unify our [terminology], and to use these terms consistently throughout the documentation.
+
+Historically, we have inconsistently referred to the items on this page as [functions], [parameters], [variables], or [methods]. They are not functions, parameters, or variables; they are methods.
+
+This page will remain in place as readers become familiar with the unified terminology. See the [methods section] for a list of methods by [object].
+
+[functions]: /getting-started/glossary/#function
+[methods section]: /methods
+[methods]: /getting-started/glossary/#method
+[object]: /getting-started/glossary/#object
+[parameters]: /getting-started/glossary/#parameter
+[terminology]: /getting-started/glossary/
+[variable]: /getting-started/glossary/#variable
+[variables]: /getting-started/glossary/#variable
+{{% /note %}}
diff --git a/content/en/variables/_index.md b/content/en/variables/_index.md
index c1f80a62c..577ef0148 100644
--- a/content/en/variables/_index.md
+++ b/content/en/variables/_index.md
@@ -1,18 +1,16 @@
 ---
-title: Variables and parameters
+title: Variables
 linkTitle: Overview
-description: Page-, file-, taxonomy-, and site-level variables and parameters available in templates.
-categories: [variables and parameters]
-keywords: [variables,params,values,globals]
+description: Use these variables in your templates.
+categories: [variables]
+keywords: []
 menu:
   docs:
     identifier: variables-overview
     parent: variables
-    weight: 1
-weight: 1
+    weight: 10
+weight: 10
 aliases: [/templates/variables/]
 ---
 
-Hugo's templates are context aware and make a large number of values available to you as you're creating views for your website.
-
-[Go templates]: /templates/introduction/
+{{% include "variables/_common/consistent-terminology.md" %}}
diff --git a/content/en/variables/file.md b/content/en/variables/file.md
new file mode 100644
index 000000000..248d84991
--- /dev/null
+++ b/content/en/variables/file.md
@@ -0,0 +1,18 @@
+---
+title: File variables
+description: Retrieve file information about any page that is backed by a file.
+categories: [variables]
+keywords: []
+menu:
+  docs:
+    parent: variables
+    weight: 20
+weight: 20
+aliases: [/variables/file-variables/,/variables/files/]
+---
+
+{{% include "variables/_common/consistent-terminology.md" %}}
+
+To retrieve file information about any page that is backed by a file, see the documentation for the [`File`] method on a `Page` object.
+
+[`File`]: /methods/page/file
diff --git a/content/en/variables/files.md b/content/en/variables/files.md
deleted file mode 100644
index fa2a63a9c..000000000
--- a/content/en/variables/files.md
+++ /dev/null
@@ -1,102 +0,0 @@
----
-title: File variables
-description: "Use File variables to access file-related values for each page that is backed by a file."
-categories: [variables and parameters]
-keywords: [files]
-menu:
-  docs:
-    parent: variables
-    weight: 40
-toc: true
-weight: 40
-aliases: [/variables/file-variables/]
----
-## Variables
-
-{{% note %}}
-The path separators (slash or backslash) in `.File.Path`, `.File.Dir`, and `.File.Filename` depend on the operating system.
-{{% /note %}}
-
-.File.Path
-: (`string`) The file path, relative to the `content` directory.
-
-.File.Dir
-: (`string`) The file path, excluding the file name, relative to the `content` directory.
-
-.File.LogicalName
-: (`string`) The file name.
-
-.File.BaseFileName
-: (`string`) The file name, excluding the extension.
-
-.File.TranslationBaseName
-: (`string`) The file name, excluding the extension and language identifier.
-
-.File.Ext
-: (`string`) The file extension.
-
-.File.Lang
-: (`string`) The language associated with the given file.
-
-
-.File.ContentBaseName
-: (`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `.TranslationBaseName`.
-
-.File.Filename
-: (`string`) The absolute file path.
-
-.File.UniqueID
-: (`string`) The MD5 hash of `.File.Path`.
-
-## Examples
-
-```text
-content/
-├── news/
-│   ├── b/
-│   │   ├── index.de.md   <-- leaf bundle
-│   │   └── index.en.md   <-- leaf bundle
-│   ├── a.de.md           <-- regular content
-│   ├── a.en.md           <-- regular content
-│   ├── _index.de.md      <-- branch bundle
-│   └── _index.en.md      <-- branch bundle
-├── _index.de.md
-└── _index.en.md
-```
-
-With the content structure above, the `.File` objects for the English pages contain the following properties:
-
- |regular content|leaf bundle|branch bundle
-:--|:--|:--|:--
-Path|news/a.en.md|news/b/index.en.md|news/_index.en.md
-Dir|news/|news/b/|news/
-LogicalName|a.en.md|index.en.md|_index.en.md
-BaseFileName|a.en|index.en|_index.en
-TranslationBaseName|a|index|_index
-Ext|md|md|md
-Lang|en|en|en
-ContentBaseName|a|b|news
-Filename|/home/user/...|/home/user/...|/home/user/...
-UniqueID|15be14b...|186868f...|7d9159d...
-
-## Defensive coding
-
-Some of the pages on a site may not be backed by a file. For example:
-
-- Top level section pages
-- Taxonomy pages
-- Term pages
-
-Without a backing file, Hugo will throw a warning if you attempt to access a `.File` property. For example:
-
-```text
-WARN .File.ContentBaseName on zero object. Wrap it in if or with...
-```
-
-To code defensively:
-
-```go-html-template
-{{ with .File }}
-  {{ .ContentBaseName }}
-{{ end }}
-```
diff --git a/content/en/variables/git.md b/content/en/variables/git.md
index 8928ca6f0..3dc473265 100644
--- a/content/en/variables/git.md
+++ b/content/en/variables/git.md
@@ -1,71 +1,18 @@
 ---
 title: Git variables
-linkTitle: Git variables
-description: Get the last Git revision information for every content file.
-categories: [variables and parameters]
-keywords: [git]
+description: Retrieve Git information related to the last commit of any page.
+categories: [variables]
+keywords: []
 menu:
   docs:
     parent: variables
-    weight: 70
-weight: 70
+    weight: 30
+weight: 30
 aliases: [/extras/gitinfo/]
 ---
 
-{{% note %}}
-Hugo's Git integrations should be fairly performant but *can* increase your build time. This will depend on the size of your Git history.
-{{% /note %}}
+{{% include "variables/_common/consistent-terminology.md" %}}
 
-## `.GitInfo` prerequisites
+To retrieve Git information related to the last commit of any page, see the documentation for the [`GitInfo`] method on a `Page` object.
 
-1. The Hugo site must be in a Git-enabled directory.
-2. The Git executable must be installed and in your system `PATH`.
-3. The `.GitInfo` feature must be enabled in your Hugo project by passing `--enableGitInfo` flag on the command line or by setting `enableGitInfo` to `true` in your [site's configuration file][configuration].
-
-## The `.GitInfo` object
-
-The `GitInfo` object contains the following fields:
-
-.AbbreviatedHash
-: the abbreviated commit hash (e.g., `866cbcc`)
-
-.AuthorName
-: the author's name, respecting [`.mailmap`](https://git-scm.com/docs/gitmailmap)
-
-.AuthorEmail
-: the author's email address, respecting [`.mailmap`](https://git-scm.com/docs/gitmailmap)
-
-.AuthorDate
-: the author date
-
-.Hash
-: the commit hash (e.g., `866cbccdab588b9908887ffd3b4f2667e94090c3`)
-
-.Subject
-: commit message subject (e.g., `tpl: Add custom index function`)
-
-## `.Lastmod`
-
-If the `.GitInfo` feature is enabled, `.Lastmod` (on `Page`) is fetched from Git i.e. `.GitInfo.AuthorDate`. This behavior can be changed by adding your own [front matter configuration for dates](/getting-started/configuration/#configure-front-matter).
-
-[configuration]: /getting-started/configuration/
-
-## Hosting considerations
-
-On the site host, your repository must be "deep-cloned," so the returned `.GitInfo` data will be accurate. Otherwise, your site may display only data from your latest commit. Where it's not possible to configure a host's cloning depth, you must handle this through CI/CD (*e.g.*, a GitHub Action or GitLab CI/CD). See the following table:
-
-| Hosting service | Clone depth | Configurable? |
-| :-------------- | :---------- | :-----------: |
-| Cloudflare Pages | Shallow | ✔️ [^CFP] |
-| DigitalOcean App Platform | Deep | ❌ |
-| GitHub Pages | Shallow | ✔️ [^GHP] |
-| GitLab Pages | Shallow | ✔️ [^GLP] |
-| Netlify | Deep | ❌ |
-| Render | Shallow | ❌ |
-| Vercel | Shallow | ❌ |
-
-[^CFP]: To configure a Cloudflare Pages site for deep cloning, preface the site's normal Hugo build command with `git fetch --unshallow &&` (*e.g.*, `git fetch --unshallow && hugo`).
-
-[^GHP]: You can configure the GitHub Action to do a deep clone by specifying `fetch-depth: 0` in the applicable "checkout" step of your workflow file, as shown in the Hugo documentation's [example workflow file](/hosting-and-deployment/hosting-on-github/#procedure).
-
-[^GLP]: You can configure the GitLab Runner's clone depth [as explained in the GitLab documentation](https://docs.gitlab.com/ee/ci/large_repositories/#shallow-cloning); see also the Hugo documentation's [example workflow file](https://gohugo.io/hosting-and-deployment/hosting-on-gitlab/#configure-gitlab-cicd).
+[`GitInfo`]: /methods/page/gitinfo
diff --git a/content/en/variables/menu-entry.md b/content/en/variables/menu-entry.md
new file mode 100644
index 000000000..901477d2b
--- /dev/null
+++ b/content/en/variables/menu-entry.md
@@ -0,0 +1,16 @@
+---
+title: Menu entry variables
+description: Use these methods in your menu templates.
+categories: [variables]
+keywords: [menus]
+menu:
+  docs:
+    parent: variables
+    weight: 40
+weight: 40
+aliases: [/variables/menus/]
+---
+
+{{% include "variables/_common/consistent-terminology.md" %}}
+
+{{< list-pages-in-section path=/methods/menu-entry titlePrefix=. >}}
diff --git a/content/en/variables/menus.md b/content/en/variables/menus.md
deleted file mode 100644
index 0fe727cd8..000000000
--- a/content/en/variables/menus.md
+++ /dev/null
@@ -1,92 +0,0 @@
----
-title: Menu variables
-description: Use these variables and methods in your menu templates.
-categories: [variables and parameters]
-keywords: [menus]
-menu:
-  docs:
-    parent: variables
-    weight: 50
-weight: 50
-aliases: [/variables/menu/]
----
-
-## Variables
-
-After [defining menu entries], access their properties in [menu templates] with these variables.
-
-.Children
-: (`menu`) A collection of child menu entries, if any, under the current menu entry.
-
-.Identifier
-: (`string`) The `identifier` property of the menu entry. If you define the menu entry [automatically], the page's `.Section`.
-
-.KeyName
-: (`string`) The `identifier` property of the menu entry, else the `name` property.
-
-.Menu
-: (`string`) The identifier of the menu that contains the menu entry.
-
-.Name
-: (`string`) The `name` property of the menu entry.
-
-- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`.
-- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`.
-
-.Page
-: (`page`) A reference to the page associated with the menu entry.
-
-
-
-.Params
-: (`map`) The `params` property of the menu entry.
-
-.Parent
-: (`string`)  The `parent` property of the menu entry.
-
-.Post
-: (`template.HTML`) The `post` property of the menu entry.
-
-.Pre
-: (`template.HTML`) The `pre` property of the menu entry.
-
-.Title
-: (`string`) The `title` property of the menu entry.
-
-- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`.
-- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`.
-
-.URL
-: (`string`) The `.RelPermalink` of the page associated with the menu entry. For menu entries pointing to external resources, the `url` property of the menu entry.
-
-.Weight
-: (`int`) The `weight` property of the menu entry.
-
-- If you define the menu entry [automatically], the page's `.Weight`.
-- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.Weight`.
-
-## Methods
-
-.HasChildren
-: (`bool`) Returns `true` if `.Children` is non-nil.
-
-.IsEqual
-: (`bool`) Returns `true` if the compared menu entries represent the same menu entry.
-
-.IsSameResource
-: (`bool`) Returns `true` if the compared menu entries point to the same resource.
-
-.Page.HasMenuCurrent
-: (`bool`) Use this method to determine ancestors of the active menu entry. See [details](/functions/hasmenucurrent/).
-
-.Page.IsMenuCurrent
-: (`bool`) Use this method to determine the active menu entry. See [details](/functions/ismenucurrent/).
-
-[automatically]: /content-management/menus/#define-automatically
-[defining menu entries]: /content-management/menus/#overview
-[in front matter]: /content-management/menus/#define-in-front-matter
-[in site configuration]: /content-management/menus/#define-in-site-configuration
-[menu templates]: /templates/menu-templates/
diff --git a/content/en/variables/page.md b/content/en/variables/page.md
index 16e5f31ff..8ee911007 100644
--- a/content/en/variables/page.md
+++ b/content/en/variables/page.md
@@ -1,357 +1,63 @@
 ---
 title: Page variables
-description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself.
-categories: [variables and parameters]
-keywords: [pages]
+description: Use these methods with a Page object.
+categories: [variables]
+keywords: [page]
 menu:
   docs:
     parent: variables
-    weight: 20
-weight: 20
+    weight: 50
+weight: 50
 toc: true
 ---
 
-The following is a list of page-level variables. Many of these will be defined in the front matter, derived from file location, or extracted from the content itself.
+{{% include "variables/_common/consistent-terminology.md" %}}
 
-## Page variables
+## All methods
 
-.AlternativeOutputFormats
-: Contains all alternative formats for a given page; this variable is especially useful `link rel` list in your site's ``. (See [Output Formats](/templates/output-formats/).)
+Use any of these methods in your templates.
 
-.Aliases
-: Aliases of this page
+{{< list-pages-in-section path=/methods/page titlePrefix=. >}}
 
-.Ancestors
-: Ancestors of this page.
+## Dates
 
-.BundleType
-: The [bundle] type: `leaf`, `branch`, or an empty string if the page is not a bundle.
+Use these methods to access content dates.
 
-.Content
-: The content itself, defined below the front matter.
+{{< list-pages-in-section path=/methods/page filter=methods_page_dates filterType=include titlePrefix=. omitElementIDs=true >}}
 
-.Data
-: The data specific to this type of page.
+## Multilingual
 
-.Date
-: The date associated with the page. By default, this is the front matter `date` value. See [configuring dates] for a description of fallback values and precedence. See also `.ExpiryDate`, `.Lastmod`, and `.PublishDate`.
+Use these methods with your multilingual projects.
 
-.Description
-: The description for the page.
+{{< list-pages-in-section path=/methods/page filter=methods_page_multilinugual filterType=include titlePrefix=. omitElementIDs=true >}}
 
-.Draft
-: A boolean, `true` if the content is marked as a draft in the front matter.
+## Navigation
 
-.ExpiryDate
-: The date on which the content is scheduled to expire. By default, this is the front matter `expiryDate` value. See [configuring dates] for a description of fallback values and precedence. See also `.Date`, `.Lastmod`, and `.PublishDate`.
+Use these methods to create navigation links between pages.
 
-.File
-: Filesystem-related data for this content file. See also [File Variables].
-
-.Fragments
-: Fragments returns the fragments for this page. See [Page Fragments](#page-fragments).
-
-.FuzzyWordCount
-: The approximate number of words in the content.
-
-.IsHome
-: `true` in the context of the [homepage](/templates/homepage/).
-
-.IsNode
-: Always `false` for regular content pages.
-
-.IsPage
-: Always `true` for regular content pages.
-
-.IsSection
-: `true` if [`.Kind`](/templates/section-templates/#page-kinds) is `section`.
-
-.IsTranslated
-: `true` if there are translations to display.
-
-.Keywords
-: The meta keywords for the content.
-
-.Kind
-: The page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `term`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections.
-
-.Language
-: A language object that points to the language's definition in the site configuration. `.Language.Lang` gives you the language code.
-
-.Lastmod
-: The date on which the content was last modified. By default, if `enableGitInfo` is `true` in your site configuration, this is the Git author date, otherwise the front matter `lastmod` value. See [configuring dates] for a description of fallback values and precedence. See also `.Date`,`ExpiryDate`, `.PublishDate`, and [`.GitInfo`][gitinfo].
-
-.LinkTitle
-: Access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`.
-
-.Next
-: Points up to the next regular page (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ with .Next }}{{ .Permalink }}{{ end }}`. Calling `.Next` from the first page returns `nil`.
-
-.NextInSection
-: Points up to the next regular page below the same top level section (e.g. in `/blog`)). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ with .NextInSection }}{{ .Permalink }}{{ end }}`. Calling `.NextInSection` from the first page returns `nil`.
-
-.OutputFormats
-: Contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).)
-
-.Permalink
-: The Permanent link for this page; see [Permalinks](/content-management/urls/)
-
-.Plain
-: The Page content stripped of HTML tags and presented as a string. You may need to pipe the result through the [`htmlUnescape`](/functions/transform/htmlunescape) function when rendering this value with the HTML [output format](/templates/output-formats#output-format-definitions).
-
-.PlainWords
-: The slice of strings that results from splitting .Plain into words, as defined in Go's [strings.Fields](https://pkg.go.dev/strings#Fields).
-
-.Prev
-: Points down to the previous regular page(sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ if .Prev }}{{ .Prev.Permalink }}{{ end }}`.  Calling `.Prev` from the last page returns `nil`.
-
-.PrevInSection
-: Points down to the previous regular page below the same top level section (e.g. `/blog`). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ if .PrevInSection }}{{ .PrevInSection.Permalink }}{{ end }}`.  Calling `.PrevInSection` from the last page returns `nil`.
-
-.PublishDate
-: The date on which the content was or will be published. By default, this is the front matter `publishDate` value. See [configuring dates] for a description of fallback values and precedence. See also `.Date`, `.ExpiryDate`, and `.Lastmod`.
-
-.RawContent
-: Raw markdown content without the front matter. Useful with [remarkjs.com](
-https://remarkjs.com)
-
-.RenderShortcodes
-: See [Render Shortcodes](#rendershortcodes).
-
-.ReadingTime
-: The estimated time, in minutes, it takes to read the content.
-
-.Resources
-: Resources such as images and CSS that are associated with this page
-
-.Ref
-: Returns the permalink for a given reference (e.g., `.Ref "sample.md"`).  `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
-
-.RelPermalink
-: The relative permanent link for this page.
-
-.RelRef
-: Returns the relative permalink for a given reference (e.g., `RelRef
-"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
-
-.Site
-: See [Site Variables](/variables/site/).
-
-.Sites
-: Returns all sites (languages). A typical use case would be to link back to the main language: `...`.
-
-.Sites.First
-: Returns the site for the first language. If this is not a multilingual setup, it will return itself.
-
-.Summary
-: A generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <!--more--> at the appropriate place in the content page, or the summary can be written independent of the page text.  See [Content Summaries](/content-management/summaries/) for more details.
-
-.TableOfContents
-: The rendered [table of contents](/content-management/toc/) for the page.
-
-.Title
-: The title for this page.
-
-.Translations
-: A list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information.
-
-.TranslationKey
-: The key used to map language translations of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information.
-
-.Truncated
-: A boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary.  See [Summaries](/content-management/summaries/) for more information.
-
-.Type
-: The [content type](/content-management/types/) of the content (e.g., `posts`).
-
-.Weight
-: Assigned weight (in the front matter) to this content, used in sorting.
-
-.WordCount
-: The number of words in the content.
+{{< list-pages-in-section path=/methods/page filter=methods_page_navigation filterType=include titlePrefix=. omitElementIDs=true >}}
 
 ## Page collections
 
-List pages receive the following page collections in [context](/getting-started/glossary/#context):
+Range through these collections when rendering lists on [section] pages, [taxonomy] pages, [term] pages, and the home page.
 
-.Pages
-: Regular pages within the current section (not recursive), and section pages for immediate descendant sections (not recursive).
+[section]: /getting-started/glossary/#section
+[taxonomy]: /getting-started/glossary/#taxonomy
+[term]: /getting-started/glossary/#term
+[context]: /getting-started/glossary/#context
 
-.RegularPages
-: Regular pages within the current section (not recursive).
+{{< list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=. omitElementIDs=true >}}
 
-.RegularPagesRecursive
-: Regular pages within the current section, and regular pages within all descendant sections.
+## Parameters
 
-## Writable page-scoped variables
+Use these methods to access page parameters.
 
-[.Scratch][scratch]
-: Returns a Scratch to store and manipulate data. In contrast to the [`.Store`][store] method, this scratch is reset on server rebuilds.
+{{< list-pages-in-section path=/methods/page filter=methods_page_parameters filterType=include titlePrefix=. omitElementIDs=true >}}
 
-[.Store][store]
-: Returns a Scratch to store and manipulate data. In contrast to the [`.Scratch`][scratch] method, this scratch is not reset on server rebuilds.
+## Sections
 
-## Section variables and methods
+Use these methods to access section pages, and their ancestors and descendants. See [details].
 
-Also see [Sections](/content-management/sections/).
+[details]: /content-management/sections/
 
-.CurrentSection
-: The page's current section. The value can be the page itself if it is a section or the homepage.
-
-.FirstSection
-: The page's first section below root, e.g. `/docs`, `/blog` etc.
-
-.InSection $anotherPage
-: Whether the given page is in the current section.
-
-.IsAncestor $anotherPage
-: Whether the current page is an ancestor of the given page.
-
-.IsDescendant $anotherPage
-: Whether the current page is a descendant of the given page.
-
-.Parent
-: A section's parent section or a page's section.
-
-.Section
-: The [section](/content-management/sections/) this content belongs to. **Note:** For nested sections, this is the first path element in the directory, for example, `/blog/funny/mypost/ => blog`.
-
-.Sections
-: The [sections](/content-management/sections/) below this content.
-
-## Page fragments
-
-{{< new-in "0.111.0" >}}
-
-The `.Fragments` method returns a list of fragments for the current page.
-
-.Headings
-: A recursive list of headings for the current page. Can be used to generate a table of contents.
-
-{{< todo >}}add .Headings toc example{{< /todo >}}
-
-.Identifiers
-: A sorted list of identifiers for the current page. Can be used to check if a page contains a specific identifier or if a page contains duplicate identifiers:
-
-```go-html-template
-{{ if .Fragments.Identifiers.Contains "my-identifier" }}
-    
    Page contains identifier "my-identifier"
    
-{{ end }}
-
-{{ if gt (.Fragments.Identifiers.Count "my-identifier")  1 }}
-    
    Page contains duplicate "my-identifier" fragments
    
-{{ end }}
-```
-
-.HeadingsMap
-: Holds a map of headings for the current page. Can be used to start the table of contents from a specific heading.
-
-Also see the [Go Doc](https://pkg.go.dev/github.com/gohugoio/hugo@v0.111.0/markup/tableofcontents#Fragments) for the return type.
-
-### Fragments in hooks and shortcodes
-
-`.Fragments` are safe to call from render hooks, even on the page you're on (`.Page.Fragments`). For shortcodes we recommend that all `.Fragments` usage is nested inside the `{{}}` shortcode delimiter (`{{%/**/%}}` takes part in the ToC creation so it's easy to end up in a situation where you bite yourself in the tail).
-
-## The `.RenderShortcodes` method {#rendershortcodes}
-
-{{< new-in "0.117.0" >}} This renders all the shortcodes in the content, preserving the surrounding markup (e.g. Markdown) as is.
-
-The common use case this is to composing a page from multiple content files while preserving a global context for table of contents and foot notes.
-
-This method is most often used in shortcode templates. A simple example of shortcode template including content from another page would look like:
-
-```go-html-template
-{{ $p := site.GetPage (.Get 0) }}
-{{ $p.RenderShortcodes }}
-```
-
-In the above it's important to understand  and the difference between the two delimiters used when including a shortcode:
-
-* `{{}}` tells Hugo that the rendered shortcode does not need further processing (e.g. it's HTML).
-* `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing (e.g. it's Markdown).
-
-The latter is what you want to use for the include shortcode outlined above:
-
-```md
-## Mypage
-{{%/* include "mypage" */%}}
-``````
-
-
-Also see [Use Shortcodes](/content-management/shortcodes/#use-shortcodes).
-
-## Page-level params
-
-Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable.
-
-{{< code-toggle file="content/example.md" fm=true copy=false >}}
-title: Example
-categories: [one]
-tags: [two,three,four]
-{{< /code-toggle >}}
-
-With the above front matter, the `tags` and `categories` taxonomies are accessible via the following:
-
-* `.Params.tags`
-* `.Params.categories`
-
-The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter:
-
-{{< code-toggle file="content/example.md" fm=true copy=false >}}
-title: Example
-affiliatelink: "http://www.my-book-link.here"
-recommendedby: "My Mother"
-{{< /code-toggle >}}
-
-These fields would then be accessible to via `.Params.affiliatelink` and `.Params.recommendedby`.
-
-```go-html-template
-
    Buy this book
    
-
    It was recommended by {{ .Params.recommendedby }}.
    
-```
-
-This template would render as follows:
-
-```html
-
    Buy this book
    
-
    It was recommended by my Mother.
    
-```
-
-{{% note %}}
-See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content.
-{{% /note %}}
-
-### The `.Param` method
-
-In Hugo, you can declare parameters in individual pages and globally for your entire website. A common use case is to have a general value for the site parameter and a more specific value for some of the pages (i.e., a header image):
-
-```go-html-template
-{{ $.Param "header_image" }}
-```
-
-The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your site configuration).
-
-### Access nested fields in front matter
-
-When front matter contains nested fields like the following:
-
-{{< code-toggle file="content/example.md" fm=true copy=false >}}
-title: Example
-author:
-  given_name: John
-  family_name: Feminella
-  display_name: John Feminella
-{{< /code-toggle >}}
-
-`.Param` can access these fields by concatenating the field names together with a dot:
-
-```go-html-template
-{{ $.Param "author.display_name" }}
-```
-
-[configuring dates]: /getting-started/configuration/#configure-dates
-[gitinfo]: /variables/git/
-[File Variables]: /variables/files/
-[bundle]: /content-management/page-bundles
-[scratch]: /functions/scratch
-[store]: /functions/store
+{{< list-pages-in-section path=/methods/page filter=methods_page_sections filterType=include titlePrefix=. omitElementIDs=true >}}
diff --git a/content/en/variables/pages.md b/content/en/variables/pages.md
index 3917a6558..2f8e79d72 100644
--- a/content/en/variables/pages.md
+++ b/content/en/variables/pages.md
@@ -1,25 +1,39 @@
 ---
-title: Pages methods
-description: Pages is the core page collection in Hugo and has many useful methods.
-categories: [variables and parameters]
+title: Pages variables
+description: Use these methods with a collection of Page objects.
+categories: [variables]
 keywords: [pages]
 menu:
   docs:
     parent: variables
-    weight: 21
-weight: 21
-aliases: [/pages]
+    weight: 60
+weight: 60
+aliases: [/variables/site-variables/]
 toc: true
 ---
 
-Also see [List templates](/templates/lists) for an overview of sort methods.
+{{% include "variables/_common/consistent-terminology.md" %}}
 
-## .Next PAGE
+## All methods
 
-`.Next` and `.Prev` on `Pages` work similar to the methods with the same names on `.Page`, but are more flexible (and slightly slower) as they can be used on any page collection.
+Use any of these methods with page collections in your templates.
 
-`.Next` points **up** to the next page relative to the page sent in as the argument. Example: `{{ with .Site.RegularPages.Next . }}{{ .RelPermalink }}{{ end }}`. Calling `.Next` with the first page in the collection returns `nil`.
+{{< list-pages-in-section path=/methods/pages titlePrefix=. >}}
 
-## .Prev PAGE
+## Sort by
 
-`.Prev` points **down** to the previous page relative to the page sent in as the argument. Example: `{{ with .Site.RegularPages.Prev . }}{{ .RelPermalink }}{{ end }}`. Calling `.Prev` with the last page in the collection returns `nil`.
+Use these methods to sort page collections.
+
+{{< list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. omitElementIDs=true >}}
+
+## Group by
+
+Use these methods to group page collections.
+
+{{< list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. omitElementIDs=true >}}
+
+## Navigation
+
+Use these methods to create navigation links between pages.
+
+{{< list-pages-in-section path=/methods/pages filter=methods_pages_navigation filterType=include titlePrefix=. omitElementIDs=true >}}
diff --git a/content/en/variables/shortcode.md b/content/en/variables/shortcode.md
new file mode 100644
index 000000000..51bf0c00c
--- /dev/null
+++ b/content/en/variables/shortcode.md
@@ -0,0 +1,16 @@
+---
+title: Shortcode variables
+description: Use these methods in your shortcode templates.
+categories: [variables]
+keywords: [shortcodes]
+menu:
+  docs:
+    parent: variables
+    weight: 70
+weight: 70
+aliases: [/variables/shortcodes]
+---
+
+{{% include "variables/_common/consistent-terminology.md" %}}
+
+{{< list-pages-in-section path=/methods/shortcode titlePrefix=. >}}
diff --git a/content/en/variables/shortcodes.md b/content/en/variables/shortcodes.md
deleted file mode 100644
index a03485d6f..000000000
--- a/content/en/variables/shortcodes.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-title: Shortcode variables
-description: Shortcodes can access page variables and also have their own specific built-in variables.
-categories: [variables and parameters]
-keywords: [shortcodes]
-menu:
-  docs:
-    parent: variables
-    weight: 20
-weight: 20
----
-
-[Shortcodes][shortcodes] have access to parameters delimited in the shortcode declaration via [`.Get`][getfunction], page- and site-level variables, and also the following shortcode-specific fields:
-
-.Name
-: Shortcode name.
-
-.Ordinal
-: Zero-based ordinal in relation to its parent. If the parent is the page itself, this ordinal will represent the position of this shortcode in the page content.
-
-.Page
-: The owning ´Page`.
-
-.Parent
-: provides access to the parent shortcode context in nested shortcodes. This can be very useful for inheritance of common shortcode parameters from the root.
-
-.Position
-: Contains [file name and position](https://godoc.org/github.com/gohugoio/hugo/common/text#Position) for the shortcode in a page. Note that this can be relatively expensive to calculate, and is meant for error reporting. See [Error Handling in Shortcodes](/templates/shortcode-templates/#error-handling-in-shortcodes).
-
-.IsNamedParams
-: boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes]
-
-.Inner
-: represents the content between the opening and closing shortcode tags when a [closing shortcode][markdownshortcode] is used
-
-.Scratch
-: returns a writable [`Scratch`][scratch] to store and manipulate data which will be attached to the shortcode context. This scratch is reset on server rebuilds.
-
-.InnerDeindent {{< new-in "0.100.0" >}}
-: Gets the `.Inner` with any indentation removed. This is what's used in the built-in `{{}}` shortcode.
-
-[getfunction]: /functions/get/
-[markdownshortcode]: /content-management/shortcodes/#shortcodes-with-markdown
-[shortcodes]: /templates/shortcode-templates/
-[scratch]: /functions/scratch
diff --git a/content/en/variables/site.md b/content/en/variables/site.md
index 2b9402c5f..3e0e964cb 100644
--- a/content/en/variables/site.md
+++ b/content/en/variables/site.md
@@ -1,108 +1,55 @@
 ---
 title: Site variables
-description: Many, but not all, site-wide variables are defined in your site's configuration. However, Hugo provides a number of built-in variables for convenient access to global values in your templates.
-categories: [variables and parameters]
-keywords: [global,site]
+description: Use these methods with Site objects. A multilingual project will have two or more sites, one for each language.
+categories: [variables]
+keywords: [site]
 menu:
   docs:
     parent: variables
-    weight: 10
-weight: 10
+    weight: 80
+weight: 80
 aliases: [/variables/site-variables/]
 toc: true
 ---
 
-The following is a list of site-level (aka "global") variables. Many of these variables are defined in your site's [configuration file][config], whereas others are built into Hugo's core for convenient usage in your templates.
+{{% include "variables/_common/consistent-terminology.md" %}}
 
-## Get the site object from a partial
+## All methods
 
-All the methods below, e.g. `.Site.RegularPages` can also be reached via the global [`site`](/functions/site/) function, e.g. `site.RegularPages`, which can be handy in partials where the `Page` object isn't easily available.
+Use any of these methods in your templates.
 
-## Site variables
+{{< list-pages-in-section path=/methods/site titlePrefix=.Site. >}}
 
-.Site.AllPages
-: array of all pages, regardless of their translation.
+## Multilingual
 
-.Site.BaseURL
-: the base URL for the site as defined in the site configuration.
+Use these methods with your multilingual projects.
 
-.Site.BuildDrafts
-: a boolean (default: `false`) to indicate whether to build drafts as defined in the site configuration.
+{{< list-pages-in-section path=/methods/site filter=methods_site_multilingual filterType=include titlePrefix=.Site. omitElementIDs=true >}}
 
-.Site.Copyright
-: a string representing the copyright of your website as defined in the site configuration.
+[`site`]: /functions/global/site
+[context]: /getting-started/glossary/#context
+[configuration file]: /getting-started/configuration
 
-.Site.Data
-: custom data, see [Data Templates](/templates/data-templates/).
+## Page collections
 
-.Site.Home
-: reference to the homepage's [page object](/variables/page/)
+Range through these collections when rendering lists on any page.
 
-.Site.IsMultiLingual
-: whether there are more than one language in this site. See [Multilingual](/content-management/multilingual/) for more information.
+{{< list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=.Site. omitElementIDs=true >}}
 
-.Site.Language.Lang
-: the language code of the current locale (e.g., `en`).
+## Global site function
 
-.Site.Language.LanguageName
-: the full language name (e.g. `English`).
+Within a partial template, if you did not pass a `Page` or `Site` object in [context], you cannot use this syntax:
 
-.Site.Language.Weight
-: the weight that defines the order in the `.Site.Languages` list.
+```go-html-template
+{{ .Site.SomeMethod }}
+```
 
-.Site.Language
-: indicates the language currently being used to render the website. This object's attributes are set in site configurations' language definition.
+Instead, use the global [`site`] function:
 
-.Site.LanguageCode
-: a string representing the language tag as defined in the site configuration.
+```go-html-template
+{{ site.SomeMethod }}
+```
 
-.Site.LanguagePrefix
-: this can be used to prefix URLs to point to the correct language. It will even work when there is only one defined language. See also the functions [absLangURL](/functions/urls/abslangurl) and [relLangURL](/functions/urls/rellangurl).
-
-.Site.Languages
-: an ordered list (ordered by defined weight) of languages.
-
-.Site.LastChange
-: a [time.Time](https://godoc.org/time#Time) value representing the date/time of the most recent change to your site.
-
-.Site.Menus
-: all the menus in the site.
-
-.Site.Pages
-: array of all content ordered by Date with the newest first. This array contains only the pages in the current language.
-
-.Site.RegularPages
-: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`.
-
-.Site.Sections
-: top-level directories of the site.
-
-.Site.Taxonomies
-: the [taxonomies](/content-management/taxonomies/) for the entire site. Also see section [Access taxonomy data from any template](/variables/taxonomy/#access-taxonomy-data-from-any-template).
-
-.Site.Title
-: a string representing the title of the site.
-
-## Site parameters
-
-`.Site.Params` is a container holding the values from the `params` section of your site configuration.
-
-### Example: `.Site.Params`
-
-The following `config.[yaml|toml|json]` defines a site-wide parameter for `description`:
-
-{{< code-toggle file="hugo" >}}
-baseURL = "https://yoursite.example.com/"
-
-[params]
-  description = "Tesla's Awesome Hugo Site"
-  author = "Nikola Tesla"
-{{}}
-
-You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description:
-
-{{< code file="layouts/partials/head.html" >}}
-
-{{< /code >}}
-
-[config]: /getting-started/configuration/
+{{% note %}}
+You can use the global site function in all templates to avoid context problems. Its usage is not limited to partial templates.
+{{% /note %}}
diff --git a/content/en/variables/sitemap.md b/content/en/variables/sitemap.md
deleted file mode 100644
index 80fb11076..000000000
--- a/content/en/variables/sitemap.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-title: Sitemap variables
-description:
-categories: [variables and parameters]
-keywords: [sitemap]
-menu:
-  docs:
-    parent: variables
-    weight: 80
-weight: 80
----
-
-A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use sitemap templates. They also have the following sitemap-specific variables available to them:
-
-.Sitemap.ChangeFreq
-: the page change frequency
-
-.Sitemap.Priority
-: the priority of the page
-
-.Sitemap.Filename
-: the sitemap file name
-
-[pagevars]: /variables/page/
diff --git a/content/en/variables/taxonomy.md b/content/en/variables/taxonomy.md
index 2c1e051a9..1637337e3 100644
--- a/content/en/variables/taxonomy.md
+++ b/content/en/variables/taxonomy.md
@@ -1,138 +1,21 @@
 ---
 title: Taxonomy variables
-description: Hugo's taxonomy system exposes variables to taxonomy and term templates.
-categories: [variables and parameters]
+description: Use these methods with Taxonomy objects.
+categories: [variables]
 keywords: [taxonomy,term]
 menu:
   docs:
     parent: variables
-    weight: 30
-toc: true
-weight: 30
+    weight: 90
+weight: 90
 ---
 
-## Taxonomy templates
+{{% include "variables/_common/consistent-terminology.md" %}}
 
-Pages rendered by taxonomy templates have `.Kind` set to `taxonomy` and `.Type` set to the taxonomy name.
+{{< list-pages-in-section path=/methods/taxonomy titlePrefix=. >}}
 
-In taxonomy templates you may access `.Site`, `.Page`. `.Section`, and `.File` variables, as well as the following _taxonomy_ variables:
+{{% note %}}
+Within a taxonomy or term template use the [`Data`] method to retrieve information specific to the taxonomy or term.
 
-.Data.Singular
-: The singular name of the taxonomy (e.g., `tags => tag`).
-
-.Data.Plural
-: The plural name of the taxonomy (e.g., `tags => tags`).
-
-.Data.Pages
-: The collection of term pages related to this taxonomy. Aliased by `.Pages`.
-
-.Data.Terms
-: A map of terms and weighted pages related to this taxonomy.
-
-.Data.Terms.Alphabetical
-: A map of terms and weighted pages related to this taxonomy, sorted alphabetically in ascending order. Reverse the sort order with`.Data.Terms.Alphabetical.Reverse`.
-
-.Data.Terms.ByCount
-: A map of terms and weighted pages related to this taxonomy, sorted by count in ascending order. Reverse the sort order with`.Data.Terms.ByCount.Reverse`.
-
-## Term templates
-
-Pages rendered by term templates have `.Kind` set to `term` and `.Type` set to the taxonomy name.
-
-In term templates you may access `.Site`, `.Page`. `.Section`, and `.File` variables, as well as the following _term_ variables:
-
-.Data.Singular
-: The singular name of the taxonomy (e.g., `tags => tag`).
-
-.Data.Plural
-: The plural name of the taxonomy (e.g., `tags => tags`).
-
-.Data.Pages
-: The collection of content pages related to this taxonomy. Aliased by `.Pages`.
-
-.Data.Term
-: The term itself (e.g., `tag-one`).
-
-## Access taxonomy data from any template
-
-Access the entire taxonomy data structure from any template with `site.Taxonomies`. This returns a map of taxonomies, terms, and a collection of weighted content pages related to each term. For example:
-
-```json
-{
-  "categories": {
-    "news": [
-      {
-        "Weight": 0,
-        "Page": {
-          "Title": "Post 1",
-          "Date": "2022-12-18T15:13:35-08:00"
-          ...
-          }
-      },
-      {
-        "Weight": 0,
-        "Page": {
-          "Title": "Post 2",
-          "Date": "2022-12-18T15:13:46-08:00",
-          ...
-        }
-      }
-    ]
-  },
-  "tags": {
-    "international": [
-      {
-        "Weight": 0,
-        "Page": {
-          "Title": "Post 1",
-          "Date": "2021-01-01T00:00:00Z"
-          ... 
-        }
-      }
-    ]
-  }
-}
-```
-
-Access a subset of the taxonomy data structure by chaining one or more identifiers, or by using the [`index`] function with one or more keys. For example, to access the collection of weighted content pages related to the news category, use either of the following:
-
-[`index`]: /functions/collections/indexfunction/
-
-```go-html-template
-{{ $pages := site.Taxonomies.categories.news }}
-{{ $pages := index site.Taxonomies "categories" "news" }}
-```
-
-For example, to render the entire taxonomy data structure as a nested unordered list:
-
-```go-html-template
-
      
-  {{ range $taxonomy, $terms := site.Taxonomies }}
-    
    • 
-      {{ with site.GetPage $taxonomy }}
-        {{ .LinkTitle }}
-      {{ end }}
-      
        
-        {{ range $term, $weightedPages := $terms }}
-        
      • 
-          {{ with site.GetPage (path.Join $taxonomy $term) }}
-            {{ .LinkTitle }}
-          {{ end }}
-        
        • 
-          
-        {{ end }}
-      
      
-    
      • 
-  {{ end }}
-
    
-```
-
-See [Taxonomy Templates] for more examples.
-
-[Taxonomy Templates]: /templates/taxonomy-templates/
+[`Data`]: /methods/page/data
+{{% /note %}}
diff --git a/data/page_filters.yaml b/data/page_filters.yaml
new file mode 100644
index 000000000..b2810d7b4
--- /dev/null
+++ b/data/page_filters.yaml
@@ -0,0 +1,89 @@
+# Do not delete. Required for layouts/shortcodes/list-pages-in-section.html.
+#
+# When calling the list-pages-in-section shortcode, you can specify a page
+# filter, and whether the pages in the filter should be included or excluded
+# from the list.
+#
+# For example:
+#
+# {{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}}
+
+functions_images_no_filters:
+  - /functions/images/filter
+  - /functions/images/config
+methods_site_multilingual:
+  - /methods/site/ismultilingual
+  - /methods/site/language
+  - /methods/site/languageprefix
+  - /methods/site/languages
+methods_site_page_collections:
+  - /methods/site/pages
+  - /methods/site/regularpages
+  - /methods/site/sections
+methods_page_dates:
+  - /methods/page/date
+  - /methods/page/expirydate
+  - /methods/page/lastmod
+  - /methods/page/publishdate
+methods_page_menu:
+  - /methods/page/hasmenucurrent
+  - /methods/page/ismenucurrent
+methods_page_multilinugual:
+  - /methods/page/alltranslations
+  - /methods/page/istranslated
+  - /methods/page/language
+  - /methods/page/translationkey
+  - /methods/page/translations
+methods_page_page_collections:
+  - /methods/page/pages
+  - /methods/page/regularpages
+  - /methods/page/regularpagesrecursive
+  - /methods/page/sections
+methods_page_parameters:
+  - /methods/page/param
+  - /methods/page/params
+methods_page_sections:
+  - /methods/page/ancestors
+  - /methods/page/currentsection
+  - /methods/page/firstsection
+  - /methods/page/insection
+  - /methods/page/isancestor
+  - /methods/page/isdescendant
+  - /methods/page/parent
+  - /methods/page/sections
+  - /methods/page/section
+methods_pages_sort:
+  - /methods/pages/bydate
+  - /methods/pages/byexpirydate
+  - /methods/pages/bylanguage
+  - /methods/pages/bylastmod
+  - /methods/pages/bylength
+  - /methods/pages/bylinktitle
+  - /methods/pages/byparam
+  - /methods/pages/bypublishdate
+  - /methods/pages/bytitle
+  - /methods/pages/byweight
+  - /methods/pages/reverse
+methods_pages_group:
+  - /methods/pages/groupby
+  - /methods/pages/groupbydate
+  - /methods/pages/groupbyexpirydate
+  - /methods/pages/groupbylastmod
+  - /methods/pages/groupbyparam
+  - /methods/pages/groupbyparamdate
+  - /methods/pages/groupbypublishdate
+  - /methods/pages/groupbydate
+  - /methods/pages/groupbydate
+  - /methods/pages/groupbydate
+  - /methods/pages/groupbydate
+  - /methods/pages/groupbydate
+  - /methods/pages/groupbydate
+  - /methods/pages/reverse
+methods_pages_navigation:
+  - /methods/pages/next
+  - /methods/pages/prev
+methods_page_navigation:
+  - /methods/page/next
+  - /methods/page/nextinsection
+  - /methods/page/prev
+  - /methods/page/previnsection
diff --git a/data/titles.toml b/data/titles.toml
deleted file mode 100644
index 2348c8561..000000000
--- a/data/titles.toml
+++ /dev/null
@@ -1,2 +0,0 @@
-[Showcase]
-title = "Site Showcase"
diff --git a/hugo.toml b/hugo.toml
index 3126027a9..9ced49e4c 100644
--- a/hugo.toml
+++ b/hugo.toml
@@ -68,10 +68,6 @@ ID = 'G-MBZGKNMDWC'
   threshold    = 80
   includeNewer = true
   toLower      = false
-  [[related.indices]]
-    toLower = true
-    name   = "relatedFunctions"
-    weight = 60
   [[related.indices]]
     name   = "keywords"
     weight = 60
@@ -87,7 +83,7 @@ ID = 'G-MBZGKNMDWC'
     cardinalityThreshold = 50
 
 # TODO delete when (a) Netlify is building the site with v0.120.0 or later,
-# and (b) the changes fom gohugoioTheme/commit/af97b8e61638ddf043b87590cd567d76045bf9be
+# and (b) the changes from gohugoioTheme/commit/af97b8e61638ddf043b87590cd567d76045bf9be
 # have been pulled into this repo.
 [social]
   twitter = "GoHugoIO"
diff --git a/layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html
new file mode 100644
index 000000000..7b3d58c2d
--- /dev/null
+++ b/layouts/_default/_markup/render-link.html
@@ -0,0 +1,250 @@
+{{- /* Last modified: 2023-09-04T09:23:04-07:00 */}}
+
+{{- /*
+Copyright 2023 Veriphor LLC
+
+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.
+*/}}
+
+{{- /*
+This render hook resolves internal destinations by looking for a matching:
+
+  1. Content page
+  2. Page resource (a file in the current page bundle)
+  3. Section resource (a file in the current section)
+  4. Global resource (a file in the assets directory)
+
+It skips the section resource lookup if the current page is a leaf bundle.
+
+External destinations are not modified.
+
+You must place global resources in the assets directory. If you have placed
+your resources in the static directory, and you are unable or unwilling to move
+them, you must mount the static directory to the assets directory by including
+both of these entries in your site configuration:
+
+  [[module.mounts]]
+  source = 'assets'
+  target = 'assets'
+
+  [[module.mounts]]
+  source = 'static'
+  target = 'assets'
+
+By default, if this render hook is unable to resolve a destination, including a
+fragment if present, it passes the destination through without modification. To
+emit a warning or error, set the error level in your site configuration:
+
+  [params.render_hooks.link]
+  errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
+
+When you set the error level to warning, and you are in a development
+environment, you can visually highlight broken internal links:
+
+  [params.render_hooks.link]
+  errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
+  highlightBroken = true # true or false (default)
+
+This will add a "broken" class to anchor elements with invalid src attributes.
+Add a rule to your CSS targeting the broken links:
+
+  a.broken {
+    background: #ff0;
+    border: 2px solid #f00;
+    padding: 0.1em 0.2em;
+  }
+
+This render hook may be unable to resolve destinations created with the ref and
+relref shortcodes. Unless you set the error level to ignore you should not use
+either of these shortcodes in conjunction with this render hook.
+
+@context {string} Destination The link destination.
+@context {page} Page A reference to the page containing the link.
+@context {string} PlainText The link description as plain text.
+@context {string} Text The link description.
+@context {string} Title The link title.
+
+@returns {template.html}
+*/}}
+
+{{- /* Initialize. */}}
+{{- $renderHookName := "link" }}
+
+{{- /* Verify minimum required version. */}}
+{{- $minHugoVersion := "0.120.0" }}
+{{- if lt hugo.Version $minHugoVersion }}
+  {{- errorf "The %q render hook requires Hugo v%s or later." $renderHookName $minHugoVersion }}
+{{- end }}
+
+{{- /* Error level when unable to resolve destination: ignore, warning, or error. */}}
+{{- $errorLevel := or site.Params.render_hooks.link.errorLevel "ignore" | lower }}
+
+{{- /* If true, adds "broken" class to broken links. Applicable in development environment when errorLevel is warning. */}}
+{{- $highlightBrokenLinks := or site.Params.render_hooks.link.highlightBroken false }}
+
+{{- /* Validate error level. */}}
+{{- if not (in (slice "ignore" "warning" "error") $errorLevel) }}
+  {{- errorf "The %q render hook is misconfigured. The errorLevel %q is invalid. Please check your site configuration." $renderHookName $errorLevel }}
+{{- end }}
+
+{{- /* Determine content path for warning and error messages. */}}
+{{- $contentPath := "" }}
+{{- with .Page.File }}
+  {{- $contentPath = .Path }}
+{{- else }}
+  {{- $contentPath = .Path }}
+{{- end }}
+
+{{- /* Parse destination. */}}
+{{- $u := urls.Parse .Destination }}
+
+{{- /* Set common message. */}}
+{{- $msg := printf "The %q render hook was unable to resolve the destination %q in %s" $renderHookName $u.String $contentPath }}
+
+{{- /* Set attributes for anchor element. */}}
+{{- $attrs := dict "href" $u.String }}
+{{- if $u.IsAbs }}
+  {{- /* Destination is a remote resource. */}}
+  {{- $attrs = merge $attrs (dict "rel" "external") }}
+{{- else }}
+  {{- with $u.Path }}
+    {{- with $p := or ($.Page.GetPage .) ($.Page.GetPage (strings.TrimRight "/" .)) }}
+      {{- /* Destination is a page. */}}
+      {{- $href := .RelPermalink }}
+      {{- with $u.RawQuery }}
+        {{- $href = printf "%s?%s" $href . }}
+      {{- end }}
+      {{- with $u.Fragment }}
+        {{- $ctx := dict
+          "contentPath" $contentPath
+          "errorLevel" $errorLevel
+          "page" $p
+          "parsedURL" $u
+          "renderHookName" $renderHookName
+        }}
+        {{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
+        {{- $href = printf "%s#%s" $href . }}
+      {{- end }}
+      {{- $attrs = dict "href" $href }}
+    {{- else }}
+      {{- with $.Page.Resources.Get $u.Path }}
+        {{- /* Destination is a page resource; drop query and fragment. */}}
+        {{- $attrs = dict "href" .RelPermalink }}
+      {{- else }}
+        {{- with (and (ne $.Page.BundleType "leaf") ($.Page.CurrentSection.Resources.Get $u.Path)) }}
+          {{- /* Destination is a section resource, and current page is not a leaf bundle. */}}
+          {{- $attrs = dict "href" .RelPermalink }}
+        {{- else }}
+          {{- with resources.Get $u.Path }}
+            {{- /* Destination is a global resource; drop query and fragment. */}}
+            {{- $attrs = dict "href" .RelPermalink }}
+          {{- else }}
+            {{- if eq $errorLevel "warning" }}
+              {{- warnf $msg }}
+              {{- if and $highlightBrokenLinks hugo.IsDevelopment }}
+                {{- $attrs = merge $attrs (dict "class" "broken") }}
+              {{- end }}
+            {{- else if eq $errorLevel "error" }}
+              {{- errorf $msg }}
+            {{- end }}
+          {{- end }}
+        {{- end }}
+      {{- end }}
+    {{- end }}
+  {{- else }}
+    {{- with $u.Fragment }}
+      {{- /* Destination is on the same page; prepend relative permalink. */}}
+      {{- $ctx := dict
+        "contentPath" $contentPath
+        "errorLevel" $errorLevel
+        "page" $.Page
+        "parsedURL" $u
+        "renderHookName" $renderHookName
+      }}
+      {{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
+      {{- $attrs = dict "href" (printf "%s#%s" $.Page.RelPermalink .) }}
+    {{- else }}
+      {{- if eq $errorLevel "warning" }}
+        {{- warnf $msg }}
+        {{- if and $highlightBrokenLinks hugo.IsDevelopment }}
+          {{- $attrs = merge $attrs (dict "class" "broken") }}
+        {{- end }}
+      {{- else if eq $errorLevel "error" }}
+        {{- errorf $msg }}
+      {{- end }}
+    {{- end }}
+  {{- end }}
+{{- end }}
+{{- with .Title }}
+  {{- $attrs = merge $attrs (dict "title" .) }}
+{{- end -}}
+
+{{- /* Render anchor element. */ -}}
+{{ .Text | safeHTML }}
+
+{{- define "partials/inline/h-rh-l/validate-fragment.html" }}
+  {{- /*
+  Validates the fragment portion of a link destination.
+
+  @context {string} contentPath The page containing the link.
+  @context {srting} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error.
+  @context {page} page The page corresponding to the link destination
+  @context {struct} parsedURL The link destination parsed by urls.Parse.
+  @context {string} renderHookName The name of the render hook.
+  */}}
+
+  {{- /* Initialize. */}}
+  {{- $contentPath := .contentPath }}
+  {{- $errorLevel := .errorLevel }}
+  {{- $p := .page }}
+  {{- $u := .parsedURL }}
+  {{- $renderHookName := .renderHookName }}
+
+  {{- /* Validate. */}}
+  {{- with $u.Fragment }}
+    {{- if $p.Fragments.Identifiers.Contains . }}
+      {{- if gt ($p.Fragments.Identifiers.Count .) 1 }}
+        {{- $msg := printf "The %q render hook detected duplicate heading IDs %q in %s" $renderHookName . $contentPath }}
+        {{- if eq $errorLevel "warning" }}
+          {{- warnf $msg }}
+        {{- else if eq $errorLevel "error" }}
+          {{- errorf $msg }}
+        {{- end }}
+      {{- end }}
+    {{- else }}
+      {{- /* Determine target path for warning and error message. */}}
+      {{- $targetPath := "" }}
+      {{- with $p.File }}
+        {{- $targetPath = .Path }}
+      {{- else }}
+        {{- $targetPath = .Path }}
+      {{- end }}
+      {{- /* Set common message. */}}
+      {{- $msg := printf "The %q render hook was unable to find heading ID %q in %s. See %s" $renderHookName . $targetPath $contentPath }}
+      {{- if eq $targetPath $contentPath }}
+        {{- $msg = printf "The %q render hook was unable to find heading ID %q in %s" $renderHookName . $targetPath }}
+      {{- end }}
+      {{- /* Throw warning or error. */}}
+      {{- if eq $errorLevel "warning" }}
+        {{- warnf $msg }}
+      {{- else if eq $errorLevel "error" }}
+        {{- errorf $msg }}
+      {{- end }}
+    {{- end }}
+  {{- end }}
+
+{{- end -}}
diff --git a/layouts/_default/page.html b/layouts/_default/page.html
index 2435e3ed7..2b96934ea 100644
--- a/layouts/_default/page.html
+++ b/layouts/_default/page.html
@@ -1,11 +1,22 @@
 
    
-  {{ if .Params.categories }}
-    {{ range .Params.categories }}
-      
-        {{ humanize  . | upper }}
+  {{ if in (slice "functions" "methods") .Type }}
+    {{ with .FirstSection }}
+      
+        {{ humanize .Title | upper }}
       
     {{ end }}
-  {{end}}
+    {{ with .CurrentSection }}
+      
+        {{ humanize .Title | upper }}
+      
+    {{ end }}
+  {{ else }}
+    {{ range .Params.categories }}
+      
+        {{ humanize . | upper }}
+      
+    {{ end }}
+  {{ end }}
   
    
     {{ .Title }}
   
    
@@ -13,7 +24,7 @@