diff options
| author | Bjørn Erik Pedersen <[email protected]> | 2023-12-04 15:14:18 +0100 |
|---|---|---|
| committer | Bjørn Erik Pedersen <[email protected]> | 2023-12-04 15:14:18 +0100 |
| commit | 35dec7c96f7ee3eb17dd444f7067f0c776fb56ae (patch) | |
| tree | f2fa4f4c1a0fe6bfd47cb84982d5f4a73bc306f2 | |
| parent | aaaf1c8df5d6aa061609d20510f7fa6c42e5cc1a (diff) | |
| download | hugo-35dec7c96f7ee3eb17dd444f7067f0c776fb56ae.tar.gz hugo-35dec7c96f7ee3eb17dd444f7067f0c776fb56ae.zip | |
Squashed 'docs/' changes from 4d936aee6..4dd2d6415
4dd2d6415 Fix erroridf example
9ae8e9199 Clarify highlight options
f3943f9c8 Fix typo
b57ea5ac8 Add field to glossary of terms
3191e35b4 Clarify comment in the new-in shortcode
870c8d35c Correct description of Ref and RelRef page methods
c9df50e6e Specify encoding in description of crypto functions
749bb37e2 Add Ref, RelRef, and Site shortcode methods
994d4374b Update fmt functions
740f5ef96 Misc additions
77acdcdb6 Remove rssLimit from root config documentation
df84a1795 Document the openapi3.Unmarshal function
24236f57d Miscellaneous edits and corrections
41b54d421 Hide the "new in" button after some period of time
3c1ebac31 Update Ancestors.md
e699eb313 Add new-in tags to select functions and methods
5c41f0bf8 Clarify time.Format method
f7bd43ae1 Add link to built-in render hook for GoAT diagrams
06f9cd4c9 Document the diagrams.Goat function
5e432e12d Adjust quick reference weights
fc915efd6 Update FAQ
5bccf8b19 Use LinkTitle consistently in examples
36f207f3a Add page collection quick reference
699de883d Inlcude example of newScratch.Values
9bb7f8c78 Include RenderString example for emoji shortcodes
783fdd3ac Fix typo
26d5a4399 Fix typo
c7e86f0cf Fix typo
ad2a82fbd Clarify data type returned by partial and partialCached
1de5a52dd Miscellaneous corrections
3509e1b4d Update configuration-markup.md
8c6a9bf02 Clairfy figure shortcode output
c9d0dc8fb Update Markdownify.md
0c4bc1447 Update theme
0f0ab2ade Add methods deprecated in v0.120.0
e1c6ecd0f Miscellaneous edits
ec53b55b9 netlify: Hugo 0.120.4
23a1f3fd5 templates/internal.md: Correct GoogleAnalytics key name
6dcfa9a82 Update troubleshooting section
0c8857e8f Adjust code and code-toggle shortcodes
8820264d3 Reduce number of site audit warnings
526d06b90 Clarify hint option in image processing spec
310849daa Image Processing: Improve sentence and fix code sample
5bb67bfd4 Revert "Image Processing: Improve sentence and fix code sample" (#2318)
77c926fde Image Processing: Improve sentence and fix code sample
52179fb18 Miscellaneous edits
f4e886715 Revert change to hugo.work
c410fefa8 Update theme
8b72dfedd Rework where function documentation
f35a7126f Minor edits to global page function
903b42ebc Cleanup shortcode calls
c9247e98d Update documentation.md
dff3c4abb Clean up build option descriptions and examples
f46d31308 Use consistent signatures
2af2470b5 Minor correction to resources.GetRemote
45ec53fe0 Remove superfluous shortcode param
2a0544757 Improve deployment documentation
3cf36a7fc Clarify lang keyword
f10d6495d Update front-matter.md
dc94e20be Add Sveltia to CMS list
b15d6d670 Update front-ends.md
bb41588b2 Update FormatCurrency.md
b40fff396 Add showcase for hidden sections without index.html
71316e181 Improve image filter examples
d46f0b1d8 Miscellaneous edits
ad3f9cdb6 Adjust quick reference guides
8657804ba Update theme
d9e981147 Miscellaneous corrections
508666575 Miscellaneous updates
80b2241f9 Miscellaneous updates
723a827fd Namespace functions and methods
40212779a netlify: Hugo 0.120.3
66017c704 Bump GitHub workflows to latest versions
db0f1e682 Update related.md
7e758c23b netlify: Hugo 0.120.2
641ba3976 Update configuration.md
d2a9909d9 Update rss.md
7eb59d7a2 netlify: Hugo 0.120.1
708c351c4 Document debug.Timer
28e2388c2 Add new-in tag to images.Padding
ee24cffb5 Add new-in tags to hugo.IsDevelopment and hugo.IsServer
aa47ca023 netlify: Hugo 0.120.0
9c3e606fc docs: Regen docshelper
159fd971e commands/new: Remove format flag from new content cmd
9f7878092 Merge commit 'aaaf1c8df5d6aa061609d20510f7fa6c42e5cc1a'
65b2dd324 docs: Regenerate docshelper
2be620663 resources/images: Create padding image filter
c777d6c5e Merge commit '3710a5ec7efe6baca6e452f43632c05d22bab3c4'
24f2afeb2 Merge commit 'e509cac533600cf4fa8382c9cdab78ddd82db688'
3f947c19a hugolib: Deprecate .Site.DisqusShortname
6bd1af892 hugolib: Deprecate .Site.GoogleAnalytics
78becc6ee tpl/tplimpl: Deprecate .Site.Social usage with internal templates
e3ec2a4f2 common/hugo: Add hugo.IsServer and hugo.IsDevelopment
git-subtree-dir: docs
git-subtree-split: 4dd2d641531f74025ed9f51ea5a961e936988cfb
813 files changed, 24197 insertions, 8120 deletions
diff --git a/.cspell.json b/.cspell.json index 0958b7645..ae469d646 100644 --- a/.cspell.json +++ b/.cspell.json @@ -1,361 +1,133 @@ { "version": "0.2", + "allowCompoundWords": true, + "files": [ + "**/*.md" + ], + "flagWords": [ + "alot", + "hte", + "reccommend", + "seperate" + ], + "ignorePaths": [ + "**/emojis.md", + "**/commands/*", + "**/showcase/*", + "**/tools/*" + ], + "ignoreRegExpList": [ + "# cspell: ignore fenced code blocks", + "^(\\s*`{3,}).*[\\s\\S]*?^\\1", + "# cspell: ignore words joined with dot", + "\\w+\\.\\w+", + "# cspell: ignore strings within backticks", + "`.+`", + "# cspell: ignore strings within single quotes", + "'.+'", + "# cspell: ignore strings within double quotes", + "\".+\"", + "# cspell: ignore strings within brackets", + "\\[.+\\]", + "# cspell: ignore strings within parentheses", + "\\(.+\\)", + "# cspell: ignore words that begin with a slash", + "/\\w+", + "# cspell: ignore everything within action delimiters", + "\\{\\{.+\\}\\}", + "# cspell: ignore everything after a right arrow", + "\\s+→\\s+.+" + ], + "language": "en", "words": [ - "aaabaab", - "aabb", - "aabba", - "aabbaa", - "aabbaabb", - "aabbaabbab", - "abbaa", - "abourget", - "absurl", - "adoc", - "algolia", - "allowfullscreen", - "ananke", - "anchorize", - "anthonyfok", - "asciidoctor", - "attrlink", - "azblob", - "baseof", - "bbaa", - "bcde", - "bcdef", - "beevelop", - "Bergevin", - "bibtex", - "Bjørn", - "blackfriday", - "blogue", - "bogem", - "Bootcamp", - "brlink", - "Brotli", - "Browsersync", - "canonicalization", - "canonify", - "Catmull", - "Catwoman", - "changefreq", - "Cheatsheet", - "choco", - "chromastyles", - "clockoon", - "Cloudinary", - "CNAME", - "Codecademy's", - "CODEOWNERS", - "Coen", - "Commento", - "Cond", - "contentdir", - "Contentful", - "Copr", - "copyrighthtml", - "corejs", - "countrunes", - "countwords", - "crossreferences", - "daftaupe", - "datatable", - "DATOCMS", - "debugconfig", + "antialiasing", + "codeowners", + "composability", + "configurators", "defang", - "Deindent", - "DELIM", - "dhersam", - "digitalcraftsman", - "Disqus", - "Dmdh", - "doas", - "dokuwiki", - "dpkg", - "DRING", - "Eiqc", + "deindent", + "downscale", + "downscaled", + "downscaling", + "exif", + "geolocalized", + "grayscale", + "marshal", + "marshaling", + "multihost", + "performantly", + "preconfigured", + "prerendering", + "redirection", + "redirections", + "shortcode", + "shortcodes", + "subexpression", + "subexpressions", + "suppressable", + "templating", + "transpile", + "transpiles", + "unmarshal", + "unmarshaling", + "# ----------------------------------------------------------------------", + "# cspell: ignore foreign language words", + "# ----------------------------------------------------------------------", + "bezpieczeństwo", + "dokumentation", + "libros", + "miesiąc", + "miesiąc", + "miesięcy", + "miesięcy", + "misérables", + "projekt", + "régime", + "# ----------------------------------------------------------------------", + "# cspell: ignore proper nouns", + "# ----------------------------------------------------------------------", "Eliott", - "embeddable", - "Emojify", - "Enwrite", - "eopkg", - "eparis", - "errorf", - "erroridf", - "esbuild", - "Evernote", - "Exif", - "exitwp", - "expirydate", - "Feminella", - "firstpost", - "Flickr", - "Formspree", - "fpath", - "Francia", - "freenode", - "frontmatter", - "funcs", - "funcsig", - "Garen", - "Garuda", - "gcloud", - "Getenv", - "getjson", - "getpage", - "Gitee", - "Gmfc", - "Goel", - "Gohugo", - "gohugoio", - "goldenbridge", - "Goldmark", - "gomodules", - "GOPATH", - "govendor", - "Gowans", - "Grayscale", "Gregor", - "Gruber", - "gtag", - "gvfs", - "hidecaption", - "hmac", - "Hokus", - "hola", - "hügó", - "hugodeps", - "hugodoc", - "Hugofy", - "hugolang", - "hugoversion", - "Hyas", - "Hyvor", - "iframes", - "ifttt", - "iife", - "imgproc", - "importr", - "IMWQ", - "indice", - "innershortcode", - "Intelli", - "interdoc", - "IPTC", - "ismenucurrent", - "Isset", - "Isso", "Jaco", - "JIRN", - "johnpatitucci", - "Joomla", - "JRBR", - "jsonify", - "Karmada", - "katex", - "keycdn", - "KEYVALS", - "kubernetes", - "Kubuntu", - "Lanczos", - "langformatnumber", - "lastmod", - "libwebp", - "linktitle", - "Lipi", - "lrwxr", - "Lubuntu", - "maingo", - "markdownified", - "markdownify", - "mathjax", - "mdhender", - "mdshortcode", - "MENUENTRY", - "mercredi", - "Milli", - "Mittwoch", - "mkdir", - "modh", - "monokai", - "Morling", - "mspowerpoint", - "Multihost", - "Muut", - "myclass", - "mydeployment", - "myindex", - "mylayout", - "mylogin", - "mypage", - "mypartials", - "mypost", - "mysite", - "myspa", - "mystyle", - "mytextpartial", - "mytheme", - "NDJSON", - "needsexample", - "Netravali", - "newparam", - "Nichlas", - "Nikhil", - "Nikola", - "Njjy", - "nlist", - "nobr", - "nocopy", - "Norsk", - "nosniff", - "NOSQL", - "notoc", - "novembre", - "numfmt", - "NUMWORKERMULTIPLIER", - "Obhu", - "octohug", - "Octopress", - "oldparam", - "onrender", - "opengraph", - "OWASP", - "Pandoc", - "partialcached", + "Noll", "Pastorius", - "Patitucci", - "PCRE", - "peaceiris", - "Pedersen", - "Pekka", - "permalinkable", - "plainify", - "POSIX", - "postprocess", - "Poupin", - "prerender", - "println", - "Pritchard", - "publishdate", - "Pygments", - "qref", - "querify", - "QVOMC", - "Racic", - "Rclone", - "rdwatters", - "readfile", - "rebinded", - "recommendedby", - "REDIR", - "reftext", - "relatedfuncs", - "relref", - "relurl", - "remarkjs", - "rgba", - "Riku", - "rlimit", - "roboto", - "rssxml", - "rwxrwxrwx", - "RYUGV", - "safehtml", - "safejs", "Samsa", - "schemaorg", - "setx", - "Shekhar", - "Shortcode", - "Shortcodes", - "signup", - "Silvola", - "Sindre", - "sitemapindex", - "sitemapxml", - "slugorfilename", - "Smartcrop", - "Sobre", - "Sprintf", - "Startseite", - "strconv", + "# ----------------------------------------------------------------------", + "# cspell: ignore operating systems and software packages", + "# ----------------------------------------------------------------------", + "asciidoctor", + "brotli", + "corejs", + "disqus", + "doas", + "eopkg", + "gitee", + "goldmark", + "kubuntu", + "lubuntu", + "nosql", + "pandoc", + "pkgin", + "rclone", + "xubuntu", + "# ----------------------------------------------------------------------", + "# cspell: ignore miscellaneous", + "# ----------------------------------------------------------------------", + "dring", + "getenv", + "gohugo", + "inor", + "jdoe", + "milli", + "rgba", + "rsmith", "stringifier", "struct", - "structs", - "subdir", - "svgs", - "symdiff", - "Talkyard", - "taxo", - "taxonomyname", - "tbody", "tdewolff", - "testshortcodes", - "thead", - "Thinkful", - "Tknx", - "TLDR", - "TMPDIR", + "tjones", "toclevels", - "TOCSS", - "todos", - "tojson", - "Tomango", - "topologix", - "Torikian", - "totoml", - "toyaml", - "twitteruser", - "Unmarshal", - "unpublishdate", - "Unsharp", - "urlize", - "urlset", - "utimestamp", - "vendored", - "vimrc", - "wanghc", - "Wappalyzer", - "warnf", - "webp", - "Wercker", - "wibble", - "wordcount", - "workson", - "Wowchemy", - "wpxr", - "Xbaabbab", - "Xubuntu", - "xvzf", - "yoyoyo", - "yunbox", - "Zgotmpl", - "Zorin", - "zzbbaabb", - "مدونتي" - ], - "language": "en,en-US,de,fr", - "allowCompoundWords": true, - "files": [ - "**/*.md" - ], - "ignoreRegExpList": [ - "<!-- prettier-ignore -->\\n(`{3,})\\w*\\n[\\s\\S]+?\\1", - "\\[(\\*{2})?@\\w+?\\1\\]", - "\\[`\\w+`\\]", - "ve{2,}r{2,}y", - "ve+r+y+long\\w*", - "\\/.*?\\/", - "\\_\\w+", - "\\#\\w+" - ], - "ignorePaths": [ - ".cspell.json", - "**/node_modules/**", - "*.min.*", - "**/news/*", - "**/showcase/*" - ], - "useGitignore": true, - "enabled": true + "vals", + "xfeff", + "zgotmplz" + ] } diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index 30f98a000..48555823e 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -15,7 +15,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Initialize CodeQL uses: github/codeql-action/init@v2 diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index 594621604..a650f153c 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -1,9 +1,9 @@ name: "Check spelling" -on: # rebuild any PRs and main branch changes +on: push: + pull_request: branches-ignore: - "dependabot/**" - pull_request: permissions: contents: read @@ -12,10 +12,11 @@ jobs: spellcheck: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 - - uses: streetsidesoftware/cspell-action@v2 + - uses: actions/checkout@v4 + - uses: streetsidesoftware/cspell-action@v4 with: check_dot_files: false + files: content/**/*.md incremental_files_only: true inline: warning strict: false diff --git a/.github/workflows/super-linter.yml b/.github/workflows/super-linter.yml index efd206960..b2a5cb6f1 100644 --- a/.github/workflows/super-linter.yml +++ b/.github/workflows/super-linter.yml @@ -18,10 +18,10 @@ jobs: steps: - name: Checkout Code - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Lint Code Base - uses: github/super-linter/slim@v4 + uses: super-linter/super-linter/slim@v5 env: DEFAULT_BRANCH: master GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 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/>>_ - -### Terms and Conditions for use, reproduction, and distribution - -#### 1. Definitions - -“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. - -“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. - -“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. - -“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. - -“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. - -#### 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. - -#### 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. - -#### 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: - -* **(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 - -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 - -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 - -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 - -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 - -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. - - 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. + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "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. + + "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. + + "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. + + "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. + + "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. + + 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. + + 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. + + 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: + + (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. 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. 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. 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. 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. 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. + + 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. @@ -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/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_print.css b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_print.css new file mode 100644 index 000000000..c0be3af61 --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_print.css @@ -0,0 +1,7 @@ +@media print { + #page-footer, + body > footer, + body > nav { + display: none; + } +} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_right-sidebar.css b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_right-sidebar.css new file mode 100644 index 000000000..757457b2d --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_right-sidebar.css @@ -0,0 +1,11 @@ +#right-sidebar { + scrollbar-width: none; /* hide scrollbar: Firefox */ + -ms-overflow-style: none; /* hide scrollbar: Internet Explorer 10+ */ + height: calc(100vh - 9rem); + overflow-y: auto; +} + +#right-sidebar::-webkit-scrollbar { /* hide scrollbar: WebKit */ + width: 0; + height: 0; +} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_shame.css b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_shame.css new file mode 100644 index 000000000..634adbf06 --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_shame.css @@ -0,0 +1,20 @@ +/* +Make h6 elements behave like dt elements. Initially implemented to support +linkable glossary entries. + +Yes, it's a hack. That's why it's in the shame file. +*/ + +h6 { + margin-top: 0; + margin-bottom: 0; + font-size: 1.125rem; +} + +h6:first-of-type { + margin-top: 3em; +} + +h6 ~ p { + margin: 0.5em 0 2em 0; +} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/main.css b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/main.css index c71f69dd1..fd0f2a503 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/main.css +++ b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/main.css @@ -21,18 +21,18 @@ @import '_no-js'; @import '_social-icons'; @import '_stickyheader'; - +@import '_right-sidebar'; @import '_svg'; @import '_chroma'; @import '_variables'; +@import '_print'; +@import '_shame'; .nested-blockquote blockquote { border-left: 4px solid var(--primary-color); padding-left: 1em; - /*margin: 0;*/ } - .mw-90 { max-width:90%; } diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css b/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css index f5e09aeb1..5e0b0c708 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css +++ b/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css @@ -5174,6 +5174,16 @@ code, .code, pre code, .highlight pre { right:0; } } +#right-sidebar { + scrollbar-width: none; /* hide scrollbar: Firefox */ + -ms-overflow-style: none; /* hide scrollbar: Internet Explorer 10+ */ + height: calc(100vh - 9rem); + overflow-y: auto; +} +#right-sidebar::-webkit-scrollbar { /* hide scrollbar: WebKit */ + width: 0; + height: 0; +} .fill-current { fill: currentColor; } /* Background */ .chroma { background-color: #ffffff } @@ -5305,10 +5315,33 @@ code, .code, pre code, .highlight pre { .chroma .gt { color: #aa0000 } /* TextWhitespace */ .chroma .w { color: #bbbbbb } +@media print { + #page-footer, + body > footer, + body > nav { + display: none; + } +} +/* +Make h6 elements behave like dt elements. Initially implemented to support +linkable glossary entries. + +Yes, it's a hack. That's why it's in the shame file. +*/ +h6 { + margin-top: 0; + margin-bottom: 0; + font-size: 1.125rem; +} +h6:first-of-type { + margin-top: 3em; +} +h6 ~ p { + margin: 0.5em 0 2em 0; +} .nested-blockquote blockquote { border-left: 4px solid #0594CB; padding-left: 1em; - /*margin: 0;*/ } .mw-90 { max-width:90%; diff --git a/layouts/_default/_markup/render-codeblock-mermaid.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-codeblock-mermaid.html index 94ea0cad0..94ea0cad0 100644 --- a/layouts/_default/_markup/render-codeblock-mermaid.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-codeblock-mermaid.html diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-heading.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-heading.html index 6f944aee3..e1b29119f 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-heading.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-heading.html @@ -1,5 +1,5 @@ <h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} -{{- if and (ge .Level 2) (le .Level 4) }}{{" " -}} +{{- if in (slice 2 3 4 6) .Level }}{{" " -}} <a class="header-link" href="#{{ .Anchor | safeURL }}"><svg class="fill-current o-60 hover-accent-color-light" height="22px" viewBox="0 0 24 24" width="22px" xmlns="http://www.w3.org/2000/svg"><path d="M0 0h24v24H0z" fill="none"/><path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"/></svg></a> {{- end -}} </h{{ .Level }}> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-link.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-link.html new file mode 100644 index 000000000..7b3d58c2d --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/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. */ -}} +<a + {{- range $k, $v := $attrs }} + {{- printf " %s=%q" $k $v | safeHTMLAttr }} + {{- end -}} +>{{ .Text | safeHTML }}</a> + +{{- 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/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html index 5767f078b..09cbb2f66 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html @@ -95,7 +95,7 @@ {{- partial "opengraph/twitter_cards.html" . -}} {{ if hugo.IsProduction }} - {{ partial "gtag" . }} + {{ partial "gtag.html" . }} {{ end }} </head> @@ -104,7 +104,7 @@ class="ma0 sans-serif bg-primary-color-light{{ with getenv "HUGO_ENV" }} {{ . }} {{ end }}"> - {{ partial "hooks/after-body-start" . }} + {{ partial "hooks/after-body-start.html" . }} {{ block "nav" . }}{{ partial "site-nav.html" . }}{{ end }} {{ block "header" . }}{{ end }} <main role="main" class="content-with-sidebar min-vh-100 pb7 pb0-ns"> @@ -113,7 +113,7 @@ {{ block "footer" . }}{{ partialCached "site-footer.html" . }}{{ end }} - {{ partial "hooks/before-body-end" . }} + {{ partial "hooks/before-body-end.html" . }} </body> </html> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/page.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/page.html index 898d7c8f4..108d32323 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/page.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/page.html @@ -1,23 +1,30 @@ <header class="flex-none w-100"> - {{ if .Params.categories }} + {{ if in (slice "functions" "methods") .Type }} + {{ with .FirstSection }} + <a href="{{ .RelPermalink }}" class="f6 fw8 mb0 link mid-gray dim mr3"> + {{ humanize .Title | upper }} + </a> + {{ end }} + {{ with .CurrentSection }} + <a href="{{ .RelPermalink }}" class="f6 fw8 mb0 link mid-gray dim mr3"> + {{ humanize .Title | upper }} + </a> + {{ end }} + {{ else }} {{ range .Params.categories }} <a href="{{ "/categories/" | relLangURL }}{{ . | urlize }}" class="f6 fw8 mb0 link mid-gray dim mr3"> - {{ humanize . | upper }} + {{ humanize . | upper }} </a> {{ end }} - {{end}} + {{ end }} <h1 class="lh-title mb3 mv0 pt3 primary-color-dark"> - {{- if eq .Section "functions" -}} - {{ .LinkTitle }} - {{- else -}} - {{ .Title }} - {{- end -}} + {{ .Title }} </h1> </header> <aside class="bt bw1 pt3 mt2 mid-gray b--mid-gray fn w-100"> {{ with .Params.description }} - <div class="f4 fw4 lh-copy"> + <div class="mb4 f4 fw4 lh-copy"> {{ . | markdownify }} </div> {{ end }} @@ -31,7 +38,11 @@ <img src="{{ . }}" alt="Featured Image for {{ $.Title }}" class="mw-100"> {{ end }} -<div class="prose prose-{{ .Type }}" id="prose"> - {{- partial "docs/functions-signature.html" . -}} +<div class="prose" id="prose"> + <div class="mb4"> + {{- partial "docs/functions-signatures.html" . -}} + {{- partial "docs/functions-return-type.html" . -}} + {{- partial "docs/functions-aliases.html" . -}} + </div> {{ .Content }} </div> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/single.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/single.html index 8cd289624..092a69270 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/single.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/single.html @@ -2,26 +2,24 @@ <article class="w-100 ph4 pb5 pb6-ns pt1 pt5-ns"> <div class="flex-l"> - <div class="order-2 w-100 w-20-l ph5-m ph0-l mb4 sticky"> - {{- partial "toc.html" . -}} + <div class="order-0 w-20 dn db-l"> + {{ partial "nav-links-docs.html" . }} </div> - - <div class="order-1 w-60-l mw7 ph0 ph5-ns mid-gray nested-copy-line-height no-underline nested-links nested-img nested-copy-seperator nested-blockquote mt0-ns" style="flex-grow:1;"> - <div class="documentation-copy center measure-wide-l"> - <div id="readout" class="fixed right-0 bottom-0"> - </div> + <div class="order-1 flex-grow-1 ph0 ph5-ns mt0-ns mid-gray nested-copy-line-height no-underline nested-links nested-img nested-copy-seperator nested-blockquote"> + <div style="max-width: 40rem;" class="documentation-copy"> + <div id="readout" class="fixed right-0 bottom-0"></div> {{ .Render "page" }} {{ partial "related.html" . }} </div> </div> - <div class="order-0 w-20 dn db-l"> - {{ partial "nav-links-docs.html" . }} + <div id="right-sidebar" class="order-2 w-20 dn db-l sticky pt2"> + {{ partial "right-sidebar.html" . }} </div> </div> </article> - <div class="w-100 bg-light-gray"> + <div id="page-footer" class="w-100 bg-light-gray"> <div class="mw7 pa4 center nested-lh-copy lh-copy"> {{ partial "docs/page-meta-data.html" . }} {{ partial "page-edit.html" . }} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.html index 93dfdd6c6..3df97ae42 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.html @@ -1,27 +1,27 @@ {{ define "header" }} - {{ partial "hero" . }} - {{ partial "boxes-small-news" . }} + {{ partial "hero.html" . }} + {{ partial "boxes-small-news.html" . }} {{ end }} {{ define "main" }} <section class="w-100 ph4 ph5-ns pv4"> - {{- partial "home-page-sections/features-icons" . -}} + {{- partial "home-page-sections/features-icons.html" . -}} </section> {{ partial "home-page-sections/sponsors.html" (dict "cx" . "gtag" "home" ) }} - {{- partial "home-page-sections/features-single" . -}} + {{- partial "home-page-sections/features-single.html" . -}} - {{- partial "home-page-sections/showcase.html" . -}} + {{- partial "home-page-sections/showcase.html" . -}} <section class="w-100 ph4 ph5-ns pv4 pv6-ns mid-gray bg-white bb bt b--light-gray"> - {{- partial "home-page-sections/installation" . -}} + {{- partial "home-page-sections/installation.html" . -}} </section> <section class="w-100 ph4 ph5-ns pv4 pv6-ns mid-gray bg-accent-color-dark"> - {{- partial "home-page-sections/tweets" . -}} + {{- partial "home-page-sections/tweets.html" . -}} </section> <section class="w-100 ph4 ph5-ns pt4 pb5 mid-gray bg-primary-color-light bb bt b--light-gray "> - {{- partial "home-page-sections/open-source-involvement" . -}} + {{- partial "home-page-sections/open-source-involvement.html" . -}} </section> {{ end }} diff --git a/layouts/index.rss.xml b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.rss.xml index 1d3498a1e..1d3498a1e 100644 --- a/layouts/index.rss.xml +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.rss.xml diff --git a/layouts/maintenance/list.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/maintenance/list.html index f78bbd08f..f78bbd08f 100644 --- a/layouts/maintenance/list.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/maintenance/list.html diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html index eeb8cb2d9..5165c8a13 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html @@ -10,32 +10,61 @@ </div> </article> - <!-- TODO: May be a good idea in this case to add monthly archives --> - <div class="flex flex-wrap"> - {{/* [wip] add archive lists - <div class="w-100 w-20-ns dn"> - <ul> - <li> - <a href="#"> - archive section - </a> - </li> - </ul> - </div> */}} - {{ $interior_classes := $.Site.Params.flex_box_interior_classes }} <section class="flex-ns flex-wrap justify-between w-100 w-80-nsTK v-top"> - {{ $paginator := .Paginate (.Pages | lang.Merge (where .Sites.First.RegularPages "Section" .Section)) -}} - {{ range $paginator.Pages }} - {{ partial "boxes-section-summaries" (dict "context" . "classes" $interior_classes "fullcontent" false) }} + + {{ $news_items := slice }} + + {{/* Get releases from GitHub. */}} + {{ $u := "https://api.github.com/repos/gohugoio/hugo/releases" }} + {{ $releases := partial "inline/get-remote-data.html" $u }} + {{ $releases = where $releases "draft" false }} + {{ $releases = where $releases "prerelease" false }} + {{ range $releases | first 20 }} + {{ $ctx := dict + "Date" (.published_at | time.AsTime) + "Title" (printf "Release %s" .name) + "Permalink" .html_url + "Section" "news" + "Summary" "" + }} + {{ $news_items = $news_items | append $ctx }} + {{ end }} + + {{/* Get content pages from news section. */}} + {{ range .Pages }} + {{ $ctx := dict + "Date" .Date + "Title" .Title + "RelPermalink" .RelPermalink + "Section" "news" + "Summary" .Summary + "Params" (dict "description" .Description) + }} + {{ $news_items = $news_items | append $ctx }} {{ end }} + + {{/* Sort by date (descending) and render. */}} + {{ range sort $news_items "Date" "desc" }} + {{ partial "boxes-section-summaries.html" (dict "context" . "classes" $interior_classes "fullcontent" false) }} + {{ end }} + </section> </div> - <div class="nested-list-reset nested-links"> - {{/* pagination.html: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/template_embedded.go#L117 */}} - {{ template "_internal/pagination.html" . }} - </div> </div> {{ end }} + +{{ define "partials/inline/get-remote-data.html" }} + {{ $u := . }} + {{ $r := "" }} + {{ with $r = resources.GetRemote $u }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ end }} + {{ else }} + {{ errorf "Unable to get remote resource %q" $u }} + {{ end }} + {{ return ($r | transform.Unmarshal) }} +{{ end }} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/single.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/single.html index 200daa70a..eb34bedd7 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/single.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/single.html @@ -34,9 +34,6 @@ Go to <a href="https://github.com/gohugoio/hugo/releases" class="link primary-color dim">Hugo Releases</a> for the release downloads. </p> {{ end }} - <!-- - NOTE: Removed to test builds without it. - partial "components/author-github-data" (dict "context" . "size" "110") --> <div class="nested-links mt4"> {{- partial "previous-next-links-in-section.html" . -}} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/boxes-section-summaries.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/boxes-section-summaries.html index b7e37c47c..b293dc17d 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/boxes-section-summaries.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/boxes-section-summaries.html @@ -1,35 +1,46 @@ <div class="relative {{ .classes }} weight-{{ .context.Weight }}"> - <div class="bg-white mb2 pa3 pa4-l gray"> + + {{ $href := .context.RelPermalink }} {{ if eq .context.Section "news" }} - <date class="f6 db" datetime="{{ .Date.Format "2006-01-02T15:04:05Z07:00" }}"> + {{ $href = .context.Permalink }} + <time class="f6 db" datetime="{{ .context.Date.Format `2006-01-02T15:04:05Z07:00` }}"> {{ .context.Date.Format "January 2, 2006" }} - </date> + </time> {{ end }} <h1 class="near-black f3"> - <a href="{{ .context.RelPermalink }}" class="link primary-color dim"> - {{- if eq .context.Section "functions" -}} - {{ .context.LinkTitle }} - {{- else -}} + <a href="{{ $href }}" class="link primary-color dim"> {{ .context.Title }} - {{- end -}} </a> </h1> - <div class="lh-copy links"> - {{ if .context.Params.description }} + {{ if eq .context.Section "commands" }} + {{ replaceRE `(?s).*?##\s.*?\n\n(.*?)\n.*` "$1" .context.RawContent }} + {{ else }} + + {{ if in (slice "functions" "methods") .context.Type }} + {{ with $signature := index .context.Params.action.signatures 0 }} + {{ if $.context.Params.action.returnType }} + {{ $signature = printf "%s ⟼ %s" $signature $.context.Params.action.returnType }} + {{ end }} + <pre class="f6 mb3 ph3 pv2 bg-light-gray overflow-x-auto"> + {{- $signature -}} + </pre> + {{ end }} + {{ end }} + + {{ if .context.Params.description }} {{ .context.Params.description | markdownify }} {{ else }} {{ .context.Summary }} - {{ end }} - - <a href="{{ .context.RelPermalink }}" class="f6 mt2 db link primary-color dim"> - Read More » - </a> + {{ end }} + {{ end }} + <a href="{{ $href }}" class="f6 mt2 db link primary-color dim"> + Read More » + </a> </div> - </div> </div> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/boxes-small-news.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/boxes-small-news.html index 0b0125740..0d53c5465 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/boxes-small-news.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/boxes-small-news.html @@ -1,18 +1 @@ -<section class="relative w-100 bg-black white"> - <div class="flex flex-wrap w-90-l center center mw9"> - <!-- <a href="/news/" class="link accent-color tr-ns f6 w-100 w-50-m w-10-l bg-animate hover-bg-accent-color hover-white pv3 pv4-l ph3 ph4-l dib"> - Latest News: - </a> --> - {{ range first 4 ( sort (where .Site.RegularPages "Section" "news") "Date" "desc" ) }} - <!-- only show 2 boxes on mobile --> - {{ $.Scratch.Add "i" 1 }}{{ $i := $.Scratch.Get "i" }} - <a href="{{ .RelPermalink }}" class="link lh-copy light-gray f6 w-100 w-50-m w-25-l bg-animate hover-bg-accent-color hover-white pv3 pv4-ns ph3 ph4-ns{{ if ge $i 3 }} dn dib-l{{ else }} dib{{ end }}"> - <span class="f6 gray pb1 db"> - {{ .Date.Format "January 2, 2006" }} - </span> - {{ .Params.description | markdownify | truncate 100 "…"}} - </a> - {{ end }} - - </div> -</section> +{{/* Empty for now. */}} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/docs/functions-aliases.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/docs/functions-aliases.html new file mode 100644 index 000000000..3db9db4dc --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/docs/functions-aliases.html @@ -0,0 +1,12 @@ +{{- with .Params.action.aliases }} + {{- $label := "Alias" }} + {{- if gt (len .) 1 }} + {{- $label = "Aliases" }} + {{- end }} + <p class="fw7 primary-color-dark">{{ $label }}</p> + {{- range . }} + <pre class="f5 ph3 pv2 bg-light-gray" style="border-left:4px solid #0594CB;"> + {{- . -}} + </pre> + {{- end }} +{{- end -}} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/docs/functions-return-type.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/docs/functions-return-type.html new file mode 100644 index 000000000..5b01bb560 --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/docs/functions-return-type.html @@ -0,0 +1,6 @@ +{{- with .Params.action.returnType }} + <p class="fw7 primary-color-dark">Returns</p> + <pre class="f5 ph3 pv2 bg-light-gray" style="border-left:4px solid #0594CB;"> + {{- . -}} + </pre> +{{- end -}} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/docs/functions-signature.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/docs/functions-signature.html deleted file mode 100644 index 090b9243b..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/docs/functions-signature.html +++ /dev/null @@ -1,11 +0,0 @@ -{{ if isset .Params "signature" -}} - {{- with .Params.signature }} - <h2 class="minor mb1 pt4 primary-color-dark">Syntax</h2> - {{- range . }} - <pre class="f5 mb4 ph3 pv2 bg-light-gray" style="border-left:4px solid #0594CB;"> - {{- . -}} - </pre> - {{- end }} - {{- end -}} -{{ end }} -{{/* The inline style overrides `pre` styling defaults */}} diff --git a/layouts/partials/docs/functions-signatures.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/docs/functions-signatures.html index b349739e9..dce160227 100644 --- a/layouts/partials/docs/functions-signatures.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/docs/functions-signatures.html @@ -1,11 +1,11 @@ -{{- with .Params.function.signatures }} - <h2 class="minor mb1 pt4 primary-color-dark">Syntax</h2> +{{- with .Params.action.signatures }} + <p class="fw7 primary-color-dark">Syntax</p> {{- range . }} {{- $signature := . }} {{- if $.Params.function.returnType }} {{- $signature = printf "%s ⟼ %s" . $.Params.function.returnType }} {{- end }} - <pre class="f5 mb4 ph3 pv2 bg-light-gray overflow-x-auto" style="border-left:4px solid #0594CB;"> + <pre class="f5 ph3 pv2 bg-light-gray overflow-x-auto" style="border-left:4px solid #0594CB;"> {{- $signature -}} </pre> {{- end }} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/gtag.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/gtag.html index fe9f4d2aa..7c6a9ade5 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/gtag.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/gtag.html @@ -1,4 +1,4 @@ -{{ with .Site.GoogleAnalytics }} +{{ with site.Config.Services.GoogleAnalytics.ID }} <script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script> <script> window.dataLayer = window.dataLayer || []; diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/tweets.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/tweets.html index 5aebf6737..32eb46ba8 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/tweets.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/tweets.html @@ -6,6 +6,7 @@ <div class="flex-ns flex-wrap justify-between"> + {{ if $.Site.Data.homepagetweets }} {{ range first 4 (sort $.Site.Data.homepagetweets.tweet "date" "desc" ) }} <div class="homepage-tweet relative {{ $interior_classes }} br1 mid-gray pv3 nested-links shadow-5"> <div class="absolute top-0 left-0 ma2 o-10"> @@ -21,5 +22,6 @@ </blockquote> </div> {{ end }} + {{ end }} </div> </div> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/hooks/before-body-end.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/hooks/before-body-end.html index 426abd018..dab653508 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/hooks/before-body-end.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/hooks/before-body-end.html @@ -1 +1,7 @@ -{{/* Deliberately empty */}} +{{ if .Page.Store.Get "hasMermaid" }} + <script type="module" async> + import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9/+esm'; + + mermaid.initialize({ startOnLoad: true }); + </script> +{{ end }} diff --git a/layouts/partials/maintenance-pages-table.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/maintenance-pages-table.html index a2429a335..a2429a335 100644 --- a/layouts/partials/maintenance-pages-table.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/maintenance-pages-table.html diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/nav-top.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/nav-top.html index d8e87eb63..f64111409 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/nav-top.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/nav-top.html @@ -9,8 +9,8 @@ </a> </div> - {{ partial "nav-links" .}} + {{ partial "nav-links.html" .}} <div class="dn-l"> - {{ partial "nav-button-open" .}} + {{ partial "nav-button-open.html" .}} </div> </header> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/opengraph/opengraph.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/opengraph/opengraph.html index c8ff64889..6d195ede6 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/opengraph/opengraph.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/opengraph/opengraph.html @@ -39,4 +39,4 @@ {{ end }}{{ end }} {{- /* Facebook Page Admin ID for Domain Insights */}} -{{- with .Site.Social.facebook_admin }}<meta property="fb:admins" content="{{ . }}" />{{ end }}
\ No newline at end of file +{{- with site.Params.social.facebook_admin }}<meta property="fb:admins" content="{{ . }}" />{{ end }} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/opengraph/twitter_cards.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/opengraph/twitter_cards.html index 9d25d0315..456f87b1c 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/opengraph/twitter_cards.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/opengraph/twitter_cards.html @@ -17,6 +17,6 @@ {{- end }} <meta name="twitter:title" content="{{ .Title }}"/> <meta name="twitter:description" content="{{ with .Description }}{{ . }}{{ else }}{{if .IsPage}}{{ .Summary }}{{ else }}{{ with .Site.Params.description }}{{ . }}{{ end }}{{ end }}{{ end -}}"/> -{{ with .Site.Social.twitter -}} +{{ with site.Params.social.twitter -}} <meta name="twitter:site" content="@{{ . }}"/> -{{ end -}}
\ No newline at end of file +{{ end -}} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/pagelayout.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/pagelayout.html index dd048223e..e6b644b2f 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/pagelayout.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/pagelayout.html @@ -16,13 +16,15 @@ </div> </article> - <!-- TODO: May be a good idea in this case to add monthly archives --> - <div class="flex flex-wrap"> {{ $interior_classes := .context.Site.Params.flex_box_interior_classes }} <section class="flex-ns flex-wrap justify-between w-100"> - {{ range $section_to_display }} - {{ partial "boxes-section-summaries" (dict "context" . "classes" $interior_classes "fullcontent" true) }} + {{ $pages := $section_to_display }} + {{ if in (slice "functions" "methods") $.context.Type }} + {{ $pages = $.context.Pages }} + {{ end }} + {{ range $pages }} + {{ partial "boxes-section-summaries.html" (dict "context" . "classes" $interior_classes "fullcontent" true) }} {{ end }} </section> </div> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/related.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/related.html index fb11699af..ff7435668 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/related.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/related.html @@ -1,9 +1,22 @@ -{{ $related := .Site.RegularPages.Related . | first 5 }} -{{ with $related }} -<h2>See Also</h2> -<ul> - {{ range . }} - <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> - {{ end }} -</ul> -{{ end }}
\ No newline at end of file +{{- $heading := "See also" }} +{{- $related := site.RegularPages.Related . | first 5 }} + +{{- if in (slice "functions" "methods") .Type }} + {{- $related = slice }} + {{- range .Params.action.related }} + {{- with site.GetPage (lower .) }} + {{- $related = $related | append . }} + {{- else }} + {{- errorf "The 'related' partial was unable to get page %s" . }} + {{- end }} + {{- end }} +{{- end }} + +{{- with $related }} + <h2>{{ $heading }}</h2> + <ul> + {{- range . }} + <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + {{- end }} + </ul> +{{- end }} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/right-sidebar.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/right-sidebar.html new file mode 100644 index 000000000..ecdbeb33f --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/right-sidebar.html @@ -0,0 +1,29 @@ +<aside class="right-0 f6 pv4 pv0-ns ph4-l nested-list-reset nested-copy-line-height"> + <div class="nested-links"> + {{- partial "previous-next-links-in-section.html" . }} + </div> + + {{- /* Table of contents is visible if toc = true in front matter. */}} + {{- if .Params.toc }} + <div class="nested-links"> + <p class="f5 fw8 mid-gray mb0">On this page</p> + {{- .TableOfContents }} + </div> + {{- end }} + + {{- /* Section menu for single pages is visible if showSectionMenu = true in top level section page. */}} + {{- if .FirstSection.Params.showSectionMenu }} + {{- with .CurrentSection.RegularPages }} + <p class="mb0"><a class="link f5 fw8 mid-gray" href="{{ $.CurrentSection.RelPermalink }}">In this section</a></p> + <nav> + <ul> + {{- range . }} + <li> + <a style="padding: 2px 5px;" class="dib link hover-bg-black-40 hover-white blue nl1" href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> + </li> + {{- end }} + </ul> + </nav> + {{- end }} + {{- end }} +</aside> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/social-follow.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/social-follow.html index 5c7430759..ce16953c8 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/social-follow.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/social-follow.html @@ -1,6 +1,6 @@ {{/* Disable Twitter for now as we lost access to the account. - with .Site.Social.twitter }} + with site.Params.social.twitter }} <a href="https://twitter.com/intent/follow?screen_name={{ . }}" title="Follow on Twitter" class="link-transition twitter link dib z-999 pt3 pt0-l mr2"> {{ partial "svg/twitter.svg" (dict "size" "32px") }} </a> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/toc.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/toc.html deleted file mode 100644 index 583feec4f..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/toc.html +++ /dev/null @@ -1,13 +0,0 @@ -<!-- TOCs need to be declared explicitly in the front matter of content/*.md --> -<aside class="fixed-lTK mw5-l right-0 f6 bl-l b--moon-gray pv4 pv0-ns ph4-l nested-list-reset nested-links nested-copy-line-height"> - {{ if .Params.toc }} - <p class="b">What's on this Page</p> - {{ .TableOfContents }} - {{ end }} - {{- partial "previous-next-links-in-section.html" . -}} - - {{- if .Params.godocref -}} - <a target="_blank" class="tooltip right godoc-link" data-tooltip="See the related Godocs for {{.Title }}" href="{{.Params.godocref}}" > - </a> - {{- end -}} -</aside> diff --git a/layouts/shortcodes/chroma-lexers.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/chroma-lexers.html index 2e10c3dee..2e10c3dee 100644 --- a/layouts/shortcodes/chroma-lexers.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/chroma-lexers.html diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/code-toggle.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/code-toggle.html index c695a7aae..d1131132d 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/code-toggle.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/code-toggle.html @@ -1,24 +1,101 @@ -{{ $langs := (slice "yaml" "toml" "json") }} -<div class="code relative" {{ with .Get "file" }}id="{{ . | urlize}}"{{ end }}> - <div class="code-nav flex flex-nowrap items-stretch"> - {{- with .Get "file" -}} - <div class="san-serif f6 dib lh-solid pl2 pv2 mr2">{{ . }}.</div> - {{- end -}} - {{ range $langs }} - <button data-toggle-tab="{{ . }}" class="tab-button {{ cond (eq . "yaml") "active" ""}} ba san-serif f6 dib lh-solid ph2 pv2">{{ . }}</button> - {{ end }} - </div> - <div class="tab-content"> - {{ range $langs }} - <div data-pane="{{ . }}" class="code-copy-content nt3 tab-pane {{ cond (eq . "yaml") "active" ""}}"> - {{ highlight ($.Inner | transform.Remarshal . | safeHTML) . ""}} - </div> - {{ if ne ($.Get "copy") "false" }} - <button class="needs-js copy copy-toggle bg-accent-color-dark f6 absolute top-0 right-0 lh-solid hover-bg-primary-color-dark bn white ph3 pv2" title="Copy this code to your clipboard." data-clipboard-action="copy" aria-label="copy button"> - </button> - {{/* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}} - {{end}} - {{ end }} - </div> +{{- /* + Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats. + @param {string} [config] The section of site.Data.docs.config to render. + @param {bool} [copy=false] If true, display a copy to clipboard button. + @param {string} [file] The file name to display above the rendered code. + @param {bool} [fm=false] If true, render the code as front matter. + @param {bool} [skipHeader=false] If false, omit top level key(s) when rendering a section of site.Data.docs.config. + + @returns {template.HTML} +*/}} + +{{- /* Initialize. */}} +{{- $config := "" }} +{{- $dataKey := "" }} +{{- $copy := false }} +{{- $file := "" }} +{{- $fm := false }} +{{- $skipHeader := false }} + +{{- /* Get parameters. */}} +{{- $config = .Get "config" }} +{{- $dataKey = .Get "dataKey" }} +{{- $file = .Get "file" }} +{{- if in (slice "false" false 0) (.Get "copy") }} + {{- $copy = false }} +{{- else if in (slice "true" true 1) (.Get "copy") }} + {{- $copy = true }} +{{- end }} +{{- if in (slice "false" false 0) (.Get "fm") }} + {{- $fm = false }} +{{- else if in (slice "true" true 1) (.Get "fm") }} + {{- $fm = true }} +{{- end }} +{{- if in (slice "false" false 0) (.Get "skipHeader") }} + {{- $skipHeader = false }} +{{- else if in (slice "true" true 1) (.Get "skipHeader") }} + {{- $skipHeader = true }} +{{- end }} + +{{- /* Define constants. */}} +{{- $delimiters := dict "toml" "+++" "yaml" "---" }} +{{- $langs := slice "yaml" "toml" "json" }} +{{- $placeHolder := "#-hugo-placeholder-#" }} + +{{- /* Render. */}} +{{- $code := "" }} +{{- if $config }} + {{- $file = $file | default "hugo" }} + {{- $sections := (split $config ".") }} + {{- $configSection := index $.Site.Data.docs.config $sections }} + {{- $code = dict $sections $configSection }} + {{- if $skipHeader }} + {{- $code = $configSection }} + {{- end }} +{{- else if $dataKey }} + {{- $file = $file | default $dataKey }} + {{- $sections := (split $dataKey ".") }} + {{- $code = index $.Site.Data.docs $sections }} +{{- else }} + {{- $code = $.Inner }} +{{- end }} +<div class="code relative" {{ with $file }}id="{{ . | urlize }}"{{ end }}> + <div class="code-nav flex flex-nowrap items-stretch"> + {{- with $file }} + <div class="san-serif f6 dib lh-solid pl2 pv2 mr2"> + {{ . }}{{ if not $fm }}.{{ end }} + </div> + {{- end }} + {{- range $langs }} + <button + data-toggle-tab="{{ . }}" + class="tab-button {{ cond (eq . "yaml") "active" "" }} ba san-serif f6 dib lh-solid ph2 pv2"> + {{ . }} + </button> + + {{- end }} + </div> + <div class="tab-content"> + {{- range $langs }} + <div + data-pane="{{ . }}" + class="code-copy-content nt3 tab-pane {{ cond (eq . "yaml") "active" "" }}"> + {{- $hCode := $code | transform.Remarshal . }} + {{- if and $fm (in (slice "toml" "yaml") .) }} + {{- $hCode = printf "%s\n%s\n%s" $placeHolder $hCode $placeHolder }} + {{- end }} + {{- $hCode = $hCode | replaceRE `\n+` "\n" }} + {{ highlight $hCode . "" | replaceRE $placeHolder (index $delimiters .) | safeHTML }} + </div> + {{- if $copy }} + <button + class="needs-js copy copy-toggle bg-accent-color-dark f6 absolute top-0 right-0 lh-solid hover-bg-primary-color-dark bn white ph3 pv2" + title="Copy this code to your clipboard." + data-clipboard-action="copy" + aria-label="copy button"></button> + {{- /* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}} + {{- end }} + {{- end }} + </div> </div> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/code.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/code.html index 6df49956a..dd21551cb 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/code.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/code.html @@ -1,15 +1,35 @@ -<div class="code relative bg-primary-color moon-gray" id="{{.Get "file" | urlize}}"> - {{- with .Get "file" -}} - <div class="filename san-serif f6 dib lh-solid pl2 pv2">{{.}}</div> - {{- end -}} - - {{ if ne (.Get "copy") "false" }} - <button class="needs-js copy bg-accent-color-dark f6 absolute top-0 right-0 lh-solid hover-bg-primary-color-dark bn white ph3 pv2" title="Copy this code to your clipboard." data-clipboard-action="copy" aria-label="copy button"> - </button> - {{/* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}} - {{end}} - <div class="code-copy-content nt3" {{with .Get "download"}}id="{{.}}"{{end}}> - {{- .Inner -}} - </div> +{{- /* +Renders syntax highlighted code. +@param {bool} [copy=false] If true, display a copy to clipboard button. +@param {string} [file] The file name to display above the rendered code. +@param {string} [lang] The code language of the inner content. + +@returns {template.HTML} +*/}} + +{{- /* Get parameters. */}} +{{- $copy := false }} +{{- if in (slice "false" false 0) (.Get "copy") }} + {{- $copy = false }} +{{- else if in (slice "true" true 1) (.Get "copy")}} + {{- $copy = true }} +{{- end }} +{{- $file := or (.Get "file") " " }} +{{- $lang := or (.Get "lang") (path.Ext $file | strings.TrimPrefix ".") "text" }} + +{{- /* Use the go-html-template Chroma lexer for HTML. */}} +{{- if eq $lang "html" }} + {{- $lang = "go-html-template" }} +{{- end }} + +{{- /* Render. */}} +<div class="code relative" id="{{ $file | urlize }}"> + <div class="f6 dib lh-solid pl2 pv2">{{ $file | htmlUnescape }}</div> + {{- if $copy }} + <button class="needs-js copy bg-accent-color-dark f6 absolute top-0 right-0 lh-solid hover-bg-primary-color-dark bn white ph3 pv2" title="Copy this code to your clipboard." data-clipboard-action="copy" aria-label="copy button"></button> + {{- end }} + <div class="code-copy-content nt3"> + {{- highlight (trim .Inner "\n\r") $lang }} + </div> </div> diff --git a/layouts/shortcodes/datatable-filtered.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/datatable-filtered.html index ff3f299bd..ff3f299bd 100644 --- a/layouts/shortcodes/datatable-filtered.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/datatable-filtered.html diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/datatable.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/datatable.html index 7ddda86d0..12054f89d 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/datatable.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/datatable.html @@ -1,18 +1,33 @@ -<table class="utils-table"> -<thead> - <tr> - <td class="col-title">Title</td> - <td class="col-author">Author</td> - <td class="col-date">Date</td> - </tr> -</thead> -<tbody> - {{ range $ind, $art := $.Site.Data.articles.article }} - <tr> - <td><a href="{{$art.url}}" target="_blank">{{$art.title | markdownify }}</a></td> - <td>{{ $art.author | markdownify }}</td> - <td>{{ $art.date }}</td> - </tr> - {{ end }} -</tbody> -</table>
\ No newline at end of file +{{ $package := (index .Params 0) }} +{{ $listname := (index .Params 1) }} +{{ $list := (index (index .Site.Data.docs $package) $listname) }} +{{ $fields := after 2 .Params }} + + +<table class="table table-bordered"> + <tr> + {{ range $fields }} + {{ $s := . }} + {{ if eq $s "_key" }} + {{ $s = "Type" }} + {{ end }} + <th>{{ $s }}</th> + {{ end }} + </tr> + {{ range $k1, $v1 := $list }} + <tr> + {{ range $k2, $v2 := . }} + {{ $.Scratch.Set $k2 $v2 }} + {{ end }} + {{ range $fields }} + {{ $s := "" }} + {{ if eq . "_key" }} + {{ $s = $k1 }} + {{ else }} + {{ $s = $.Scratch.Get . }} + {{ end }} + <td>{{ $s }}</td> + {{ end }} + </tr> + {{ end }} +</table> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/deprecated-in.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/deprecated-in.html new file mode 100644 index 000000000..cab85541d --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/deprecated-in.html @@ -0,0 +1,14 @@ +{{ $_hugo_config := `{ "version": 1 }` }} + +{{ with .Get 0 }} + {{ $version := printf "v%v" (strings.TrimLeft "vV" .) }} + {{ $href := printf "https://github.com/gohugoio/hugo/releases/tag/%s" $version }} + <aside> + <div class="admonition-content bl bw2 b--dark-red" > + <p>Deprecated in <a href="{{ $href }}">{{ $version }}</a></p> + {{ $.Inner }} + </div> + </aside> +{{ else }} + {{ errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }} +{{ end }} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/directoryindex.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/directoryindex.html deleted file mode 100644 index 37e7d3ad1..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/directoryindex.html +++ /dev/null @@ -1,13 +0,0 @@ -{{- $pathURL := .Get "pathURL" -}} -{{- $path := .Get "path" -}} -{{- $files := readDir $path -}} -<table> - <th>Size in bytes</th> - <th>Name</th> -{{- range $files }} - <tr> - <td>{{ .Size }}</td> - <td><a href="{{ $pathURL }}{{ .Name | relURL }}" target="_blank"> {{ .Name }}</a></td> - </tr> -{{- end }} -</table> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/docfile.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/docfile.html deleted file mode 100644 index 2f982aae8..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/docfile.html +++ /dev/null @@ -1,11 +0,0 @@ -{{ $file := .Get 0}} -{{ $filepath := $file }} -{{ $syntax := index (split $file ".") 1 }} -{{ $syntaxoverride := eq (len .Params) 2 }} -<div class="code-copy" id="{{$file | urlize}}"> - <div class="code-copy-header"><div class="action-buttons"></div><span title="" class="filename">{{$filepath}}</span><i class="icon-{{$syntax}} input"></i></div> - <button class="copy-button" title="Copy to clipboard" data-clipboard-snippet> - <div class="copy-text"><i class="icon-clipboard"></i> COPY</div> - </button> - <pre><code class="language-{{if $syntaxoverride}}{{.Get 1}}{{else}}{{$syntax}}{{end}}">{{- readFile $file -}}</code></pre> -</div> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/exfile.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/exfile.html deleted file mode 100644 index 226782957..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/exfile.html +++ /dev/null @@ -1,12 +0,0 @@ -{{ $file := .Get 0}} -{{ $filepath := replace $file "static/" ""}} -{{ $syntax := index (split $file ".") 1 }} -{{ $syntaxoverride := eq (len .Params) 2 }} -<div class="code-copy" id="{{$file | urlize}}"> - <div class="code-copy-header examplesite"><div class="action-buttons"></div><span class="filename"><i class="icon-website"></i>{{$filepath}}</span><i class="icon-{{$syntax}} input"></i></div> - <button class="copy-button" title="Copy to clipboard" data-clipboard-snippet> - <div class="copy-text"><i class="icon-clipboard"></i> COPY</div> - </button> - <pre><code class="language-{{if $syntaxoverride}}{{.Get 1}}{{else}}{{$syntax}}{{end}}">{{- readFile $file -}}</code></pre> - <a role="button" target="_blank" href="{{$.Site.Params.ghdocsrepo}}{{$file}}" title="See {{$filepath}} source on GitHub" class="tooltip see-on-github" data-tooltip="See {{$filepath}} source on GitHub">Source<i class="icon-github"></i></a> -</div> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/exfm.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/exfm.html deleted file mode 100644 index c0429bbe1..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/exfm.html +++ /dev/null @@ -1,13 +0,0 @@ -<!-- Similar to exfile.html but *only* pulls the front matter from the example/content/*md --> -{{ $file := .Get 0}} -{{ $filepath := replace $file "static/" ""}} -{{ $syntax := index (split $file ".") 1 }} -{{ $syntaxoverride := eq (len .Params) 2 }} -<div class="code-copy" id="{{$file | urlize}}"> - <div class="code-copy-header examplesite"><div class="action-buttons"></div><span title="" class="filename">{{$filepath}}</span><i class="icon-{{$syntax}} input"></i></div> - <button class="copy-button" title="Copy to clipboard" data-clipboard-snippet> - <div class="copy-text"><i class="icon-clipboard"></i> COPY</div> - </button> - <pre><code class="language-{{if $syntaxoverride}}{{.Get 1}}{{else}}{{$syntax}}{{end}}">{{- readFile $file -}}</code></pre> - <a role="button" target="_blank" href="{{$.Site.Params.ghdocsrepo}}{{$file}}" title="See {{$filepath}} on GitHub" class="see-on-github">Source<i class="icon-github"></i></a> -</div>
\ No newline at end of file diff --git a/layouts/shortcodes/funcsig.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/funcsig.html index 77b0990a5..4e96504ab 100644 --- a/layouts/shortcodes/funcsig.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/funcsig.html @@ -1,4 +1,4 @@ <h4 class="minor mb1 pt2 primary-color-dark">Syntax</h4> <pre class="f5 mb4 ph3 pv2 bg-light-gray overflow-x-auto" style="border-left:4px solid #0594CB;"> - {{- .Inner -}} + {{- .Inner -}} </pre> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gh.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gh.html deleted file mode 100644 index e027dc0f0..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gh.html +++ /dev/null @@ -1,9 +0,0 @@ -{{ range .Params }} - {{ if eq (substr . 0 1) "@" }} - <a href="//github.com/{{ substr . 1 }}">{{ . }}</a> - {{ else if eq (substr . 0 2) "0x" }} - <a href="//github.com/gohugoio/hugo/commit/{{ substr . 2 }}">{{ substr . 2 6 }}</a> - {{ else }} - <a href="//github.com/gohugoio/hugo/issues/{{ . }}">#{{ . }}</a> - {{ end }} -{{ end }}
\ No newline at end of file diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/ghrepo.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/ghrepo.html deleted file mode 100644 index e9df40d6a..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/ghrepo.html +++ /dev/null @@ -1 +0,0 @@ -<a href="{{$.Site.Params.ghrepo}}" target="_blank">GitHub repository</a>
\ No newline at end of file diff --git a/layouts/shortcodes/gomodules-info.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html index b56758ac3..b56758ac3 100644 --- a/layouts/shortcodes/gomodules-info.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html new file mode 100644 index 000000000..ea5b6de1d --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html @@ -0,0 +1,374 @@ +{{- /* +Renders the given image using the given filter, if any. + +@param {string} src The path to the image which must be a remote, page, or global resource. +@param {string} [filter] The filter to apply to the image (case-insensitive). +@param {string} [filterArgs] A comma-delimited list of arguments to pass to the filter. +@param {bool} [example=false] If true, renders a before/after example. +@param {int} [exampleWidth=384] Image width, in pixels, when rendering a before/after example. + +@returns {template.HTML} + +@examples + + {{< img src="zion-national-park.jpg" >}} + + {{< img src="zion-national-park.jpg" alt="Zion National Park" >}} + + {{< img + src="zion-national-park.jpg" + alt="Zion National Park" + filter="grayscale" + >}} + + {{< img + src="zion-national-park.jpg" + alt="Zion National Park" + filter="process" + filterArgs="resize 400x webp" + >}} + + {{< img + src="zion-national-park.jpg" + alt="Zion National Park" + filter="colorize" + filterArgs="180,50,20" + >}} + + {{< img + src="zion-national-park.jpg" + alt="Zion National Park" + filter="grayscale" + example=true + >}} + + {{< img + src="zion-national-park.jpg" + alt="Zion National Park" + filter="grayscale" + example=true + exampleWidth=400 + >}} + + When using the text filter, provide the arguments in this order: + + 0. The text + 1. The horizontal offset, in pixels, relative to the left of the image (default 20) + 2. The vertical offset, in pixels, relative to the top of the image (default 20) + 3. The font size in pixels (default 64) + 4. The line height (default 1.2) + 5. The font color (default #ffffff) + + {{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Text" + filterArgs="Zion National Park,25,250,56" + example=true + >}} + + When using the padding filter, provide all arguments in this order: + + 0. Padding top + 1. Padding right + 2. Padding bottom + 3. Padding right + 4. Canvas color + + {{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Padding" + filterArgs="20,50,20,50,#0705" + example=true + >}} + +*/}} + +{{- /* Initialize. */}} +{{- $alt := "" }} +{{- $src := "" }} +{{- $filter := "" }} +{{- $filterArgs := slice }} +{{- $example := false }} +{{- $exampleWidth := 384 }} + +{{- /* Default values to use with the text filter. */}} +{{ $textFilterOpts := dict + "xOffset" 20 + "yOffset" 20 + "fontSize" 64 + "lineHeight" 1.2 + "fontColor" "#ffffff" + "fontPath" "https://github.com/google/fonts/raw/main/apache/roboto/static/Roboto-Regular.ttf" +}} + +{{- /* Get and validate parameters. */}} +{{- with .Get "alt" }} + {{- $alt = .}} +{{- end }} + +{{- with .Get "src" }} + {{- $src = . }} +{{- else }} + {{- errorf "The %q shortcode requires a file parameter. See %s" .Name .Position }} +{{- end }} + +{{- with .Get "filter" }} + {{- $filter = . | lower }} +{{- end }} + +{{- $validFilters := slice + "brightness" "colorbalance" "colorize" "contrast" "gamma" "gaussianblur" + "grayscale" "hue" "invert" "none" "opacity" "overlay" "padding" "pixelate" + "process" "saturation" "sepia" "sigmoid" "text" "unsharpmask" +}} + +{{- with $filter }} + {{- if not (in $validFilters .) }} + {{- errorf "The filter passed to the %q shortcode is invalid. The filter must be one of %s. See %s" $.Name (delimit $validFilters ", " ", or ") $.Position }} + {{- end }} +{{- end }} + +{{- with .Get "filterArgs" }} + {{- $filterArgs = split . "," }} + {{- $filterArgs = apply $filterArgs "trim" "." " " }} +{{- end }} + +{{- if in (slice "false" false 0) (.Get "example") }} + {{- $example = false }} +{{- else if in (slice "true" true 1) (.Get "example")}} + {{- $example = true }} +{{- end }} + +{{- with .Get "exampleWidth" }} + {{- $exampleWidth = . | int }} +{{- end }} + +{{- /* Get image. */}} +{{- $ctx := dict "page" .Page "src" $src "name" .Name "position" .Position }} +{{- $i := partial "inline/get-resource.html" $ctx }} + +{{- /* Resize if rendering before/after examples. */}} +{{- if $example }} + {{- $i = $i.Resize (printf "%dx" $exampleWidth) }} +{{- end }} + +{{- /* Create filter. */}} +{{- $f := "" }} +{{- $ctx := dict "filter" $filter "args" $filterArgs "name" .Name "position" .Position }} +{{- if eq $filter "brightness" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" -100 "max" 100) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.Brightness (index $filterArgs 0) }} +{{- else if eq $filter "colorbalance" }} + {{- $ctx = merge $ctx (dict "argsRequired" 3) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "percentage red" "argValue" (index $filterArgs 0) "min" -100 "max" 500) }} + {{- template "validate-arg-value" $ctx }} + {{- $ctx = merge $ctx (dict "argName" "percentage green" "argValue" (index $filterArgs 1) "min" -100 "max" 500) }} + {{- template "validate-arg-value" $ctx }} + {{- $ctx = merge $ctx (dict "argName" "percentage blue" "argValue" (index $filterArgs 2) "min" -100 "max" 500) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.ColorBalance (index $filterArgs 0) (index $filterArgs 1) (index $filterArgs 2) }} +{{- else if eq $filter "colorize" }} + {{- $ctx = merge $ctx (dict "argsRequired" 3) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "hue" "argValue" (index $filterArgs 0) "min" 0 "max" 360) }} + {{- template "validate-arg-value" $ctx }} + {{- $ctx = merge $ctx (dict "argName" "saturation" "argValue" (index $filterArgs 1) "min" 0 "max" 100) }} + {{- template "validate-arg-value" $ctx }} + {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 2) "min" 0 "max" 100) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.Colorize (index $filterArgs 0) (index $filterArgs 1) (index $filterArgs 2) }} +{{- else if eq $filter "contrast" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" -100 "max" 100) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.Contrast (index $filterArgs 0) }} +{{- else if eq $filter "gamma" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "gamma" "argValue" (index $filterArgs 0) "min" 0 "max" 100) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.Gamma (index $filterArgs 0) }} +{{- else if eq $filter "gaussianblur" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "sigma" "argValue" (index $filterArgs 0) "min" 0 "max" 1000) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.GaussianBlur (index $filterArgs 0) }} +{{- else if eq $filter "grayscale" }} + {{- $ctx = merge $ctx (dict "argsRequired" 0) }} + {{- template "validate-arg-count" $ctx }} + {{- $f = images.Grayscale }} +{{- else if eq $filter "hue" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "shift" "argValue" (index $filterArgs 0) "min" -180 "max" 180) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.Hue (index $filterArgs 0) }} +{{- else if eq $filter "invert" }} + {{- $ctx = merge $ctx (dict "argsRequired" 0) }} + {{- template "validate-arg-count" $ctx }} + {{- $f = images.Invert }} +{{- else if eq $filter "opacity" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "opacity" "argValue" (index $filterArgs 0) "min" 0 "max" 1) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.Opacity (index $filterArgs 0) }} +{{- else if eq $filter "overlay" }} + {{- $ctx = merge $ctx (dict "argsRequired" 3) }} + {{- template "validate-arg-count" $ctx }} + {{- $ctx := dict "src" (index $filterArgs 0) "name" .Name "position" .Position }} + {{- $overlayImg := partial "inline/get-resource.html" $ctx }} + {{- $f = images.Overlay $overlayImg (index $filterArgs 1 | float ) (index $filterArgs 2 | float) }} +{{- else if eq $filter "padding" }} + {{- $ctx = merge $ctx (dict "argsRequired" 5) }} + {{- template "validate-arg-count" $ctx }} + {{- $f = images.Padding + (index $filterArgs 0 | int) + (index $filterArgs 1 | int) + (index $filterArgs 2 | int) + (index $filterArgs 3 | int) + (index $filterArgs 4) + }} +{{- else if eq $filter "pixelate" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "size" "argValue" (index $filterArgs 0) "min" 0 "max" 1000) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.Pixelate (index $filterArgs 0) }} +{{- else if eq $filter "process" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $f = images.Process (index $filterArgs 0) }} +{{- else if eq $filter "saturation" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" -100 "max" 500) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.Saturation (index $filterArgs 0) }} +{{- else if eq $filter "sepia" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" 0 "max" 100) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.Sepia (index $filterArgs 0) }} +{{- else if eq $filter "sigmoid" }} + {{- $ctx = merge $ctx (dict "argsRequired" 2) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "midpoint" "argValue" (index $filterArgs 0) "min" 0 "max" 1) }} + {{- template "validate-arg-value" $ctx }} + {{- $ctx = merge $ctx (dict "argName" "factor" "argValue" (index $filterArgs 1) "min" -10 "max" 10) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.Sigmoid (index $filterArgs 0) (index $filterArgs 1) }} +{{- else if eq $filter "text" }} + {{- $ctx = merge $ctx (dict "argsRequired" 1) }} + {{- template "validate-arg-count" $ctx }} + {{- $ctx := dict "src" $textFilterOpts.fontPath "name" .Name "position" .Position }} + {{- $font := or (partial "inline/get-resource.html" $ctx) }} + {{- $fontSize := or (index $filterArgs 3 | int) $textFilterOpts.fontSize }} + {{- $lineHeight := math.Max (or (index $filterArgs 4 | float) $textFilterOpts.lineHeight) 1 }} + {{- $opts := dict + "x" (or (index $filterArgs 1 | int) $textFilterOpts.xOffset) + "y" (or (index $filterArgs 2 | int) $textFilterOpts.yOffset) + "size" $fontSize + "linespacing" (mul (sub $lineHeight 1) $fontSize) + "color" (or (index $filterArgs 5) $textFilterOpts.fontColor) + "font" $font + }} + {{- $f = images.Text (index $filterArgs 0) $opts }} +{{- else if eq $filter "unsharpmask" }} + {{- $ctx = merge $ctx (dict "argsRequired" 3) }} + {{- template "validate-arg-count" $ctx }} + {{- $filterArgs = apply $filterArgs "float" "." }} + {{- $ctx = merge $ctx (dict "argName" "sigma" "argValue" (index $filterArgs 0) "min" 0 "max" 500) }} + {{- template "validate-arg-value" $ctx }} + {{- $ctx = merge $ctx (dict "argName" "amount" "argValue" (index $filterArgs 1) "min" 0 "max" 100) }} + {{- template "validate-arg-value" $ctx }} + {{- $ctx = merge $ctx (dict "argName" "threshold" "argValue" (index $filterArgs 2) "min" 0 "max" 1) }} + {{- template "validate-arg-value" $ctx }} + {{- $f = images.UnsharpMask (index $filterArgs 0) (index $filterArgs 1) (index $filterArgs 2) }} +{{- end }} + +{{- /* Apply filter. */}} +{{- $fi := $i }} +{{- with $f }} + {{- $fi = $i.Filter . }} +{{- end }} + +{{- /* Render. */}} +{{- if $example }} + <p>Original</p> + <img class='di ba b--black-20' style="width: initial;" src="{{ $i.RelPermalink }}" alt="{{ $alt }}"> + <p>Processed</p> + <img class='di ba b--black-20' style="width: initial;" src="{{ $fi.RelPermalink }}" alt="{{ $alt }}"> +{{- else -}} + <img class='di' style="width: initial;" src="{{ $fi.RelPermalink }}" alt="{{ $alt }}"> +{{- end }} + +{{- define "validate-arg-count" }} + {{- $msg := "When using the %q filter, the %q shortcode requires an args parameter with %d %s. See %s" }} + {{- if lt (len .args) .argsRequired }} + {{- $text := "values" }} + {{- if eq 1 .argsRequired }} + {{- $text = "value" }} + {{- end }} + {{- errorf $msg .filter .name .argsRequired $text .position }} + {{- end }} +{{- end }} + +{{- define "validate-arg-value" }} + {{- $msg := "The %q argument passed to the %q shortcode is invalid. Expected a value in the range [%v,%v], but received %v. See %s" }} + {{- if or (lt .argValue .min) (gt .argValue .max) }} + {{- errorf $msg .argName .name .min .max .argValue .position }} + {{- end }} +{{- end }} + +{{- define "partials/inline/get-resource.html" }} + {{- $r := "" }} + {{- $u := urls.Parse .src }} + {{- $msg := "The %q shortcode was unable to resolve %s. See %s" }} + {{- if $u.IsAbs }} + {{- with resources.GetRemote $u.String }} + {{- with .Err }} + {{- errorf "%s" }} + {{- else }} + {{- /* This is a remote resource. */}} + {{- $r = . }} + {{- end }} + {{- else }} + {{- errorf $msg $.name $u.String $.position }} + {{- end }} + {{- else }} + {{- with .page.Resources.Get (strings.TrimPrefix "./" $u.Path) }} + {{- /* This is a page resource. */}} + {{- $r = . }} + {{- else }} + {{- with resources.Get $u.Path }} + {{- /* This is a global resource. */}} + {{- $r = . }} + {{- else }} + {{- errorf $msg $.name $u.Path $.position }} + {{- end }} + {{- end }} + {{- end }} + {{- return $r}} +{{- end -}} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/imgproc.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/imgproc.html new file mode 100644 index 000000000..c09133ba8 --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/imgproc.html @@ -0,0 +1,37 @@ +{{- /* +Renders the given image using the given process specification. + +@param {string} (positional parameter 0) The path to the image, relative to the current page. The image must be a page resource. +@param {string}} (positional parameter 1) The image processing specification. + +@returns template.HTML + +@example {{< imgproc "sunset.jpg" "resize 300x" />}} +*/}} + +{{- with $.Get 0 }} + {{- with $i := $.Page.Resources.Get . }} + {{- with $spec := $.Get 1 }} + {{- with $i.Process . }} + <figure style="padding: 0.25rem; margin: 2rem 0; background-color: #cccc"> + <img style="max-width: 100%; width: auto; height: auto;" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + <figcaption> + <small> + {{- with $.Inner }} + {{ . }} + {{- else }} + {{ $spec }} + {{- end }} + </small> + </figcaption> + </figure> + {{- end }} + {{- else }} + {{- errorf "The %q shortcode requires a positional parameter (1) containing the image processing specification. See %s" $.Name $.Position }} + {{- end }} + {{- else }} + {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }} + {{- end }} +{{- else }} + {{- errorf "The %q shortcode requires a positional parameter (0) indicating the image path, relative to the current page. See %s" $.Name $.Position }} +{{- end }} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/include.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/include.html new file mode 100644 index 000000000..a13dd756a --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/include.html @@ -0,0 +1,20 @@ +{{- /* +Renders the page using the RenderShortcode method on the Page object. + +You must call this shortcode using the {{% %}} notation. + +@param {string} (postional parameter 0) The path to the page, relative to the content directory. +@returns template.HTML + +@example {{% include "functions/_common/glob-patterns" %}} +*/}} + +{{- with .Get 0 }} + {{- with site.GetPage . }} + {{- .RenderShortcodes }} + {{- else }} + {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }} + {{- end }} +{{- else }} + {{- errorf "The %q shortcode requires a positional parameter indicating the path of the file to include. See %s" .Name .Position }} +{{- end }} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/list-pages-in-section.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/list-pages-in-section.html new file mode 100644 index 000000000..07a41d613 --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/list-pages-in-section.html @@ -0,0 +1,96 @@ +{{- /* +Renders a desciption list of the pages in the given section. + +Render a subset of the pages in the section by specifying a predefined filter, +and whether to include those pages. + +Filters are defined in the data directory, in the file named page_filters. Each +filter is an array of paths to a file, relative to the root of the content +directory. Hugo will throw an error if the specified filter does not exist, or +if any of the pages in the filter do not exist. + +The definition term elements (dt) have an id attribute derived from the title +of the page. This is probably unique, because pages of the same title in the +same section is unlikely. + +If you render a complete list on a page, then call the shortcode again to +render a subset, you will generate duplicate element ids. In this case, set +omitElementIDs to true for the subset. + +@param {string} path The path to the section. +@param {string} [filter=""] The name of filter list. +@param {string} [filterType=""] The type of filter, either include or exclude. +@param {string} [omitElementIDs=false] Whether to omit dt element ids. +@param {string} [titlePrefix=""] The string to prepend to the link title. + +@returns template.HTML + +@example {{< list-pages-in-section path=/methods/resources >}} +@example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude >}} +@example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude titlePrefix=foo >}} +@example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude titlePrefix=foo omitElementIDs=true >}} +*/}} + +{{- /* Initialize. */}} +{{- $filter := or "" (.Get "filter" | lower)}} +{{- $filterType := or (.Get "filterType") "none" | lower }} +{{- $filteredPages := slice }} +{{- $titlePrefix := or (.Get "titlePrefix") "" }} +{{- $omitElementIDs := false }} + +{{- /* Get boolean parameters. */}} +{{- if in (slice "false" false 0) (.Get "omitElementIDs") }} + {{- $omitElementIDs = false }} +{{- else if in (slice "true" true 1) (.Get "omitElementIDs")}} + {{- $omitElementIDs = true }} +{{- end }} + +{{- /* Build slice of filtered pages. */}} +{{- with $filter }} + {{- with index site.Data.page_filters . }} + {{- range . }} + {{- with site.GetPage . }} + {{- $filteredPages = $filteredPages | append . }} + {{- else }} + {{- errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }} + {{- end }} + {{- end }} + {{- else }} + {{- errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }} + {{- end }} +{{- end }} + +{{- /* Render */}} +{{- with $sectionPath := .Get "path" }} + {{- with site.GetPage . }} + {{- with .RegularPages }} + <dl> + {{- range $page := .ByTitle }} + {{- if or + (and (eq $filterType "include") (in $filteredPages $page)) + (and (eq $filterType "exclude") (not (in $filteredPages $page))) + (eq $filterType "none") + }} + {{- $linkTitle := .LinkTitle }} + {{- with $titlePrefix }} + {{- $linkTitle = printf "%s%s" . $linkTitle }} + {{- end }} + {{- $idAttribute := "" }} + {{- if not $omitElementIDs }} + {{- $id := path.Join .File.Dir .File.ContentBaseName | replaceRE `[\|/]` ":" | lower }} + {{- $idAttribute = printf " id=%q" $id }} + {{- end }} + <dt {{- $idAttribute | safeHTMLAttr }}><a href="{{ $page.RelPermalink }}">{{ $linkTitle }}</a></dt> + <dd>{{- $page.Description | $page.RenderString }}</dd> + {{- end }} + {{- end }} + </dl> + {{- else }} + {{- warnf "The %q shortcode found no pages in the %q section. See %s" $.Name $sectionPath $.Position }} + {{- end }} + {{- else }} + {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name $sectionPath $.Position }} + {{- end }} +{{- else }} + {{- errorf "The %q shortcode requires a 'path' parameter indicating the path to the section. See %s" $.Name $.Position }} +{{- end }} diff --git a/layouts/shortcodes/module-mounts-note.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/module-mounts-note.html index e8b2a7a7e..e8b2a7a7e 100644 --- a/layouts/shortcodes/module-mounts-note.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/module-mounts-note.html diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html new file mode 100644 index 000000000..9236cf2bc --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html @@ -0,0 +1,13 @@ +{{ $version := .Get 0 }} +{{ if not $version }} + {{ errorf "Missing version in new-in shortcode " }} +{{ end }} +{{ $version = $version | strings.TrimPrefix "v" }} +<button + class="bg-white hover:bg-gray-100 text-gray-800 font-semibold py-2 mr2 px-4 border border-gray-400 rounded shadow"> + <a + href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}" + target="_blank" + >New in v{{ $version }}</a + > +</button> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/nohighlight.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/nohighlight.html deleted file mode 100644 index 0f254b4ca..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/nohighlight.html +++ /dev/null @@ -1 +0,0 @@ -<pre><code class="nohighlight">{{ .Inner }}</code></pre> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/note.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/note.html index 24d2cd0b2..99818114e 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/note.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/note.html @@ -1,9 +1,7 @@ {{ $_hugo_config := `{ "version": 1 }` }} -<aside class="admonition note"> - <div class="note-icon"> - {{partial "svg/exclamation.svg" (dict "size" "20px" ) }} - </div> - <!-- <h2 id="{{if .Get 0}}{{.Get 0 | urlize}}{{else}}note{{end}}">{{if .Get 0}}{{.Get 0 | markdownify}}{{else}}Note{{end}}</h2> --> - <!-- <h3>Note</h3> --> - <div class="admonition-content">{{- .Inner -}}</div> + +<aside> + <div class="admonition-content bl bw2 b--blue" > + {{ .Inner }} + </div> </aside> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/output.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/output.html deleted file mode 100644 index df1a8ae89..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/output.html +++ /dev/null @@ -1,11 +0,0 @@ -{{$file := .Get "file"}} -{{$icon := index (split $file ".") 1 }} -<div class="code" id="{{$file | urlize}}"> - <div class="filename" title="{{$file}}">{{$file}}</div> -<!-- <div class="code-icon"> - <i class="icon-{{$icon}}"></i> - </div> --> - <div class="code-copy-content output-content"> - {{- .Inner -}} - </div> -</div>
\ No newline at end of file diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/quick-reference.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/quick-reference.html new file mode 100644 index 000000000..250bfc065 --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/quick-reference.html @@ -0,0 +1,37 @@ +{{/* +Renders the child sections of the given top-level section, listing each childs's immediate descendants. + +@param {string} section The top-level section to render. +@returns template.HTML + +@example {{% quick-reference section="functions" %}} +*/}} + +{{ $section := "" }} +{{ with .Get "section" }} + {{ $section = . }} +{{ else }} + {{ errorf "The %q shortcodes requires a 'section' parameter. See %s" .Name .Postion }} +{{ end }} + +{{/* Do not change the markdown indentation, and do not remove blank lines. */}} +{{ with site.GetPage $section }} + {{ range .Sections }} + +## {{ .LinkTitle }} +{{ .RawContent }} + + {{ range .Pages }} + {{ $aliases := "" }} + {{ if eq .Section "functions" }} + {{ $aliases = delimit .Params.action.aliases " or " }} + {{ end }} + +[{{ .LinkTitle }}]({{ .RelPermalink }}) {{ with $aliases }}({{ . }}){{ end }} +: {{ .Description }} + + {{ end }} + {{ end }} +{{ else }} + {{ errorf "The %q shortcodes was unable to find the %q section. See %s" .Name $section .Postion }} +{{ end }} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/readfile.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/readfile.html index f777abe26..de8083443 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/readfile.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/readfile.html @@ -1,6 +1,29 @@ -{{$file := .Get "file"}} -{{- if eq (.Get "markdown") "true" -}} -{{- $file | readFile | markdownify -}} -{{- else -}} -{{ $file | readFile | safeHTML }} -{{- end -}}
\ No newline at end of file +{{- $highlight := or (.Get "highlight") "" }} + +{{- $markdown := false }} +{{- if in (slice "false" false 0) (.Get "markdown") }} + {{- $markdown = false }} +{{- else if in (slice "true" true 1) (.Get "markdown") }} + {{- $markdown = true }} +{{- end }} + +{{- with .Get "file" }} + {{- if os.FileExists . }} + {{- with os.ReadFile . }} + {{- $content := trim . "\n\r" }} + {{- if $markdown }} + {{- $content | markdownify }} + {{- else if $highlight }} + {{- highlight $content $highlight }} + {{- else }} + {{- $content | safeHTML }} + {{- end }} + {{- else }} + {{- errorf "The %q shortcode was unable to read %q. See %s" $.Name . $.Position }} + {{- end }} + {{- else }} + {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }} + {{- end }} +{{- else }} + {{- errorf "The %q shortcode requires a 'file' parameter. See %s" $.Name $.Position }} +{{- end }} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/tip.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/tip.html deleted file mode 100644 index 139e3376b..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/tip.html +++ /dev/null @@ -1,9 +0,0 @@ -{{ $_hugo_config := `{ "version": 1 }` }} -<aside class="admonition tip"> - <div class="tip-icon"> - {{partial "svg/exclamation.svg" .}} - </div> - <!-- <h2 id="{{if .Get 0}}{{.Get 0 | urlize}}{{else}}tip{{end}}">{{if .Get 0}}{{.Get 0 | markdownify}}{{else}}Tip{{end}}</h2> --> - <!-- <h3>Tip</h3> --> - <div class="admonition-content">{{- .Inner -}}</div> -</aside> diff --git a/layouts/shortcodes/todo.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/todo.html index 50a099267..50a099267 100644 --- a/layouts/shortcodes/todo.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/todo.html diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/warning.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/warning.html deleted file mode 100644 index c9147be64..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/warning.html +++ /dev/null @@ -1,9 +0,0 @@ -{{ $_hugo_config := `{ "version": 1 }` }} -<aside class="admonition warning"> - <div class="admonition-icon"> - {{partial "svg/exclamation.svg" .}} - </div> - <!-- <h2 id="{{if .Get 0}}{{.Get 0 | urlize}}{{else}}warning{{end}}">{{if .Get 0}}{{.Get 0 | markdownify}}{{else}}Warning{{end}}</h2> --> - <!-- <h3>Warning</h3> --> - <div class="admonition-content">{{- .Inner -}}</div> -</aside> diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/yt.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/yt.html deleted file mode 100644 index 6915cec5f..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/yt.html +++ /dev/null @@ -1,11 +0,0 @@ -<div class="video-wrapper" data-streaming="youtube" data-videoid="{{.Get "id"}}" > - <i class="icon-video-play-button shortcode"></i> - {{if (.Get "thumbnail")}} - <div style="background-image:url(/images/thumbnails/{{.Get "thumbnail"}})" alt="YouTube Thumbnail" class="video-thumbnail"></div> - {{else}} - <div style="background-image:url(//img.youtube.com/vi/{{.Get "id"}}/0.jpg)" alt="YouTube Thumbnail" class="video-thumbnail"></div> - {{end}} -</div> -{{ if (.Get "description") }} -<div class="video-description">{{ .Get "description" | markdownify }}</div> -{{ end }}
\ No newline at end of file diff --git a/layouts/template-func/page.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/template-func/page.html index 8b5f0da85..8b5f0da85 100644 --- a/layouts/template-func/page.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/template-func/page.html diff --git a/_vendor/modules.txt b/_vendor/modules.txt index 4d5e68903..7a692e0ce 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -1 +1 @@ -# github.com/gohugoio/gohugoioTheme v0.0.0-20230927165800-342e2c850f18 +# github.com/gohugoio/gohugoioTheme v0.0.0-20231111235806-77931ac4875e 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 Binary files differnew file mode 100644 index 000000000..908bd88c6 --- /dev/null +++ b/assets/images/examples/zion-national-park-grayscale.jpg diff --git a/assets/images/examples/zion-national-park.jpg b/assets/images/examples/zion-national-park.jpg Binary files differnew file mode 100644 index 000000000..7980abccb --- /dev/null +++ b/assets/images/examples/zion-national-park.jpg diff --git a/assets/images/logos/logo-128x128.png b/assets/images/logos/logo-128x128.png Binary files differnew file mode 100644 index 000000000..ec1a2d6e1 --- /dev/null +++ b/assets/images/logos/logo-128x128.png diff --git a/assets/images/logos/logo-256x256.png b/assets/images/logos/logo-256x256.png Binary files differnew file mode 100644 index 000000000..d9fdb888a --- /dev/null +++ b/assets/images/logos/logo-256x256.png diff --git a/assets/images/logos/logo-512x512.png b/assets/images/logos/logo-512x512.png Binary files differnew file mode 100644 index 000000000..76d463600 --- /dev/null +++ b/assets/images/logos/logo-512x512.png diff --git a/assets/images/logos/logo-64x64.png b/assets/images/logos/logo-64x64.png Binary files differnew file mode 100644 index 000000000..9857bcea1 --- /dev/null +++ b/assets/images/logos/logo-64x64.png diff --git a/assets/images/logos/logo-96x96.png b/assets/images/logos/logo-96x96.png Binary files differnew file mode 100644 index 000000000..48d0cb98e --- /dev/null +++ b/assets/images/logos/logo-96x96.png diff --git a/config/_default/menus/menus.en.toml b/config/_default/menus/menus.en.toml index 327a5777b..cd337cbee 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/' +post = 'break' [[docs]] - name = "Hugo Modules" - weight = 40 - identifier = "modules" - post = "break" - url = "/hugo-modules/" +name = 'Content management' +weight = 40 +identifier = 'content-management' +post = 'expanded' +pageRef = '/content-management/' -# Core menus +[[docs]] +name = 'Templates' +weight = 50 +identifier = 'templates' +pageRef = '/templates/' + +[[docs]] +name = 'Functions' +weight = 60 +identifier = 'functions' +pageRef = '/functions/' [[docs]] - name = "Content management" - weight = 50 - identifier = "content-management" - post = "expanded" - url = "/content-management/" +name = 'Methods' +weight = 70 +identifier = 'methods' +pageRef = '/methods/' [[docs]] - name = "Templates" - weight = 60 - identifier = "templates" - url = "/templates/" +name = 'Quick reference' +weight = 80 +identifier = 'quick-reference' +pageRef = '/quick-reference/' [[docs]] - name = "Functions" - weight = 70 - identifier = "functions" - url = "/functions/" +name = 'Variables' +weight = 85 +identifier = 'variables' +pageRef = '/variables/' [[docs]] - name = "Variables" - weight = 80 - identifier = "variables" - url = "/variables/" +name = 'Hugo Modules' +weight = 90 +identifier = 'modules' +pageRef = '/hugo-modules/' [[docs]] - name = "Hugo Pipes" - weight = 90 - identifier = "hugo-pipes" - url = "/hugo-pipes/" +name = 'Hugo Pipes' +weight = 100 +identifier = 'hugo-pipes' +pageRef = '/hugo-pipes/' [[docs]] - name = "CLI" - weight = 100 - post = "break" - identifier = "commands" - url = "/commands/" +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/benefits.md b/content/en/about/benefits.md index f1fc0cfb6..82952c4e6 100644 --- a/content/en/about/benefits.md +++ b/content/en/about/benefits.md @@ -2,6 +2,7 @@ title: Benefits of static site generators linkTitle: Static site generators description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing. +categories: [about] keywords: [ssg,static,performance,security] menu: docs: diff --git a/content/en/about/features.md b/content/en/about/features.md index dcb85e8b5..a94ce5526 100644 --- a/content/en/about/features.md +++ b/content/en/about/features.md @@ -1,6 +1,8 @@ --- title: Hugo features description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites. +categories: [about] +keywords: [] menu: docs: parent: about diff --git a/content/en/about/hugo-and-gdpr.md b/content/en/about/hugo-and-gdpr.md index 85e996f59..daf4e80f0 100644 --- a/content/en/about/hugo-and-gdpr.md +++ b/content/en/about/hugo-and-gdpr.md @@ -2,15 +2,15 @@ title: Hugo and the General Data Protection Regulation linkTitle: Hugo and the GDPR description: About how to configure your Hugo site to meet the new regulations. -layout: single +categories: [about] keywords: ["GDPR", "Privacy", "Data Protection"] menu: docs: parent: about weight: 60 weight: 60 -aliases: [/privacy/,/gdpr/] toc: true +aliases: [/privacy/,/gdpr/] --- General Data Protection Regulation ([GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation)) is a regulation in EU law on data protection and privacy for all individuals within the European Union and the European Economic Area. It became enforceable on 25 May 2018. @@ -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..e488bb87a 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. -categories: ["about hugo"] -keywords: ["License","apache"] +description: Hugo is released under the Apache 2.0 license. +categories: [about] +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 %}} - -_Version 2.0, January 2004_ <br> -<https://www.apache.org/licenses/LICENSE-2.0> - -*Terms and Conditions for use, reproduction, and distribution* - -## 1. Definitions - -“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. - -“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. - -“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. - -“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. - -“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. - -## 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. - -## 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. - -## 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: - -* **(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. +## Apache 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 +_Version 2.0, January 2004_ +_<http://www.apache.org/licenses/>_ -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. +### Terms and Conditions for use, reproduction, and distribution -## 6. Trademarks +#### 1. Definitions -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. +“License” shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. -## 7. Disclaimer of Warranty +“Licensor” shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. -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. +“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. -## 8. Limitation of Liability +“You” (or “Your”) shall mean an individual or Legal Entity exercising permissions granted by this License. -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. +“Source” form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. -## 9. Accepting Warranty or Additional Liability +“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. -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. +“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. + +“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. + +#### 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. + +#### 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. -_END OF TERMS AND CONDITIONS_ +#### 4. Redistribution -## APPENDIX: How to apply the Apache License to your work +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: -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. +* **(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 + +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 -{{< code file="apache-notice.txt" >}} -Copyright [yyyy] [name of copyright owner] +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 -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 +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. - https://www.apache.org/licenses/LICENSE-2.0 +#### 8. Limitation of Liability -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 >}} +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 + +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. diff --git a/content/en/about/security-model.md b/content/en/about/security-model.md index 3b93167ab..af1dd7d75 100644 --- a/content/en/about/security-model.md +++ b/content/en/about/security-model.md @@ -1,15 +1,15 @@ --- title: Hugo's security model description: A summary of Hugo's security model. -layout: single -keywords: ["Security", "Privacy"] +categories: [about] +keywords: [security,privacy] menu: docs: parent: about weight: 50 weight: 50 -aliases: [/security/] toc: true +aliases: [/security/] --- ## Runtime security @@ -31,7 +31,7 @@ Hugo has a built-in security policy that restricts access to [os/exec](https://p The default configuration is listed below. Any build using features not in the allow list of the security policy will fail with a detailed message about what needs to be done. Most of these settings are allow lists (string or slice, [Regular Expressions](https://pkg.go.dev/regexp) or `none` which matches nothing). -{{< code-toggle config="security" />}} +{{< code-toggle config=security />}} Note that these and other configuration settings in Hugo can be overridden by the OS environment. If you want to block all remote HTTP fetching of data: diff --git a/content/en/about/what-is-hugo.md b/content/en/about/what-is-hugo.md index be564233f..e4326d173 100644 --- a/content/en/about/what-is-hugo.md +++ b/content/en/about/what-is-hugo.md @@ -1,14 +1,15 @@ --- title: What is Hugo description: Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again. -layout: single +categories: [about] +keywords: [] menu: docs: parent: about weight: 20 weight: 20 -aliases: [/overview/introduction/,/about/why-i-built-hugo/] toc: true +aliases: [/overview/introduction/,/about/why-i-built-hugo/] --- Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors. diff --git a/content/en/commands/hugo_new_content.md b/content/en/commands/hugo_new_content.md index dd646766b..cc53346ad 100644 --- a/content/en/commands/hugo_new_content.md +++ b/content/en/commands/hugo_new_content.md @@ -30,7 +30,6 @@ hugo new content [path] [flags] -c, --contentDir string filesystem path to content directory --editor string edit new content with this editor, if provided -f, --force overwrite file if it already exists - --format string preferred file format (toml, yaml or json) (default "toml") -h, --help help for content -k, --kind string content type to create -t, --theme strings themes to use (located in /themes/THEMENAME/) 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 +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/layouts/shortcodes/page-kinds.html b/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/_index.md b/content/en/content-management/_index.md index 35f85a641..66af24681 100644 --- a/content/en/content-management/_index.md +++ b/content/en/content-management/_index.md @@ -2,13 +2,13 @@ title: Content management linkTitle: Overview description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more. +categories: [] +keywords: [] menu: docs: identifier: content-management-overview parent: content-management weight: 10 -keywords: [source, organization] -categories: [content management] weight: 10 aliases: [/content/,/content/organization] --- diff --git a/content/en/content-management/archetypes.md b/content/en/content-management/archetypes.md index fe460f91f..94f038848 100644 --- a/content/en/content-management/archetypes.md +++ b/content/en/content-management/archetypes.md @@ -1,15 +1,15 @@ --- title: Archetypes description: An archetype is a template for new content. -keywords: [archetypes,generators,metadata,front matter] categories: [content management] +keywords: [archetypes,generators,metadata,front matter] menu: docs: parent: content-management weight: 140 quicklinks: -toc: true weight: 140 +toc: true aliases: [/content/archetypes/] --- @@ -19,7 +19,7 @@ A content file consists of [front matter] and markup. The markup is typically ma The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype: -{{< code-toggle file="archetypes/default.md" copy=false fm=true >}} +{{< code-toggle file=archetypes/default.md fm=true >}} title = '{{ replace .File.ContentBaseName `-` ` ` | title }}' date = '{{ .Date }}' draft = true @@ -27,13 +27,13 @@ draft = true When you create new content, Hugo evaluates the [template actions] within the archetype. For example: -```text +```sh hugo new content posts/my-first-post.md ``` With the default archetype shown above, Hugo creates this content file: -{{< code-toggle file="content/posts/my-first-post.md" copy=false fm=true >}} +{{< code-toggle file=content/posts/my-first-post.md fm=true >}} title = 'My First Post' date = '2023-08-24T11:49:46-07:00' draft = true @@ -53,7 +53,7 @@ Hugo looks for archetypes in the `archetypes` directory in the root of your proj For example, with this command: -```text +```sh hugo new content posts/my-first-post.md ``` @@ -75,7 +75,7 @@ Archetypes receive the following objects and values in [context]: - `.Date` - `.Type` - `.Site` (see [details](/variables/site/)) -- `.File` (see [details](/variables/files/)) +- `.File` (see [details](/variables/file/)) As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter. @@ -85,8 +85,7 @@ Although typically used as a front matter template, you can also use an archetyp For example, in a documentation site you might have a section (content type) for functions. Every page within this section should follow the same format: a brief description, the function signature, examples, and notes. We can pre-populate the page to remind content authors of the standard format. - -{{< code file="archetypes/functions.md" copy=false >}} +{{< code file=archetypes/functions.md >}} --- date: '{{ .Date }}' draft: true @@ -125,17 +124,17 @@ Create an archetype for galleries: ```text archetypes/ ├── galleries/ -│ ├── images/ -│ │ └── .gitkeep -│ └── index.md <-- same format as default.md +│ ├── images/ +│ │ └── .gitkeep +│ └── index.md <-- same format as default.md └── default.md ``` Subdirectories within an archetype must contain at least one file. Without a file, Hugo will not create the subdirectory when you create new content. The name and size of the file are irrelevant. The example above includes a `.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..bc9d7ff49 100644 --- a/content/en/content-management/build-options.md +++ b/content/en/content-management/build-options.md @@ -1,102 +1,321 @@ --- title: Build options description: Build options help define how Hugo must treat a given page when building the site. +categories: [content management,fundamentals] keywords: [build,content,front matter, page resources] -categories: [fundamentals,content management] menu: docs: parent: content-management weight: 70 -toc: true weight: 70 +toc: true aliases: [/content/build-options/] --- -They are stored in a reserved front matter object named `_build` with the following defaults: +Build options are stored in a reserved front matter object named `_build` with these defaults: -{{< code-toggle >}} -_build: - render: always - list: always - publishResources: true +{{< code-toggle file=content/example/index.md fm=true >}} +[_build] +list = 'always' +publishResources = true +render = 'always' {{< /code-toggle >}} -#### render -If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink. +list +: When to include the page within page collections. Specify one of: + + - `always` + : Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value. -Valid values are: + - `local` + : Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections. - `never` - : The page will not be included in any page collection. - - `always (default)` - : The page will be rendered to disk and get a `RelPermalink` etc. - - `link` - : The page will be not be rendered to disk, but will get a `RelPermalink`. + : Do not include the page in _any_ page collection. -#### list +publishResources +: Applicable to [page bundles], determines whether to publish the associated [page resources]. Specify one of: -Valid values are: - - - `never` - : The page will not be included in any page collection. - - `always (default)` - : The page will be included in all page collections, e.g. `site.RegularPages`, `.Pages`. - - `local` - : The page will be included in any _local_ page collection, e.g. `.RegularPages`, `.Pages`. One use case for this would be to create fully navigable, but headless content sections. + - `true` + : Always publish resources. This is the default value. -#### publishResources + - `false` + : Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template. -If set to `true` (default) the [Bundle's Resources](/content-management/page-bundles) will be published. -Setting this to `false` will still publish Resources on demand (when a resource's `.Permalink` or `.RelPermalink` is invoked from the templates) but will skip the others. +render +: When to render the page. Specify one of: + + - `always` + : Always render the page to disk. This is the default value. + + - `link` + : Do not render the page to disk, but include it in all page collections. + + - `never` + : Never render the page to disk, and exclude it from all page collections. + +[page bundles]: content-management/page-bundles +[page resources]: /content-management/page-resources +[`Permalink`]: /methods/resource/permalink +[`RelPermalink`]: /methods/resource/relpermalink +[`Publish`]: /methods/resource/publish {{% note %}} -Any page, regardless of their build options, will always be available using the [`.GetPage`](/functions/getpage) methods. +Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method. + +[`.Page.GetPage`]: /methods/page/getpage +[`.Site.GetPage`]: /methods/site/getpage {{% /note %}} -### Illustrative use cases +## Example -- headless page + +Create a unpublished page whose content and resources can be included in other pages. + +```text +content/ +├── headless/ +│ ├── a.jpg +│ ├── b.jpg +│ └── index.md <-- leaf bundle +└── _index.md <-- home page +``` + +Set the build options in front matter: + +{{< code-toggle file=content/headless/index.md fm=true >}} +title = 'Headless page' +[_build] + list = 'never' + publishResources = false + render = 'never' +{{< /code-toggle >}} + +To include the content and images on the home page: + +{{< code file=layouts/_default/home.html >}} +{{ with .Site.GetPage "/headless" }} + {{ .Content }} + {{ range .Resources.ByType "image" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +{{< /code >}} + +The published site will have this structure: + +```text +public/ +├── headless/ +│ ├── a.jpg +│ └── b.jpg +└── index.html +``` + +In the example above, note that: + +1. Hugo did not publish an HTML file for the page. +2. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior. + +## Example -- headless section -#### Not publishing a page +Create a unpublished section whose content and resources can be included in other pages. -Project needs a "Who We Are" content file for front matter and body to be used by the homepage but nowhere else. +[branch bundle]: /content-management/page-bundles -{{< code-toggle file="content/who-we-are.md" fm=true copy=false >}} -title: Who we are -_build: - list: false - render: false +```text +content/ +├── headless/ +│ ├── note-1/ +│ │ ├── a.jpg +│ │ ├── b.jpg +│ │ └── index.md <-- leaf bundle +│ ├── note-2/ +│ │ ├── c.jpg +│ │ ├── d.jpg +│ │ └── index.md <-- leaf bundle +│ └── _index.md <-- branch bundle +└── _index.md <-- home page +``` + +Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages. + +{{< code-toggle file=content/headless/_index.md fm=true >}} +title = 'Headless section' +[[cascade]] +[cascade._build] + list = 'local' + publishResources = false + render = 'never' {{< /code-toggle >}} -{{< code file="layouts/index.html" copy=false >}} -<section id="who-we-are"> - {{ with site.GetPage "who-we-are" }} +In the front matter above, note that we have set `list` to `local` to include the descendant pages in local page collections. + +To include the content and images on the home page: + +{{< code file=layouts/_default/home.html >}} +{{ with .Site.GetPage "/headless" }} + {{ range .Pages }} {{ .Content }} + {{ range .Resources.ByType "image" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} {{ end }} -</section> +{{ end }} {{< /code >}} -#### Listing pages without publishing them +The published site will have this structure: + +```text +public/ +├── headless/ +│ ├── note-1/ +│ │ ├── a.jpg +│ │ └── b.jpg +│ └── note-2/ +│ ├── c.jpg +│ └── d.jpg +└── index.html +``` + +In the example above, note that: + +1. Hugo did not publish an HTML file for the page. +2. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior. + +## Example -- list without publishing -Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them. +Publish a section page without publishing the descendant pages. For example, to create a glossary: -To avoid setting the build options on every testimonials, one can use [`cascade`](/content-management/front-matter#front-matter-cascade) on the testimonial section's content file. +```text +content/ +├── glossary/ +│ ├── _index.md +│ ├── bar.md +│ ├── baz.md +│ └── foo.md +└── _index.md +``` -{{< code-toggle >}} -title: Testimonials -_build: - render: true -cascade: - _build: - render: false - list: true # default +Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages. + +{{< code-toggle file=content/glossary/_index.md fm=true >}} +title = 'Glossary' +[_build] +render = 'always' +[[cascade]] +[cascade._build] + list = 'local' + publishResources = false + render = 'never' {{< /code-toggle >}} -{{< code file="layouts/_defaults/testimonials.html" copy=false >}} -<section id="testimonials"> - {{ range first 5 .Pages }} - <blockquote cite="{{ .Params.cite }}"> - {{ .Content }} - </blockquote> +To render the glossary: + +{{< code file=layouts/glossary/list.html >}} +<dl> + {{ range .Pages }} + <dt>{{ .Title }}</dt> + <dd>{{ .Content }}</dd> {{ end }} -</section> +</dl> {{< /code >}} + +The published site will have this structure: + +```text +public/ +├── glossary/ +│ └── index.html +└── index.html +``` + +## Example -- publish without listing + +Publish a section's descendant pages without publishing the section page itself. + +```text +content/ +├── books/ +│ ├── _index.md +│ ├── book-1.md +│ └── book-2.md +└── _index.md +``` + +Set the build options in front matter: + +{{< code-toggle file=content/books/_index.md >}} +title = 'Books' +[_build] +render = 'never' +list = 'never' +{{< /code-toggle >}} + +The published site will have this structure: + +```html +public/ +├── books/ +│ ├── book-1/ +│ │ └── index.html +│ └── book-2/ +│ └── index.html +└── index.html +``` + +## Example -- conditionally hide section + +Consider this example. A documentation site has a team of contributors with access to 20 custom shortcodes. Each shortcode takes several arguments, and requires documentation for the contributors to reference when using them. + +Instead of external documentation for the shortcodes, include an "internal" section that is hidden when building the production site. + +```text +content/ +├── internal/ +│ ├── shortcodes/ +│ │ ├── _index.md +│ │ ├── shortcode-1.md +│ │ └── shortcode-2.md +│ └── _index.md +├── reference/ +│ ├── _index.md +│ ├── reference-1.md +│ └── reference-2.md +├── tutorials/ +│ ├── _index.md +│ ├── tutorial-1.md +│ └── tutorial-2.md +└── _index.md +``` + +Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages, and use the `target` keyword to target the production environment. + +{{< code-toggle file=content/internal/_index.md >}} +title = 'Internal' +[[cascade]] +[cascade._build] +render = 'never' +list = 'never' +[cascade._target] +environment = 'production' +{{< /code-toggle >}} + +The production site will have this structure: + +```html +public/ +├── reference/ +│ ├── reference-1/ +│ │ └── index.html +│ ├── reference-2/ +│ │ └── index.html +│ └── index.html +├── tutorials/ +│ ├── tutorial-1/ +│ │ └── index.html +│ ├── tutorial-2/ +│ │ └── index.html +│ └── index.html +└── index.html +``` diff --git a/content/en/content-management/comments.md b/content/en/content-management/comments.md index df9453c48..5f2f9660b 100644 --- a/content/en/content-management/comments.md +++ b/content/en/content-management/comments.md @@ -1,14 +1,14 @@ --- title: Comments description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website. +categories: [content management] keywords: [sections,content,organization] -categories: [project organization] menu: docs: parent: content-management weight: 220 -toc: true weight: 220 +toc: true aliases: [/extras/comments/] --- @@ -24,7 +24,7 @@ Hugo comes with all the code you need to load Disqus into your templates. Before Disqus comments require you set a single value in your [site's configuration file][configuration] like so: -{{< code-toggle copy=false >}} +{{< code-toggle file=hugo >}} disqusShortname = "yourDisqusShortname" {{</ code-toggle >}} diff --git a/content/en/content-management/cross-references.md b/content/en/content-management/cross-references.md index c989cc560..500e388a4 100644 --- a/content/en/content-management/cross-references.md +++ b/content/en/content-management/cross-references.md @@ -2,13 +2,13 @@ title: Links and cross references description: Shortcodes for creating links to documents. categories: [content management] -keywords: ["cross references","references", "anchors", "urls"] +keywords: [cross references,references,anchors,urls] menu: docs: parent: content-management weight: 170 -toc: true weight: 170 +toc: true aliases: [/extras/crossreferences/] --- @@ -35,7 +35,6 @@ The `ref` and `relref` shortcodes require a single parameter: the path to a cont The pages can be referenced as follows: - ```text {{</* ref "document2" */>}} // <- From pages/document1.md, relative path {{</* ref "document2#anchor" */>}} @@ -138,7 +137,7 @@ produces this HTML: ## Ref and RelRef Configuration -The behavior can, since Hugo 0.45, be configured in `hugo.toml`: +The behavior can be configured in `hugo.toml`: refLinksErrorLevel ("ERROR") : When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). @@ -146,7 +145,6 @@ refLinksErrorLevel ("ERROR") refLinksNotFoundURL : URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. - [lists]: /templates/lists/ [output formats]: /templates/output-formats/ [shortcode]: /content-management/shortcodes/ diff --git a/content/en/content-management/diagrams.md b/content/en/content-management/diagrams.md index c0b2349b0..17407098f 100644 --- a/content/en/content-management/diagrams.md +++ b/content/en/content-management/diagrams.md @@ -7,12 +7,12 @@ menu: docs: parent: content-management weight: 50 -toc: true weight: 50 +toc: true --- -{{< new-in "0.93.0" >}} +{{< new-in 0.93.0 >}} -## GoAT diagrams (Ascii) +## GoAT diagrams (ASCII) Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block: @@ -165,7 +165,6 @@ Created from <https://arthursonzogni.com/Diagon/#Tree> └─Fedora ``` - ### Sequence diagram <https://arthursonzogni.com/Diagon/#Sequence> @@ -186,7 +185,6 @@ Created from <https://arthursonzogni.com/Diagon/#Tree> ``` - ### Flowchart <https://arthursonzogni.com/Diagon/#Flowchart> @@ -232,7 +230,6 @@ Created from <https://arthursonzogni.com/Diagon/#Tree> ``` - ### Table <https://arthursonzogni.com/Diagon/#Table> diff --git a/content/en/content-management/formats.md b/content/en/content-management/formats.md index ccc45b943..76c8102b5 100644 --- a/content/en/content-management/formats.md +++ b/content/en/content-management/formats.md @@ -7,8 +7,8 @@ menu: docs: parent: content-management weight: 40 -toc: true weight: 40 +toc: true aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/] --- @@ -24,12 +24,12 @@ The current list of content formats in Hugo: | Name | Markup identifiers | Comment | | ------------- | ------------- |-------------| -| Goldmark | md, markdown, goldmark |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).| -|Emacs Org-Mode|org|See [go-org](https://github.com/niklasfasching/go-org).| -|AsciiDoc|asciidocext, adoc, ad|Needs [Asciidoctor][ascii] installed.| -|RST|rst|Needs [RST](https://docutils.sourceforge.io/rst.html) installed.| -|Pandoc|pandoc, pdc|Needs [Pandoc](https://www.pandoc.org/) installed.| -|HTML|html, htm|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.| +| Goldmark | `markdown`, `goldmark` |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).| +|Emacs Org-Mode|`org`|See [go-org](https://github.com/niklasfasching/go-org).| +|AsciiDoc|`asciidocext`, `adoc`, `ad`|Needs [Asciidoctor][ascii] installed.| +|RST|`rst`|Needs [RST](https://docutils.sourceforge.io/rst.html) installed.| +|Pandoc|`pandoc`, `pdc`|Needs [Pandoc](https://www.pandoc.org/) installed.| +|HTML|`html`, `htm`|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.| The `markup identifier` is fetched from either the `markup` variable in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/). @@ -59,7 +59,7 @@ optional extensions like `asciidoctor-diagram` or `asciidoctor-html5s` are insta External `asciidoctor` command requires Hugo rendering to _disk_ to a specific destination directory. It is required to run Hugo with the command option `--destination`. {{% /note %}} -Some Asciidoctor parameters can be customized in Hugo. See [details]. +Some Asciidoctor parameters can be customized in Hugo. See [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..dba67ba10 100644 --- a/content/en/content-management/front-matter.md +++ b/content/en/content-management/front-matter.md @@ -2,13 +2,13 @@ title: Front matter description: Hugo allows you to add front matter in yaml, toml, or json to your content files. categories: [content management] -keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"] +keywords: [front matter,yaml,toml,json,metadata,archetypes] menu: docs: parent: content-management weight: 60 -toc: true weight: 60 +toc: true aliases: [/content/front-matter/] --- @@ -93,7 +93,7 @@ lastmod : The datetime at which the content was last modified. linkTitle -: Used for creating links to content; if set, Hugo defaults to using the `linkTitle` before the `title`. Hugo can also [order lists of content by `linkTitle`][bylinktitle]. +: Used for creating links to content; if set, Hugo defaults to using the `linkTitle` before the `title`. markup : **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown. @@ -131,7 +131,7 @@ videos weight : used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight. -\<taxonomies\> +taxonomies : Field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.* {{% note %}} @@ -144,7 +144,7 @@ You can add fields to your front matter arbitrarily to meet your needs. These us The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables] section provides more information on using Hugo's page- and site-level variables in your templates. -{{< code-toggle copy=false >}} +{{< code-toggle >}} include_toc: true show_comments: false {{</ code-toggle >}} @@ -157,7 +157,7 @@ Any node or section can pass down to descendants a set of front matter values as The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets. -{{< code-toggle copy=false >}} +{{< code-toggle >}} title ="Blog" [[cascade]] background = "yosemite.jpg" @@ -187,11 +187,17 @@ environment Any of the above can be omitted. +{{% note %}} +When making a site that supports multiple languages, defining a `[[cascade]]` is recommended to be done in [Site Config](../../getting-started/configuration/#cascade) to prevent duplication. + +If you instea define a `[[cascade]]` in front matter for multiple languages, an `content/XX/foo/_index.md` file needs to be made on a per-language basis, with `XX` the glob pattern matching the Page's language. In this case, the **lang** keyword is ignored. +{{% /note %}} + ### Example In `content/blog/_index.md` -{{< code-toggle copy=false >}} +{{< code-toggle >}} title: Blog cascade: banner: images/typewriter.jpg @@ -219,13 +225,12 @@ It's possible to set some options for Markdown rendering in a content's front ma [variables]: /variables/ [aliases]: /content-management/urls/#aliases [archetype]: /content-management/archetypes/ -[bylinktitle]: /templates/lists/#by-link-title [config]: /getting-started/configuration/ [content type]: /content-management/types/ [contentorg]: /content-management/organization/ [headless-bundle]: /content-management/page-bundles/#headless-bundle [json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf -[lists]: /templates/lists/#order-content +[lists]: /templates/lists/#sort-content [lookup]: /templates/lookup-order/ [ordering]: /templates/lists/ [outputs]: /templates/output-formats/ diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index 9cce9070a..511365700 100644 --- a/content/en/content-management/image-processing/index.md +++ b/content/en/content-management/image-processing/index.md @@ -1,8 +1,8 @@ --- title: Image processing description: Resize, crop, rotate, filter, and convert images. -categories: [fundamentals,content management] -keywords: [resources, images] +categories: [content management,fundamentals] +keywords: [resources,images] menu: docs: parent: content-management @@ -10,6 +10,7 @@ menu: toc: true weight: 90 --- + ## Image resources To process an image you must access the file as a page resource, global resource, or remote resource. @@ -50,7 +51,7 @@ To access an image as a global resource: ### Remote resource -A remote resource is a file on a remote server, accessible via http or https. To access an image as a remote resource: +A remote resource is a file on a remote server, accessible via HTTP or HTTPS. To access an image as a remote resource: ```go-html-template {{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }} @@ -104,15 +105,15 @@ Example 4: Skips rendering if there's problem accessing a remote resource. The `image` resource implements the [`Process`], [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods. {{% note %}} -Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`] method with the _original_ image to extract EXIF metadata from JPEG or TIFF images. +Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the `Exif` method with the _original_ image to extract EXIF metadata from JPEG or TIFF images. {{% /note %}} ### Process -{{< new-in "0.119.0" >}} +{{< new-in 0.119.0 >}} {{% note %}} -The `Process` method is also available as a filter, which is more effective if need to apply multiple filters to an image. See [Process filter](/functions/images/#process). +The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process). {{% /note %}} Process processes the image with the given specification. The specification can contain an optional action, one of `resize`, `crop`, `fit` or `fill`. This means that you can use this method instead of [`Resize`], [`Fit`], [`Fill`], or [`Crop`]. @@ -139,10 +140,9 @@ Some more examples: {{ $image := $image.Process "fill 600x400" }} ``` - ### Resize -Resize an image to the specified width and/or height. +Resize an image to the given width and/or height. If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio. @@ -205,7 +205,7 @@ Sometimes it can be useful to create the filter chain once and then reuse it. ### Colors -{{< new-in "0.104.0" >}} +{{< new-in 0.104.0 >}} `.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method. @@ -215,7 +215,6 @@ Sometimes it can be useful to create the filter chain once and then reuse it. This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled down image. - ### EXIF Provides an [EXIF] object containing image metadata. @@ -266,7 +265,7 @@ You may also access EXIF fields individually, using the [`lang.FormatNumber`] fu ## Image processing options -The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-separated, case-insensitive list of options. The order of the options within the list is irrelevant. +The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-delimited, case-insensitive list of options. The order of the options within the list is irrelevant. ### Dimensions @@ -347,9 +346,9 @@ The default value is 75. You may override the default value in the [site configu ### Hint -<!-- Specifies a libwebp preset, not a libwebp image hint. --> +Applicable to WebP images, this option corresponds to a set of predefined encoding parameters, and is equivalent to the `-preset` flag for the [`cwebp`] encoder. -Applicable to WebP images, this option corresponds to a set of predefined encoding parameters. +[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp Value|Example :--|:-- @@ -369,7 +368,7 @@ The default value is `photo`. You may override the default value in the [site co When converting an image from a format that supports transparency (e.g., PNG) to a format that does _not_ support transparency (e.g., JPEG), you may specify the background color of the resulting image. -Use either a 3-digit or a 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`). +Use either a 3-digit or 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`). The default value is `#ffffff` (white). You may override the default value in the [site configuration]. @@ -402,28 +401,26 @@ See [github.com/disintegration/imaging] for the complete list of resampling filt _The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ -{{< imgproc sunset Resize "300x" />}} +{{< imgproc "sunset.jpg" "resize 300x" />}} -{{< imgproc sunset Fill "90x120 left" />}} +{{< imgproc "sunset.jpg" "fill 90x120 left" />}} -{{< imgproc sunset Fill "90x120 right" />}} +{{< imgproc "sunset.jpg" "fill 90x120 right" />}} -{{< imgproc sunset Fit "90x90" />}} +{{< imgproc "sunset.jpg" "fit 90x90" />}} -{{< imgproc sunset Crop "250x250 center" />}} +{{< imgproc "sunset.jpg" "crop 250x250 center" />}} -{{< imgproc sunset Resize "300x q10" />}} +{{< imgproc "sunset.jpg" "resize 300x q10" />}} This is the shortcode used to generate the examples above: -{{< code file="layouts/shortcodes/imgproc.html" >}} -{{< readfile file="layouts/shortcodes/imgproc.html" >}} -{{< /code >}} +{{< readfile file=layouts/shortcodes/imgproc.html highlight=go-html-template >}} Call the shortcode from your Markdown like this: ```go-html-template -{{</* imgproc sunset Resize "300x" /*/>}} +{{</* imgproc "sunset.jpg" "resize 300x" /*/>}} ``` {{% note %}} @@ -436,7 +433,7 @@ Note the self-closing shortcode syntax above. You may call the `imgproc` shortco Define an `imaging` section in your site configuration to set the default [image processing options](#image-processing-options). -{{< code-toggle config="imaging" />}} +{{< code-toggle config=imaging />}} anchor : See image processing options: [anchor](#anchor). @@ -457,7 +454,7 @@ resampleFilter Define an `imaging.exif` section in your site configuration to control the availability of EXIF data. -{{< code-toggle file="hugo" copy=true >}} +{{< code-toggle file=hugo >}} [imaging.exif] includeFields = "" excludeFields = "" @@ -478,7 +475,9 @@ includeFields : Regular expression matching the EXIF tags to include in the `.Tags` collection. Default is `""`. To include all available tags, set this value to `".*"`. {{% note %}} -To improve performance and decrease cache size, if you set neither `excludeFields` nor `includeFields`, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`. +To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`. + +To control tag availability, change the `excludeFields` or `includeFields` settings as described above. {{% /note %}} ## Smart cropping of images @@ -487,9 +486,9 @@ By default, Hugo uses the [Smartcrop] library when cropping images with the `Cro Examples using the sunset image from above: -{{< imgproc sunset Fill "200x200 smart" />}} +{{< imgproc "sunset.jpg" "fill 200x200 smart" />}} -{{< imgproc sunset Crop "200x200 smart" />}} +{{< imgproc "sunset.jpg" "crop 200x200 smart" />}} ## Image processing performance consideration @@ -497,7 +496,7 @@ Hugo caches processed images in the `resources` directory. If you include this d If you change image processing methods or options, or if you rename or remove images, the `resources` directory will contain unused images. To remove the unused images, perform garbage collection with: -```bash +```sh hugo --gc ``` diff --git a/content/en/content-management/menus.md b/content/en/content-management/menus.md index 07bf41669..e2a72f124 100644 --- a/content/en/content-management/menus.md +++ b/content/en/content-management/menus.md @@ -7,8 +7,8 @@ menu: docs: parent: content-management weight: 190 -toc: true weight: 190 +toc: true aliases: [/extras/menus/] --- @@ -36,7 +36,7 @@ Although you can use these methods in combination when defining a menu, the menu To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration. -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} sectionPagesMenu = "main" {{< /code-toggle >}} @@ -46,7 +46,7 @@ This creates a menu structure that you can access with `site.Menus.main` in your To add a page to the "main" menu: -{{< code-toggle file="content/about.md" copy=false fm=true >}} +{{< code-toggle file=content/about.md fm=true >}} title = 'About' menu = 'main' {{< /code-toggle >}} @@ -55,7 +55,7 @@ Access the entry with `site.Menus.main` in your templates. See [menu templates] To add a page to the "main" and "footer" menus: -{{< code-toggle file="content/contact.md" copy=false fm=true >}} +{{< code-toggle file=content/contact.md fm=true >}} title = 'Contact' menu = ['main','footer'] {{< /code-toggle >}} @@ -94,7 +94,7 @@ weight This front matter menu entry demonstrates some of the available properties: -{{< code-toggle file="content/products/software.md" copy=false fm=true >}} +{{< code-toggle file=content/products/software.md fm=true >}} title = 'Software' [menu.main] parent = 'Products' @@ -106,12 +106,11 @@ class = 'center' Access the entry with `site.Menus.main` in your templates. See [menu templates] for details. - ## Define in site configuration To define entries for the "main" menu: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [[menu.main]] name = 'Home' pageRef = '/' @@ -132,7 +131,7 @@ This creates a menu structure that you can access with `site.Menus.main` in your To define entries for the "footer" menu: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [[menu.footer]] name = 'Terms' pageRef = '/terms' @@ -177,7 +176,7 @@ url This nested menu demonstrates some of the available properties: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [[menu.main]] name = 'Products' pageRef = '/products' diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md index 6e787c526..07eecbaaf 100644 --- a/content/en/content-management/multilingual.md +++ b/content/en/content-management/multilingual.md @@ -3,13 +3,13 @@ title: Multilingual mode linkTitle: Multilingual description: Hugo supports the creation of websites with multiple languages side by side. categories: [content management] -keywords: [multilingual,i18n, internationalization] +keywords: [multilingual,i18n,internationalization] menu: docs: parent: content-management weight: 230 -toc: true weight: 230 +toc: true aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/] --- @@ -21,11 +21,11 @@ Also See [Hugo Multilingual Part 1: Content translation]. This is the default language configuration: -{{< code-toggle config="languages" />}} +{{< code-toggle config=languages />}} This is an example of a site configuration for a multilingual project. Any key not defined in a `languages` object will fall back to the global value in the root of your site configuration. -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} defaultContentLanguage = 'de' defaultContentLanguageInSubdir = true @@ -54,39 +54,39 @@ weight = 2 subtitle = 'Reference, Tutorials, and Explanations' {{< /code-toggle >}} -`defaultContentLanguage` +defaultContentLanguage : (`string`) The project's default language tag as defined by [RFC 5646]. Must be lower case, and must match one of the defined language keys. Default is `en`. Examples: - `en` - `en-gb` - `pt-br` -`defaultContentLanguageInSubdir` +defaultContentLanguageInSubdir : (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`. -`contentDir` +contentDir : (`string`) The content directory for this language. Omit if [translating by file name]. -`disabled` +disabled : (`bool`) If `true`, Hugo will not render content for this language. Default is `false`. -`languageCode` +languageCode : (`string`) The language tag as defined by [RFC 5646]. This value may include upper and lower case characters, hyphens or underscores, and does not affect localization or URLs. Hugo uses this value to populate the `language` element in the [built-in RSS template], and the `lang` attribute of the `html` element in the [built-in alias template]. Examples: - `en` - `en-GB` - `pt-BR` -`languageDirection` +languageDirection : (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`] HTML attribute. -`languageName` +languageName : (`string`) The language name, typically used when rendering a language switcher. -`title` +title : (`string`) The language title. When set, this overrides the site title for this language. -`weight` +weight : (`int`) The language weight. When set to a non-zero value, this is the primary sort criteria for this language. [`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir @@ -97,14 +97,14 @@ subtitle = 'Reference, Tutorials, and Explanations' ### Changes in Hugo 0.112.0 -{{< new-in "0.112.0" >}} +{{< new-in 0.112.0 >}} In Hugo `v0.112.0` we consolidated all configuration options, and improved how the languages and their parameters are merged with the main configuration. But while testing this on Hugo sites out there, we received some error reports and reverted some of the changes in favor of deprecation warnings: 1. `site.Language.Params` is deprecated. Use `site.Params` directly. 1. Adding custom parameters to the top level language configuration is deprecated. Define custom parameters within `languages.xx.params`. See `color` in the example below. -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} title = "My blog" languageCode = "en-us" @@ -129,20 +129,20 @@ In the example above, all settings except `color` below `params` map to predefin To disable a language within a `languages` object in your site configuration: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [languages.es] disabled = true {{< /code-toggle >}} To disable one or more languages in the root of your site configuration: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} disableLanguages = ["es", "fr"] {{< /code-toggle >}} To disable one or more languages using an environment variable: -```bash +```sh HUGO_DISABLELANGUAGES="es fr" hugo ``` @@ -160,7 +160,7 @@ If a `baseURL` is set on the `language` level, then all languages must have one Example: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [languages] [languages.fr] baseURL = "https://example.fr" @@ -169,7 +169,7 @@ weight = 1 title = "En Français" [languages.en] -baseURL = "https://example.com" +baseURL = "https://example.org/" languageName = "English" weight = 2 title = "In English" @@ -183,13 +183,13 @@ public └── fr ``` -**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.** +**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.org/`.** When you run `hugo server` we will start multiple HTTP servers. You will typically see something like this in the console: ```text -Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) -Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) +Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) fr +Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) en Press Ctrl+C to stop ``` @@ -221,7 +221,7 @@ If a file has no language code, it will be assigned the default language. This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` parameter. -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} languages: en: weight: 10 @@ -277,7 +277,7 @@ To localize URLs: For example, a French translation can have its own localized slug. -{{< code-toggle file="content/about.fr.md" fm=true copy=false >}} +{{< code-toggle file=content/about.fr.md fm=true >}} title: A Propos slug: "a-propos" {{< /code-toggle >}} @@ -303,13 +303,13 @@ Page Bundle resources follow the same language assignment logic as content files To create a list of links to translated content, use a template similar to the following: -{{< code file="layouts/partials/i18nlist.html" >}} +{{< code file=layouts/partials/i18nlist.html >}} {{ if .IsTranslated }} <h4>{{ i18n "translations" }}</h4> <ul> {{ range .Translations }} <li> - <a href="{{ .Permalink }}">{{ .Lang }}: {{ .Title }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a> + <a href="{{ .RelPermalink }}">{{ .Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a> </li> {{ end }} </ul> @@ -324,10 +324,10 @@ The above also uses the [`i18n` function][i18func] described in the next section `.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator: -{{< code file="layouts/partials/allLanguages.html" >}} +{{< code file=layouts/partials/allLanguages.html >}} <ul> {{ range $.Site.Home.AllTranslations }} -<li><a href="{{ .Permalink }}">{{ .Language.LanguageName }}</a></li> +<li><a href="{{ .RelPermalink }}">{{ .Language.LanguageName }}</a></li> {{ end }} </ul> {{< /code >}} @@ -349,7 +349,9 @@ Private use subtags must not exceed 8 alphanumeric characters. ### Query basic translation -From within your templates, use the `i18n` function like this: +From within your templates, use the [`i18n`] function like this: + +[`i18n`]: /functions/lang/translate ```go-html-template {{ i18n "home" }} @@ -357,7 +359,7 @@ From within your templates, use the `i18n` function like this: The function will search for the `"home"` id: -{{< code-toggle file="i18n/en-US" >}} +{{< code-toggle file=i18n/en-US >}} [home] other = "Home" {{< /code-toggle >}} @@ -378,7 +380,7 @@ Often you will want to use the page variables in the translation strings. To do The function will pass the `.` context to the `"wordCount"` id: -{{< code-toggle file="i18n/en-US" >}} +{{< code-toggle file=i18n/en-US >}} [wordCount] other = "This article has {{ .WordCount }} words." {{< /code-toggle >}} @@ -399,7 +401,7 @@ To enable pluralization when translating, pass a map with a numeric `.Count` pro The function will read `.Count` from `.ReadingTime` and evaluate whether the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file: -{{< code-toggle file="i18n/en-US" >}} +{{< code-toggle file=i18n/en-US >}} [readingTime] one = "One minute to read" other = "{{ .Count }} minutes to read" @@ -427,7 +429,7 @@ In case you need to pass a custom data: (`(dict "Count" numeric_value_only)` is The following localization examples assume your site's primary language is English, with translations to French and German. -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} defaultContentLanguage = 'en' [languages] @@ -530,7 +532,7 @@ Localization of menu entries depends on how you define them: - When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry. - When you define menu entries [in front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry. -- When you define menu entries [in site configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficent, use translation tables to localize each entry. +- When you define menu entries [in site configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry. ### Create language-specific menu entries @@ -538,7 +540,7 @@ Localization of menu entries depends on how you define them: For a simple menu with a small number of entries, use a single configuration file. For example: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [languages.de] languageCode = 'de-DE' languageName = 'Deutsch' @@ -583,7 +585,7 @@ config/ └── hugo.toml ``` -{{< code-toggle file="config/_default/menus/menu.de" copy=false >}} +{{< code-toggle file=config/_default/menus/menu.de >}} [[main]] name = 'Produkte' pageRef = '/products' @@ -594,7 +596,7 @@ pageRef = '/services' weight = 20 {{< /code-toggle >}} -{{< code-toggle file="config/_default/menus/menu.en" copy=false >}} +{{< code-toggle file=config/_default/menus/menu.en >}} [[main]] name = 'Products' pageRef = '/products' @@ -624,7 +626,7 @@ The `identifier` depends on how you define menu entries: For example, if you define menu entries in site configuration: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [[menu.main]] identifier = 'products' name = 'Products' @@ -639,7 +641,7 @@ For example, if you define menu entries in site configuration: Create corresponding entries in the translation tables: -{{< code-toggle file="i18n/de" copy=false >}} +{{< code-toggle file=i18n/de >}} products = 'Produkte' services = 'Leistungen' {{< / code-toggle >}} @@ -663,7 +665,7 @@ For merging of content from other languages (i.e. missing content translations), To track down missing translation strings, run Hugo with the `--printI18nWarnings` flag: -```bash +```sh hugo --printI18nWarnings | grep i18n i18n|MISSING_TRANSLATION|en|wordCount ``` @@ -677,19 +679,18 @@ To support Multilingual mode in your themes, some considerations must be taken f If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites). - ## Generate multilingual content with `hugo new content` If you organize content with translations in the same directory: -```text +```sh hugo new content post/test.en.md hugo new content post/test.de.md ``` If you organize content with translations in different directories: -```text +```sh hugo new content content/en/post/test.md hugo new content content/de/post/test.md ``` diff --git a/content/en/content-management/organization/index.md b/content/en/content-management/organization/index.md index 2c0d2e604..22b341fcf 100644 --- a/content/en/content-management/organization/index.md +++ b/content/en/content-management/organization/index.md @@ -2,14 +2,14 @@ title: Content organization linkTitle: Organization description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site. -categories: [fundamentals,content management] +categories: [content management,fundamentals] keywords: [sections,content,organization,bundle,resources] menu: docs: parent: content-management weight: 20 -toc: true weight: 20 +toc: true aliases: [/content/sections/] --- @@ -19,16 +19,14 @@ Hugo `0.32` announced page-relative images and other resources packaged into `Pa These terms are connected, and you also need to read about [Page Resources](/content-management/page-resources) and [Image Processing](/content-management/image-processing) to get the full picture. -{{< imgproc 1-featured Resize "300x" >}} +{{< imgproc "1-featured-content-bundles.png" "resize 300x" >}} The illustration shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed. {{< /imgproc >}} - {{% note %}} The bundle documentation is a **work in progress**. We will publish more comprehensive docs about this soon. {{% /note %}} - ## Organization of content source In Hugo, your content should be organized in a manner that reflects the rendered website. @@ -41,33 +39,31 @@ Without any additional configuration, the following will automatically work: . └── content └── about - | └── index.md // <- https://example.com/about/ + | └── index.md // <- https://example.org/about/ ├── posts - | ├── firstpost.md // <- https://example.com/posts/firstpost/ + | ├── firstpost.md // <- https://example.org/posts/firstpost/ | ├── happy - | | └── ness.md // <- https://example.com/posts/happy/ness/ - | └── secondpost.md // <- https://example.com/posts/secondpost/ + | | └── ness.md // <- https://example.org/posts/happy/ness/ + | └── secondpost.md // <- https://example.org/posts/secondpost/ └── quote - ├── first.md // <- https://example.com/quote/first/ - └── second.md // <- https://example.com/quote/second/ + ├── first.md // <- https://example.org/quote/first/ + └── second.md // <- https://example.org/quote/second/ ``` ## Path breakdown in Hugo - -The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.com"` in your [site's configuration file][config]. +The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org"` in your [site's configuration file][config]. ### Index pages: `_index.md` `_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates], [taxonomy templates], [taxonomy terms templates], and your [homepage template]. {{% note %}} -**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/getpage/). +**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/methods/page/getpage). {{% /note %}} You can create one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website: - ```txt . url . ⊢--^-⊣ @@ -88,17 +84,15 @@ At build, this will output to the following destination with the associated valu ⊢--------^---------⊣⊢-^-⊣ permalink ⊢----------^-------------⊣ -https://example.com/posts/index.html +https://example.org/posts/index.html ``` The [sections] can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. `_index.md`). - ### Single pages in sections Single content files in each of your sections will be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`: - ```txt path ("posts/my-first-hugo-post.md") . ⊢-----------^------------⊣ @@ -117,10 +111,9 @@ When Hugo builds your site, the content will be output to the following destinat ⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣ permalink ⊢--------------------^---------------------⊣ -https://example.com/posts/my-first-hugo-post/index.html +https://example.org/posts/my-first-hugo-post/index.html ``` - ## Paths explained The following concepts provide more insight into the relationship between your project's organization and the default Hugo behavior when building output for the website. @@ -147,7 +140,7 @@ The `url` is the entire URL path, defined by the file path and optionally overri [config]: /getting-started/configuration/ [formats]: /content-management/formats/ [front matter]: /content-management/front-matter/ -[getpage]: /functions/getpage/ +[getpage]: /methods/page/getpage [homepage template]: /templates/homepage/ [homepage]: /templates/homepage/ [lists]: /templates/lists/ diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md index c4ce69f5f..860fff2bb 100644 --- a/content/en/content-management/page-bundles.md +++ b/content/en/content-management/page-bundles.md @@ -1,14 +1,14 @@ --- title: Page bundles description: Content organization using Page Bundles -keywords: [page, bundle, leaf, branch] categories: [content management] +keywords: [page,bundle,leaf,branch] menu : docs: parent: content-management weight: 30 -toc: true weight: 30 +toc: true --- Page Bundles are a way to group [Page Resources](/content-management/page-resources/). @@ -48,24 +48,24 @@ content/ │ │ ├── image2.png │ │ └── index.md │ └── my-other-post -│ └── index.md +│ └── index.md │ └── another-section ├── .. - └── not-a-leaf-bundle + └── not-a-leaf-bundle ├── .. - └── another-leaf-bundle - └── index.md + └── another-leaf-bundle + └── index.md ``` In the above example `content/` directory, there are four leaf bundles: -`about` +about : This leaf bundle is at the root level (directly under `content` directory) and has only the `index.md`. -`my-post` +my-post : This leaf bundle has the `index.md`, two other content Markdown files and two image files. @@ -78,10 +78,10 @@ These content files are page resources of `my-post` and only available in `my-post/index.md` resources. They will **not** be rendered as individual pages. -`my-other-post` +my-other-post : This leaf bundle has only the `index.md`. -`another-leaf-bundle` +another-leaf-bundle : This leaf bundle is nested under couple of directories. This bundle also has only the `index.md`. @@ -90,7 +90,6 @@ The hierarchy depth at which a leaf bundle is created does not matter, as long as it is not inside another **leaf** bundle. {{% /note %}} - ### Headless bundle A headless bundle is a bundle that is configured to not get published @@ -128,7 +127,7 @@ Explanation of the above example: A leaf bundle can be made headless by adding below in the front matter (in the `index.md`): -{{< code-toggle file="content/headless/index.md" fm=true copy=false >}} +{{< code-toggle file=content/headless/index.md fm=true >}} headless = true {{< /code-toggle >}} @@ -149,17 +148,16 @@ Here `md` (markdown) is used just as an example. You can use any file type as a content resource as long as it is a content type recognized by Hugo. {{% /note %}} - ### Examples of branch bundle organization ```text content/ ├── branch-bundle-1 -│ ├── branch-content1.md -│ ├── branch-content2.md -│ ├── image1.jpg -│ ├── image2.png -│ └── _index.md +│ ├── branch-content1.md +│ ├── branch-content2.md +│ ├── image1.jpg +│ ├── image2.png +│ └── _index.md └── branch-bundle-2 ├── _index.md └── a-leaf-bundle @@ -169,11 +167,11 @@ content/ In the above example `content/` directory, there are two branch bundles (and a leaf bundle): -`branch-bundle-1` +branch-bundle-1 : This branch bundle has the `_index.md`, two other content Markdown files and two image files. -`branch-bundle-2` +branch-bundle-2 : This branch bundle has the `_index.md` and a nested leaf bundle. diff --git a/content/en/content-management/page-resources.md b/content/en/content-management/page-resources.md index bbf288459..f141510bb 100644 --- a/content/en/content-management/page-resources.md +++ b/content/en/content-management/page-resources.md @@ -7,8 +7,8 @@ menu: docs: parent: content-management weight: 80 -toc: true weight: 80 +toc: true --- Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or `_index.md` files at their root. Page resources are only available to the @@ -112,7 +112,6 @@ GetMatch .Resources.Match "*" 🚫 .Resources.Match "sunset.jpg" 🚫 .Resources.Match "*sunset.jpg" 🚫 - ``` ## Page resources metadata @@ -138,7 +137,7 @@ params ### Resources metadata example -{{< code-toggle copy=false >}} +{{< code-toggle >}} title: Application date : 2018-01-25 resources : @@ -184,7 +183,8 @@ The counter starts at 1 the first time they are used in either `name` or `title` For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as: -{{< code-toggle copy=false >}} +{{< code-toggle file=content/inspections/engine/index.md fm=true >}} +title = 'Engine inspections' [[resources]] src = "*specs.pdf" title = "Specification #:counter" diff --git a/content/en/content-management/related.md b/content/en/content-management/related.md index 42d577b95..e73dfc32a 100644 --- a/content/en/content-management/related.md +++ b/content/en/content-management/related.md @@ -7,8 +7,8 @@ menu: docs: parent: content-management weight: 110 -toc: true weight: 110 +toc: true aliases: [/content/related/,/related/] --- @@ -18,13 +18,13 @@ Hugo uses a set of factors to identify a page's related content based on front m To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template: -{{< code file="layouts/partials/related.html" >}} +{{< code file=layouts/partials/related.html >}} {{ $related := .Site.RegularPages.Related . | first 5 }} {{ with $related }} <h3>See Also</h3> <ul> {{ range . }} - <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> {{ end }} </ul> {{ end }} @@ -33,22 +33,25 @@ To list up to 5 related pages (which share the same _date_ or _keyword_ paramete The `Related` method takes one argument which may be a `Page` or a options map. The options map have these options: indices -: The indices to search in. +: (`slice`) The indices to search within. document -: The document to search for related content for. +: (`page`) The page for which to find related content. Required when specifying an options map. namedSlices -: The keywords to search for. +: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function. fragments -: Fragments holds a a list of special keywords that is used for indices configured as type "fragments". This will match the fragment identifiers of the documents. +: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment] identifiers of the documents. + +[fragment]: /getting-started/glossary/#fragment +[`keyVals`]: /functions/collections/keyvals/ A fictional example using all of the above options: ```go-html-template {{ $page := . }} -{{ $opts := +{{ $opts := dict "indices" (slice "tags" "keywords") "document" $page "namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date)) @@ -57,16 +60,16 @@ A fictional example using all of the above options: ``` {{% note %}} -We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndicies`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature. +We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndices`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature. {{% /note %}} ## Index content headings in related content -{{< new-in "0.111.0" >}} +{{< new-in 0.111.0 >}} Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [related] threshold = 20 includeNewer = true @@ -74,7 +77,7 @@ toLower = false [[related.indices]] name = "fragmentrefs" type = "fragments" -applyFilter = false +applyFilter = true weight = 80 {{< /code-toggle >}} @@ -88,7 +91,7 @@ weight = 80 <ul> {{ range $i, $p := . }} <li> - <a href="{{ .RelPermalink }}">{{ .Title }}</a> + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> {{ with .HeadingsFiltered }} <ul> {{ range . }} @@ -113,7 +116,7 @@ Hugo provides a sensible default configuration of Related Content, but you can f Without any `related` configuration set on the project, Hugo's Related Content methods will use the following. -{{< code-toggle config="related" />}} +{{< code-toggle config=related />}} Custom configuration should be set using the same syntax. @@ -124,37 +127,36 @@ If you add a `related` configuration section, you need to add a complete configu ### Top level configuration options threshold -: A value between 0-100. Lower value will give more, but maybe not so relevant, matches. +: (`int`) A value between 0-100. Lower value will give more, but maybe not so relevant, matches. includeNewer -: Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added. +: (`bool`) Set to `true` to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added. toLower -: Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index. +: (`bool`) Set to `true` to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index. ### Configuration options per index name -: The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. +: (`string`) The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. -type -: {{< new-in "0.111.0" >}}. One of `basic`(default) or `fragments`. +type {{< new-in 0.111.0 >}} +: (`string`) One of `basic`(default) or `fragments`. -applyFilter -: {{< new-in "0.111.0" >}}. Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type. +applyFilter {{< new-in 0.111.0 >}} +: (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type. weight -: An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. - +: (`int`) An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. -cardinalityThreshold (default 0) -: {{< new-in "0.111.0" >}}. A percentage (0-100) used to remove common keywords from the index. As an example, setting this to 50 will remove all keywords that are used in more than 50% of the documents in the index. +cardinalityThreshold {{< new-in 0.111.0 >}} +: (`int`) A percentage (0-100) used to remove common keywords from the index. As an example, setting this to `50` will remove all keywords that are used in more than 50% of the documents in the index. Default is `0`. pattern -: This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default. +: (`string`) This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default. toLower -: See above. +: (`bool`) See above. ## Performance considerations diff --git a/content/en/content-management/sections.md b/content/en/content-management/sections.md index a3e4397f3..1b694ce44 100644 --- a/content/en/content-management/sections.md +++ b/content/en/content-management/sections.md @@ -8,8 +8,8 @@ menu: docs: parent: content-management weight: 120 -toc: true weight: 120 +toc: true aliases: [/content/sections/] --- @@ -26,35 +26,35 @@ A typical site consists of one or more sections. For example: ```text content/ ├── articles/ <-- section (top-level directory) -│ ├── 2022/ -│ │ ├── article-1/ -│ │ │ ├── cover.jpg -│ │ │ └── index.md -│ │ └── article-2.md -│ └── 2023/ -│ ├── article-3.md -│ └── article-4.md +│ ├── 2022/ +│ │ ├── article-1/ +│ │ │ ├── cover.jpg +│ │ │ └── index.md +│ │ └── article-2.md +│ └── 2023/ +│ ├── article-3.md +│ └── article-4.md ├── products/ <-- section (top-level directory) -│ ├── product-1/ <-- section (has _index.md file) -│ │ ├── benefits/ <-- section (has _index.md file) -│ │ │ ├── _index.md -│ │ │ ├── benefit-1.md -│ │ │ └── benefit-2.md -│ │ ├── features/ <-- section (has _index.md file) -│ │ │ ├── _index.md -│ │ │ ├── feature-1.md -│ │ │ └── feature-2.md -│ │ └── _index.md -│ └── product-2/ <-- section (has _index.md file) -│ ├── benefits/ <-- section (has _index.md file) -│ │ ├── _index.md -│ │ ├── benefit-1.md -│ │ └── benefit-2.md -│ ├── features/ <-- section (has _index.md file) -│ │ ├── _index.md -│ │ ├── feature-1.md -│ │ └── feature-2.md -│ └── _index.md +│ ├── product-1/ <-- section (has _index.md file) +│ │ ├── benefits/ <-- section (has _index.md file) +│ │ │ ├── _index.md +│ │ │ ├── benefit-1.md +│ │ │ └── benefit-2.md +│ │ ├── features/ <-- section (has _index.md file) +│ │ │ ├── _index.md +│ │ │ ├── feature-1.md +│ │ │ └── feature-2.md +│ │ └── _index.md +│ └── product-2/ <-- section (has _index.md file) +│ ├── benefits/ <-- section (has _index.md file) +│ │ ├── _index.md +│ │ ├── benefit-1.md +│ │ └── benefit-2.md +│ ├── features/ <-- section (has _index.md file) +│ │ ├── _index.md +│ │ ├── feature-1.md +│ │ └── feature-2.md +│ └── _index.md ├── _index.md └── about.md ``` @@ -77,7 +77,7 @@ With the file structure from the [example above](#overview): 1. The articles/2022 and articles/2023 directories do not have list pages; they are not sections. -1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `.RegularPagesRecursive` collection instead of the `.Pages` collection in the list template. See [details](/variables/page/#page-collections). +1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `.RegularPagesRecursive` collection instead of the `.Pages` collection in the list template. See [details](/variables/page/#page-collections). 1. All directories in the products section have list pages; each directory is a section. @@ -106,8 +106,7 @@ If you need to use a different template for a subsection, specify `type` and/or ## Ancestors and descendants -A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview): - +A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview): ```text content/products/product-1/benefits/benefit-1.md @@ -117,16 +116,16 @@ The content file (benefit-1.md) has four ancestors: benefits, product-1, product For example, use the `.Ancestors` method to render breadcrumb navigation. -{{< code file="layouts/partials/breadcrumb.html" >}} +{{< code file=layouts/partials/breadcrumb.html >}} <nav aria-label="breadcrumb" class="breadcrumb"> <ol> {{ range .Ancestors.Reverse }} <li> - <a href="{{ .Permalink }}">{{ .LinkTitle }}</a> + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> </li> {{ end }} <li class="active"> - <a aria-current="page" href="{{ .Permalink }}">{{ .LinkTitle }}</a> + <a aria-current="page" href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> </li> </ol> </nav> @@ -154,7 +153,6 @@ Hugo renders this, where each breadcrumb is a link to the corresponding page: Home » Products » Product 1 » Benefits » Benefit 1 ``` - [archetype]: /content-management/archetypes/ [content type]: /content-management/types/ [directory structure]: /getting-started/directory-structure/ diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md index b1e32d902..bbc2b0cc8 100644 --- a/content/en/content-management/shortcodes.md +++ b/content/en/content-management/shortcodes.md @@ -7,8 +7,8 @@ menu: docs: parent: content-management weight: 100 -toc: true weight: 100 +toc: true aliases: [/extras/shortcodes/] testparam: "Hugo Rocks!" --- @@ -58,7 +58,6 @@ and a new line with a "quoted string".` */>}} Shortcodes using the `%` as the outer-most delimiter will be fully rendered when sent to the content renderer. This means that the rendered output from a shortcode can be part of the page's table of contents, footnotes, etc. - ### Shortcodes without markdown The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML: @@ -100,7 +99,7 @@ title : Image title. caption -: Image caption. Markdown within the value of `caption` will be rendered. +: Image caption. Markdown within the value of `caption` will be rendered. class : `class` attribute of the HTML `figure` tag. @@ -122,7 +121,7 @@ attrlink #### Example `figure` input -{{< code file="figure-input-example.md" >}} +{{< code file=figure-input-example.md >}} {{</* figure src="elephant.jpg" title="An elephant at sunset" */>}} {{< /code >}} @@ -131,7 +130,7 @@ attrlink ```html <figure> <img src="elephant.jpg"> - <figcaption>An elephant at sunset</figcaption> + <figcaption><h4>An elephant at sunset</h4></figcaption> </figure> ``` @@ -153,17 +152,17 @@ Include this in your markdown: This will display all files in the gist alphabetically by file name. -{{< gist jmooring 50a7482715eac222e230d1e64dd9a89b >}} +{{< gist jmooring 23932424365401ffa5e9d9810102a477 >}} To display a specific file within the gist: ```text -{{</* gist user 50a7482715eac222e230d1e64dd9a89b 1-template.html */>}} +{{</* gist user 23932424365401ffa5e9d9810102a477 list.html */>}} ``` Rendered: -{{< gist jmooring 50a7482715eac222e230d1e64dd9a89b 1-template.html >}} +{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}} ### `highlight` @@ -220,14 +219,14 @@ You must obtain an Access Token to use the `instagram` shortcode. If your site configuration is private: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [services.instagram] accessToken = 'xxx' {{< /code-toggle >}} If your site configuration is _not_ private, set the Access Token with an environment variable: -```text +```sh HUGO_SERVICES_INSTAGRAM_ACCESSTOKEN=xxx hugo --gc --minify ``` @@ -251,7 +250,7 @@ Include this in your markdown: Gets a value from the current `Page's` parameters set in front matter, with a fallback to the site parameter value. It will log an `ERROR` if the parameter with the given key could not be found in either. -```bash +```sh {{</* param testparam */>}} ``` @@ -261,7 +260,7 @@ Since `testparam` is a parameter defined in front matter of this page with the v To access deeply nested parameters, use "dot syntax", e.g: -```bash +```sh {{</* param "my.nested.param" */>}} ``` @@ -289,7 +288,7 @@ Read a more extensive description of `ref` and `relref` in the [cross references Assuming that standard Hugo pretty URLs are turned on. ```html -<a href="https://example.com/blog/neat">Neat</a> +<a href="https://example.org/blog/neat">Neat</a> <a href="/about/#who">Who</a> ``` @@ -349,20 +348,19 @@ https://www.youtube.com/watch?v=w7Ft2ymGmfc Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode: -{{< code file="example-youtube-input.md" >}} +{{< code file=example-youtube-input.md >}} {{</* youtube w7Ft2ymGmfc */>}} {{< /code >}} Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named and unnamed parameters, so you'll need to assign the yet unnamed video ID to the parameter `id`: - -{{< code file="example-youtube-input-with-autoplay.md" >}} +{{< code file=example-youtube-input-with-autoplay.md >}} {{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}} {{< /code >}} -For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video. You can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used. +For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video. You can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used. -{{< code file="example-youtube-input-with-title.md" >}} +{{< code file=example-youtube-input-with-title.md >}} {{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}} {{< /code >}} @@ -370,7 +368,7 @@ For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titl Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup: -{{< code file="example-youtube-output.html" >}} +{{< code file=example-youtube-output.html >}} {{< youtube id="w7Ft2ymGmfc" autoplay="true" >}} {{< /code >}} @@ -398,7 +396,7 @@ To learn more about creating custom shortcodes, see the [shortcode template docu [partials]: /templates/partials/ [quickstart]: /getting-started/quick-start/ [sctemps]: /templates/shortcode-templates/ -[scvars]: /variables/shortcodes/ +[scvars]: /variables/shortcode/ [shortcode template documentation]: /templates/shortcode-templates/ [templatessection]: /templates/ [Vimeo]: https://vimeo.com/ diff --git a/content/en/content-management/static-files.md b/content/en/content-management/static-files.md index 78772af99..c1197ede1 100644 --- a/content/en/content-management/static-files.md +++ b/content/en/content-management/static-files.md @@ -7,8 +7,8 @@ menu: docs: parent: content-management weight: 200 -toc: true weight: 200 +toc: true aliases: [/static-files] --- @@ -27,13 +27,13 @@ This union filesystem will be served from your site root. So a file Here's an example of setting `staticDir` and `staticDir2` for a multi-language site: -{{< code-toggle copy=false file="hugo" >}} +{{< code-toggle file=hugo >}} staticDir = ["static1", "static2"] [languages] [languages.en] staticDir2 = "static_en" -baseURL = "https://example.com" +baseURL = "https://example.org/" languageName = "English" weight = 2 title = "In English" diff --git a/content/en/content-management/summaries.md b/content/en/content-management/summaries.md index 74c5623cb..2ff1fec34 100644 --- a/content/en/content-management/summaries.md +++ b/content/en/content-management/summaries.md @@ -8,11 +8,13 @@ menu: docs: parent: content-management weight: 160 -toc: true weight: 160 +toc: true aliases: [/content/summaries/,/content-management/content-summaries/] --- +<!--more--> + With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views. ## Summary splitting options @@ -37,7 +39,7 @@ The Hugo-defined summaries are set to use word count calculated by splitting the ### Manual summary splitting -Alternatively, you may add the <code><!--more--></code> summary divider where you want to split the article. +Alternatively, you may add the `<!--more-->` summary divider where you want to split the article. For [Org mode content][org], use `# more` where you want to split the article. @@ -48,42 +50,42 @@ The concept of a *summary divider* is not unique to Hugo. It is also called the {{% /note %}} Pros -: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved. +: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved. Cons -: Extra work for content authors, since they need to remember to type <code><!--more--></code> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/). +: Extra work for content authors, since they need to remember to type `<!--more-->` (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/). -{{% warning "Be Precise with the Summary Divider" %}} -Be careful to enter <code><!--more--></code> exactly; i.e., all lowercase and with no whitespace. +{{% note %}} +Be careful to enter `<!--more-->` exactly; i.e., all lowercase and with no whitespace. {{% /note %}} ### Front matter summary -You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter. +You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter. Pros -: Complete freedom of text independent of the content of the article. Markup can be used within the summary. +: Complete freedom of text independent of the content of the article. Markup can be used within the summary. Cons : Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article. ## Summary selection order -Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`. It is as follows: +Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`. It is as follows: -1. If there is a <code><!--more--></code> summary divider present in the article the text up to the divider will be provided as per the manual summary split method +1. If there is a `<!--more-->`> summary divider present in the article the text up to the divider will be provided as per the manual summary split method 2. If there is a `summary` variable in the article front matter the value of the variable will be provided as per the front matter summary method 3. The text at the start of the article will be provided as per the automatic summary split method -{{% warning "Competing selections" %}} -Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a <code><!--more--></code> summary divider Hugo will use the manual summary split method. +{{% note %}} +Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a `<!--more-->` summary divider Hugo will use the manual summary split method. {{% /note %}} ## Example: first 10 articles with summaries You can show content summaries with the following code. You could use the following snippet, for example, in a [section template]. -{{< code file="page-list-with-summaries.html" >}} +{{< code file=page-list-with-summaries.html >}} {{ range first 10 .Pages }} <article> <!-- this <div> includes the title summary --> diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md index 39fef0f9b..62071cd46 100644 --- a/content/en/content-management/syntax-highlighting.md +++ b/content/en/content-management/syntax-highlighting.md @@ -1,14 +1,14 @@ --- title: Syntax highlighting description: Hugo comes with really fast syntax highlighting from Chroma. -keywords: [highlighting,chroma,code blocks,syntax] categories: [content management] +keywords: [highlighting,chroma,code blocks,syntax] menu: docs: parent: content-management weight: 240 -toc: true weight: 240 +toc: true aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/] --- @@ -24,7 +24,7 @@ If you run with `markup.highlight.noClasses=false` in your site configuration, y You can generate one with Hugo: -```bash +```sh hugo gen chromastyles --style=monokai > syntax.css ``` @@ -41,7 +41,7 @@ Options: * `linenostart=199`: starts the line number count from 199. * `anchorlinenos`: Configure anchors on line numbers. Valid values are `true` or `false`; * `lineanchors`: Configure a prefix for the anchors on line numbers. Will be suffixed with `-`, so linking to the line number 1 with the option `lineanchors=prefix` adds the anchor `prefix-1` to the page. -* `hl_inline` Highlight inside a `<code>` (inline HTML element) tag. Valid values are `true` or `false`. The `code` tag will get a class with name `code-inline`. {{< new-in "0.101.0" >}} +* `hl_inline` Highlight inside a `<code>` (inline HTML element) tag. Valid values are `true` or `false`. The `code` tag will get a class with name `code-inline`. {{< new-in 0.101.0 >}} ### Example: highlight shortcode @@ -104,7 +104,6 @@ Highlighting in code fences is enabled by default. ``` ```` - Gives this: ```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199} diff --git a/content/en/content-management/taxonomies.md b/content/en/content-management/taxonomies.md index af8297876..94f2f6357 100644 --- a/content/en/content-management/taxonomies.md +++ b/content/en/content-management/taxonomies.md @@ -1,14 +1,14 @@ --- title: Taxonomies description: Hugo includes support for user-defined taxonomies. -keywords: [taxonomies,metadata,front matter,terms] categories: [content management] +keywords: [taxonomies,metadata,front matter,terms] menu: docs: parent: content-management weight: 150 -toc: true weight: 150 +toc: true aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes] --- @@ -27,7 +27,6 @@ Term Value : a piece of content assigned to a term - ## Example taxonomy: movie website Let's assume you are making a website about movies. You may want to include the following taxonomies: @@ -82,15 +81,15 @@ Hugo natively supports taxonomies. Without adding a single line to your [site configuration] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be the same as manually [configuring your taxonomies](#configure-taxonomies) as below: -{{< code-toggle config="taxonomies" />}} +{{< code-toggle config=taxonomies />}} If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site configuration] to the following: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} disableKinds = ["taxonomy","term"] {{</ code-toggle >}} -{{% page-kinds %}} +{{% include "content-management/_common/page-kinds.md" %}} ### Default destinations @@ -109,7 +108,7 @@ Custom taxonomies other than the [defaults](#default-taxonomies) must be defined While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_. {{% /note %}} -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [taxonomies] tag = "tags" category = "categories" @@ -120,7 +119,7 @@ While adding custom taxonomies, you need to put in the default taxonomies too, _ If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so by modifying the `taxonomies` value in your [site configuration]. -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [taxonomies] tag = "tags" {{</ code-toggle >}} @@ -129,14 +128,6 @@ If you want to disable all taxonomies altogether, see the use of `disableKinds` {{% note %}} You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose. - -Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not. -{{% /note %}} - -{{% note %}} -The configuration option `preserveTaxonomyNames` was removed in Hugo 0.55. - -You can now use `.Page.Title` on the relevant taxonomy node to get the original value. {{% /note %}} ## Add taxonomies to content @@ -151,7 +142,7 @@ If you would like the ability to quickly generate content files with preconfigur ### Example: front matter with taxonomies -{{< code-toggle file="content/example.md" fm=true copy=false >}} +{{< code-toggle file=content/example.md fm=true >}} title = "Hugo: A fast and flexible static site generator" tags = [ "Development", "Go", "fast", "Blogging" ] categories = [ "Development" ] @@ -168,7 +159,7 @@ The following show a piece of content that has a weight of 22, which can be used ### Example: taxonomic `weight` -{{< code-toggle copy=false >}} +{{< code-toggle >}} title = "foo" tags = [ "a", "b", "c" ] tags_weight = 22 @@ -178,15 +169,11 @@ categories_weight = 44 By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies. -{{% note %}} -Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight--date--linktitle--filepath). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/). -{{% /note %}} - ## Add custom metadata to a taxonomy or term If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter. Continuing with our 'Actors' example, let's say you want to add a Wikipedia page link to each actor. Your terms pages would be something like this: -{{< code-toggle file="content/actors/bruce-willis/_index.md" fm=true copy=false >}} +{{< code-toggle file=content/actors/bruce-willis/_index.md fm=true >}} title: "Bruce Willis" wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis" {{< /code-toggle >}} diff --git a/content/en/content-management/toc.md b/content/en/content-management/toc.md index ca179c77d..69021ac45 100644 --- a/content/en/content-management/toc.md +++ b/content/en/content-management/toc.md @@ -7,8 +7,8 @@ menu: docs: parent: content-management weight: 210 -toc: true weight: 210 +toc: true aliases: [/extras/toc/] --- @@ -37,7 +37,7 @@ He lay on his armour-like back, and if he lifted his head a little he could see ### My Subheading -A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops +A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops ``` Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`. @@ -48,7 +48,7 @@ The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">` The following is an example of a very basic [single page template]: -{{< code file="layout/_default/single.html" >}} +{{< code file=layout/_default/single.html >}} {{ define "main" }} <main> <article> @@ -68,7 +68,7 @@ The following is an example of a very basic [single page template]: The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals] in your templating: -{{< code file="layouts/partials/toc.html" >}} +{{< code file=layouts/partials/toc.html >}} {{ if and (gt .WordCount 400 ) (.Params.toc) }} <aside> <header> @@ -105,8 +105,9 @@ He lay on his armour-like back, and if he lifted his head a little he could see === My Subheading -A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops +A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops ``` + Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown. [conditionals]: /templates/introduction/#conditionals diff --git a/content/en/content-management/types.md b/content/en/content-management/types.md index e72361f1c..67dbe1596 100644 --- a/content/en/content-management/types.md +++ b/content/en/content-management/types.md @@ -2,13 +2,13 @@ title: Content types description: Hugo is built around content organized in sections. categories: [content management] -keywords: [lists, sections, content types, types, organization] +keywords: [lists,sections,content types,types,organization] menu: docs: parent: content-management weight: 130 -toc: true weight: 130 +toc: true aliases: [/content/types] --- diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md index 60f9615b8..a91fe21c0 100644 --- a/content/en/content-management/urls.md +++ b/content/en/content-management/urls.md @@ -7,8 +7,8 @@ menu: docs: parent: content-management weight: 180 -toc: true weight: 180 +toc: true aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/] --- @@ -28,7 +28,7 @@ You can change the structure and appearance of URLs with front matter values and Set the `slug` in front matter to override the last segment of the path. The `slug` value does not affect section pages. -{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}} +{{< code-toggle file=content/posts/post-1.md fm=true >}} title = 'My First Post' slug = 'my-first-post' {{< /code-toggle >}} @@ -45,7 +45,7 @@ Set the `url` in front matter to override the entire path. Use this with either With this front matter: -{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}} +{{< code-toggle file=content/posts/post-1.md fm=true >}} title = 'My First Article' url = '/articles/my-first-article' {{< /code-toggle >}} @@ -58,7 +58,7 @@ https://example.org/articles/my-first-article/ If you include a file extension: -{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}} +{{< code-toggle file=content/posts/post-1.md fm=true >}} title = 'My First Article' url = '/articles/my-first-article.html' {{< /code-toggle >}} @@ -112,7 +112,7 @@ content/ Render tutorials under "training", and render the posts under "articles" with a date-base hierarchy: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [permalinks.page] posts = '/articles/:year/:month/:slug/' tutorials = '/training/:slug/' @@ -145,14 +145,14 @@ public/ To create a date-based hierarchy for regular pages in the content root: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [permalinks.page] "/" = "/:year/:month/:slug/" {{< /code-toggle >}} Use the same approach with taxonomy terms. For example, to omit the taxonomy segment of the URL: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [permalinks.term] 'tags' = '/:slug/' {{< /code-toggle >}} @@ -179,7 +179,7 @@ content/ And this site configuration: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} defaultContentLanguage = 'en' defaultContentLanguageInSubdir = true @@ -280,7 +280,7 @@ For time-related values, you can also use the layout string components defined i [time package]: https://pkg.go.dev/time#pkg-constants -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} permalinks: posts: /:06/:1/:2/:title/ {{< /code-toggle >}} @@ -296,7 +296,7 @@ pretty|content/about.md|`https://example.org/about/` By default, Hugo produces pretty URLs. To generate ugly URLs, change your site configuration: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} uglyURLs = true {{< /code-toggle >}} @@ -314,7 +314,7 @@ This is a legacy configuration option, superseded by template functions and mark If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then prepends the `baseURL` to create absolute URLs. -```text +```html <a href="/about"> → <a href="https://example.org/about/"> <img src="/a.gif"> → <img src="https://example.org/a.gif"> ``` @@ -323,7 +323,7 @@ This is an imperfect, brute force approach that can affect content as well as HT To enable: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} canonifyURLs = true {{< /code-toggle >}} @@ -337,7 +337,7 @@ If enabled, Hugo performs a search and replace _after_ it renders the page. It s For example, when rendering `content/posts/post-1`: -```text +```html <a href="/about"> → <a href="../../about"> <img src="/a.gif"> → <img src="../../a.gif"> ``` @@ -346,7 +346,7 @@ This is an imperfect, brute force approach that can affect content as well as HT To enable: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} relativeURLs = true {{< /code-toggle >}} @@ -361,7 +361,7 @@ Create redirects from old URLs to new URLs with aliases: Change the file name of an existing page, and create an alias from the previous URL to the new URL: -{{< code-toggle file="content/posts/new-file-name.md" copy=false >}} +{{< code-toggle file=content/posts/new-file-name.md >}} aliases = ['/posts/previous-file-name'] {{< /code-toggle >}} @@ -373,13 +373,13 @@ Each of these directory-relative aliases is equivalent to the site-relative alia You can create more than one alias to the current page: -{{< code-toggle file="content/posts/new-file-name.md" copy=false >}} +{{< code-toggle file=content/posts/new-file-name.md >}} aliases = ['previous-file-name','original-file-name'] {{< /code-toggle >}} In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias: -{{< code-toggle file="content/posts/new-file-name.de.md" copy=false >}} +{{< code-toggle file=content/posts/new-file-name.de.md >}} aliases = ['/de/posts/previous-file-name'] {{< /code-toggle >}} @@ -400,7 +400,7 @@ public/ The alias from the previous URL to the new URL is a client-side redirect: -{{< code file="posts/previous-file-name/index.html" copy=false >}} +{{< code file=posts/previous-file-name/index.html >}} <!DOCTYPE html> <html lang="en-us"> <head> @@ -425,8 +425,8 @@ Hugo renders alias files before rendering pages. A new page with the previous fi Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context: -`Permalink` +Permalink : the link to the page being aliased -`Page` +Page : the Page data for the page being aliased diff --git a/content/en/contribute/_index.md b/content/en/contribute/_index.md index 77a5cdb4d..ca7a18c36 100644 --- a/content/en/contribute/_index.md +++ b/content/en/contribute/_index.md @@ -1,8 +1,8 @@ --- title: Contribute to the Hugo project linkTitle: Overview -description: Contribute to Hugo development and documentation. -categories: [contribute] +description: Contribute to Hugo development, documentation, and themes. +categories: [] keywords: [] menu: docs: @@ -13,6 +13,4 @@ weight: 10 aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/] --- -Hugo relies heavily on the enthusiasm and participation of the open-source community. We need your support in both its development and documentation. - -Hugo's contribution guidelines are [detailed in a `CONTRIBUTING.md`](https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md) in the Hugo source repository on GitHub. +Hugo relies heavily on the enthusiasm and participation of the open-source community. We need your support. diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md index 7bc201288..b4de88256 100644 --- a/content/en/contribute/development.md +++ b/content/en/contribute/development.md @@ -1,9 +1,8 @@ --- -title: Contribute to development -linkTitle: Development -description: Hugo relies heavily on contributions from the open source community. +title: Development +description: Contribute to the development of Hugo. categories: [contribute] -keywords: [dev,open source] +keywords: [development] menu: docs: parent: contribute @@ -61,7 +60,7 @@ You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty strin If you are a macOS user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command: -{{< code file="install-go.sh" >}} +{{< code file=install-go.sh >}} brew install go {{< /code >}} @@ -313,7 +312,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 %}} @@ -326,7 +325,7 @@ git rebase --interactive @~6 The `6` at the end of the command represents the number of commits that should be modified. An editor should open and present a list of last six commit messages: ```txt -pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick 80d02a1 tpl: Add hasPrefix to template function smoke test" pick aaee038 tpl: Sort the smoke tests pick f0dbf2c tpl: Add the other test case for hasPrefix pick 911c35b Add "How to contribute to Hugo" tutorial @@ -339,7 +338,7 @@ In the case above we should merge the last two commits in the commit of this tut All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short: ```txt -pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick 80d02a1 tpl: Add hasPrefix to template function smoke test" pick aaee038 tpl: Sort the smoke tests pick f0dbf2c tpl: Add the other test case for hasPrefix pick 911c35b Add "How to contribute to Hugo" tutorial @@ -352,7 +351,7 @@ We also want to rewrite the commits message of the third last commit. We forgot You should end up with a similar setup: ```txt -pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick 80d02a1 tpl: Add hasPrefix to template function smoke test" pick aaee038 tpl: Sort the smoke tests pick f0dbf2c tpl: Add the other test case for hasPrefix reword 911c35b Add "How to contribute to Hugo" tutorial diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index 03939f837..14df5cdee 100644 --- a/content/en/contribute/documentation.md +++ b/content/en/contribute/documentation.md @@ -1,70 +1,110 @@ --- -title: Contribute to documentation -linkTitle: Documentation -description: Documentation is an integral part of any open source project. The Hugo documentation is as much a work in progress as the source it attempts to cover. +title: Documentation +description: Help us to improve the documentation by identifying issues and suggesting changes. categories: [contribute] -keywords: [docs,documentation,community, contribute] +keywords: [documentation] menu: docs: parent: contribute weight: 30 -toc: true weight: 30 +toc: true aliases: [/contribute/docs/] --- -## GitHub workflow +## Introduction -Step 1 -: Fork the [documentation repository]. +We welcome corrections and improvements to the documentation. Please note that the documentation resides in its own repository, separate from the project repository. -Step 2 -: Clone your fork. +For corrections and improvements to the current documentation, please submit issues and pull requests to the [documentation repository]. -Step 3 -: Create a new branch with a descriptive name. +For documentation related to a new feature, please include the documentation changes when you submit a pull request to the [project repository]. -```bash -git checkout -b fix/typos-site-variables -``` +## Guidelines -Step 4 -: Make changes. +### Markdown -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]. +Please follow these markdown guidelines: -```bash -git commit -m "Fix typos on site variables page +- Use [ATX] headings, not [setext] headings, levels 2 through 4 +- Use [fenced code blocks], not [indented code blocks] +- Use hyphens, not asterisks, with unordered [list items] +- Use the [note shortcode] instead of blockquotes +- Do not mix [raw HTML] within markdown +- Do not use bold text instead of a heading or description term (`dt`) +- Remove consecutive blank lines (maximum of two) +- Remove trailing spaces -Closes #1234 -Closes #5678" -``` +### Style -Step 5 -: Push the new branch to your fork of the documentation repository. +Although we do not strictly adhere to the [Microsoft Writing Style Guide], it is an excellent resource for questions related to style, grammar, and voice. -Step 6 -: Visit the [documentation repository] and create a pull request (PR). +#### Terminology -[documentation repository]: https://github.com/gohugoio/hugoDocs/ -[issues]: https://github.com/gohugoio/hugoDocs/issues +Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note: -Step 7 -: A project maintainer will review your PR, and may request changes. You may delete your branch after the maintainer merges your PR. +- The term "front matter" is two words unless you are referring to the configuration key +- Use the word "map" instead of "dictionary" +- Use the word "flag" instead of "option" when referring to a command line flag -## Including sample code +#### Page titles and headings -{{% note %}} -Use this syntax to include shortcodes calls within your code samples: +Please follow these guidelines for page titles and headings: + +- Use sentence-style capitalization +- Avoid markdown in headings and page titles +- Shorter is better + +#### Use active voice with present tense + +In software documentation, passive voice is unavoidable in some cases. Please use active voice when possible. + +No → With Hugo you can build a static site.\ +Yes → Build a static site with Hugo. + +No → This will cause Hugo to generate HTML files in the public directory.\ +Yes → Hugo generates HTML files in the public directory. + +#### Use second person instead of third person + +No → Users should exercise caution when deleting files.\ +Better → You must be cautious when deleting files.\ +Best → Be cautious when deleting files. + +#### Avoid adverbs when possible -`{{</*/* foo */*/>}}`\ -`{{%/*/* foo */*/%}}` +No → Hugo is extremely fast.\ +Yes → Hugo is fast. + +{{% note %}} +"It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995). {{% /note %}} +#### Miscellaneous + +Other guidelines to consider: + +- Do not place list items directly under a heading; include an introductory sentence or phrase before the list. +- Avoid use of **bold** text. Use the [note shortcode] to draw attention to important content. +- Do not place description terms (`dt`) within backticks unless required for syntactic clarity. +- Do not use Hugo's `ref` or `relref` shortcodes. We use a link render hook to resolve and validate link destinations, including fragments. +- Shorter is better. If there is more than one way to do something, describe the current best practice. For example, avoid phrases such as "you can also do..." and "in older versions you had to..." +- When including code samples, use short snippets that demonstrate the concept. +- The Hugo user community is global; use [basic english](https://simple.wikipedia.org/wiki/Basic_English) when possible. + +#### Level 6 markdown headings + +Level 6 markdown headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms. + +[glossary]: /getting-started/glossary + +## Code examples + +Indent code by two spaces. With examples of template code, include a space after opening action delimiters, and include a space before closing action delimeters. + ### Fenced code blocks -Include the language when using a fenced code block. +Always include the language code when using a fenced code block: ````text ```go-html-template @@ -82,95 +122,254 @@ Rendered: {{ end }} ``` -### The code shortcode +### Shortcode calls -Use the `code` shortcode to include the file name and a copy-to-clipboard button. This shortcode accepts these optional parameters: +Use this syntax to include shortcodes calls within your code examples: -copy -: (`bool`) If `true`, displays a copy-to-clipboard button. Default is `true`. +```text +{{</*/* foo */*/>}} +{{%/*/* foo */*/%}} +``` -file -: (`string`) The file name to display. If you do not provide a `lang` parameter, the file extension determines the code language. +Rendered: -lang -: (`string`) The code language. Default is `text`. +```text +{{</* foo */>}} +{{%/* foo */%}} +``` -````text -{{</* code file="layouts/_default_/single.html" */>}} -{{ if eq $foo "bar" }} - {{ print "foo is bar" }} +### Site configuration + +Use the [code-toggle shortcode] to include site configuration examples: + +```text +{{</* code-toggle file=hugo */>}} +baseURL = 'https://example.org/' +languageCode = 'en-US' +title = 'My Site' +{{</* /code-toggle */>}} +``` + +Rendered: + +{{< code-toggle file=hugo >}} +baseURL = 'https://example.org/' +languageCode = 'en-US' +title = 'My Site' +{{< /code-toggle >}} + +### Front matter + +Use the [code-toggle shortcode] to include front matter examples: + +```text +{{</* code-toggle file=content/posts/my-first-post.md fm=true */>}} +title = 'My first post' +date = 2023-11-09T12:56:07-08:00 +draft = false +{{</* /code-toggle */>}} +``` + +Rendered: + +{{< code-toggle file=content/posts/my-first-post.md fm=true >}} +title = 'My first post' +date = 2023-11-09T12:56:07-08:00 +draft = false +{{< /code-toggle >}} + +### Other code examples + +Use the [code shortcode] for other code examples that require a file name: + +```text +{{</* code file=layouts/_default/single.html */>}} +{{ range .Site.RegularPages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} {{</* /code */>}} - -```` +``` Rendered: -{{< code file="layouts/_default_/single.html" >}} -{{ if eq $foo "bar" }} - {{ print "foo is bar" }} +{{< code file=layouts/_default/single.html >}} +{{ range .Site.RegularPages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} {{< /code >}} -### The code-toggle shortcode +## Shortcodes + +These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use. + +### deprecated-in + +Use the “deprecated-in” shortcode to indicate that a feature is deprecated: + +```text +{{%/* deprecated-in 0.120.0 */%}} +Use [`hugo.IsServer`] instead. + +[`hugo.IsServer`]: /functions/hugo/isserver +{{%/* /deprecated-in */%}} +``` + +Rendered: + +{{% deprecated-in 0.120.0 %}} +Use [`hugo.IsServer`] instead. + +[`hugo.IsServer`]: /functions/hugo/isserver +{{% /deprecated-in %}} + +### code + +Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments: + +copy +: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`. + +file +: (`string`) The file name to display. + +lang +: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is "html", sets the code language to `go-html-template`. Default is `text`. + +### code-toggle -Use the `code-toggle` shortcode to display examples of site configuration, front matter, or data files. This shortcode accepts these optional parameters: +Use the "code-toggle" shortcode to display examples of site configuration, front matter, or data files. See the [code examples] above. This shortcode takes these arguments: copy -: (`bool`) If `true`, displays a copy-to-clipboard button. Default is `true`. +: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`. file -: (`string`) The file name to display. Omit the file extension for site configuration and data file examples. +: (`string`) The file name to display. Omit the file extension for site configuration examples. fm -: (`bool`) If `true`, displays the code as front matter. Default is `false`. +: (`bool`) Whether the example is front matter. Default is `false`. + +### new-in -#### Site configuration example +Use the "new-in" shortcode to indicate a new feature: ```text -{{</* code-toggle file="hugo" */>}} -baseURL = 'https://example.org' -languageCode = 'en-US' -title = "Example Site" -{{</* /code-toggle */>}} +{{</* new-in 0.120.0 */>}} ``` Rendered: -{{< code-toggle file="hugo" >}} -baseURL = 'https://example.org' -languageCode = 'en-US' -title = "Example Site" -{{< /code-toggle >}} +{{< new-in 0.120.0 >}} -#### Front matter example +### note + +Use the "note" shortcode with `{{%/* */%}}` delimiters to call attention to important content: ```text -{{</* code-toggle file="content/about.md" fm=true */>}} -title = "About" -date = 2023-04-02T12:47:24-07:00 -draft = false -{{</* /code-toggle */>}} +{{%/* note */%}} +Use the [`math.Mod`] function to control... + +[`math.Mod`]: /functions/math/mod/ +{{%/* /code */%}} ``` Rendered: -{{< code-toggle file="content/about.md" fm=true >}} -title = "About" -date = 2023-04-02T12:47:24-07:00 -draft = false +{{% note %}} +Use the [`math.Mod`] function to control... + +[`math.Mod`]: /functions/math/mod/ +{{% /code %}} + +## New features + +Use the "new-in" shortcode to indicate a new feature: + +{{< code file=content/something/foo.md lang=text >}} +{{</* new-in 0.120.0 */>}} +{{< /code >}} + +The "new in" label will be hidden if the specified version is older than a predefined threshold, based on differences in major and minor versions. See [details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/new-in.html). + +## Deprecated features + +Use the "deprecated-in" shortcode to indicate that a feature is deprecated: + +{{< code file=content/something/foo.md >}} +{{%/* deprecated-in 0.120.0 */%}} +Use [`hugo.IsServer`] instead. + +[`hugo.IsServer`]: /functions/hugo/isserver +{{%/* /deprecated-in */%}} +{{< /code >}} + +When deprecating a function or method, add this to front matter: + +{{< code-toggle file=content/something/foo.md fm=true >}} +expiryDate: 2024-10-30 +_build: + list: never {{< /code-toggle >}} -## Admonitions +Set the `expiryDate` to one year from the date of deprecation, and add a brief front matter comment to explain the settings. -Use the `note` shortcode to draw attention to content. Use the `{{%/* */%}}` notation when calling this shortcode. +Users will be able to search for the page, but the page will not appear in any list views, including section menus. -```text -{{%/* note */%}} -This is **bold** text. -{{%/* /note */%}} -``` +## GitHub workflow {{% note %}} -This is **bold** text. +This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line. {{% /note %}} + +Use this workflow to create and submit pull requests. + +Step 1 +: Fork the [documentation repository]. + +Step 2 +: Clone your fork. + +Step 3 +: Create a new branch with a descriptive name. + +```sh +git checkout -b fix/typos-shortcode-templates +``` + +Step 4 +: Make changes. + +Step 5 +: Commit your changes with a descriptive commit message, typically 50 characters or less. Add the "Closes" keyword if your change addresses one or more open [issues]. + +```sh +git commit -m "Fix typos on the shortcode templates page + +Closes #1234 +Closes #5678" +``` + +Step 5 +: Push the new branch to your fork of the documentation repository. + +Step 6 +: Visit the [documentation repository] and create a pull request (PR). + +Step 7 +: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR. + +[ATX]: https://spec.commonmark.org/0.30/#atx-headings +[Microsoft Writing Style Guide]: https://learn.microsoft.com/en-us/style-guide/welcome/ +[basic english]: https://simple.wikipedia.org/wiki/Basic_English +[code examples]: #code-examples +[code shortcode]: #code +[code-toggle shortcode]: #code-toggle +[documentation repository]: https://github.com/gohugoio/hugoDocs/ +[fenced code blocks]: https://spec.commonmark.org/0.30/#fenced-code-blocks +[glossary of terms]: /getting-started/glossary/ +[indented code blocks]: https://spec.commonmark.org/0.30/#indented-code-blocks +[issues]: https://github.com/gohugoio/hugoDocs/issues +[list items]: https://spec.commonmark.org/0.30/#list-items +[note shortcode]: #note +[project repository]: https://github.com/gohugoio/hugo +[raw HTML]: https://spec.commonmark.org/0.30/#raw-html +[setext]: https://spec.commonmark.org/0.30/#setext-heading diff --git a/content/en/contribute/themes.md b/content/en/contribute/themes.md index 0371f7f8c..34056c35a 100644 --- a/content/en/contribute/themes.md +++ b/content/en/contribute/themes.md @@ -1,24 +1,30 @@ --- -title: Add your hugo theme to the showcase -linkTitle: Themes -description: If you've built a Hugo theme and want to contribute back to the Hugo Community, share it with us. +title: Themes +description: If you've built a Hugo theme and want to contribute back to the Hugo Community, please share it with us. categories: [contribute] -keywords: [contribute,themes,design] +keywords: [themes] menu: docs: parent: contribute weight: 40 weight: 40 aliases: [/contribute/theme/] -toc: true --- -A collection of all themes created by the Hugo community, including screenshots and demos, can be found at [themes.gohugo.io]. Every theme in this list will automatically be added to the theme site. +Visit [themes.gohugo.io] to browse a collection of themes created by the Hugo community. -Another great site for Hugo themes is [jamstackthemes.dev/](https://jamstackthemes.dev/ssg/hugo/). +To submit your theme: -### Add your theme to the repository +1. Read the [submission guidelines] +2. Open a pull request in the [themes repository] -In order to add your Hugo theme to [themes.gohugo.io] please [open a pull request in the theme repository](https://github.com/gohugoio/hugoThemesSiteBuilder). **Please make sure that you've read the theme submission guidelines in the [README](https://github.com/gohugoio/hugoThemesSiteBuilder/blob/main/README.md#hugo-themes) of the hugoThemesSiteBuilder repository.** +Other useful theme directories: +- [jamstack.club] +- [jamstackthemes.dev] + +[jamstack.club]: https://jamstack.club/#ssg=hugo +[jamstackthemes.dev]: https://jamstackthemes.dev/ssg/hugo +[submission guidelines]: https://github.com/gohugoio/hugoThemesSiteBuilder/tree/main#readme +[themes repository]: https://github.com/gohugoio/hugoThemesSiteBuilder [themes.gohugo.io]: https://themes.gohugo.io/ 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" >}} -<ul class="most-popular-tags"> -{{ $t := .Site.GetPage "/tags" }} -{{ range first 2 $t.Data.Terms.ByCount }} - <li>{{ . }}</li> -{{ end }} -</ul> -{{< /code >}} - -## `.GetPage` on page bundles - -If the page retrieved by `.GetPage` is a [Leaf Bundle][leaf_bundle], and you -need to get the nested _**page** resources_ in that, you will need to use the -methods in `.Resources` as explained in the [Page Resources][page_resources] -section. - -See the [Headless Bundle][headless_bundle] documentation for an example. - - -[partials]: /templates/partials/ -[taxonomy]: /content-management/taxonomies/ -[page_kinds]: /templates/section-templates/#page-kinds -[leaf_bundle]: /content-management/page-bundles/#leaf-bundles -[headless_bundle]: /content-management/page-bundles/#headless-bundle -[page_resources]: /content-management/page-resources/ 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 `<p></p>` on short snippets will be trimmed. - -markup (defaults to the Page's markup) -: See identifiers in [List of content formats](/content-management/formats/#list-of-content-formats). - -Some examples: - -```go-html-template -{{ $optBlock := dict "display" "block" }} -{{ $optOrg := dict "markup" "org" }} -{{ "**Bold Markdown**" | $p.RenderString }} -{{ "**Bold Block Markdown**" | $p.RenderString $optBlock }} -{{ "/italic org mode/" | $p.RenderString $optOrg }} -``` - -{{< new-in "0.93.0" >}} **Note**: [markdownify](/functions/transform/markdownify) uses this function in order to support [Render Hooks](/getting-started/configuration-markup/#markdown-render-hooks). 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 +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/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..f82f029d5 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] --- @@ -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..0cf25c7dd 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] --- @@ -22,10 +17,20 @@ The following shows `after` being used in conjunction with the [`slice`]function ```go-html-template {{ $data := slice "one" "two" "three" "four" }} -{{ range after 2 $data }} - {{ . }} -{{ end }} -→ ["three", "four"] +<ul> + {{ range after 2 $data }} + <li>{{ . }}</li> + {{ end }} +</ul> +``` + +The template above is rendered to: + +```html +<ul> + <li>three</li> + <li>four</li> +</ul> ``` ## Example of `after` with `first`: 2nd–4th most recent articles @@ -35,32 +40,32 @@ You can use `after` in combination with the [`first`] function and Hugo's [power 1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter). 2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles. -{{< code file="layouts/section/articles.html" >}} +{{< code file=layouts/section/articles.html >}} {{ define "main" }} -<section class="row featured-article"> - <h2>Featured Article</h2> - {{ range first 1 .Pages.ByPublishDate.Reverse }} - <header> - <h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3> - </header> - <p>{{ .Description }}</p> -{{ end }} -</section> -<div class="row recent-articles"> - <h2>Recent Articles</h2> - {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }} - <section class="recent-article"> - <header> - <h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3> - </header> - <p>{{ .Description }}</p> - </section> + <section class="row featured-article"> + <h2>Featured Article</h2> + {{ range first 1 .Pages.ByPublishDate.Reverse }} + <header> + <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3> + </header> + <p>{{ .Description }}</p> {{ end }} -</div> + </section> + <div class="row recent-articles"> + <h2>Recent Articles</h2> + {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }} + <section class="recent-article"> + <header> + <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3> + </header> + <p>{{ .Description }}</p> + </section> + {{ end }} + </div> {{ end }} {{< /code >}} [`first`]: /functions/collections/first [list/section page]: /templates/section-templates -[lists]: /templates/lists/#order-content +[lists]: /templates/lists/#sort-content [`slice`]: /functions/collections/slice/ diff --git a/content/en/functions/collections/Append.md b/content/en/functions/collections/Append.md index 31657288f..5632dccfb 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 COLLECTION -relatedFunctions: - - collections.Append - - collections.Merge - - collections.Slice + - collections.Append ELEMENT [ELEMENT...] COLLECTION + - collections.Append COLLECTION1 COLLECTION2 aliases: [/functions/append] --- 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..b2a4b42a4 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] ``` @@ -65,7 +59,7 @@ 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") }} 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..2e933aca9 100644 --- a/content/en/functions/collections/Dictionary.md +++ b/content/en/functions/collections/Dictionary.md @@ -1,40 +1,59 @@ --- 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] --- -`dict` is especially useful for passing more than one value to a partial template. +```go-html-template +{{ $m := dict "a" 1 "b" 2 }} +``` + +The above produces this data structure: + +```json +{ + "a": 1, + "b": 2 +} +``` + 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" }} ``` -## Example: using `dict` to pass multiple values to a `partial` +The above produces this data structure: + +```json +{ + "a": { + "b": { + "c": "value" + } + } +} +``` + +## Pass values to a partial template The partial below creates an SVG and expects `fill`, `height` and `width` from the caller: ### Partial definition -{{< code file="layouts/partials/svgs/external-links.svg" >}} +{{< code file=layouts/partials/svgs/external-links.svg >}} <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 32" aria-label="External Link"> <path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path> @@ -45,7 +64,7 @@ fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 3 The `fill`, `height` and `width` values can be stored in one object with `dict` and passed to the partial: -{{< code file="layouts/_default/list.html" >}} +{{< code file=layouts/_default/list.html >}} {{ partial "svgs/external-links.svg" (dict "fill" "#01589B" "width" 10 "height" 20 ) }} {{< /code >}} 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..49a0362f5 100644 --- a/content/en/functions/collections/First.md +++ b/content/en/functions/collections/First.md @@ -1,53 +1,36 @@ --- title: collections.First -linkTitle: first -description: Slices an array to the first N elements. -categories: [functions] +description: Returns the given collection, limited to the first N elements. +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 + signatures: [collections.First N COLLECTION] 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` 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" }} +```go-html-template +{{ range first 5 .Pages }} + {{ .Render "summary" }} {{ end }} -{{< /code >}} +``` -*Note: Exclusive to `first`, LIMIT can be '0' to return an empty array.* +Set `N` to zero to return an empty collection. -## `first` and `where` Together +```go-html-template +{{ $emptyPageCollection := first 0 .Pages}} +``` -Using `first` and [`where`] together can be very -powerful. Below snippet gets a list of posts only from [main -sections], sorts it by the `title` parameter, and then -ranges through only the first 5 posts in that list: +Use `first` and [`where`] together. -{{< code file="first-and-where-together.html" >}} -{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections).ByTitle }} - {{ .Content }} +```go-html-template +{{ range where .Pages "Section" "articles" | first 5 }} + {{ .Render "summary" }} {{ 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..74aa869df 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] +description: Groups the given page collection by the given key. +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 + signatures: [collections.Group KEY PAGES] 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 }} @@ -29,12 +24,12 @@ aliases: [/functions/group] <ul> {{ range .Pages }} <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li> {{ end }} </ul> {{ end }} -{{< /code >}} +``` The page group you get from `group` is of the same type you get from the built-in [group methods](/templates/lists#group-content) in Hugo. The above example can be [paginated](/templates/pagination/#list-paginator-pages). diff --git a/content/en/functions/collections/In.md b/content/en/functions/collections/In.md index 57ffbd653..a3ec83d9b 100644 --- a/content/en/functions/collections/In.md +++ b/content/en/functions/collections/In.md @@ -1,21 +1,27 @@ --- title: collections.In -linkTitle: in -description: Reports whether an element is in an array or slice, or if a substring is in a string. +description: Reports whether the given value is a member of the given set. +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 + signatures: [collections.In SET VALUE] aliases: [/functions/in] --- +The `SET` can be an [array], [slice], or [string]. +[array]: /getting-started/glossary/#array +[slice]: /getting-started/glossary/#slice +[string]: /getting-started/glossary/#string ```go-html-template {{ $s := slice "a" "b" "c" }} diff --git a/content/en/functions/collections/IndexFunction.md b/content/en/functions/collections/IndexFunction.md index cd063f36e..e595d2b41 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..8bc60f8e1 100644 --- a/content/en/functions/collections/Intersect.md +++ b/content/en/functions/collections/Intersect.md @@ -1,26 +1,20 @@ --- 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: -## AND filter in where query +A useful example is to use it as `AND` filters when combined with where: ```go-html-template {{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }} @@ -32,6 +26,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..3d21ca6fd 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). @@ -39,7 +38,6 @@ The resulting data structure is: To extract the key and values: ```go-html-template - {{ $kv.Key }} → foo {{ $kv.Values }} → [a b c] ``` diff --git a/content/en/functions/collections/Last.md b/content/en/functions/collections/Last.md index 3f8496354..8219e120d 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] +description: Returns the given collection, limited to the last N elements. +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 + signatures: [collections.Last N COLLECTION] aliases: [/functions/last] --- @@ -23,3 +18,17 @@ aliases: [/functions/last] {{ .Render "summary" }} {{ end }} ``` + +Set `N` to zero to return an empty collection. + +```go-html-template +{{ $emptyPageCollection := last 0 .Pages}} +``` + +Use `last` and [`where`] together. + +```go-html-template +{{ range where .Pages "Section" "articles" | last 5 }} + {{ .Render "summary" }} +{{ end }} +``` 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..793b2b4b5 100644 --- a/content/en/functions/collections/NewScratch.md +++ b/content/en/functions/collections/NewScratch.md @@ -1,22 +1,115 @@ --- 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 +{{ $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 -{{ $scratch := newScratch }} -{{ $scratch.Add "b" 2 }} -{{ $scratch.Add "b" 2 }} -{{ $scratch.Get "b" }} → 4 +{{ $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. + +```go-html-template +{{ $s := newScratch }} +{{ $s.SetInMap "greetings" "english" "Hello" }} +{{ $s.SetInMap "greetings" "french" "Bonjour" }} + +{{ $map := $s.Values }} ``` 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..e7430e0d0 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 @@ -40,3 +36,11 @@ Iterate over a sequence of integers: {{ end }} {{ $product }} → 24 ``` + +The example above is contrived. To calculate the product of 2 or more numbers, use the [`math.Product`] function: + +```go-html-template +{{ math.Product (seq 4) }} → 24 +``` + +[`math.Product`]: /functions/math/product 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..e24b394ca 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] +description: Creates a slice of all passed arguments. +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..6b9ea2c34 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: @@ -111,25 +107,16 @@ Victor Marius Jean ## Sort a page collection -Although you can use the `sort` function to sort a page collection, Hugo provides [built-in methods for sorting page collections] by: +{{% note %}} +Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well. -- weight -- linktitle -- title -- front matter parameter -- date -- expiration date -- last modified date -- publish date -- length +[sorting and grouping methods]: /methods/pages +{{% /note %}} In this contrived example, sort the site's regular pages by `.Type` in descending order: -{{< code file="layouts/_default/home.html" copy=false >}} +```go-html-template {{ range sort site.RegularPages "Type" "desc" }} - <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} -{{< /code >}} - - -[built-in methods for sorting page collections]: /templates/lists/#order-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 <https://en.wikipedia.org/wiki/Symmetric_difference>. diff --git a/content/en/functions/collections/Union.md b/content/en/functions/collections/Union.md index 119da6fb4..e2eb61313 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] +description: Given two arrays or slices, returns a new array that contains the elements that belong to either or both arrays/slices. +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 @@ -19,7 +15,7 @@ relatedFunctions: aliases: [/functions/union] --- -Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both. The elements supported are strings, integers, and floats (only float64). +Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both. ```go-html-template {{ union (slice 1 2 3) (slice 3 4 5) }} diff --git a/content/en/functions/collections/Uniq.md b/content/en/functions/collections/Uniq.md index 1b0a8f8f4..8266142ac 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] +description: Returns the given collection, removing duplicate elements. +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..e053ed3d5 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] +description: Returns the given collection, removing elements that do not satisfy the comparison condition. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [where] returnType: any - signatures: ['collections.Where COLLECTION KEY [OPERATOR] MATCH'] -relatedFunctions: + signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE'] +related: - collections.Dictionary - collections.Group - collections.Index @@ -21,170 +17,434 @@ aliases: [/functions/where] toc: true --- -`where` filters an array to only the elements containing a matching -value for a given field. +The `where` function returns the given collection, removing elements that do not satisfy the comparison condition. The comparison condition is comprised of the `KEY`, `OPERATOR`, and `VALUE` arguments: -It works in a similar manner to the [`where` keyword in -SQL][wherekeyword]. +```text +collections.Where COLLECTION KEY [OPERATOR] VALUE + -------------------- + comparison condition +``` + +Hugo will test for equality if you do not provide an `OPERATOR` argument. For example: ```go-html-template -{{ range where .Pages "Section" "foo" }} - {{ .Content }} -{{ end }} +{{ $pages := where .Site.RegularPages "Section" "books" }} +{{ $books := where .Site.Data.books "genres" "suspense" }} ``` -It can be used by dot-chaining the second argument to refer to a nested element of a value. +## Arguments -{{< code-toggle file="content/example.md" fm=true copy=false >}} -title: Example -series: golang -{{< /code-toggle >}} +The where function takes three or four arguments. The `OPERATOR` argument is optional. -```go-html-template -{{ range where .Site.Pages "Params.series" "golang" }} - {{ .Content }} -{{ end }} -``` +COLLECTION +: (`any`) Typically a page collection or a [slice] of [maps]. -It can also be used with the logical operators `!=`, `>=`, `in`, etc. Without an operator, `where` compares a given field with a matching value equivalent to `=`. +[maps]: /getting-started/glossary/#map +[slice]: /getting-started/glossary/#slice + +KEY +: (`string`) The key of the page or map value to compare with `VALUE`. With page collections, commonly used comparison keys are `Section`, `Type`, and `Params`. To compare with a member of the page `Params` map, [chain] the subkey as shown below: ```go-html-template -{{ range where .Pages "Section" "!=" "foo" }} - {{ .Content }} -{{ end }} +{{ $result := where .Site.RegularPages "Params.foo" "bar" }} ``` -The following logical operators are available with `where`: +[chain]: /getting-started/glossary/#chain + +OPERATOR +: (`string`) The logical comparison [operator](#operators). + +VALUE +: (`any`) The value with which to compare. The values to compare must have comparable data types. For example: + +Comparison|Result +:--|:-- +`"123" "eq" "123"`|`true` +`"123" "eq" 123`|`false` +`false "eq" "false"`|`false` +`false "eq" false`|`true` + +When one or both of the values to compare is a slice, use the `in`, `not in` or `intersect` operators as described below. + +## Operators + +Use any of the following logical operators: `=`, `==`, `eq` -: `true` if a given field value equals a matching value +: (`bool`) Reports whether the given field value is equal to `VALUE`. `!=`, `<>`, `ne` -: `true` if a given field value doesn't equal a matching value +: (`bool`) Reports whether the given field value is not equal to `VALUE`. `>=`, `ge` -: `true` if a given field value is greater than or equal to a matching value +: (`bool`) Reports whether the given field value is greater than or equal to `VALUE`. `>`, `gt` -: `true` if a given field value is greater than a matching value +: `true` Reports whether the given field value is greater than `VALUE`. `<=`, `le` -: `true` if a given field value is lesser than or equal to a matching value +: (`bool`) Reports whether the given field value is less than or equal to `VALUE`. `<`, `lt` -: `true` if a given field value is lesser than a matching value +: (`bool`) Reports whether the given field value is less than `VALUE`. `in` -: `true` if a given field value is included in a matching value; a matching value must be an array or a slice +: (`bool`) Reports whether the given field value is a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in). `not in` -: `true` if a given field value isn't included in a matching value; a matching value must be an array or a slice +: (`bool`) Reports whether the given field value is not a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in). `intersect` -: `true` if a given field value that is a slice/array of strings or integers contains elements in common with the matching value; it follows the same rules as the [`intersect` function][intersect]. +: (`bool`) Reports whether the given field value (a slice) contains one or more elements in common with `VALUE`. See [details](/functions/collections/intersect). + +`like` {{< new-in 0.116.0 >}} +: (`bool`) Reports whether the given field value matches the regular expression specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression. + +{{% note %}} +The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps. +{{% /note %}} + +## String comparison -`like` -: `true` if a given field value matches a regular expression. Use the `like` operator to compare `string` values. Returns `false` when comparing other data types to the regular expression. +Compare the value of the given field to a [`string`]: + +[`string`]: /getting-started/glossary/#string -## Use `where` with boolean values -When using booleans you should not put quotation marks. ```go-html-template -{{ range where .Pages "Draft" true }} - <p>{{ .Title }}</p> -{{ end }} +{{ $pages := where .Site.RegularPages "Section" "eq" "books" }} +{{ $pages := where .Site.RegularPages "Section" "ne" "books" }} ``` -## Use `where` with `intersect` +## Numeric comparison + +Compare the value of the given field to an [`int`] or [`float`]: + +[`int`]: /getting-started/glossary/#int +[`float`]: /getting-started/glossary/#float ```go-html-template -{{ range where .Site.Pages "Params.tags" "intersect" .Params.tags }} - {{ if ne .Permalink $.Permalink }} - {{ .Render "summary" }} - {{ end }} -{{ end }} +{{ $sectionPages := where site.RegularPages "Section" "eq" "books" }} + +{{ $pages := where $sectionPages "Params.price" "eq" 42 }} +{{ $pages := where $sectionPages "Params.price" "ne" 42.67 }} +{{ $pages := where $sectionPages "Params.price" "ge" 42 }} +{{ $pages := where $sectionPages "Params.price" "gt" 42.67 }} +{{ $pages := where $sectionPages "Params.price" "le" 42 }} +{{ $pages := where $sectionPages "Params.price" "lt" 42.67 }} ``` -You can also put the returned value of the `where` clauses into a variable: +## Boolean comparison -{{< code file="where-intersect-variables.html" >}} -{{ $v1 := where .Site.Pages "Params.a" "v1" }} -{{ $v2 := where .Site.Pages "Params.b" "v2" }} -{{ $filtered := $v1 | intersect $v2 }} -{{ range $filtered }} -{{ end }} -{{< /code >}} +Compare the value of the given field to a [`bool`]: -## Use `where` with `like` +[`bool`]: /getting-started/glossary/#bool -This example matches pages where the "foo" parameter begins with "ab": +```go-html-template +{{ $sectionPages := where site.RegularPages "Section" "eq" "books" }} + +{{ $pages := where $sectionPages "Params.fiction" "eq" true }} +{{ $pages := where $sectionPages "Params.fiction" "eq" false }} +{{ $pages := where $sectionPages "Params.fiction" "ne" true }} +{{ $pages := where $sectionPages "Params.fiction" "ne" false }} +``` + +## Member comparison + +Compare a [`scalar`] to a [`slice`]. + +[`scalar`]: /getting-started/glossary/#scalar +[`slice`]: /getting-started/glossary/#slice + +For example, to return a collection of pages where the `color` page parameter is either "red" or "yellow": ```go-html-template -{{ range where site.RegularPages "Params.foo" "like" `^ab` }} - <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> -{{ end }} +{{ $sectionPages := where site.RegularPages "Section" "eq" "fruit" }} + +{{ $colors := slice "red" "yellow" }} +{{ $pages := where $sectionPages "Params.color" "in" $colors }} ``` -{{% readfile file="/functions/_common/regular-expressions.md" %}} +To return a collection of pages where the "color" page parameter is neither "red" nor "yellow": -## Use `where` with `first` +```go-html-template +{{ $sectionPages := where site.RegularPages "Section" "eq" "fruit" }} -Using `first` and `where` together can be very -powerful. Below snippet gets a list of posts only from [**main -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: +{{ $colors := slice "red" "yellow" }} +{{ $pages := where $sectionPages "Params.color" "not in" $colors }} +``` -{{< code file="first-and-where-together.html" >}} -{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections) }} - {{ .Content }} -{{ end }} -{{< /code >}} +## Intersection comparison + +Compare a [`slice`] to a [`slice`], returning collection elements with common values. This is frequently used when comparing taxonomy terms. + +For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance": + +```go-html-template +{{ $sectionPages := where site.RegularPages "Section" "eq" "books" }} + +{{ $genres := slice "suspense" "romance" }} +{{ $pages := where $sectionPages "Params.genres" "intersect" $genres }} +``` + +## Regular expression comparison -## Nest `where` clauses +{{< new-in 0.116.0 >}} -You can also nest `where` clauses to drill down on lists of content by more than one parameter. The following first grabs all pages in the "blog" section and then ranges through the result of the first `where` clause and finds all pages that are *not* featured: +To return a collection of pages where the "author" page parameter begins with either "victor" or "Victor": ```go-html-template -{{ range where (where .Pages "Section" "blog" ) "Params.featured" "!=" true }} +{{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }} ``` -## Unset fields +{{% include "functions/_common/regular-expressions.md" %}} + +{{% note %}} +Use the `like` operator to compare string values. Comparing other data types will result in an empty collection. +{{% /note %}} -Filtering only works for set fields. To check whether a field is set or exists, you can use the operand `nil`. +## Date comparison -This can be useful to filter a small amount of pages from a large pool. Instead of setting a field on all pages, you can set that field on required pages only. +### Predefined dates -Only the following operators are available for `nil` +There are four predefined front matter dates: [`date`], [`publishDate`], [`lastmod`], and [`expiryDate`]. Regardless of the front matter data format (TOML, YAML, or JSON) these are [`time.Time`] values, allowing precise comparisons. -* `=`, `==`, `eq`: True if the given field is not set. -* `!=`, `<>`, `ne`: True if the given field is set. +[`date`]: /methods/page/date +[`publishdate`]: /methods/page/publishdate +[`lastmod`]: /methods/page/lastmod +[`expirydate`]: /methods/page/expirydate +[`time.Time`]: https://pkg.go.dev/time#Time + +For example, to return a collection of pages that were created before the current year: ```go-html-template -{{ range where .Pages "Params.specialpost" "!=" nil }} - {{ .Content }} +{{ $startOfYear := time.AsTime (printf "%d-01-01" now.Year) }} +{{ $pages := where .Site.RegularPages "Date" "lt" $startOfYear }} +``` + +### Custom dates + +With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON). + +{{% note %}} +Using TOML for pages with custom front matter dates enables precise date comparisons. +{{% /note %}} + +With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons. + +In the TOML example below, note that the event date is not quoted. + +{{< code file="content/events/2024-user-conference.md" >}} ++++ +title = '2024 User Conference" +eventDate = 2024-04-01 ++++ +{{< /code >}} + +To return a collection of future events: + +```go-html-template +{{ $events := where .Site.RegularPages "Type" "events" }} +{{ $futureEvents := where $events "Params.eventDate" "gt" now }} +``` + +When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. However, to be safe, filter the pages by ranging through the collection: + +```go-html-template +{{ $events := where .Site.RegularPages "Type" "events" }} +{{ $futureEvents := slice }} +{{ range $events }} + {{ if gt (time.AsTime .Params.eventDate) now }} + {{ $futureEvents = $futureEvents | append . }} + {{ end }} {{ end }} ``` -## Portable `where` filters -- `site.Params.mainSections` {#mainsections} +## Nil comparison -**This is especially important for themes.** +To return a collection of pages where the "color" parameter is present in front matter, compare to `nil`: + +```go-html-template +{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }} +``` -To list the most relevant pages on the front page or similar, you -should use the `site.Params.mainSections` list instead of comparing -section names to hard-coded values like `"posts"` or `"post"`. +To return a collection of pages where the "color" parameter is not present in front matter, compare to `nil`: ```go-html-template -{{ $pages := where site.RegularPages "Type" "in" site.Params.mainSections }} +{{ $pages := where .Site.RegularPages "Params.color" "eq" nil }} ``` -If the user has not set this configuration parameter in their site configuration, it will default to the *section with the most pages*. +In both examples above, note that `nil` is not quoted. + +## Nested comparison -The user can override the default: +These are equivalent: -{{< code-toggle file="hugo" >}} +```go-html-template +{{ $pages := where .Site.RegularPages "Type" "tutorials" }} +{{ $pages = where $pages "Params.level" "eq" "beginner" }} +``` + +```go-html-template +{{ $pages := where (where .Site.RegularPages "Type" "tutorials") "Params.level" "eq" "beginner" }} +``` + +## Portable section comparison + +Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object. + +[`MainSections`]: /methods/site/mainsections + +```go-html-template +{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }} +``` + +With this construct, a theme author can instruct users to specify their main sections in the site configuration: + +{{< code-toggle file=hugo >}} [params] - mainSections = ["blog", "docs"] +mainSections = ['blog','galleries'] {{< /code-toggle >}} -[intersect]: /functions/collections/intersect -[wherekeyword]: https://www.techonthenet.com/sql/where.php +If `params.mainSections` is not defined in the site configuration, the `MainSections` method returns a slice with one element---the top level section with the most pages. + +## Boolean/undefined comparison + +Consider this site content: + +```text +content/ +├── posts/ +│ ├── _index.md +│ ├── post-1.md <-- front matter: exclude = false +│ ├── post-2.md <-- front matter: exclude = true +│ └── post-3.md <-- front matter: exclude not defined +└── _index.md +``` + +The first two pages have an "exclude" field in front matter, but the last page does not. When testing for _equality_, the third page is _excluded_ from the result. When testing for _inequality_, the third page is _included_ in the result. + +### Equality test + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "eq" false }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 1</a></li> +</ul> +``` + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "eq" true }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-2/">Post 2</a></li> +</ul> +``` + +### Inequality test + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "ne" false }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-2/">Post 2</a></li> + <li><a href="/posts/post-3/">Post 3</a></li> +</ul> +``` + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "ne" true }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 1</a></li> + <li><a href="/posts/post-3/">Post 3</a></li> +</ul> +``` + +To exclude a page with an undefined field from a boolean _inequality_ test: + +1. Create a collection using a boolean comparison +2. Create a collection using a nil comparison +3. Subtract the second collection from the first collection using the [`collections.Complement`] function. + +[`collections.Complement`]: /functions/collections/complement + +This template: + +```go-html-template +{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }} +{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} +<ul> + {{ range $p1 | complement $p2 }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 1</a></li> +</ul> +``` + +This template: + +```go-html-template +{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }} +{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} +<ul> + {{ range $p1 | complement $p2 }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 2</a></li> +</ul> +``` 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 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 >}} - -`default` can be written in more than one way: - -```go-html-template -{{ .Params.font | default "Roboto" }} -{{ default "Roboto" .Params.font }} -``` - -Both of the above `default` function calls return `Roboto`. - -A `default` value, however, does not need to be hard coded like the previous example. The `default` value can be a variable or pulled directly from the front matter using dot notation: - -```go-html-template -{{ $old := .Params.oldparam }} -<p>{{ .Params.newparam | default $old }}</p> -``` - -Which would return: - -```html -<p>The default function helps make your templating DRYer.</p> -``` - -And then using dot notation - -```go-html-template -<title>{{ .Params.seo_title | default .Title }}</title> -``` - -Which would return - -```html -<title>Sane Defaults</title> -``` +To set a default value based on truthiness, use the [`or`] operator instead. -The following have equivalent return values but are far less terse. This demonstrates the utility of `default`: +[`or`]: /functions/go-template/or +{{% /note %}} -Using `if`: +The `default` function returns the second argument if set: ```go-html-template -<title>{{ if .Params.seo_title }}{{ .Params.seo_title }}{{ else }}{{ .Title }}{{ end }}</title> -=> Sane Defaults +{{ default 42 1 }} → 1 +{{ default 42 "foo" }} → foo +{{ default 42 (dict "k" "v") }} → map[k:v] +{{ default 42 (slice "a" "b") }} → [a b] +{{ default 42 true }} → true + +<!-- As noted above, the boolean "false" is considered set --> +{{ default 42 false }} → false ``` -Using `with`: +The `default` function returns the first argument if the second argument is not set: ```go-html-template -<title>{{ with .Params.seo_title }}{{ . }}{{ else }}{{ .Title }}{{ end }}</title> -=> Sane Defaults +{{ default 42 0 }} → 42 +{{ default 42 "" }} → 42 +{{ default 42 dict }} → 42 +{{ default 42 slice }} → 42 +{{ default 42 <nil> }} → 42 ``` 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..ba44660df 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 encoded to a hexadecimal string. +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..204ff0384 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] +description: Hashes the given input and returns its SHA1 checksum encoded to a hexadecimal string. +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..6fb657767 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] +description: Hashes the given input and returns its SHA256 checksum encoded to a hexadecimal string. +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..d61ea791d 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,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/ @@ -97,7 +117,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 +134,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 new file mode 100644 index 000000000..ae6c3188f --- /dev/null +++ b/content/en/functions/debug/Timer.md @@ -0,0 +1,37 @@ +--- +title: debug.Timer +description: Creates a named timer that reports elapsed time to the console. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: debug.Timer + signatures: [debug.Timer NAME] +--- + +{{< new-in 0.120.0 >}} + +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. + +```go-html-template +{{ $t := debug.Timer "TestSqrt" }} +{{ range seq 2000 }} + {{ $f := math.Sqrt . }} +{{ end }} +{{ $t.Stop }} +``` + +Use the `--logLevel info` command line flag when you build the site. + +```sh +hugo --logLevel info +``` + +The results are displayed in the console at the end of the build. You can have as many timers as you want and if you don't stop them, they will be stopped at the end of build. + +```text +INFO timer: name TestSqrt total 12.429355ms +``` 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/diagrams/Goat.md b/content/en/functions/diagrams/Goat.md new file mode 100644 index 000000000..2b31d9824 --- /dev/null +++ b/content/en/functions/diagrams/Goat.md @@ -0,0 +1,113 @@ +--- +title: diagrams.Goat +description: Converts ASCII art to an SVG diagram, returning a GoAT diagram object. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: diagrams.goatDiagram + signatures: ['diagrams.Goat INPUT'] +toc: true +--- + +Useful in a code block [render hook], the `diagram.Goat` function converts ASCII art to an SVG diagram, returning a [GoAT] diagram object with the following methods: + +[GoAT]: https://github.com/blampe/goat#readme +[render hook]: https://gohugo.io/templates/render-hooks/ + +Inner +: (`template.HTML`) Returns the SVG child elements without a wrapping `svg` element, allowing you to create your own wrapper. + +Wrapped +: (`template.HTML`) Returns the SVG child elements wrapped in an `svg` element. + +Width +: (`int`) Returns the width of the rendered diagram, in pixels. + +Height +: (`int`) Returns the height of the rendered diagram, in pixels. + +## GoAT Diagrams + +Hugo natively supports [GoAT] diagrams. + +This markdown: + +```` +```goat +.---. .-. .-. .-. .---. +| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B | +'---' '-' '+' '+' '---' +``` +```` + +Is rendered to: + +```html +<div class="goat svg-container"> + <svg xmlns="http://www.w3.org/2000/svg" font-family="Menlo,Lucida Console,monospace" viewBox="0 0 352 57"> + ... + </svg> +</div> +``` + +Which appears in your browser as: + +```goat {class="mw6-ns"} +.---. .-. .-. .-. .---. +| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B | +'---' '-' '+' '+' '---' +``` + +To customize rendering, override Hugo's [built-in code block render hook] for GoAT diagrams. + +[built-in code block render hook]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-codeblock-goat.html + +## Code block render hook + +By way of example, let's create a code block render hook to render GoAT diagrams as `figure` elements with an optional caption. + +{{< code file=layouts/_default/_markup/render-codeblock-goat.html >}} +{{ $caption := or .Attributes.caption "" }} +{{ $class := or .Attributes.class "diagram" }} +{{ $id := or .Attributes.id (printf "diagram-%d" (add 1 .Ordinal)) }} + +<figure id="{{ $id }}"> + {{ with diagrams.Goat (trim .Inner "\n\r") }} + <svg class="{{ $class }}" width="{{ .Width }}" height="{{ .Height }}" xmlns="http://www.w3.org/2000/svg" version="1.1"> + {{ .Inner }} + </svg> + {{ end }} + <figcaption>{{ $caption }}</figcaption> +</figure> +{{< /code >}} + +This markdown: + +{{< code file=content/example.md lang=text >}} +```goat {class="foo" caption="Diagram 1: Example"} +.---. .-. .-. .-. .---. +| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B | +'---' '-' '+' '+' '---' +``` +{{< /code >}} + +Is rendered to: + +```html +<figure id="diagram-1"> + <svg class="foo" width="272" height="57" xmlns="http://www.w3.org/2000/svg" version="1.1"> + ... + </svg> + <figcaption>Diagram 1: Example</figcaption> +</figure> +``` + +Use CSS to style the SVG as needed: + +```css +svg.foo { + font-family: "Segoe UI","Noto Sans",Helvetica,Arial,sans-serif +} +``` diff --git a/content/en/functions/diagrams/_index.md b/content/en/functions/diagrams/_index.md new file mode 100644 index 000000000..e136b4f33 --- /dev/null +++ b/content/en/functions/diagrams/_index.md @@ -0,0 +1,12 @@ +--- +title: Diagram functions +linkTitle: diagrams +description: Template functions to render diagrams. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to render diagrams. 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..475f8a76a 100644 --- a/content/en/functions/encoding/Jsonify.md +++ b/content/en/functions/encoding/Jsonify.md @@ -1,31 +1,24 @@ --- title: encoding.Jsonify -linkTitle: jsonify -description: Encodes a given object to JSON. -categories: [functions] +description: Encodes the given object to JSON. +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 + - encoding.Jsonify [OPTIONS] INPUT aliases: [/functions/jsonify] --- -To customize the printing of the JSON, pass a map of options as the first -argument. Supported options are "prefix" and "indent". Each JSON element in +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 +27,11 @@ more copies of *indent* according to the indentation nesting. ## Options -indent ("") -: Indentation to use. - -prefix ("") -: Indentation prefix. - -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. +indent +: (`string`) Indentation to use. Default is "". -See also the `.PlainWords`, `.Plain`, and `.RawContent` [page variables][pagevars]. +prefix +: (`string`) Indentation prefix. Default is "". -[pagevars]: /variables/page/ +noHTMLEscape +: (`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`. 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..bbdd62c53 100644 --- a/content/en/functions/fmt/Errorf.md +++ b/content/en/functions/fmt/Errorf.md @@ -1,26 +1,21 @@ --- 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] --- -The documentation for [Go's fmt package] describes the structure and content of the format string. +{{% include "functions/fmt/_common/fmt-layout.md" %}} -Like the [`printf`] function, the `errorf` function evaluates the format string. It then prints the result to the ERROR log and fails the build. Hugo prints each unique message once to avoid flooding the log with duplicate errors. +The `errorf` function evaluates the format string, then prints the result to the ERROR log and fails the build. ```go-html-template {{ errorf "The %q shortcode requires a src parameter. See %s" .Name .Position }} @@ -29,5 +24,3 @@ Like the [`printf`] function, the `errorf` function evaluates the format string Use the [`erroridf`] function to allow optional suppression of specific errors. [`erroridf`]: /functions/fmt/erroridf -[`printf`]: /functions/fmt/printf -[Go's fmt package]: https://pkg.go.dev/fmt diff --git a/content/en/functions/fmt/Erroridf.md b/content/en/functions/fmt/Erroridf.md index 986810436..9884f4935 100644 --- a/content/en/functions/fmt/Erroridf.md +++ b/content/en/functions/fmt/Erroridf.md @@ -1,28 +1,21 @@ --- 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] --- -The documentation for [Go's fmt package] describes the structure and content of the format string. +{{% include "functions/fmt/_common/fmt-layout.md" %}} -Like the [`errorf`] function, the `erroridf` function evaluates the format string, prints the result to the ERROR log, then fails the build. Hugo prints each unique message once to avoid flooding the log with duplicate errors. - -Unlike the `errorf` function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreErrors` array in your site configuration. +The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreErrors` array in your site configuration. This template code: @@ -34,15 +27,14 @@ Produces this console log: ```text ERROR You should consider fixing this. -If you feel that this should not be logged as an ERROR, you can ignore it by adding this to your site config: -ignoreErrors = ["error-42"] +You can suppress this error by adding the following to your site configuration: +ignoreErrors = ['error-42'] ``` To suppress this message: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} ignoreErrors = ["error-42"] {{< /code-toggle >}} [`errorf`]: /functions/fmt/errorf -[Go's fmt package]: https://pkg.go.dev/fmt 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..5d0127460 100644 --- a/content/en/functions/fmt/Printf.md +++ b/content/en/functions/fmt/Printf.md @@ -1,26 +1,19 @@ --- 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] --- -The documentation for [Go's fmt package] describes the structure and content of the format string. - -[Go's fmt package]: https://pkg.go.dev/fmt +{{% include "functions/fmt/_common/fmt-layout.md" %}} ```go-html-template {{ $var := "world" }} 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..b07cf3cc3 100644 --- a/content/en/functions/fmt/Warnf.md +++ b/content/en/functions/fmt/Warnf.md @@ -1,30 +1,22 @@ --- 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] --- -The documentation for [Go's fmt package] describes the structure and content of the format string. +{{% include "functions/fmt/_common/fmt-layout.md" %}} -Like the [`printf`] function, the `warnf` function evaluates the format string. It then prints the result to the WARNING log. Hugo prints each unique message once to avoid flooding the log with duplicate warnings. +The `warnf` function evaluates the format string, then prints the result to the WARNING log. Hugo prints each unique message once to avoid flooding the log with duplicate warnings. ```go-html-template -{{ warnf "Copyright notice missing from site configuration" }} +{{ warnf "The %q shortcode was unable to find %s. See %s" .Name $file .Position }} ``` - -[`printf`]: /functions/fmt/printf -[Go's fmt package]: https://pkg.go.dev/fmt diff --git a/content/en/functions/fmt/_common/_index.md b/content/en/functions/fmt/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/functions/fmt/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/content/en/functions/fmt/_common/fmt-layout.md b/content/en/functions/fmt/_common/fmt-layout.md new file mode 100644 index 000000000..ff69ce5e4 --- /dev/null +++ b/content/en/functions/fmt/_common/fmt-layout.md @@ -0,0 +1,7 @@ +--- +# Do not remove front matter. +--- + +The documentation for Go's [fmt] package describes the structure and content of the format string. + +[fmt]: https://pkg.go.dev/fmt 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 index 01f014078..e17fb0767 100644 --- a/content/en/functions/page/index.md +++ b/content/en/functions/global/page.md @@ -1,23 +1,21 @@ --- 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] --- -At the top level of a template that receives the `Page` object in context, these are equivalent: +{{< new-in 0.111.0 >}} + +At the top level of a template that receives a `Page` object in context, these are equivalent: ```go-html-template {{ .Params.foo }} @@ -25,7 +23,7 @@ At the top level of a template that receives the `Page` object in context, these {{ page.Params.foo }} ``` -When the `Page` object is not in context, you can use the global `page` function: +When a `Page` object is not in context, you can use the global `page` function: ```go-html-template {{ page.Params.foo }} @@ -39,7 +37,7 @@ Do not use the global `page` function in shortcodes, partials called by shortcod Hugo almost always passes a `Page` as the data context into the top level template (e.g., `single.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` variable in the template. -But when you are deeply nested inside of a [content view], [partial], or [render hook], it isn't always practical or possible to access the `Page` object. +But when you are deeply nested inside of a [content view], [partial], or [render hook], it is not always practical or possible to access the `Page` object. Use the global `page` function to access the `Page` object from anywhere in any template. @@ -47,7 +45,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: @@ -86,9 +84,9 @@ Do not use the global `page` function in: - Shortcodes - Partials called by shortcodes -- Partials cached by the `partialCached` function +- Partials cached by the [`partialCached`] function -Hugo caches rendered shortcodes. If you use the `global` page function within a shortcode, and the page content is rendered in two or more templates, the cached shortcodes may be incorrect. +Hugo caches rendered shortcodes. If you use the global `page` function within a shortcode, and the page content is rendered in two or more templates, the cached shortcodes may be incorrect. Consider this section template: @@ -99,10 +97,12 @@ Consider this section template: {{ end }} ``` -When you call the `.Summary` method, Hugo renders the page `.Content` including shortcodes. In this case, within a shortcode, the global `page` function accesses the `Page` object of the section page, not the content page. +When you call the [`Summary`] method, Hugo renders the page content including shortcodes. In this case, within a shortcode, the global `page` function accesses the `Page` object of the section page, not the content page. If Hugo renders the section page before a content page, the cached rendered shortcode will be incorrect. You cannot control the rendering sequence due to concurrency. +[`Summary`]: /methods/page/summary +[`partialCached`]: /functions/partials/includecached [content view]: /getting-started/glossary/#content-view [partial]: /getting-started/glossary/#partial [render hook]: /getting-started/glossary/#render-hook diff --git a/content/en/functions/site/index.md b/content/en/functions/global/site.md index 3341bff98..a097e471b 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 current 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 +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/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..9075756aa --- /dev/null +++ b/content/en/functions/go-template/_index.md @@ -0,0 +1,14 @@ +--- +title: Go template functions, operators, and statements +linkTitle: go template +description: Template functions, operators, and statements provided by Go's text/template package. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +These are the functions, operators, and statements 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..f8a082037 --- /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 >}} +<body> + <main> + {{ block "main" . }} + {{ print "default value if 'main' template is empty" }} + {{ end }} + </main> +</body> +{{< /code >}} + +{{< code file=layouts/_default/single.html >}} +{{ define "main" }} + <h1>{{ .Title }}</h1> + {{ .Content }} +{{ end }} +{{< /code >}} + +{{< code file=layouts/_default/list.html >}} +{{ define "main" }} + <h1>{{ .Title }}</h1> + {{ .Content }} + {{ range .Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> + {{ 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 }} + <p>{{ . }}</p> +{{ end }} +``` + +Is rendered to: + +```html +<p>foo</p> +``` + +{{% 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 }} + <p>{{ . }}</p> +{{ end }} +``` + +Is rendered to: + +```html +<p>foo</p> +<p>baz</p> +``` + +{{% 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" }} + <h1>{{ .Title }}</h1> + {{ .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..e8642e50b 100644 --- a/content/en/functions/go-template/range.md +++ b/content/en/functions/go-template/range.md @@ -1,36 +1,95 @@ --- 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 }} <p>{{ . }}</p> +{{ else }} + <p>The collection is empty</p> +{{ 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 }} ``` -Result: +{{% 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" }} +{{ range $s }} + <p>{{ . }}</p> +{{ end }} +``` + +Is rendered to: ```html <p>foo</p> @@ -38,7 +97,7 @@ Result: <p>baz</p> ``` -Template: +This template code: ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -47,7 +106,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html <p>foo</p> @@ -55,7 +114,7 @@ Result: <p>baz</p> ``` -Template: +This template code: ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -64,7 +123,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html <p>0: foo</p> @@ -72,9 +131,9 @@ Result: <p>2: baz</p> ``` -## 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 <p>John is 30</p> @@ -95,9 +154,9 @@ Result: <p>Joey is 24</p> ``` -## Page collections +## Array or slice of pages -Template: +This template code: ```go-html-template {{ range where site.RegularPages "Type" "articles" }} @@ -105,7 +164,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html <h2><a href="/articles/article-3/">Article 3</a></h2> @@ -113,47 +172,28 @@ Result: <h2><a href="/articles/article-1/">Article 1</a></h2> ``` -## Break - -Use the `break` statement to stop the innermost iteration and bypass all remaining iterations. +## Maps -Template: +This template code: ```go-html-template -{{ $s := slice "foo" "bar" "baz" }} -{{ range $s }} - {{ if eq . "bar" }} - {{ break }} - {{ end }} - <p>{{ . }}</p> +{{ $m := dict "name" "John" "age" 30 }} +{{ range $k, $v := $m }} + <p>key = {{ $k }} value = {{ $v }}</p> {{ end }} ``` -Result: - -```html -<p>foo</p> -``` - -## 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 }} - <p>{{ . }}</p> -{{ end }} +<p>key = age value = 30</p> +<p>key = name value = John</p> ``` -Result: +Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map. -```html -<p>foo</p> -<p>baz</p> -``` +{{% 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/return.md b/content/en/functions/go-template/return.md new file mode 100644 index 000000000..2a166c718 --- /dev/null +++ b/content/en/functions/go-template/return.md @@ -0,0 +1,110 @@ +--- +title: return +description: Used within partial templates, terminates template execution and returns the given value, if any. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/partials/Include + - functions/partials/IncludeCached + returnType: any + signatures: ['return [VALUE]'] +toc: true +--- + +The `return` statement is a custom addition to Go's [text/template] package. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any. + +The returned value may be of any data type including, but not limited to, [`bool`], [`float`], [`int`], [`map`], [`resource`], [`slice`], and [`string`]. + +A `return` statement without a value returns an empty string of type `template.HTML`. + +[`bool`]: /getting-started/glossary/#bool +[`float`]: /getting-started/glossary/#float +[`int`]: /getting-started/glossary/#int +[`map`]: /getting-started/glossary/#map +[`resource`]: /getting-started/glossary/#resource +[`slice`]: /getting-started/glossary/#slice +[`string`]: /getting-started/glossary/#string +[text/template]: https://pkg.go.dev/text/template + +{{% note %}} +Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below. +{{% /note %}} + +## Example + +By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even: + +{{< code file="layouts/partials/odd-or-even.html" >}} +{{ if math.ModBool . 2 }} + <p>{{ . }} is even</p> +{{ else }} + <p>{{ . }} is odd</p> +{{ end }} +{{< /code >}} + +When called, the partial renders HTML: + +```go-html-template +{{ partial "odd-or-even.html" 42 }} → <p>42 is even</p> +``` + +Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even: + +{{< code file="layouts/partials/is-even.html" >}} +{{ return math.ModBool . 2 }} +{{< /code >}} + +With this template: + +```go-html-template +{{ $number := 42 }} +{{ if partial "is-even.html" $number }} + <p>{{ $number }} is even</p> +{{ else }} + <p>{{ $number }} is odd</p> +{{ end }} +``` + +Hugo renders: + +```html +<p>42 is even</p> +``` + +See additional examples in the [partial templates] section. + +[partial templates]: /templates/partials/#returning-a-value-from-a-partial + +## Usage + +{{% note %}} +Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks +{{% /note %}} + +A partial that returns a value must contain only one `return` statement, placed at the end of the template. + +For example: + +{{< code file="layouts/partials/is-even.html" >}} +{{ $result := false }} +{{ if math.ModBool . 2 }} + {{ $result = "even" }} +{{ else }} + {{ $result = "odd" }} +{{ end }} +{{ return $result }} +{{< /code >}} + +{{% note %}} +The construct below is incorrect; it contains more than one `return` statement. +{{% /note %}} + +{{< code file="layouts/partials/do-not-do-this.html" >}} +{{ if math.ModBool . 2 }} + {{ return "even" }} +{{ else }} + {{ return "odd" }} +{{ end }} +{{< /code >}} diff --git a/content/en/functions/go-template/template.md b/content/en/functions/go-template/template.md new file mode 100644 index 000000000..a78ec5c65 --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ 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 <a href="https://example.org?url=https%3A%2F%2Fexample.com">Link</a> ``` + +{{% 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..197181953 100644 --- a/content/en/functions/go-template/with.md +++ b/content/en/functions/go-template/with.md @@ -1,35 +1,87 @@ --- 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: +Intialize a variable, scoped to the current block: -{{< code file="layouts/partials/twitter.html" >}} -{{ with .Site.Params.twitteruser }}<span class="twitter"> -<a href="https://twitter.com/{{ . }}" rel="author"> -<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{ . }}" - alt="Twitter"></a> -</span>{{ end }} -{{< /code >}} +```go-html-template +{{ with $var := 42 }} + {{ . }} → 42 + {{ $var }} → 42 +{{ end }} +{{ $var }} → undefined +``` + +## Understanding context + +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 +<h2>Dependencies</h2> +<table class="table table-dark"> + <thead> + <tr> + <th scope="col">#</th> + <th scope="col">Owner</th> + <th scope="col">Path</th> + <th scope="col">Version</th> + <th scope="col">Time</th> + <th scope="col">Vendor</th> + </tr> + </thead> + <tbody> + {{ range $index, $element := hugo.Deps }} + <tr> + <th scope="row">{{ add $index 1 }}</th> + <td>{{ with $element.Owner }}{{ .Path }}{{ end }}</td> + <td> + {{ $element.Path }} + {{ with $element.Replace }} + => {{ .Path }} + {{ end }} + </td> + <td>{{ $element.Version }}</td> + <td>{{ with $element.Time }}{{ . }}{{ end }}</td> + <td>{{ $element.Vendor }}</td> + </tr> + {{ end }} + </tbody> +</table> +``` diff --git a/content/en/functions/hugo/Environment.md b/content/en/functions/hugo/Environment.md new file mode 100644 index 000000000..f130de787 --- /dev/null +++ b/content/en/functions/hugo/Environment.md @@ -0,0 +1,30 @@ +--- +title: hugo.Environment +description: Returns the current running environment. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/hugo/IsDevelopment + - functions/hugo/IsProduction + 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 }} → <meta name="generator" content="Hugo 0.120.3"> +``` diff --git a/content/en/functions/hugo/GoVersion.md b/content/en/functions/hugo/GoVersion.md new file mode 100644 index 000000000..1640c3862 --- /dev/null +++ b/content/en/functions/hugo/GoVersion.md @@ -0,0 +1,17 @@ +--- +title: hugo.GoVersion +description: Returns the Go version used to compile the Hugo binary +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: string + signatures: [hugo.GoVersion] +--- + +{{< new-in 0.101.0 >}} + +```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..9926b67c9 --- /dev/null +++ b/content/en/functions/hugo/IsDevelopment.md @@ -0,0 +1,19 @@ +--- +title: hugo.IsDevelopment +description: Reports whether the current running environment is "development". +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/hugo/IsProduction + - functions/hugo/Environment + returnType: bool + signatures: [hugo.IsDevelopment] +--- + +{{< new-in 0.120.0 >}} + +```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..7e9bda0e3 --- /dev/null +++ b/content/en/functions/hugo/IsProduction.md @@ -0,0 +1,17 @@ +--- +title: hugo.IsProduction +description: Reports whether the current running environment is "production". +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/hugo/IsDevelopment + - functions/hugo/Environment + 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..942261007 --- /dev/null +++ b/content/en/functions/hugo/IsServer.md @@ -0,0 +1,17 @@ +--- +title: hugo.IsServer +description: Reports whether the built-in development server is running. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: bool + signatures: [hugo.IsServer] +--- + +{{< new-in 0.120.0 >}} + +```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..c3ad686da --- /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 208ea39b5..000000000 --- a/content/en/functions/hugo/index.md +++ /dev/null @@ -1,111 +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., `<meta name="generator" content="Hugo 0.112.0">`). - -`hugo.GoVersion` -: (`string`) The Go version used to compile the Hugo binary (e.g., `go1.20.4`). {{< new-in "0.101.0" >}} - -`hugo.IsExtended` -: (`bool`) Returns `true` if the Hugo binary is the extended version. - -`hugo.IsProduction` -: (`bool`) Returns `true` if `hugo.Environment` is set to the production environment. - -`hugo.Version` -: (`hugo.VersionString`) The current version of the Hugo binary (e.g., `0.112.1`). - -`hugo.WorkingDir` -: (`string`) The project working directory (e.g., `/home/user/projects/my-hugo-site`). {{< new-in "0.112.0" >}} - -## 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 -<h2>Dependencies</h2> -<table class="table table-dark"> - <thead> - <tr> - <th scope="col">#</th> - <th scope="col">Owner</th> - <th scope="col">Path</th> - <th scope="col">Version</th> - <th scope="col">Time</th> - <th scope="col">Vendor</th> - </tr> - </thead> - <tbody> - {{ range $index, $element := hugo.Deps }} - <tr> - <th scope="row">{{ add $index 1 }}</th> - <td>{{ with $element.Owner }}{{ .Path }}{{ end }}</td> - <td> - {{ $element.Path }} - {{ with $element.Replace }} - => {{ .Path }} - {{ end }} - </td> - <td>{{ $element.Version }}</td> - <td>{{ with $element.Time }}{{ . }}{{ end }}</td> - <td>{{ $element.Vendor }}</td> - </tr> - {{ end }} - </tbody> -</table> -``` 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..0a4d225bc --- /dev/null +++ b/content/en/functions/images/Config.md @@ -0,0 +1,36 @@ +--- +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. + +[`Width`]: /methods/resource/width +[`Height`]: /methods/resource/height +[global]: /getting-started/glossary/#global-resource +[image processing]: /content-management/image-processing +[page]: /getting-started/glossary/#page-resource +[remote]: /getting-started/glossary/#remote-resource +{{% /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 . }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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 . }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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 . }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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..6a74fd081 --- /dev/null +++ b/content/en/functions/images/Opacity.md @@ -0,0 +1,52 @@ +--- +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 +--- + +{{< new-in 0.119.0 >}} + +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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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..39e62b121 --- /dev/null +++ b/content/en/functions/images/Overlay.md @@ -0,0 +1,52 @@ +--- +title: images.Overlay +description: Returns an image filter that overlays the source image at the given coordinates, relative to the upper left corner. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Overlay RESOURCE X Y] +toc: true +--- + +## 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..139626596 --- /dev/null +++ b/content/en/functions/images/Padding.md @@ -0,0 +1,75 @@ +--- +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 +--- + +{{< new-in 0.120.0 >}} + +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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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..a5e4d88dd --- /dev/null +++ b/content/en/functions/images/Process.md @@ -0,0 +1,115 @@ +--- +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 +--- + +{{< new-in 0.119.0 >}} + +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 `crop`, `fill`, `fit`, or `resize`. 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 and equivalent to the `-preset` flag for the [`cwebp`] encoder. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint). + +[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp + + +```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 +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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 d42072393..000000000 --- a/content/en/functions/images/index.md +++ /dev/null @@ -1,274 +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 -))}} -``` - - -## 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] --- -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 +``` +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..835785486 --- /dev/null +++ b/content/en/functions/js/Build.md @@ -0,0 +1,184 @@ +--- +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 }} + <script src="{{ .RelPermalink }}"></script> + {{ end }} + {{ else }} + {{ $opts := dict "minify" true }} + {{ with . | js.Build $opts | fingerprint }} + <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script> + {{ 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`) 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 `<script>` tag. + +sourceMap +: (`string`) Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created. + +### Import JS code from /assets + +`js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this: + +```js +import { hello } from 'my/module'; +``` + +And it will resolve to the top-most `index.{js,ts,tsx,jsx}` inside `assets/my/module` in the layered file system. + +```js +import { hello3 } from 'my/module/hello3'; +``` + +Will resolve to `hello3.{js,ts,tsx,jsx}` inside `assets/my/module`. + +Any imports starting with `.` is resolved relative to the current file: + +```js +import { hello4 } from './lib'; +``` + +For other files (e.g. `JSON`, `CSS`) you need to use the relative path including any extension, e.g: + +```js +import * as data from 'my/module/data.json'; +``` + +Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. + +Also note the new `params` option that can be passed from template to 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'; +``` + +Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/getting-started/configuration/#configure-build). + +## Node.js dependencies + +Use the `js.Build` function to include Node.js dependencies. + +Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. + +The start directory for resolving npm packages (aka. packages that live inside a `node_modules` folder) is always the main project folder. + +{{% note %}} +If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project. +{{% /note %}} + +## Examples + +```go-html-template +{{ $built := resources.Get "js/index.js" | js.Build "main.js" }} +``` + +Or with options: + +```go-html-template +{{ $externals := slice "react" "react-dom" }} +{{ $defines := dict "process.env.NODE_ENV" `"development"` }} + +{{ $opts := dict "targetPath" "main.js" "externals" $externals "defines" $defines }} +{{ $built := resources.Get "scripts/main.js" | js.Build $opts }} +<script src="{{ $built.RelPermalink }}" defer></script> +``` 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..bd83c2ec5 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 + signatures: [lang.FormatCurrency PRECISION CURRENCY NUMBER] --- ```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..682b8426f --- /dev/null +++ b/content/en/functions/math/Abs.md @@ -0,0 +1,17 @@ +--- +title: math.Abs +description: Returns the absolute value of the given number. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: float64 + signatures: [math.Abs VALUE] +--- + +{{< new-in 0.112.0 >}} + +```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..afa8d48aa --- /dev/null +++ b/content/en/functions/math/Add.md @@ -0,0 +1,24 @@ +--- +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 +``` + +[`float`]: /getting-started/glossary/#float 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..530474a78 --- /dev/null +++ b/content/en/functions/math/Div.md @@ -0,0 +1,24 @@ +--- +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 +``` + +[`float`]: /getting-started/glossary/#float 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..6824599e3 --- /dev/null +++ b/content/en/functions/math/Mul.md @@ -0,0 +1,24 @@ +--- +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 +``` + +[`float`]: /getting-started/glossary/#float 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..d94df4f1b --- /dev/null +++ b/content/en/functions/math/Product.md @@ -0,0 +1,22 @@ +--- +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...] +--- + +{{< new-in 0.114.0 >}} + +```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..2865ac191 --- /dev/null +++ b/content/en/functions/math/Sub.md @@ -0,0 +1,23 @@ +--- +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 +``` + +[`float`]: /getting-started/glossary/#float diff --git a/content/en/functions/math/Sum.md b/content/en/functions/math/Sum.md new file mode 100644 index 000000000..eba03f72d --- /dev/null +++ b/content/en/functions/math/Sum.md @@ -0,0 +1,21 @@ +--- +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...] +--- + +{{< new-in 0.114.0 >}} + +```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/openapi3/Unmarshal.md b/content/en/functions/openapi3/Unmarshal.md new file mode 100644 index 000000000..50c793685 --- /dev/null +++ b/content/en/functions/openapi3/Unmarshal.md @@ -0,0 +1,76 @@ +--- +title: openapi3.Unmarshal +description: Unmarshals the given resource into an OpenAPI 3 document. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: openapi3.OpenAPIDocument + signatures: ['openapi3.Unmarshal RESOURCE'] +--- + +Use the `openapi3.Unmarshal` function with [global], [page], or [remote] resources. + +[global]: /getting-started/glossary/#global-resource +[page]: /getting-started/glossary/#page-resource +[remote]: /getting-started/glossary/#remote-resource +[OpenAPI]: https://www.openapis.org/ + +For example, to work with a remote [OpenAPI] defintion: + +```go-html-template +{{ $url := "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json" }} +{{ $api := "" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ $api = . | openapi3.Unmarshal }} + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +To inspect the data structure: + +```go-html-template +<pre>{{ debug.Dump $api }}</pre> +``` + +To list the GET and POST operations for each of the API paths: + +```go-html-template +{{ range $path, $details := $api.Paths }} + <p>{{ $path }}</p> + <dl> + {{ with $details.Get }} + <dt>GET</dt> + <dd>{{ .Summary }}</dd> + {{ end }} + {{ with $details.Post }} + <dt>POST</dt> + <dd>{{ .Summary }}</dd> + {{ end }} + </dl> +{{ end }} +``` + +Hugo renders this to: + + +```html +<p>/pets</p> +<dl> + <dt>GET</dt> + <dd>List all pets</dd> + <dt>POST</dt> + <dd>Create a pet</dd> +</dl> +<p>/pets/{petId}</p> +<dl> + <dt>GET</dt> + <dd>Info for a specific pet</dd> +</dl> +``` diff --git a/content/en/functions/openapi3/_index.md b/content/en/functions/openapi3/_index.md new file mode 100644 index 000000000..9b6aa9584 --- /dev/null +++ b/content/en/functions/openapi3/_index.md @@ -0,0 +1,12 @@ +--- +title: OpenAPI functions +linkTitle: openapi3 +description: Template functions to work with OpenAPI 3 definitions. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with OpenAPI 3 definitions. 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..859f6665b 100644 --- a/content/en/functions/partials/Include.md +++ b/content/en/functions/partials/Include.md @@ -1,22 +1,24 @@ --- 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 template contains a return statement, returns the given value, else returns the rendered output. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [partial] + related: + - functions/go-template/return + - functions/partials/IncludeCached + - functions/go-template/template + - methods/page/Render returnType: any - signatures: ['partials.Include LAYOUT [CONTEXT]'] -relatedFunctions: - - partials.Include - - partials.IncludeCached + signatures: ['partials.Include NAME [CONTEXT]'] aliases: [/functions/partial] --- +Without a [`return`] statement, the `partial` function returns a string of type `template.HTML`. With a `return` statement, the `partial` function can return any data type. + +[`return`]: /functions/go-template/return + In this example we have three partial templates: ```text @@ -63,5 +65,21 @@ Then, within the partial template: <p>{{ .name }} is majoring in {{ .major }}. Their grade point average is {{ .gpa }}.</p> ``` +To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template: + +```go-html-template +{{ $result := false }} +{{ if math.ModBool . 2 }} + {{ $result = "even" }} +{{ else }} + {{ $result = "odd" }} +{{ end }} +{{ return $result }} +``` + +See [details][`return`]. + +[`return`]: /functions/go-template/return [breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants +[details]: /functions/go-template/return diff --git a/content/en/functions/partials/IncludeCached.md b/content/en/functions/partials/IncludeCached.md index ab9a77835..db275fa9e 100644 --- a/content/en/functions/partials/IncludeCached.md +++ b/content/en/functions/partials/IncludeCached.md @@ -1,30 +1,32 @@ --- 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 template contains a return statement, returns the given value, else returns the rendered output. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [partialCached] + related: + - functions/go-template/return + - functions/partials/Include + - functions/go-template/template + - 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] --- -The `partialCached` template function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. +Without a [`return`] statement, the `partialCached` function returns a string of type `template.HTML`. With a `return` statement, the `partialCached` function can return any data type. -**Note:** Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once. +The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. -**Note**: Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result. +{{% note %}} +Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once. + +Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result. +{{% /note %}} Here is the simplest usage: @@ -32,18 +34,32 @@ Here is the simplest usage: {{ partialCached "footer.html" . }} ``` -You can also pass additional arguments to `partialCached` to create *variants* of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, you could use a variant based upon section so that the partial is only rendered once per section: +Pass additional arguments to `partialCached` to create variants of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, use a variant based on section so that the partial is only rendered once per section: -{{< code file="partial-cached-example.html" >}} +{{< code file=partial-cached-example.html >}} {{ partialCached "footer.html" . .Section }} {{< /code >}} -If you need to pass additional arguments to create unique variants, you can pass as many variant arguments as you need: +Pass additional arguments, of any data type, as needed to create unique variants: ```go-html-template {{ partialCached "footer.html" . .Params.country .Params.province }} ``` -Note that the variant arguments are not made available to the underlying partial template. They are only use to create a unique cache key. Since Hugo `0.61.0` you can use any object as cache key(s), not just strings. +The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys. + +To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template: + +```go-html-template +{{ $result := false }} +{{ if math.ModBool . 2 }} + {{ $result = "even" }} +{{ else }} + {{ $result = "odd" }} +{{ end }} +{{ return $result }} +``` + +See [details][`return`]. -See also [The Full Partial Series Part 1: Caching!](https://regisphilibert.com/blog/2019/12/hugo-partial-series-part-1-caching-with-partialcached/). +[`return`]: /functions/go-template/return 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..4c4340a09 100644 --- a/content/en/functions/path/BaseName.md +++ b/content/en/functions/path/BaseName.md @@ -1,33 +1,28 @@ --- 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. +{{< new-in 0.101.0 >}} ```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. -```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: +[`path.Clean`]: https://pkg.go.dev/path#Clean ```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..ada5a221d 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] +description: Reports whether the given value is a map. +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..cda24a5e1 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] +description: Reports whether the given value is a slice. +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 }} + <script src="{{ .RelPermalink }}"></script> + {{ end }} + {{ else }} + {{ $opts := dict "minified" true }} + {{ with . | babel $opts | fingerprint }} + <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script> + {{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ 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..f8e962aee --- /dev/null +++ b/content/en/functions/resources/Copy.md @@ -0,0 +1,32 @@ +--- +title: resources.Copy +description: Copies the given resource to the target path. +categories: [] +action: + aliases: [] + related: [] + returnType: resource.Resource + signatures: [resources.Copy TARGETPATH RESOURCE] +--- + +{{< new-in 0.100.0 >}} + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with resources.Copy "img/new-image-name.jpg" . }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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..d17f0580c --- /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 file=assets/css/template.css lang=go-html-template >}} +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" $ . }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> + {{ 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" }} + <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script> + {{ end }} +{{ end }} +``` + +Hugo renders this to something like: + +```html +<script src="/js/main.62e...df1.js" integrity="sha256-Yuh...rfE=" crossorigin="anonymous"></script> +``` + +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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ 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..0e6b91b64 --- /dev/null +++ b/content/en/functions/resources/GetRemote.md @@ -0,0 +1,177 @@ +--- +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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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. + +[`transform.Unmarshal`]: /functions/transform/unmarshal +[unmarshal]: /getting-started/glossary/#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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ 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 }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> +{{ 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 }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> +{{ 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 }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> +{{ 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 }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> +{{ 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 }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> + {{ else }} + {{ with . | postCSS | minify | fingerprint | resources.PostProcess }} + <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> + {{ 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 }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> + {{ else }} + {{ with . | postCSS | minify | fingerprint | resources.PostProcess }} + <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> + {{ 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 }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> + {{ else }} + {{ with . | minify | fingerprint }} + <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> + {{ 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 }} + <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> +{{ 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 }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> + {{ else }} + {{ with . | minify | fingerprint }} + <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> + {{ 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 +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/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..08307fb15 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 given 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] --- @@ -30,9 +25,9 @@ In this context, *safe* means CSS content that matches any of the following: Example: Given `style = "color: red;"` defined in the front matter of your `.md` file: -* <span class="good">`<p style="{{ .Params.style | safeCSS }}">…</p>` → `<p style="color: red;">…</p>`</span> -* <span class="bad">`<p style="{{ .Params.style }}">…</p>` → `<p style="ZgotmplZ">…</p>`</span> +* `<p style="{{ .Params.style | safeCSS }}">…</p>` → `<p style="color: red;">…</p>` +* `<p style="{{ .Params.style }}">…</p>` → `<p style="ZgotmplZ">…</p>` {{% note %}} -"ZgotmplZ" is a special value that indicates that unsafe content reached a CSS or URL context. +`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context. {{% /note %}} diff --git a/content/en/functions/safe/HTML.md b/content/en/functions/safe/HTML.md index ea3afe8f3..ecc4f1346 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 the given 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. <a href=\"https://creativecommons.org/licenses/by/4.0/\">Some rights reserved</a>." {{< /code-toggle >}} diff --git a/content/en/functions/safe/HTMLAttr.md b/content/en/functions/safe/HTMLAttr.md index 7d1b06c47..6e1fd2af7 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] +description: Declares the given key/value pair as a safe HTML attribute. +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 }} <a href="{{ .URL }}">{{ .Name }}</a> {{ end }} -``` +``` Will produce: diff --git a/content/en/functions/safe/JS.md b/content/en/functions/safe/JS.md index e679b5f85..65279b89b 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 given string as a safe JavaScript expression. +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] --- @@ -27,5 +22,5 @@ Template authors are responsible for ensuring that typed expressions do not brea Example: Given `hash = "619c16f"` defined in the front matter of your `.md` file: -* <span class="good">`<script>var form_{{ .Params.hash | safeJS }};…</script>` → `<script>var form_619c16f;…</script>`</span> -* <span class="bad">`<script>var form_{{ .Params.hash }};…</script>` → `<script>var form_"619c16f";…</script>`</span> +* `<script>var form_{{ .Params.hash | safeJS }};…</script>` → `<script>var form_619c16f;…</script>` +* `<script>var form_{{ .Params.hash }};…</script>` → `<script>var form_"619c16f";…</script>` diff --git a/content/en/functions/safe/JSStr.md b/content/en/functions/safe/JSStr.md index 790de3a73..36d2b36fa 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] +description: Declares the given string as a safe JavaScript string. +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 <script> const a = "Title: " + "Lilo \u0026 Stitch"; diff --git a/content/en/functions/safe/URL.md b/content/en/functions/safe/URL.md index edc62ff9d..2ae67bd7f 100644 --- a/content/en/functions/safe/URL.md +++ b/content/en/functions/safe/URL.md @@ -1,23 +1,18 @@ --- title: safe.URL -linkTitle: safeURL -description: Declares the provided string as a safe URL or URL substring. -categories: [functions] +description: Declares the given string as a safe URL or URL substring. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeURL] + related: + - functions/safe/CSS + - functions/safe/HTML + - functions/safe/HTMLAttr + - functions/safe/JS + - functions/safe/JSStr returnType: template.URL signatures: [safe.URL INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safeurl] --- @@ -27,7 +22,7 @@ Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are cons The following examples use a [site `hugo.toml`][configuration] with the following [menu entry][menus]: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [[menu.main]] name = "IRC: #golang at freenode" url = "irc://irc.freenode.net/#golang" @@ -35,7 +30,7 @@ url = "irc://irc.freenode.net/#golang" The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example: -{{< code file="layouts/partials/bad-url-sidebar-menu.html" copy=false >}} +{{< code file=layouts/partials/bad-url-sidebar-menu.html >}} <!-- This unordered list may be part of a sidebar menu --> <ul> {{ range .Site.Menus.main }} @@ -55,7 +50,7 @@ This partial would produce the following HTML output: The odd output can be remedied by adding ` | safeURL` to our `.URL` page variable: -{{< code file="layouts/partials/correct-url-sidebar-menu.html" copy=false >}} +{{< code file=layouts/partials/correct-url-sidebar-menu.html >}} <!-- This unordered list may be part of a sidebar menu --> <ul> <li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li> diff --git a/content/en/functions/safe/_index.md b/content/en/functions/safe/_index.md new file mode 100644 index 000000000..f80a2cff4 --- /dev/null +++ b/content/en/functions/safe/_index.md @@ -0,0 +1,14 @@ +--- +title: Safe functions +linkTitle: safe +description: Template functions to declare a value as safe in the context of Go's html/template package. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to declare a value as safe in the context of Go's [html/template] package. + +[html/template]: https://pkg.go.dev/html/template diff --git a/content/en/functions/strings/Chomp.md b/content/en/functions/strings/Chomp.md index 22e2b546b..349f1e9b7 100644 --- a/content/en/functions/strings/Chomp.md +++ b/content/en/functions/strings/Chomp.md @@ -1,31 +1,27 @@ --- -title: chomp -linkTitle: chomp -description: Removes any trailing newline characters. -categories: [functions] +title: strings.Chomp +description: Returns the given string, removing all trailing newline characters and carriage returns. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [chomp] + related: + - functions/strings/Trim + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimRight + - functions/strings/TrimSuffix returnType: any signatures: [strings.Chomp STRING] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/chomp] --- -If the argument is of type template.HTML, returns template.HTML, else returns a string. - - -Useful in a pipeline to remove newlines added by other processing (e.g., [`markdownify`](/functions/transform/markdownify)). +If the argument is of type `template.HTML`, returns `template.HTML`, else returns a `string`. ```go-html-template -{{ chomp "<p>Blockhead</p>\n" }} → "<p>Blockhead</p>" +{{ chomp | "foo\n" }} → foo +{{ chomp | "foo\n\n" }} → foo + +{{ chomp | "foo\r\n" }} → foo +{{ chomp | "foo\r\n\r\n" }} → foo ``` diff --git a/content/en/functions/strings/Contains.md b/content/en/functions/strings/Contains.md index 66a90aeea..0344b2981 100644 --- a/content/en/functions/strings/Contains.md +++ b/content/en/functions/strings/Contains.md @@ -1,28 +1,26 @@ --- title: strings.Contains -description: Reports whether the string contains a substring. -categories: [functions] +description: Reports whether the given string contains the given substring. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/ContainsAny + - functions/strings/ContainsNonSpace + - functions/strings/HasPrefix + - functions/strings/HasSuffix + - functions/collections/In returnType: bool signatures: [strings.Contains STRING SUBSTRING] -relatedFunctions: - - strings.Contains - - strings.ContainsAny - - strings.ContainsNonSpace - - strings.HasPrefix - - strings.HasSuffix aliases: [/functions/strings.contains] --- ```go-html-template {{ strings.Contains "Hugo" "go" }} → true ``` -The check is case sensitive: + +The check is case sensitive: ```go-html-template {{ strings.Contains "Hugo" "Go" }} → false diff --git a/content/en/functions/strings/ContainsAny.md b/content/en/functions/strings/ContainsAny.md index 4f324358a..f331d09f7 100644 --- a/content/en/functions/strings/ContainsAny.md +++ b/content/en/functions/strings/ContainsAny.md @@ -1,21 +1,18 @@ --- title: strings.ContainsAny -description: Reports whether a string contains any character from a given string. -categories: [functions] +description: Reports whether the given string contains any character within the given set. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Contains + - functions/strings/ContainsNonSpace + - functions/strings/HasPrefix + - functions/strings/HasSuffix + - functions/collections/In returnType: bool - signatures: [strings.ContainsAny STRING CHARACTERS] -relatedFunctions: - - strings.Contains - - strings.ContainsAny - - strings.ContainsNonSpace - - strings.HasPrefix - - strings.HasSuffix + signatures: [strings.ContainsAny STRING SET] aliases: [/functions/strings.containsany] --- @@ -23,7 +20,7 @@ aliases: [/functions/strings.containsany] {{ strings.ContainsAny "Hugo" "gm" }} → true ``` -The check is case sensitive: +The check is case sensitive: ```go-html-template {{ strings.ContainsAny "Hugo" "Gm" }} → false diff --git a/content/en/functions/strings/ContainsNonSpace.md b/content/en/functions/strings/ContainsNonSpace.md index d2e6114b3..188aa14ba 100644 --- a/content/en/functions/strings/ContainsNonSpace.md +++ b/content/en/functions/strings/ContainsNonSpace.md @@ -1,27 +1,26 @@ --- title: strings.ContainsNonSpace -description: Reports whether a string contains any non-space characters as defined by Unicode’s White Space property. -categories: [functions] +description: Reports whether the given string contains any non-space characters as defined by Unicode’s White Space property. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Contains + - functions/strings/ContainsAny + - functions/strings/HasPrefix + - functions/strings/HasSuffix + - functions/collections/In returnType: bool signatures: [strings.ContainsNonSpace STRING] -relatedFunctions: - - strings.Contains - - strings.ContainsAny - - strings.ContainsNonSpace - - strings.HasPrefix - - strings.HasSuffix aliases: [/functions/strings.containsnonspace] --- +{{< new-in 0.111.0 >}} + ```go-html-template -{{ strings.ContainsNonSpace "\n" }} → false -{{ strings.ContainsNonSpace " " }} → false +{{ strings.ContainsNonSpace "\n" }} → false +{{ strings.ContainsNonSpace " " }} → false {{ strings.ContainsNonSpace "\n abc" }} → true ``` diff --git a/content/en/functions/strings/Count.md b/content/en/functions/strings/Count.md index 25ea58967..43b5baeff 100644 --- a/content/en/functions/strings/Count.md +++ b/content/en/functions/strings/Count.md @@ -1,21 +1,17 @@ --- title: strings.Count -description: Returns the number of non-overlapping instances of a substring within a string. -categories: [functions] +description: Returns the number of non-overlapping instances of the given substring within the given string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/go-template/len + - functions/strings/CountRunes + - functions/strings/CountWords + - functions/strings/RuneCount returnType: int signatures: [strings.Count SUBSTR STRING] -relatedFunctions: - - len - - strings.Count - - strings.CountRunes - - strings.CountWords - - strings.RuneCount aliases: [/functions/strings.count] --- diff --git a/content/en/functions/strings/CountRunes.md b/content/en/functions/strings/CountRunes.md index 4a17d04ab..10788e174 100644 --- a/content/en/functions/strings/CountRunes.md +++ b/content/en/functions/strings/CountRunes.md @@ -1,22 +1,17 @@ --- title: strings.CountRunes -linkTitle: countrunes -description: Returns the number of runes in a string excluding whitespace. -categories: [functions] +description: Returns the number of runes in the given string excluding whitespace. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [countrunes] + related: + - functions/go-template/len + - functions/strings/Count + - functions/strings/CountWords + - functions/strings/RuneCount returnType: int signatures: [strings.CountRunes INPUT] -relatedFunctions: - - len - - strings.Count - - strings.CountRunes - - strings.CountWords - - strings.RuneCount aliases: [/functions/countrunes] --- diff --git a/content/en/functions/strings/CountWords.md b/content/en/functions/strings/CountWords.md index e6915e6cd..3e4ec0465 100644 --- a/content/en/functions/strings/CountWords.md +++ b/content/en/functions/strings/CountWords.md @@ -1,31 +1,20 @@ --- title: strings.CountWords -linkTitle: countwords -description: Counts the number of words in a string. -categories: [functions] +description: Returns the number of words in the given string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [countwords] + related: + - functions/go-template/len + - functions/strings/Count + - functions/strings/CountRunes + - functions/strings/RuneCount returnType: int signatures: [strings.CountWords INPUT] -relatedFunctions: - - len - - strings.Count - - strings.CountRunes - - strings.CountWords - - strings.RuneCount aliases: [/functions/countwords] --- -The template function works similar to the [.WordCount page variable][pagevars]. - ```go-html-template -{{ "Hugo is a static site generator." | countwords }} -<!-- outputs a content length of 6 words. --> +{{ "Hugo is a static site generator." | countwords }} → 6 ``` - - -[pagevars]: /variables/page/ diff --git a/content/en/functions/strings/FindRESubmatch.md b/content/en/functions/strings/FindRESubmatch.md index 5a0410fdb..029cb323e 100644 --- a/content/en/functions/strings/FindRESubmatch.md +++ b/content/en/functions/strings/FindRESubmatch.md @@ -1,27 +1,22 @@ --- title: strings.FindRESubmatch -linkTitle: findRESubmatch description: Returns a slice of all successive matches of the regular expression. Each element is a slice of strings holding the text of the leftmost match of the regular expression and the matches, if any, of its subexpressions. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [findRESubmatch] + related: + - functions/strings/FindRE + - functions/strings/Replace + - functions/strings/ReplaceRE returnType: '[]string' signatures: ['strings.FindRESubmatch PATTERN INPUT [LIMIT]'] -relatedFunctions: - - strings.FindRE - - strings.FindRESubmatch - - strings.Replace - - strings.ReplaceRE aliases: [/functions/findresubmatch] --- By default, `findRESubmatch` finds all matches. You can limit the number of matches with an optional LIMIT argument. A return value of nil indicates no match. -{{% readfile file="/functions/_common/regular-expressions.md" %}} +{{% include "functions/_common/regular-expressions.md" %}} ## Demonstrative examples diff --git a/content/en/functions/strings/FindRe.md b/content/en/functions/strings/FindRe.md index 4a7811f3d..d26bae4a3 100644 --- a/content/en/functions/strings/FindRe.md +++ b/content/en/functions/strings/FindRe.md @@ -1,26 +1,21 @@ --- title: strings.FindRE -linkTitle: findRE description: Returns a slice of strings that match the regular expression. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [findRE] + related: + - functions/strings/FindRESubmatch + - functions/strings/Replace + - functions/strings/ReplaceRE returnType: string signatures: ['strings.FindRE PATTERN INPUT [LIMIT]'] -relatedFunctions: - - strings.FindRE - - strings.FindRESubmatch - - strings.Replace - - strings.ReplaceRE aliases: [/functions/findre] --- By default, `findRE` finds all matches. You can limit the number of matches with an optional LIMIT argument. -{{% readfile file="/functions/_common/regular-expressions.md" %}} +{{% include "functions/_common/regular-expressions.md" %}} This example returns a slice of all second level headings (`h2` elements) within the rendered `.Content`: diff --git a/content/en/functions/strings/FirstUpper.md b/content/en/functions/strings/FirstUpper.md index 320f01eda..8826b4f18 100644 --- a/content/en/functions/strings/FirstUpper.md +++ b/content/en/functions/strings/FirstUpper.md @@ -1,23 +1,19 @@ --- title: strings.FirstUpper -description: Capitalizes the first character of a given string. -categories: [functions] +description: Returns the given string, capitalizing the first character. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Title + - functions/strings/ToLower + - functions/strings/ToUpper returnType: string signatures: [strings.FirstUpper STRING] -relatedFunctions: - - strings.FirstUpper - - strings.Title - - strings.ToLower - - strings.ToUpper aliases: [/functions/strings.firstupper] --- ```go-html-template -{{ strings.FirstUpper "foo" }} → "Foo" +{{ strings.FirstUpper "foo" }} → Foo ``` diff --git a/content/en/functions/strings/HasPrefix.md b/content/en/functions/strings/HasPrefix.md index 88a79a935..455de0586 100644 --- a/content/en/functions/strings/HasPrefix.md +++ b/content/en/functions/strings/HasPrefix.md @@ -1,21 +1,18 @@ --- title: strings.HasPrefix -description: Reports whether a string begins with prefix. -categories: [functions] +description: Reports whether the given string begins with the given prefix. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [hasPrefix] + related: + - functions/strings/Contains + - functions/strings/ContainsAny + - functions/strings/ContainsNonSpace + - functions/strings/HasSuffix + - functions/collections/In returnType: bool signatures: [strings.HasPrefix STRING PREFIX] -relatedFunctions: - - strings.Contains - - strings.ContainsAny - - strings.ContainsNonSpace - - strings.HasPrefix - - strings.HasSuffix aliases: [/functions/hasprefix,/functions/strings.hasprefix] --- diff --git a/content/en/functions/strings/HasSuffix.md b/content/en/functions/strings/HasSuffix.md index d11f3e8cf..e7f253ce9 100644 --- a/content/en/functions/strings/HasSuffix.md +++ b/content/en/functions/strings/HasSuffix.md @@ -1,21 +1,18 @@ --- title: strings.HasSuffix -description: Reports whether a string ends with suffix. -categories: [functions] +description: Reports whether the given string begins with the given suffix. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [hasSuffix] + related: + - functions/strings/Contains + - functions/strings/ContainsAny + - functions/strings/ContainsNonSpace + - functions/strings/HasPrefix + - functions/collections/In returnType: bool signatures: [strings.HasSuffix STRING SUFFIX] -relatedFunctions: - - strings.Contains - - strings.ContainsAny - - strings.ContainsNonSpace - - strings.HasPrefix - - strings.HasSuffix aliases: [/functions/hassuffix,/functions/strings/hassuffix] --- diff --git a/content/en/functions/strings/Repeat.md b/content/en/functions/strings/Repeat.md index 718f24984..530b0d14b 100644 --- a/content/en/functions/strings/Repeat.md +++ b/content/en/functions/strings/Repeat.md @@ -1,20 +1,16 @@ --- title: strings.Repeat description: Returns a new string consisting of zero or more copies of another string. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: [] returnType: string signatures: [strings.Repeat COUNT INPUT] -relatedFunctions: [] aliases: [/functions/strings.repeat] --- ```go-html-template -{{ strings.Repeat 3 "yo" }} → "yoyoyo" -{{ "yo" | strings.Repeat 3 }} → "yoyoyo" +{{ strings.Repeat 3 "yo" }} → yoyoyo ``` diff --git a/content/en/functions/strings/Replace.md b/content/en/functions/strings/Replace.md index 8d5e54859..9add6e12b 100644 --- a/content/en/functions/strings/Replace.md +++ b/content/en/functions/strings/Replace.md @@ -1,30 +1,26 @@ --- title: strings.Replace -linkTitle: replace -description: Replaces all occurrences of the search string with the replacement string. -categories: [functions] +description: Returns a copy of INPUT, replacing all occurrences of OLD with NEW. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [replace] + related: + - functions/strings/FindRE + - functions/strings/FindRESubmatch + - functions/strings/ReplaceRE returnType: string signatures: ['strings.Replace INPUT OLD NEW [LIMIT]'] -relatedFunctions: - - strings.FindRE - - strings.FindRESubmatch - - strings.Replace - - strings.ReplaceRE aliases: [/functions/replace] --- -Replace returns a copy of `INPUT` with all occurrences of `OLD` replaced with `NEW`. -The number of replacements can be limited with an optional `LIMIT` argument. - +```go-html-template +{{ $s := "Batman and Robin" }} +{{ replace $s "Robin" "Catwoman" }} → Batman and Catwoman ``` -{{ replace "Batman and Robin" "Robin" "Catwoman" }} -→ "Batman and Catwoman" -{{ replace "aabbaabb" "a" "z" 2 }} → "zzbbaabb" +Limit the number of replacements using the `LIMIT` argument: + +```go-html-template +{{ replace "aabbaabb" "a" "z" 2 }} → zzbbaabb ``` diff --git a/content/en/functions/strings/ReplaceRE.md b/content/en/functions/strings/ReplaceRE.md index 247595877..1c32c34fb 100644 --- a/content/en/functions/strings/ReplaceRE.md +++ b/content/en/functions/strings/ReplaceRE.md @@ -1,42 +1,34 @@ --- title: strings.ReplaceRE -linkTitle: replaceRE -description: Returns a string, replacing all occurrences of a regular expression with a replacement pattern. -categories: [functions] +description: Returns a copy of INPUT, replacing all occurrences of a regular expression with a replacement pattern. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [replaceRE] + related: + - functions/strings/FindRE + - functions/strings/FindRESubmatch + - functions/strings/Replace returnType: string signatures: ['strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]'] -relatedFunctions: - - strings.FindRE - - strings.FindRESubmatch - - strings.Replace - - strings.ReplaceRE aliases: [/functions/replacere] --- -By default, `replaceRE` replaces all matches. You can limit the number of matches with an optional LIMIT argument. -{{% readfile file="/functions/_common/regular-expressions.md" %}} - -This example replaces two or more consecutive hyphens with a single hyphen: +{{% include "functions/_common/regular-expressions.md" %}} ```go-html-template {{ $s := "a-b--c---d" }} {{ replaceRE `(-{2,})` "-" $s }} → a-b-c-d ``` -To limit the number of replacements to one: +Limit the number of replacements using the LIMIT argument: ```go-html-template {{ $s := "a-b--c---d" }} {{ replaceRE `(-{2,})` "-" $s 1 }} → a-b-c---d ``` -You can use `$1`, `$2`, etc. within the replacement string to insert the groups captured within the regular expression: +Use `$1`, `$2`, etc. within the replacement string to insert the content of each capturing group within the regular expression: ```go-html-template {{ $s := "http://gohugo.io/docs" }} diff --git a/content/en/functions/strings/RuneCount.md b/content/en/functions/strings/RuneCount.md index a4d5a8dbe..46fedf01f 100644 --- a/content/en/functions/strings/RuneCount.md +++ b/content/en/functions/strings/RuneCount.md @@ -1,21 +1,17 @@ --- title: strings.RuneCount -description: Returns the number of runes in a string. -categories: [functions] +description: Returns the number of runes in the given string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/go-template/len + - functions/strings/Count + - functions/strings/CountRunes + - functions/strings/CountWords returnType: int signatures: [strings.RuneCount INPUT] -relatedFunctions: - - len - - strings.Count - - strings.CountRunes - - strings.CountWords - - strings.RuneCount aliases: [/functions/strings.runecount] --- diff --git a/content/en/functions/strings/SliceString.md b/content/en/functions/strings/SliceString.md index 8d26d76e4..2f33f8f65 100644 --- a/content/en/functions/strings/SliceString.md +++ b/content/en/functions/strings/SliceString.md @@ -1,24 +1,20 @@ --- title: strings.SliceString -linkTitle: slicestr description: Creates a slice of a half-open range, including start and end indices. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [slicestr] + related: [] returnType: string signatures: ['strings.SliceString STRING START [END]'] -relatedFunctions: [] aliases: [/functions/slicestr] --- -For example, 1 and 4 creates a slice including elements 1 through 3. +For example, 1 and 4 creates a slice including elements 1 through 3. The `end` index can be omitted; it defaults to the string's length. ```go-html-template -{{ slicestr "BatMan" 3 }}` → "Man" -{{ slicestr "BatMan" 0 3 }}` → "Bat" +{{ slicestr "BatMan" 3 }}` → Man +{{ slicestr "BatMan" 0 3 }}` → Bat ``` diff --git a/content/en/functions/strings/Split.md b/content/en/functions/strings/Split.md index 7d15704b2..a9973ea63 100644 --- a/content/en/functions/strings/Split.md +++ b/content/en/functions/strings/Split.md @@ -1,19 +1,14 @@ --- title: strings.Split -linkTitle: split -description: Returns a slice of strings by splitting STRING by DELIM. -categories: [functions] +description: Returns a slice of strings by splitting the given string by a delimiter. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [split] + related: + - functions/collections/Delimit returnType: string signatures: [strings.Split STRING DELIM] -relatedFunctions: - - collections.Delimit - - strings.Split aliases: [/functions/split] --- @@ -24,7 +19,8 @@ Examples: {{ split "abc" "" }} → ["a", "b", "c"] ``` - {{% note %}} -`split` essentially does the opposite of [delimit](/functions/collections/delimit). While `split` creates a slice from a string, `delimit` creates a string from a slice. +The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice. + +[`collections.Delimit`]: /functions/collections/delimit {{% /note %}} diff --git a/content/en/functions/strings/Substr.md b/content/en/functions/strings/Substr.md index 9dafa0737..6c1852f58 100644 --- a/content/en/functions/strings/Substr.md +++ b/content/en/functions/strings/Substr.md @@ -1,17 +1,13 @@ --- title: strings.Substr -linkTitle: substr description: Extracts parts of a string from a specified character's position and returns the specified number of characters. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [substr] + related: [] returnType: string signatures: ['strings.Substr STRING START [LENGTH]'] -relatedFunctions: [] aliases: [/functions/substr] --- @@ -22,21 +18,21 @@ To extract characters from the end of the string, use a negative start number. If `length` is given and is negative, that number of characters will be omitted from the end of string. ```go-html-template -{{ substr "abcdef" 0 }} → "abcdef" -{{ substr "abcdef" 1 }} → "bcdef" +{{ substr "abcdef" 0 }} → abcdef +{{ substr "abcdef" 1 }} → bcdef -{{ substr "abcdef" 0 1 }} → "a" -{{ substr "abcdef" 1 1 }} → "b" +{{ substr "abcdef" 0 1 }} → a +{{ substr "abcdef" 1 1 }} → b -{{ substr "abcdef" 0 -1 }} → "abcde" -{{ substr "abcdef" 1 -1 }} → "bcde" +{{ substr "abcdef" 0 -1 }} → abcde +{{ substr "abcdef" 1 -1 }} → bcde -{{ substr "abcdef" -1 }} → "f" -{{ substr "abcdef" -2 }} → "ef" +{{ substr "abcdef" -1 }} → f +{{ substr "abcdef" -2 }} → ef -{{ substr "abcdef" -1 1 }} → "f" -{{ substr "abcdef" -2 1 }} → "e" +{{ substr "abcdef" -1 1 }} → f +{{ substr "abcdef" -2 1 }} → e -{{ substr "abcdef" -3 -1 }} → "de" -{{ substr "abcdef" -3 -2 }} → "d" +{{ substr "abcdef" -3 -1 }} → de +{{ substr "abcdef" -3 -2 }} → d ``` diff --git a/content/en/functions/strings/Title.md b/content/en/functions/strings/Title.md index 1e20d1f59..b7f1f9e5c 100644 --- a/content/en/functions/strings/Title.md +++ b/content/en/functions/strings/Title.md @@ -1,30 +1,32 @@ --- title: strings.Title -linkTitle: title -description: Converts the provided string to title case. -categories: [functions] +description: Returns the given string, converting it to title case. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [title] + related: + - functions/strings/FirstUpper + - functions/strings/ToLower + - functions/strings/ToUpper returnType: string signatures: [strings.Title STRING] -relatedFunctions: - - strings.FirstUpper - - strings.Title - - strings.ToLower - - strings.ToUpper aliases: [/functions/title] --- ```go-html-template -{{ title "table of contents (TOC)" }} → "Table of Contents (TOC)" +{{ title "table of contents (TOC)" }} → Table of Contents (TOC) ``` -By default, Hugo adheres to the capitalization rules in the [Associated Press (AP) Stylebook]. Change your [site configuration] if you would prefer to follow the [Chicago Manual of Style], or to use Go's convention of capitalizing every word. +By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook]. Change your [site configuration] if you would prefer to: -[Associated Press (AP) Stylebook]: https://www.apstylebook.com/ +- Follow the capitalization rules published in the [Chicago Manual of Style] +- Capitalize the first letter of every word +- Capitalize the first letter of the first word +- Disable the effects of the `title` function + +The last option is useful if your theme uses the `title` function, and you would prefer to manually capitalize strings as needed. + +[Associated Press Stylebook]: https://www.apstylebook.com/ [Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html [site configuration]: /getting-started/configuration/#configure-title-case diff --git a/content/en/functions/strings/ToLower.md b/content/en/functions/strings/ToLower.md index cb76462ea..3da047ae4 100644 --- a/content/en/functions/strings/ToLower.md +++ b/content/en/functions/strings/ToLower.md @@ -1,28 +1,19 @@ --- title: strings.ToLower -linkTitle: lower -description: Converts all characters in the provided string to lowercase. -categories: [functions] +description: Returns the given string, converting all characters to lowercase. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [lower] + related: + - functions/strings/FirstUpper + - functions/strings/Title + - functions/strings/ToUpper returnType: string signatures: [strings.ToLower INPUT] -relatedFunctions: - - strings.FirstUpper - - strings.Title - - strings.ToLower - - strings.ToUpper aliases: [/functions/lower] --- - -Note that `lower` can be applied in your templates in more than one way: - ```go-html-template -{{ lower "BatMan" }} → "batman" -{{ "BatMan" | lower }} → "batman" +{{ lower "BatMan" }} → batman ``` diff --git a/content/en/functions/strings/ToUpper.md b/content/en/functions/strings/ToUpper.md index d46491637..617e1e68a 100644 --- a/content/en/functions/strings/ToUpper.md +++ b/content/en/functions/strings/ToUpper.md @@ -1,27 +1,19 @@ --- title: strings.ToUpper -linkTitle: upper -description: Converts all characters in a string to uppercase -categories: [functions] +description: Returns the given string, converting all characters to uppercase. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [upper] + related: + - functions/strings/FirstUpper + - functions/strings/Title + - functions/strings/ToLower returnType: string signatures: [strings.ToUpper INPUT] -relatedFunctions: - - strings.FirstUpper - - strings.Title - - strings.ToLower - - strings.ToUpper aliases: [/functions/upper] --- -Note that `upper` can be applied in your templates in more than one way: - ```go-html-template -{{ upper "BatMan" }} → "BATMAN" -{{ "BatMan" | upper }} → "BATMAN" +{{ upper "BatMan" }} → BATMAN ``` diff --git a/content/en/functions/strings/Trim.md b/content/en/functions/strings/Trim.md index 9eae9ee45..6dfac024b 100644 --- a/content/en/functions/strings/Trim.md +++ b/content/en/functions/strings/Trim.md @@ -1,45 +1,59 @@ --- title: strings.Trim -linkTitle: trim -description: Returns a slice of a passed string with all leading and trailing characters from cutset removed. -categories: [functions] +description: Returns the given string, removing leading and trailing characters specified in the cutset. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: - aliases: [title] +action: + aliases: [trim] + related: + - functions/strings/Chomp + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimRight + - functions/strings/TrimSuffix returnType: string signatures: [strings.Trim INPUT CUTSET] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/trim] --- ```go-html-template -{{ trim "++Batman--" "+-" }} → "Batman" +{{ trim "++foo--" "+-" }} → foo ``` -`trim` *requires* the second argument, which tells the function specifically what to remove from the first argument. There is no default value for the second argument, so **the following usage will not work**: +To remove leading and trailing newline characters and carriage returns: ```go-html-template -{{ trim .Inner }} +{{ trim "\nfoo\n" "\n\r" }} → foo +{{ trim "\n\nfoo\n\n" "\n\r" }} → foo + +{{ trim "\r\nfoo\r\n" "\n\r" }} → foo +{{ trim "\r\n\r\nfoo\r\n\r\n" "\n\r" }} → foo ``` -Instead, the following example tells `trim` to remove extra new lines from the content contained in the [shortcode `.Inner` variable][shortcodevars]: +The `strings.Trim` function is commonly used in shortcodes to remove leading and trailing newlines characters and carriage returns from the content within the opening and closing shortcode tags. -```go-html-template -{{ trim .Inner "\n" }} +For example, with this markdown: + +```text +{{</* my-shortcode */>}} +Able was I ere I saw Elba. +{{</* /my-shortcode */>}} +``` + +The value of `.Inner` in the shortcode template is: + +```text +\nAble was I ere I saw Elba.\n ``` -{{% note %}} -Go templates also provide a simple [method for trimming whitespace](/templates/introduction/#whitespace) from either side of a Go tag by including a hyphen (`-`). -{{% /note %}} +If authored on a Windows system the value of `.Inner` might, depending on the editor configuration, be: + +```text +\r\nAble was I ere I saw Elba.\r\n +``` +This construct is common in shortcode templates: -[shortcodevars]: /variables/shortcodes/ +```go-html-template +{{ trim .Inner "\n\r" }} +``` diff --git a/content/en/functions/strings/TrimLeft.md b/content/en/functions/strings/TrimLeft.md index 3924e492f..07cdf0064 100644 --- a/content/en/functions/strings/TrimLeft.md +++ b/content/en/functions/strings/TrimLeft.md @@ -1,33 +1,28 @@ --- title: strings.TrimLeft -description: Returns a slice of a given string with all leading characters contained in the cutset removed. -categories: [functions] +description: Returns the given string, removing leading characters specified in the cutset. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimPrefix + - functions/strings/TrimRight + - functions/strings/TrimSuffix returnType: string signatures: [strings.TrimLeft CUTSET STRING] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/strings.trimleft] --- -Given the string `"abba"`, leading `"a"`'s can be removed a follows: - ```go-html-template -{{ strings.TrimLeft "a" "abba" }} → "bba" +{{ strings.TrimLeft "a" "abba" }} → bba ``` -Numbers can be handled as well: +The `strings.TrimLeft` function converts the arguments to strings if possible: ```go-html-template -{{ strings.TrimLeft 12 1221341221 }} → "341221" +{{ strings.TrimLeft 21 12345 }} → 345 (string) +{{ strings.TrimLeft "rt" true }} → ue ``` diff --git a/content/en/functions/strings/TrimPrefix.md b/content/en/functions/strings/TrimPrefix.md index 37657732d..917cf06f5 100644 --- a/content/en/functions/strings/TrimPrefix.md +++ b/content/en/functions/strings/TrimPrefix.md @@ -1,29 +1,23 @@ --- title: strings.TrimPrefix -description: Returns a given string s without the provided leading prefix string. If s doesn't start with prefix, s is returned unchanged. -categories: [functions] +description: Returns the given string, removing the prefix from the beginning of the string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimLeft + - functions/strings/TrimRight + - functions/strings/TrimSuffix returnType: string signatures: [strings.TrimPrefix PREFIX STRING] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/strings.trimprefix] --- -Given the string `"aabbaa"`, the specified prefix is only removed if `"aabbaa"` starts with it: - ```go-html-template -{{ strings.TrimPrefix "a" "aabbaa" }} → "abbaa" -{{ strings.TrimPrefix "aa" "aabbaa" }} → "bbaa" -{{ strings.TrimPrefix "aaa" "aabbaa" }} → "aabbaa" +{{ strings.TrimPrefix "a" "aabbaa" }} → abbaa +{{ strings.TrimPrefix "aa" "aabbaa" }} → bbaa +{{ strings.TrimPrefix "aaa" "aabbaa" }} → aabbaa ``` diff --git a/content/en/functions/strings/TrimRight.md b/content/en/functions/strings/TrimRight.md index fa538b605..b244925ef 100644 --- a/content/en/functions/strings/TrimRight.md +++ b/content/en/functions/strings/TrimRight.md @@ -1,33 +1,28 @@ --- title: strings.TrimRight -description: Returns a slice of a given string with all trailing characters contained in the cutset removed. -categories: [functions] +description: Returns the given string, removing trailing characters specified in the cutset. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimSuffix returnType: string signatures: [strings.TrimRight CUTSET STRING] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/strings.trimright] --- -Given the string `"abba"`, trailing `"a"`'s can be removed a follows: - ```go-html-template -{{ strings.TrimRight "a" "abba" }} → "abb" +{{ strings.TrimRight "a" "abba" }} → abb ``` -Numbers can be handled as well: +The `strings.TrimRight` function converts the arguments to strings if possible: ```go-html-template -{{ strings.TrimRight 12 1221341221 }} → "122134" +{{ strings.TrimRight 54 12345 }} → 123 (string) +{{ strings.TrimRight "eu" true }} → tr ``` diff --git a/content/en/functions/strings/TrimSuffix.md b/content/en/functions/strings/TrimSuffix.md index 6dc9becfc..704bbd2d2 100644 --- a/content/en/functions/strings/TrimSuffix.md +++ b/content/en/functions/strings/TrimSuffix.md @@ -1,29 +1,23 @@ --- title: strings.TrimSuffix -description: Returns a given string s without the provided trailing suffix string. If s doesn't end with suffix, s is returned unchanged. -categories: [functions] +description: Returns the given string, removing the suffix from the end of the string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimRight returnType: string signatures: [strings.TrimSuffix SUFFIX STRING] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/strings.trimsuffix] --- -Given the string `"aabbaa"`, the specified suffix is only removed if `"aabbaa"` ends with it: - ```go-html-template -{{ strings.TrimSuffix "a" "aabbaa" }} → "aabba" -{{ strings.TrimSuffix "aa" "aabbaa" }} → "aabb" -{{ strings.TrimSuffix "aaa" "aabbaa" }} → "aabbaa" +{{ strings.TrimSuffix "a" "aabbaa" }} → aabba +{{ strings.TrimSuffix "aa" "aabbaa" }} → aabb +{{ strings.TrimSuffix "aaa" "aabbaa" }} → aabbaa ``` diff --git a/content/en/functions/strings/Truncate.md b/content/en/functions/strings/Truncate.md index 0bd78d840..17ae0afc6 100644 --- a/content/en/functions/strings/Truncate.md +++ b/content/en/functions/strings/Truncate.md @@ -1,17 +1,13 @@ --- title: strings.Truncate -linkTitle: truncate -description: Truncates a text to a max length without cutting words or leaving unclosed HTML tags. -categories: [functions] +description: Returns the given string, truncating it to a maximum length without cutting words or leaving unclosed HTML tags. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [truncate] + related: [] returnType: template.HTML signatures: ['strings.Truncate SIZE [ELLIPSIS] INPUT'] -relatedFunctions: [] aliases: [/functions/truncate] --- @@ -22,5 +18,7 @@ Since Go templates are HTML-aware, `truncate` will intelligently handle normal s ``` {{% note %}} -If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML` template function](/functions/safe/html) before sending the value to truncate. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. +If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. + +[`safeHTML`]: /functions/safe/html {{% /note %}} diff --git a/content/en/functions/strings/_index.md b/content/en/functions/strings/_index.md new file mode 100644 index 000000000..364522a3a --- /dev/null +++ b/content/en/functions/strings/_index.md @@ -0,0 +1,12 @@ +--- +title: String functions +linkTitle: strings +description: Template functions to work with strings. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with strings. diff --git a/content/en/functions/templates/Exists.md b/content/en/functions/templates/Exists.md index d4a8fab76..e57610488 100644 --- a/content/en/functions/templates/Exists.md +++ b/content/en/functions/templates/Exists.md @@ -1,23 +1,19 @@ --- title: templates.Exists -description: Reports whether a template file exists under the given path relative to the `layouts` directory. -categories: [functions] +description: Reports whether a template file exists under the given path relative to the layouts directory. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: [] returnType: bool signatures: [templates.Exists PATH] -namespace: templates -relatedFunctions: [] aliases: [/functions/templates.exists] --- -A template file is any file living below the `layouts` directories of either the project or any of its theme components including partials and shortcodes. +A template file is any file within the `layouts` directory of either the project or any of its theme components. -The function is particularly handy with dynamic path. The following example ensures the build will not break on a `.Type` missing its dedicated `header` partial. +Use the `templates.Exists` function with dynamic template paths: ```go-html-template {{ $partialPath := printf "headers/%s.html" .Type }} @@ -27,3 +23,5 @@ The function is particularly handy with dynamic path. The following example ensu {{ partial "headers/default.html" . }} {{ end }} ``` + +In the example above, if a "headers" partial does not exist for the given content type, Hugo falls back to a default template. diff --git a/content/en/functions/templates/_index.md b/content/en/functions/templates/_index.md new file mode 100644 index 000000000..89da6c38f --- /dev/null +++ b/content/en/functions/templates/_index.md @@ -0,0 +1,13 @@ +--- +title: Template functions +linkTitle: templates +description: +categories: [] +keywords: [] +menu: + docs: + identifier: templates-functions + parent: functions +--- + +Use these functions to query the template system. diff --git a/content/en/functions/time/AsTime.md b/content/en/functions/time/AsTime.md index 1244eeb5c..23e5304a5 100644 --- a/content/en/functions/time/AsTime.md +++ b/content/en/functions/time/AsTime.md @@ -1,64 +1,61 @@ --- title: time.AsTime -linkTitle: time -description: Converts a timestamp string into a `time.Time` structure. -categories: [functions] +description: Returns the given string representation of a date/time value as a time.Time value. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [time] + related: + - functions/time/Duration + - functions/time/Format + - functions/time/Now + - functions/time/ParseDuration returnType: time.Time signatures: ['time.AsTime INPUT [TIMEZONE]'] -relatedFunctions: - - time.AsTime - - time.Duration - - time.Format - - time.Now - - time.ParseDuration aliases: [/functions/time] +toc: true --- +## Overview -`time` converts a timestamp string with an optional default location into a [`time.Time`](https://godoc.org/time#Time) structure so you can access its fields: +Hugo provides [functions] and [methods] to format, localize, parse, compare, and manipulate date/time values. Before you can do any of these with string representations of date/time values, you must first convert them to [`time.Time`] values using the `time.AsTime` function. ```go-html-template -{{ time "2016-05-28" }} → "2016-05-28T00:00:00Z" -{{ (time "2016-05-28").YearDay }} → 149 -{{ mul 1000 (time "2016-05-28T10:30:00.00+10:00").Unix }} → 1464395400000, or Unix time in milliseconds +{{ $t := "2023-10-15T14:20:28-07:00" }} +{{ time.AsTime $t }} → 2023-10-15 14:20:28 -0700 PDT (time.Time) ``` -## Using locations +## Parsable strings -The optional `TIMEZONE` argument is a string that sets a default time zone (or more specific, the location, which represents the collection of time offsets in a geographical area) that is associated with the specified time value. If the time value has an explicit timezone or offset specified, it will take precedence over the `TIMEZONE` argument. +As shown above, the first argument must be a *parsable* string representation of a date/time value. For example: -The list of valid locations may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). +{{% include "functions/time/_common/parsable-date-time-strings.md" %}} -If no `TIMEZONE` is set, the `timeZone` from site configuration will be used. +## Time zones -```go-html-template -{{ time "2020-10-20" }} → 2020-10-20 00:00:00 +0000 UTC -{{ time "2020-10-20" "America/Los_Angeles" }} → 2020-10-20 00:00:00 -0700 PDT -{{ time "2020-01-20" "America/Los_Angeles" }} → 2020-01-20 00:00:00 -0800 PST -``` +When the parsable string does not contain a time zone offset, you can do either of the following to assign a time zone other than Etc/UTC: + +- Provide a second argument to the `time.AsTime` function + + ```go-html-template + {{ time.AsTime "15 Oct 2023" "America/Chicago" }} + ``` -## Example: Using `time` to get month index +- Set the default time zone in your site configuration -The following example takes a UNIX timestamp---set as `utimestamp: "1489276800"` in a content's front matter---converts the timestamp (string) to an integer using the [`int` function][int], and then uses [`printf`] to convert the `Month` property of `time` into an index. + {{< code-toggle file=hugo >}} + timeZone = 'America/New_York' + {{< /code-toggle >}} -The following example may be useful when setting up [multilingual sites][multilingual]: +The order of precedence for determining the time zone is: -{{< code file="unix-to-month-integer.html" >}} -{{ $time := time (int .Params.addDate)}} -=> $time = 1489276800 -{{ $time.Month }} -=> "March" -{{ $monthindex := printf "%d" $time.Month }} -=> $monthindex = 3 -{{< /code >}} +1. The time zone offset in the date/time string +2. The time zone provide as the second argument to the `time.AsTime` function +3. The time zone specified in your site configuration +The list of valid time zones may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database]. -[int]: /functions/cast/toint -[multilingual]: /content-management/multilingual/ -[`printf`]: /functions/fmt/printf +[`time.Time`]: https://pkg.go.dev/time#Time +[functions]: /functions/time/ +[iana time zone database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones +[methods]: /methods/time/ diff --git a/content/en/functions/time/Duration.md b/content/en/functions/time/Duration.md index 921f25a96..f9c26d294 100644 --- a/content/en/functions/time/Duration.md +++ b/content/en/functions/time/Duration.md @@ -1,40 +1,37 @@ --- title: time.Duration -linkTitle: duration -description: Returns a `time.Duration` structure, using the given time unit and duration number. -categories: [functions] +description: Returns a time.Duration value using the given time unit and number. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [duration] + related: + - functions/time/AsTime + - functions/time/Format + - functions/time/Now + - functions/time/ParseDuration returnType: time.Duration - signatures: [time.Duration TIME_UNIT DURATION_NUMBER] -relatedFunctions: - - time.AsTime - - time.Duration - - time.Format - - time.Now - - time.ParseDuration + signatures: [time.Duration TIME_UNIT NUMBER] aliases: [/functions/duration] --- -`time.Duration` converts a given number into a [`time.Duration`](https://pkg.go.dev/time#Duration) structure so you can access its fields. E.g. you can perform [time operations](https://pkg.go.dev/time#Duration) on the returned `time.Duration` value: +The `time.Duration` function returns a [`time.Duration`] value that you can use with any of the `Duration` [methods]. + +This template: ```go-html-template -{{ printf "There are %.0f seconds in one day." (duration "hour" 24).Seconds }} -<!-- Output: There are 86400 seconds in one day. --> +{{ $duration := time.Duration "hour" 24 }} +{{ printf "There are %.0f seconds in one day." $duration.Seconds }} ``` -Make your code simpler to understand by using a [chained pipeline](https://pkg.go.dev/text/template#hdr-Pipelines): +Is rendered to: -```go-html-template -{{ mul 7.75 60 | duration "minute" }} → 7h45m0s -{{ mul 120 60 | mul 1000 | duration "millisecond" }} → 2h0m0s +```text +There are 86400 seconds in one day. ``` -You have to specify a time unit for the number given to the function. Valid time units are: +The time unit must be one of the following: + Duration|Valid time units :--|:-- @@ -44,3 +41,6 @@ seconds|`second`, `s` milliseconds|`millisecond`, `ms` microseconds|`microsecond`, `us`, `µs` nanoseconds|`nanosecond`, `ns` + +[`time.Duration`]: https://pkg.go.dev/time#Duration +[methods]: /methods/duration diff --git a/content/en/functions/time/Format.md b/content/en/functions/time/Format.md index 3a0b1eb2a..74384959b 100644 --- a/content/en/functions/time/Format.md +++ b/content/en/functions/time/Format.md @@ -1,51 +1,52 @@ --- title: time.Format -description: Returns a formatted and localized time.Time value. -categories: [functions] +description: Returns the given date/time as a formatted and localized string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [dateFormat] + related: + - functions/time/AsTime + - functions/time/Duration + - functions/time/Now + - functions/time/ParseDuration returnType: string signatures: [time.Format LAYOUT INPUT] -relatedFunctions: - - time.AsTime - - time.Duration - - time.Format - - time.Now - - time.ParseDuration aliases: [/functions/dateformat] toc: true --- -```go-template -{{ $t := "2023-01-27T23:44:58-08:00" }} -{{ $format := "2 Jan 2006" }} +Use the `time.Format` function with `time.Time` values: -{{ $t | time.Format $format }} → 27 Jan 2023 +```go-html-template +{{ $t := time.AsTime "2023-02-27T23:44:58-08:00" }} +{{ time.Format "2 Jan 2006" $t }} → 27 Feb 2023 +``` + +Or use `time.Format` with a *parsable* string representation of a date/time value: -{{ $t = time.AsTime $t }} -{{ $t | time.Format $format }} → 27 Jan 2023 +```go-html-template +{{ $t := "27 Feb 2023" }} +{{ time.Format "January 2, 2006" $t }} → February 27, 2023 ``` +Examples of parsable string representations: + +{{% include "functions/time/_common/parsable-date-time-strings.md" %}} + ## Layout string -{{% readfile file="/functions/_common/time-layout-string.md" %}} +{{% include "functions/_common/time-layout-string.md" %}} ## Localization Use the `time.Format` function to localize `time.Time` values for the current language and region. -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} - +{{% include "functions/_common/locales.md" %}} Use the layout string as described above, or one of the tokens below. For example: -```go-template +```go-html-template {{ .Date | time.Format ":date_medium" }} → Jan 27, 2023 ``` diff --git a/content/en/functions/time/Now.md b/content/en/functions/time/Now.md index 74b01ecc5..60e45a91c 100644 --- a/content/en/functions/time/Now.md +++ b/content/en/functions/time/Now.md @@ -1,51 +1,48 @@ --- title: time.Now -linkTitle: now -description: Returns the current local time -categories: [functions] +description: Returns the current local time. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [now] + related: + - functions/time/AsTime + - functions/time/Duration + - functions/time/Format + - functions/time/ParseDuration returnType: time.Time signatures: [time.Now] -relatedFunctions: - - time.AsTime - - time.Duration - - time.Format - - time.Now - - time.ParseDuration aliases: [/functions/now] --- -See [`time.Time`](https://godoc.org/time#Time). - -For example, building your site on June 24, 2017, with the following templating: +For example, when building a site on October 15, 2023 in the America/Los_Angeles time zone: ```go-html-template -<div> - <small>© {{ now.Format "2006" }}</small> -</div> +{{ time.Now }} ``` -would produce the following: +This produces a `time.Time` value, with a string representation such as: -```html -<div> - <small>© 2017</small> -</div> +```text +2023-10-15 12:59:28.337140706 -0700 PDT m=+0.041752605 ``` -The above example uses the [`.Format` function](/functions/format), which page includes a full listing of date formatting using Go's layout string. +To format and [localize] the value, pass it through the [`time.Format`] function: + +```go-html-template +{{ time.Now | time.Format "Jan 2006" }} → Oct 2023 +``` -{{% note %}} -Older Hugo themes may still be using the obsolete Page’s `.Now` (uppercase with leading dot), which causes build error that looks like the following: +The `time.Now` function returns a `time.Time` value, so you can chain any of the [time methods] to the resulting value. For example: - ERROR ... Error while rendering "..." in "...": ... - executing "..." at <.Now.Format>: - can't evaluate field Now in type *hugolib.PageOutput -Be sure to use `now` (lowercase with _**no**_ leading dot) in your templating. -{{% /note %}} +```go-html-template +{{ time.Now.Year }} → 2023 (int) +{{ time.Now.Weekday.String }} → Sunday +{{ time.Now.Month.String }} → October +{{ time.Now.Unix }} → 1697400955 (int64) +``` + +[`time.Format`]: /functions/time/format +[localize]: /getting-started/glossary/#localization +[time methods]: /methods/time/ diff --git a/content/en/functions/time/ParseDuration.md b/content/en/functions/time/ParseDuration.md index e3abc7c15..091914132 100644 --- a/content/en/functions/time/ParseDuration.md +++ b/content/en/functions/time/ParseDuration.md @@ -1,30 +1,37 @@ --- title: time.ParseDuration -description: Parses a given duration string into a `time.Duration` structure. -categories: [functions] +description: Returns a time.Duration value by parsing the given duration string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/time/AsTime + - functions/time/Duration + - functions/time/Format + - functions/time/Now returnType: time.Duration signatures: [time.ParseDuration DURATION] -relatedFunctions: - - time.AsTime - - time.Duration - - time.Format - - time.Now - - time.ParseDuration aliases: [/functions/time.parseduration] --- -`time.ParseDuration` parses a duration string into a [`time.Duration`](https://pkg.go.dev/time#Duration) structure so you can access its fields. +The `time.ParseDuration` function returns a time.Duration value that you can use with any of the `Duration` [methods]. + + A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. -You can perform [time operations](https://pkg.go.dev/time#Duration) on the returned `time.Duration` value: +This template: ```go-html-template -{{ printf "There are %.0f seconds in one day." (time.ParseDuration "24h").Seconds }} -<!-- Output: There are 86400 seconds in one day. --> +{{ $duration := time.ParseDuration "24h" }} +{{ printf "There are %.0f seconds in one day." $duration.Seconds }} +``` + +Is rendered to: + +```text +There are 86400 seconds in one day. ``` + +[`time.Duration`]: https://pkg.go.dev/time#Duration +[methods]: /methods/duration diff --git a/content/en/functions/time/_common/_index.md b/content/en/functions/time/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/functions/time/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/content/en/functions/time/_common/parsable-date-time-strings.md b/content/en/functions/time/_common/parsable-date-time-strings.md new file mode 100644 index 000000000..a38b9983e --- /dev/null +++ b/content/en/functions/time/_common/parsable-date-time-strings.md @@ -0,0 +1,14 @@ +--- +# Do not remove front matter. +--- + +String representation|Time zone +:--|:-- +2023-10-15T14:20:28-07:00|America/Los_Angeles +2023-10-15T13:18:50-0700|America/Los_Angeles +2023-10-15T13:18:50Z|Etc/UTC +2023-10-15T13:18:50|Etc/UTC +2023-10-15|Etc/UTC +15 Oct 2023|Etc/UTC + +The last four examples are not fully qualified. Without a time zone offset, the time zone is set to Etc/UTC (Coordinated Universal Time). diff --git a/content/en/functions/time/_index.md b/content/en/functions/time/_index.md new file mode 100644 index 000000000..7e0b82f91 --- /dev/null +++ b/content/en/functions/time/_index.md @@ -0,0 +1,12 @@ +--- +title: Time functions +linkTitle: time +description: Template functions to work with time values. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with time values. diff --git a/content/en/functions/transform/CanHighlight.md b/content/en/functions/transform/CanHighlight.md index eabef933b..039cb12b7 100644 --- a/content/en/functions/transform/CanHighlight.md +++ b/content/en/functions/transform/CanHighlight.md @@ -1,19 +1,15 @@ --- title: transform.CanHighlight description: Reports whether the given code language is supported by the Chroma highlighter. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/transform/Highlight + - functions/transform/HighlightCodeBlock returnType: bool signatures: [transform.CanHighlight LANGUAGE] -relatedFunctions: - - transform.CanHighlight - - transform.Highlight - - transform.HighlightCodeBlock --- ```go-html-template diff --git a/content/en/functions/transform/Emojify.md b/content/en/functions/transform/Emojify.md index 324c41851..d9f0adf67 100644 --- a/content/en/functions/transform/Emojify.md +++ b/content/en/functions/transform/Emojify.md @@ -1,31 +1,30 @@ --- title: transform.Emojify -linkTitle: emojify description: Runs a string through the Emoji emoticons processor. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [emojify] + related: [] returnType: template.HTML signatures: [transform.Emojify INPUT] -namespace: transform -relatedFunctions: [] aliases: [/functions/emojify] --- `emojify` runs a passed string through the Emoji emoticons processor. -See the [Emoji cheat sheet][emojis] for available emoticons. +See the list of [emoji shortcodes] for available emoticons. -The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set `enableEmoji` to `true` in your site's [configuration]. Then you can write emoji shorthand directly into your content files; e.g. <code>I :</code><code>heart</code><code>: Hugo!</code>: +The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set `enableEmoji` to `true` in your site's [configuration]. Then you can write emoji shorthand directly into your content files; + +```text I :heart: Hugo! +``` +I :heart: Hugo! [configuration]: /getting-started/configuration/ -[emojis]: https://www.webfx.com/tools/emoji-cheat-sheet/ +[emoji shortcodes]: /quick-reference/emojis/ [sc]: /templates/shortcode-templates/ [scsource]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes diff --git a/content/en/functions/transform/HTMLEscape.md b/content/en/functions/transform/HTMLEscape.md index 62249367b..bb522769c 100644 --- a/content/en/functions/transform/HTMLEscape.md +++ b/content/en/functions/transform/HTMLEscape.md @@ -1,24 +1,30 @@ --- title: transform.HTMLEscape -linkTitle: htmlEscape -description: Returns the given string with the reserved HTML codes escaped. -categories: [functions] +description: Returns the given string, escaping special characters by replacing them with HTML entities. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [htmlEscape] + related: + - functions/transform/HTMLUnescape returnType: string signatures: [transform.HTMLEscape INPUT] -relatedFunctions: - - transform.HTMLEscape - - transform.HTMLUnescape aliases: [/functions/htmlescape] --- -In the result `&` becomes `&` and so on. It escapes only: `<`, `>`, `&`, `'` and `"`. +The `transform.HTMLEscape` function escapes five special characters by replacing them with [HTML entities]: + +- `&` → `&` +- `<` → `<` +- `>` → `>` +- `'` → `'` +- `"` → `"` + +For example: ```go-html-template -{{ htmlEscape "Hugo & Caddy > WordPress & Apache" }} → "Hugo & Caddy > WordPress & Apache" +{{ htmlEscape "Lilo & Stitch" }} → Lilo & Stitch +{{ htmlEscape "7 > 6" }} → 7 > 6 ``` + +[html entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity diff --git a/content/en/functions/transform/HTMLUnescape.md b/content/en/functions/transform/HTMLUnescape.md index c0774232f..180318077 100644 --- a/content/en/functions/transform/HTMLUnescape.md +++ b/content/en/functions/transform/HTMLUnescape.md @@ -1,24 +1,30 @@ --- title: transform.HTMLUnescape -linkTitle: htmlUnescape -description: Returns the given string with HTML escape codes un-escaped. -categories: [functions] +description: Returns the given string, replacing each HTML entity with its corresponding character. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [htmlUnescape] + related: + - functions/transform/HTMLEscape returnType: string signatures: [transform.HTMLUnescape INPUT] -relatedFunctions: - - transform.HTMLEscape - - transform.HTMLUnescape aliases: [/functions/htmlunescape] --- -Remember to pass the output of this to `safeHTML` if fully un-escaped characters are desired. Otherwise, the output will be escaped again as normal. +The `transform.HTMLUnescape` function replaces [HTML entities] with their corresponding characters. ```go-html-template -{{ htmlUnescape "Hugo & Caddy > WordPress & Apache" }} → "Hugo & Caddy > WordPress & Apache" +{{ htmlUnescape "Lilo & Stitch" }} → Lilo & Stitch +{{ htmlUnescape "7 > 6" }} → 7 > 6 ``` + +In most contexts Go's [html/template] package will escape special characters. To bypass this behavior, pass the unescaped string through the [`safeHTML`] function. + +```go-html-template +{{ htmlUnescape "Lilo & Stitch" | safeHTML }} +``` + +[`safehtml`]: /functions/safe/html +[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity +[html/template]: https://pkg.go.dev/html/template diff --git a/content/en/functions/transform/Highlight.md b/content/en/functions/transform/Highlight.md index 93043b4a1..29d0efdef 100644 --- a/content/en/functions/transform/Highlight.md +++ b/content/en/functions/transform/Highlight.md @@ -1,21 +1,15 @@ --- title: transform.Highlight -linkTitle: highlight description: Renders code with a syntax highlighter. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [highlight] + related: + - functions/transform/CanHighlight + - functions/transform/HighlightCodeBlock returnType: template.HTML signatures: ['transform.Highlight INPUT LANG [OPTIONS]'] -namespace: transform -relatedFunctions: - - transform.CanHighlight - - transform.Highlight - - transform.HighlightCodeBlock aliases: [/functions/highlight] toc: true --- @@ -31,7 +25,7 @@ LANG : The language of the code to highlight. Choose from one of the [supported languages]. Case-insensitive. OPTIONS -: An optional, comma-separated list of zero or more [options]. Set default values in [site configuration]. +: A map, or comma-separated list, of zero or more [options]. Set default values in [site configuration]. ## Options @@ -57,7 +51,7 @@ The number to display at the beginning of the first line. Irrelevant if `lineNos hl_Lines : String. Default is `""`.\ -A space-separated list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option. +A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option. hl_inline : Boolean. Default is `false`.\ @@ -82,10 +76,10 @@ If the `LANG` argument is blank or an unrecognized language, auto-detect the lan {{% note %}} Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation: -`lineNos=inline` +lineNos=inline : equivalent to `lineNos=true` and `lineNumbersInTable=false` -`lineNos=table` +lineNos=table : equivalent to `lineNos=true` and `lineNumbersInTable=true` {{% /note %}} @@ -101,8 +95,8 @@ Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the f {{ $input := `echo "Hello World!"` }} {{ $lang := "bash" }} -{{ $options := dict "lineNos" "table" "style" "dracula" }} -{{ transform.Highlight $input $lang $options }} +{{ $opts := dict "lineNos" "table" "style" "dracula" }} +{{ transform.Highlight $input $lang $opts }} ``` [Chroma]: https://github.com/alecthomas/chroma diff --git a/content/en/functions/transform/HighlightCodeBlock.md b/content/en/functions/transform/HighlightCodeBlock.md index fa7045641..dc396bad0 100644 --- a/content/en/functions/transform/HighlightCodeBlock.md +++ b/content/en/functions/transform/HighlightCodeBlock.md @@ -1,19 +1,15 @@ --- title: transform.HighlightCodeBlock description: Highlights code received in context within a code block render hook. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/transform/CanHighlight + - functions/transform/Highlight returnType: highlight.HighlightResult signatures: ['transform.HighlightCodeBlock CONTEXT [OPTIONS]'] -relatedFunctions: - - transform.CanHighlight - - transform.Highlight - - transform.HighlightCodeBlock --- This function is only useful within a code block render hook. @@ -26,7 +22,6 @@ Given the context passed into a code block render hook, `transform.HighlightCode .Inner : (`template.HTML`) Returns highlighted code without any wrapping elements, allowing you to create your own wrapper. - ```go-html-template {{ $result := transform.HighlightCodeBlock . }} {{ $result.Wrapped }} @@ -35,8 +30,8 @@ Given the context passed into a code block render hook, `transform.HighlightCode To override the default [highlighting options]: ```go-html-template -{{ $options := merge .Options (dict "linenos" true) }} -{{ $result := transform.HighlightCodeBlock . $options }} +{{ $opts := merge .Options (dict "linenos" true) }} +{{ $result := transform.HighlightCodeBlock . $opts }} {{ $result.Wrapped }} ``` diff --git a/content/en/functions/transform/Markdownify.md b/content/en/functions/transform/Markdownify.md index b0be902ce..8fb1e48ce 100644 --- a/content/en/functions/transform/Markdownify.md +++ b/content/en/functions/transform/Markdownify.md @@ -1,34 +1,30 @@ --- title: transform.Markdownify -linkTitle: markdownify description: Renders markdown to HTML. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [markdownify] + related: + - methods/page/RenderString + - methods/page/RenderShortcodes returnType: template.HTML signatures: [transform.Markdownify INPUT] -relatedFunctions: [] aliases: [/functions/markdownify] --- ```go-html-template -{{ .Title | markdownify }} +<h2>{{ .Title | markdownify }}</h2> ``` If the resulting HTML is a single paragraph, Hugo removes the wrapping `p` tags to produce inline HTML as required per the example above. -To keep the wrapping `p` tags for a single paragraph, use the [`.Page.RenderString`] method, setting the `display` option to `block`. +To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] method on the `Page` object, setting the `display` option to `block`. -If the resulting HTML is two or more paragraphs, Hugo leaves the wrapping `p` tags in place. - -[`.Page.RenderString`]: /functions/renderstring/ +[`RenderString`]: /methods/page/renderstring/ {{% note %}} -Although the `markdownify` function honors [markdown render hooks] when rendering markdown to HTML, use the `.Page.RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details. +Although the `markdownify` function honors [markdown render hooks] when rendering markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details. [markdown render hooks]: /templates/render-hooks/ [#9692]: https://github.com/gohugoio/hugo/issues/9692 diff --git a/content/en/functions/transform/Plainify.md b/content/en/functions/transform/Plainify.md index 163233d4a..040145170 100644 --- a/content/en/functions/transform/Plainify.md +++ b/content/en/functions/transform/Plainify.md @@ -1,24 +1,16 @@ --- title: transform.Plainify -linkTitle: plainify description: Returns a string with all HTML tags removed. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [plainify] + related: [] returnType: string signatures: [transform.Plainify INPUT] -relatedFunctions: [] aliases: [/functions/plainify] --- ```go-html-template -{{ "<b>BatMan</b>" | plainify }} → "BatMan" +{{ "<b>BatMan</b>" | plainify }} → BatMan ``` - -See also the `.PlainWords`, `.Plain`, and `.RawContent` [page variables][pagevars]. - -[pagevars]: /variables/page/ diff --git a/content/en/functions/transform/Remarshal.md b/content/en/functions/transform/Remarshal.md index 8f6e58247..24ef4381d 100644 --- a/content/en/functions/transform/Remarshal.md +++ b/content/en/functions/transform/Remarshal.md @@ -1,23 +1,19 @@ --- title: transform.Remarshal description: Marshals a string of serialized data, or a map, into a string of serialized data in the specified format. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/encoding/Jsonify + - functions/transform/Unmarshal returnType: string signatures: [transform.Remarshal FORMAT INPUT] -relatedFunctions: - - encoding.Jsonify - - transform.Remarshal - - transform.Unmarshal aliases: [/functions/transform.remarshal] --- -The FORMAT must be one of `json`, `toml`, `yaml`, or `xml`. If the INPUT is a string of serialized data, it must be valid JSON, TOML, YAML, or XML. +The format must be one of `json`, `toml`, `yaml`, or `xml`. If the input is a string of serialized data, it must be valid JSON, TOML, YAML, or XML. {{% note %}} This function is primarily a helper for Hugo's documentation, used to convert configuration and front matter examples to JSON, TOML, and YAML. diff --git a/content/en/functions/transform/Unmarshal.md b/content/en/functions/transform/Unmarshal.md index ab32d13de..02524509b 100644 --- a/content/en/functions/transform/Unmarshal.md +++ b/content/en/functions/transform/Unmarshal.md @@ -1,83 +1,289 @@ --- title: transform.Unmarshal -description: Parses the input and converts it into a map or an array. Supported formats are JSON, TOML, YAML, XML and CSV. -categories: [functions] +description: Parses serialized data and returns a map or an array. Supports CSV, JSON, TOML, YAML, and XML. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [unmarshal] + related: + - functions/transform/Remarshal + - functions/resources/Get + - functions/resources/GetRemote + - functions/encoding/Jsonify returnType: any - signatures: - - RESOURCE or STRING | transform.Unmarshal [OPTIONS] - - RESOURCE or STRING | unmarshal [OPTIONS] -relatedFunctions: - - encoding.Jsonify - - transform.Remarshal - - transform.Unmarshal + signatures: ['transform.Unmarshal [OPTIONS] INPUT'] +toc: true aliases: [/functions/transform.unmarshal] --- -The function accepts either a `Resource` created in [Hugo Pipes](/hugo-pipes/) or via [Page Bundles](/content-management/page-bundles/), or simply a string. The two examples below will produce the same map: +The input can be a string or a [resource]. + +## Unmarshal a string + +```go-html-template +{{ $string := ` +title: Les Misérables +author: Victor Hugo +`}} + +{{ $book := unmarshal $string }} +{{ $book.title }} → Les Misérables +{{ $book.author }} → Victor Hugo +``` + +## Unmarshal a resource + +Use the `transform.Unmarshal` function with global, page, and remote resources. + +### Global resource + +A global resource is a file within the assets directory, or within any directory mounted to the assets directory. + +```text +assets/ +└── data/ + └── books.json +``` ```go-html-template -{{ $greetings := "hello = \"Hello Hugo\"" | transform.Unmarshal }}` +{{ $data := "" }} +{{ $path := "data/books.json" }} +{{ with resources.Get $path }} + {{ with unmarshal . }} + {{ $data = . }} + {{ end }} +{{ else }} + {{ errorf "Unable to get global resource %q" $path }} +{{ end }} + +{{ range where $data "author" "Victor Hugo" }} + {{ .title }} → Les Misérables +{{ end }} +``` + +### Page resource + +A page resource is a file within a [page bundle]. + +```text +content/ +├── post/ +│ └── book-reviews/ +│ ├── books.json +│ └── index.md +└── _index.md ``` ```go-html-template -{{ $greetings := "hello = \"Hello Hugo\"" | resources.FromString "data/greetings.toml" | transform.Unmarshal }} +{{ $data := "" }} +{{ $path := "books.json" }} +{{ with .Resources.Get $path }} + {{ with unmarshal . }} + {{ $data = . }} + {{ end }} +{{ else }} + {{ errorf "Unable to get page resource %q" $path }} +{{ end }} + +{{ range where $data "author" "Victor Hugo" }} + {{ .title }} → Les Misérables +{{ end }} ``` -In both the above examples, you get a map you can work with: +### Remote resource + +A remote resource is a file on a remote server, accessible via HTTP or HTTPS. ```go-html-template -{{ $greetings.hello }} +{{ $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 }} + +{{ range where $data "author" "Victor Hugo" }} + {{ .title }} → Les Misérables +{{ end }} ``` -The above prints `Hello Hugo`. +[resource]: /getting-started/glossary/#resource +[page bundle]: /content-management/page-bundles -## CSV options +## Options -Unmarshal with CSV as input has some options you can set: +When unmarshaling a CSV file, provide an optional map of options. delimiter -: The delimiter used, default is `,`. +: (`string`) The delimiter used, default is `,`. comment -: The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.: - -Example: +: (`string`) The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored. ```go-html-template {{ $csv := "a;b;c" | transform.Unmarshal (dict "delimiter" ";") }} ``` -## XML data - -As a convenience, Hugo allows you to access XML data in the same way that you access JSON, TOML, and YAML: you do not need to specify the root node when accessing the data. +## Working with XML -To get the contents of `<title>` in the document below, you use `{{ .message.title }}`: +When unmarshaling an XML file, do not include the root node when accessing data. For example, after unmarshaling the RSS feed below, access the feed title with `$data.channel.title`. ```xml -<root> - <message> - <title>Hugo rocks!</title> - <description>Thanks for using Hugo</description> - </message> -</root> +<?xml version="1.0" encoding="utf-8" standalone="yes"?> +<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> + <channel> + <title>Books on Example Site</title> + <link>https://example.org/books/</link> + <description>Recent content in Books on Example Site</description> + <language>en-US</language> + <atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" /> + <item> + <title>The Hunchback of Notre Dame</title> + <description>Written by Victor Hugo</description> + <link>https://example.org/books/the-hunchback-of-notre-dame/</link> + <pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate> + <guid>https://example.org/books/the-hunchback-of-notre-dame/</guid> + </item> + <item> + <title>Les Misérables</title> + <description>Written by Victor Hugo</description> + <link>https://example.org/books/les-miserables/</link> + <pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate> + <guid>https://example.org/books/les-miserables/</guid> + </item> + </channel> +</rss> ``` -The following example lists the items of an RSS feed: +Get the remote data: ```go-html-template -{{ with resources.GetRemote "https://example.com/rss.xml" | transform.Unmarshal }} - {{ range .channel.item }} - <strong>{{ .title | plainify | htmlUnescape }}</strong><br> - <p>{{ .description | plainify | htmlUnescape }}</p> - {{ $link := .link | plainify | htmlUnescape }} - <a href="{{ $link }}">{{ $link }}</a><br> - <hr> +{{ $data := "" }} +{{ $url := "https://example.org/books/index.xml" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ $data = . | transform.Unmarshal }} {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} {{ end }} ``` + +Inspect the data structure: + +```go-html-template +<pre>{{ jsonify (dict "indent" " ") $data }}</pre> +``` + +List the book titles: + +```go-html-template +{{ with $data.channel.item }} + <ul> + {{ range . }} + <li>{{ .title }}</li> + {{ end }} + </ul> +{{ end }} +``` + +Hugo renders this to: + +```html +<ul> + <li>The Hunchback of Notre Dame</li> + <li>Les Misérables</li> +</ul> +``` + +### XML attributes and namespaces + +Let's add a `lang` attribute to the `title` nodes of our RSS feed, and a namespaced node for the ISBN number: + +```xml +<?xml version="1.0" encoding="utf-8" standalone="yes"?> +<rss version="2.0" + xmlns:atom="http://www.w3.org/2005/Atom" + xmlns:isbn="http://schemas.isbn.org/ns/1999/basic.dtd" +> + <channel> + <title>Books on Example Site</title> + <link>https://example.org/books/</link> + <description>Recent content in Books on Example Site</description> + <language>en-US</language> + <atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" /> + <item> + <title lang="fr">The Hunchback of Notre Dame</title> + <description>Written by Victor Hugo</description> + <isbn:number>9780140443530</isbn:number> + <link>https://example.org/books/the-hunchback-of-notre-dame/</link> + <pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate> + <guid>https://example.org/books/the-hunchback-of-notre-dame/</guid> + </item> + <item> + <title lang="en">Les Misérables</title> + <description>Written by Victor Hugo</description> + <isbn:number>9780451419439</isbn:number> + <link>https://example.org/books/les-miserables/</link> + <pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate> + <guid>https://example.org/books/les-miserables/</guid> + </item> + </channel> +</rss> +``` + +After retrieving the remote data, inspect the data structure: + +```go-html-template +<pre>{{ jsonify (dict "indent" " ") $data }}</pre> +``` + +Each item node looks like this: + +```json +{ + "description": "Written by Victor Hugo", + "guid": "https://example.org/books/the-hunchback-of-notre-dame/", + "link": "https://example.org/books/the-hunchback-of-notre-dame/", + "number": "9780140443530", + "pubDate": "Mon, 09 Oct 2023 09:27:12 -0700", + "title": { + "#text": "The Hunchback of Notre Dame", + "-lang": "fr" + } +} +``` + +The title keys do not begin with an underscore or a letter---they are not valid [identifiers]. Use the [`index`] function to access the values: + +```go-html-template +{{ with $data.channel.item }} + <ul> + {{ range . }} + {{ $title := index .title "#text" }} + {{ $lang := index .title "-lang" }} + {{ $ISBN := .number }} + <li>{{ $title }} ({{ $lang }}) {{ $ISBN }}</li> + {{ end }} + </ul> +{{ end }} +``` + +Hugo renders this to: + +```html +<ul> + <li>The Hunchback of Notre Dame (fr) 9780140443530</li> + <li>Les Misérables (en) 9780451419439</li> +</ul> +``` + +[`index`]: /functions/collections/indexfunction +[identifiers]: https://go.dev/ref/spec#Identifiers diff --git a/content/en/functions/transform/_index.md b/content/en/functions/transform/_index.md new file mode 100644 index 000000000..70e286b24 --- /dev/null +++ b/content/en/functions/transform/_index.md @@ -0,0 +1,12 @@ +--- +title: Transform functions +linkTitle: transform +description: Template functions to transform values from one format to another. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to transform values from one format to another. diff --git a/content/en/functions/urls/AbsLangURL.md b/content/en/functions/urls/AbsLangURL.md index ad73bbff0..876552bb7 100644 --- a/content/en/functions/urls/AbsLangURL.md +++ b/content/en/functions/urls/AbsLangURL.md @@ -1,21 +1,16 @@ --- title: urls.AbsLangURL -linkTitle: absLangURL description: Returns an absolute URL with a language prefix, if any. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [absLangURL] - returnType: template.HTML + related: + - functions/urls/AbsURL + - functions/urls/RelLangURL + - functions/urls/RelURL + returnType: string signatures: [urls.AbsLangURL INPUT] -relatedFunctions: - - urls.AbsLangURL - - urls.AbsURL - - urls.RelLangURL - - urls.RelURL aliases: [/functions/abslangurl] --- diff --git a/content/en/functions/urls/AbsURL.md b/content/en/functions/urls/AbsURL.md index bb6816f57..5b027ae84 100644 --- a/content/en/functions/urls/AbsURL.md +++ b/content/en/functions/urls/AbsURL.md @@ -1,25 +1,20 @@ --- title: urls.AbsURL -linkTitle: absURL description: Returns an absolute URL. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [absURL] - returnType: template.html + related: + - functions/urls/AbsLangURL + - functions/urls/RelLangURL + - functions/urls/RelURL + returnType: string signatures: [urls.AbsURL INPUT] -relatedFunctions: - - urls.AbsLangURL - - urls.AbsURL - - urls.RelLangURL - - urls.RelURL aliases: [/functions/absurl] --- -With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on: +With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on: - Whether the input begins with a slash - The `baseURL` in site configuration diff --git a/content/en/functions/urls/Anchorize.md b/content/en/functions/urls/Anchorize.md index 15efe9a5e..72b3d54a9 100644 --- a/content/en/functions/urls/Anchorize.md +++ b/content/en/functions/urls/Anchorize.md @@ -1,31 +1,37 @@ --- title: urls.Anchorize -linkTitle: anchorize -description: Takes a string and sanitizes it the same way as the [`defaultMarkdownHandler`](/getting-started/configuration-markup#default-configuration) does for markdown headers. -categories: [functions] +description: Returns the given string, sanitized for usage in an HTML id attribute. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [anchorize] + related: + - functions/urls/URLize returnType: string signatures: [urls.Anchorize INPUT] -relatedFunctions: - - urls.Anchorize - - urls.URLize aliases: [/functions/anchorize] --- -If [Goldmark](/getting-started/configuration-markup#goldmark) is set as `defaultMarkdownHandler`, the sanitizing logic adheres to the setting [`markup.goldmark.parser.autoHeadingIDType`](/getting-started/configuration-markup#goldmark). +{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}} -Since the `defaultMarkdownHandler` and this template function use the same sanitizing logic, you can use the latter to determine the ID of a header for linking with anchor tags. +## Sanitizing logic -```go-html-template -{{ anchorize "This is a header" }} → "this-is-a-header" -{{ anchorize "This is also a header" }} → "this-is-also----a-header" -{{ anchorize "main.go" }} → "maingo" -{{ anchorize "Article 123" }} → "article-123" -{{ anchorize "<- Let's try this, shall we?" }} → "--lets-try-this-shall-we" -{{ anchorize "Hello, 世界" }} → "hello-世界" -``` +With the default markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration: + +{{< code-toggle file=hugo >}} +[markup.goldmark.parser] +autoHeadingIDType = 'github' +{{< /code-toggle >}} + +This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering markdown to HTML. + +Set `autoHeadingIDType` to one of: + +github +: Compatible with GitHub. This is the default, and strongly recommended. + +github-ascii +: Similar to the "github" setting, but removes non-ASCII characters. + +blackfriday +: Provided for backwards compatibility with Hugo v0.59.1 and earlier. This option will be removed in a future release. diff --git a/content/en/functions/urls/JoinPath.md b/content/en/functions/urls/JoinPath.md index 41adf7ee7..7acecb506 100644 --- a/content/en/functions/urls/JoinPath.md +++ b/content/en/functions/urls/JoinPath.md @@ -1,30 +1,28 @@ --- title: urls.JoinPath description: Joins the provided elements into a URL string and cleans the result of any ./ or ../ elements. If the argument list is empty, JoinPath returns an empty string. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Join returnType: string signatures: [urls.JoinPath ELEMENT...] -relatedFunctions: - - path.Join - - urls.JoinPath aliases: [/functions/urls.joinpath] --- +{{< new-in 0.112.0 >}} + ```go-html-template -{{ urls.JoinPath }} → "" -{{ urls.JoinPath "" }} → "/" -{{ urls.JoinPath "a" }} → "a" -{{ urls.JoinPath "a" "b" }} → "a/b" -{{ urls.JoinPath "/a" "b" }} → "/a/b" -{{ urls.JoinPath "https://example.org" "b" }} → "https://example.org/b" +{{ urls.JoinPath }} → "" (empty string) +{{ urls.JoinPath "" }} → / +{{ urls.JoinPath "a" }} → a +{{ urls.JoinPath "a" "b" }} → a/b +{{ urls.JoinPath "/a" "b" }} → /a/b +{{ urls.JoinPath "https://example.org" "b" }} → https://example.org/b -{{ urls.JoinPath (slice "a" "b") }} → "a/b" +{{ urls.JoinPath (slice "a" "b") }} → a/b ``` Unlike the [`path.Join`] function, `urls.JoinPath` retains consecutive leading slashes. diff --git a/content/en/functions/urls/Parse.md b/content/en/functions/urls/Parse.md index 17c924d51..2eb4eeadf 100644 --- a/content/en/functions/urls/Parse.md +++ b/content/en/functions/urls/Parse.md @@ -1,16 +1,13 @@ --- title: urls.Parse description: Parses a URL into a URL structure. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] - returnType: URL + related: [] + returnType: url.URL signatures: [urls.Parse URL] -relatedFunctions: [] aliases: [/functions/urls.parse] --- @@ -18,7 +15,6 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/ [scheme]: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml#uri-schemes-1 - ```go-html-template {{ $url := "https://example.org:123/foo?a=6&b=7#bar" }} {{ $u := urls.Parse $url }} diff --git a/content/en/functions/urls/Ref.md b/content/en/functions/urls/Ref.md index 908fd6ca8..6cd97f030 100644 --- a/content/en/functions/urls/Ref.md +++ b/content/en/functions/urls/Ref.md @@ -1,26 +1,24 @@ --- title: urls.Ref -linkTitle: ref -description: Returns the absolute permalink to a page. -categories: [functions] +description: Returns the absolute permalink to a page at the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [ref] - returnType: template.HTML - signatures: [urls.Ref . PAGE] -relatedFunctions: - - urls.Ref - - urls.RelRef + related: + - functions/urls/RelRef + - methods/page/Ref + - methods/page/RelRef + returnType: string + signatures: + - urls.Ref PAGE PATH + - urls.Ref PAGE OPTIONS aliases: [/functions/ref] --- -This function takes two arguments: +The first argument is the context of the page from which to resolve relative paths, typically the current page. -- The context of the page from which to resolve relative paths, typically the current page (`.`) -- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. +The second argument is a path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. Alternatively, provide an [options map](#options) instead of a path. ```go-html-template {{ ref . "about" }} @@ -32,6 +30,19 @@ This function takes two arguments: {{ ref . "/blog/my-post.md" }} ``` +## Options + +Instead of specifying a path, you can also provide an options map: + +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. + To return the absolute permalink to another language version of a page: ```go-html-template @@ -44,6 +55,9 @@ To return the absolute permalink to another Output Format of a page: {{ ref . (dict "path" "about.md" "outputFormat" "rss") }} ``` -Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration). +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. -This function is used by Hugo's built-in [`ref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/). +{{< code-toggle file=hugo >}} +refLinksErrorLevel = 'warning' +refLinksNotFoundURL = '/some/other/url' +{{< /code-toggle >}} diff --git a/content/en/functions/urls/RelLangURL.md b/content/en/functions/urls/RelLangURL.md index b8850c71d..2c1037038 100644 --- a/content/en/functions/urls/RelLangURL.md +++ b/content/en/functions/urls/RelLangURL.md @@ -1,21 +1,16 @@ --- title: urls.RelLangURL -linkTitle: relLangURL description: Returns a relative URL with a language prefix, if any. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [relLangURL] - returnType: template.HTML + related: + - functions/urls/AbsLangURL + - functions/urls/AbsURL + - functions/urls/RelURL + returnType: string signatures: [urls.RelLangURL INPUT] -relatedFunctions: - - urls.AbsLangURL - - urls.AbsURL - - urls.RelLangURL - - urls.RelURL aliases: [/functions/rellangurl] --- @@ -37,7 +32,7 @@ With `baseURL = https://example.org/` {{ relLangURL "" }} → /en/ {{ relLangURL "articles" }} → /en/articles {{ relLangURL "style.css" }} → /en/style.css -``` +``` With `baseURL = https://example.org/docs/` @@ -57,7 +52,7 @@ With `baseURL = https://example.org/` {{ relLangURL "/" }} → /en/ {{ relLangURL "/articles" }} → /en/articles {{ relLangURL "/style.css" }} → /en/style.css -``` +``` With `baseURL = https://example.org/docs/` diff --git a/content/en/functions/urls/RelRef.md b/content/en/functions/urls/RelRef.md index 1ff213b70..6b45b2131 100644 --- a/content/en/functions/urls/RelRef.md +++ b/content/en/functions/urls/RelRef.md @@ -1,27 +1,25 @@ --- title: urls.RelRef -linkTitle: relref -description: Returns the relative permalink to a page. -categories: [functions] +description: Returns the relative permalink to a page at the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [relref] - returnType: template.HTML - signatures: [urls.RelRef . PAGE] -relatedFunctions: - - urls.Ref - - urls.RelRef + related: + - functions/urls/Ref + - methods/page/Ref + - methods/page/RelRef + returnType: string + signatures: + - urls.RelRef PAGE PATH + - urls.RelRef PAGE OPTIONS aliases: [/functions/relref] --- -This function takes two arguments: - -- The context of the page from which to resolve relative paths, typically the current page (`.`) -- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. +The first argument is the context of the page from which to resolve relative paths, typically the current page. +The second argument is a path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. Alternatively, provide an [options map](#options) instead of a path. +. ```go-html-template {{ relref . "about" }} {{ relref . "about#anchor" }} @@ -36,8 +34,21 @@ The permalink returned is relative to the protocol+host portion of the baseURL s Code|baseURL|Permalink :--|:--|:-- -`{{ relref . "/about" }}`|`http://example.org/`|`/about/` -`{{ relref . "/about" }}`|`http://example.org/x/`|`/x/about/` +`{{ relref . "/about" }}`|`https://example.org/`|`/about/` +`{{ relref . "/about" }}`|`https://example.org/x/`|`/x/about/` + +## Options + +Instead of specifying a path, you can also provide an options map: + +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. To return the relative permalink to another language version of a page: @@ -51,6 +62,9 @@ To return the relative permalink to another Output Format of a page: {{ relref . (dict "path" "about.md" "outputFormat" "rss") }} ``` -Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration). +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. -This function is used by Hugo's built-in [`relref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/). +{{< code-toggle file=hugo >}} +refLinksErrorLevel = 'warning' +refLinksNotFoundURL = '/some/other/url' +{{< /code-toggle >}} diff --git a/content/en/functions/urls/RelURL.md b/content/en/functions/urls/RelURL.md index fa1f9af73..9320c2827 100644 --- a/content/en/functions/urls/RelURL.md +++ b/content/en/functions/urls/RelURL.md @@ -1,21 +1,16 @@ --- title: urls.RelURL -linkTitle: relURL description: Returns a relative URL. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [relURL] - returnType: template.HTML + related: + - functions/urls/AbsLangURL + - functions/urls/AbsURL + - functions/urls/RelLangURL + returnType: string signatures: [urls.RelURL INPUT] -relatedFunctions: - - urls.AbsLangURL - - urls.AbsURL - - urls.RelLangURL - - urls.RelURL aliases: [/functions/relurl] --- diff --git a/content/en/functions/urls/URLize.md b/content/en/functions/urls/URLize.md index 3c80a92f8..bf44a82d1 100644 --- a/content/en/functions/urls/URLize.md +++ b/content/en/functions/urls/URLize.md @@ -1,69 +1,63 @@ --- title: urls.URLize -linkTitle: urlize -description: Takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens. -categories: [functions] +description: Returns the given string, sanitized for usage in a URL. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [urlize] + related: + - functions/urls/Anchorize returnType: string signatures: [urls.URLize INPUT] -relatedFunctions: - - urls.Anchorize - - urls.URLize aliases: [/functions/urlize] --- -The following examples pull from a content file with the following front matter: +{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}} -{{< code-toggle file="content/blog/greatest-city.md" fm=true copy=false >}} -title = "The World's Greatest City" -location = "Chicago IL" -tags = ["pizza","beer","hot dogs"] +## Example + +Use the `urlize` function to create a link to a [term] page. + +Consider this site configuration: + +{{< code-toggle file=hugo >}} +[taxonomies] +author = 'authors' +{{< /code-toggle >}} + +And this front matter: + +{{< code-toggle file=content/books/les-miserables.md fm=true >}} +title = 'Les Misérables' +authors = ['Victor Hugo'] {{< /code-toggle >}} -The following might be used as a partial within a [single page template][singletemplate]: +The published site will have this structure: -{{< code file="layouts/partials/content-header.html" >}} -<header> - <h1>{{ .Title }}</h1> - {{ with .Params.location }} - <div><a href="/locations/{{ . | urlize }}">{{ . }}</a></div> - {{ end }} - <!-- Creates a list of tags for the content and links to each of their pages --> - {{ with .Params.tags }} - <ul> - {{ range .}} - <li> - <a href="/tags/{{ . | urlize }}">{{ . }}</a> - </li> - {{ end }} - </ul> - {{ end }} -</header> -{{< /code >}} +```text +public/ +├── authors/ +│ ├── victor-hugo/ +│ │ └── index.html +│ └── index.html +├── books/ +│ ├── les-miserables/ +│ │ └── index.html +│ └── index.html +└── index.html +``` -The preceding partial would then output to the rendered page as follows: +To create a link to the term page: -```html -<header> - <h1>The World's Greatest City</h1> - <div><a href="/locations/chicago-il">Chicago IL</a></div> - <ul> - <li> - <a href="/tags/pizza">pizza</a> - </li> - <li> - <a href="/tags/beer">beer</a> - </li> - <li> - <a href="/tags/hot-dogs">hot dogs</a> - </li> - </ul> -</header> +```go-html-template +{{ $taxonomy := "authors" }} +{{ $term := "Victor Hugo" }} +{{ with index .Site.Taxonomies $taxonomy (urlize $term) }} + <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> +{{ end }} ``` -[singletemplate]: /templates/single-page-templates/ +To generate a list of term pages associated with a given content page, use the [`GetTerms`] method on a `Page` object. + +[`GetTerms`]: /methods/page/getterms/ +[term]: /getting-started/glossary/#term diff --git a/content/en/functions/urls/_common/_index.md b/content/en/functions/urls/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/functions/urls/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/content/en/functions/urls/_common/anchorize-vs-urlize.md b/content/en/functions/urls/_common/anchorize-vs-urlize.md new file mode 100644 index 000000000..0f01bcf78 --- /dev/null +++ b/content/en/functions/urls/_common/anchorize-vs-urlize.md @@ -0,0 +1,35 @@ +--- +# Do not remove front matter. +--- + +The [`anchorize`] and [`urlize`] functions are similar: + +[`anchorize`]: /functions/urls/anchorize +[`urlize`]: /functions/urls/urlize + +- Use the `anchorize` function to generate an HTML `id` attribute value +- Use the `urlize` function to sanitize a string for usage in a URL + +For example: + +```go-html-template +{{ $s := "A B C" }} +{{ $s | anchorize }} → a-b-c +{{ $s | urlize }} → a-b-c + +{{ $s := "a b c" }} +{{ $s | anchorize }} → a-b---c +{{ $s | urlize }} → a-b-c + +{{ $s := "< a, b, & c >" }} +{{ $s | anchorize }} → -a-b--c- +{{ $s | urlize }} → a-b-c + +{{ $s := "main.go" }} +{{ $s | anchorize }} → maingo +{{ $s | urlize }} → main.go + +{{ $s := "Hugö" }} +{{ $s | anchorize }} → hugö +{{ $s | urlize }} → hug%C3%B6 +``` diff --git a/content/en/functions/urls/_index.md b/content/en/functions/urls/_index.md new file mode 100644 index 000000000..5f16feeeb --- /dev/null +++ b/content/en/functions/urls/_index.md @@ -0,0 +1,12 @@ +--- +title: URL functions +linkTitle: urls +description: Template functions to work with URLs. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with URLs. diff --git a/content/en/getting-started/_index.md b/content/en/getting-started/_index.md index 3265e1782..780b96a62 100644 --- a/content/en/getting-started/_index.md +++ b/content/en/getting-started/_index.md @@ -2,8 +2,8 @@ title: Getting started linkTitle: Overview description: Quick start and guides for installing Hugo on your preferred operating system. -categories: [getting started] -keywords: [usage,docs] +categories: [] +keywords: [] menu: docs: identifier: getting-started-overview diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md index 02c4ea998..607301d3a 100644 --- a/content/en/getting-started/configuration-markup.md +++ b/content/en/getting-started/configuration-markup.md @@ -1,7 +1,7 @@ --- title: Configure markup description: Configure rendering of markup to HTML. -categories: [fundamentals, getting started] +categories: [getting started,fundamentals] keywords: [configuration,highlighting] menu: docs: @@ -16,7 +16,7 @@ toc: true By default, Hugo uses [Goldmark] to render markdown to HTML. -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} [markup] defaultMarkdownHandler = 'goldmark' {{< /code-toggle >}} @@ -54,9 +54,9 @@ Unless you need a unique capability provided by one of the alternate markdown ha This is the default configuration for the Goldmark markdown renderer: -{{< code-toggle config="markup.goldmark" />}} +{{< code-toggle config=markup.goldmark />}} -For details on the extensions, refer to [this section](https://github.com/yuin/goldmark/#built-in-extensions) of the Goldmark documentation +For details on the extensions, refer to the [Goldmark documentation](https://github.com/yuin/goldmark/#built-in-extensions). Some settings explained: @@ -82,7 +82,6 @@ Markdown|Replaced by|Description `”`|`”`|right double quote `’`|`’`|right single quote - attribute : Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets (`{.myclass class="class1 class2" }`) and placing it _after the Markdown element it decorates_, on the same line for titles and on a new line directly below for blocks. @@ -120,13 +119,13 @@ Note that attributes in [code fences](/content-management/syntax-highlighting/#h ```` autoHeadingIDType ("github") -: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-Ascii characters after accent normalization, and `blackfriday` will make the IDs compatible with Blackfriday, the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/urls/anchorize) template func. +: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-ASCII characters after accent normalization, and `blackfriday` will make the IDs compatible with Blackfriday, the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/urls/anchorize) template func. ## Asciidoc This is the default configuration for the AsciiDoc markdown renderer: -{{< code-toggle config="markup.asciidocExt" />}} +{{< code-toggle config=markup.asciidocExt />}} attributes : (`map`) Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See Asciidoctor’s [attributes]. @@ -190,7 +189,7 @@ INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\ascii This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/). -{{< code-toggle config="markup.highlight" />}} +{{< code-toggle config=markup.highlight />}} For `style`, see these galleries: @@ -201,7 +200,7 @@ For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highli ## Table of contents -{{< code-toggle config="markup.tableOfContents" />}} +{{< code-toggle config=markup.tableOfContents />}} These settings only works for the Goldmark renderer: diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index e72bb8d3b..2ab5450f3 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -2,15 +2,15 @@ title: Configure Hugo linkTitle: Configuration description: How to configure your Hugo site. -categories: [fundamentals,getting started] +categories: [getting started,fundamentals] keywords: [configuration,toml,yaml,json] menu: docs: parent: getting-started weight: 40 weight: 40 -aliases: [/overview/source-directory/,/overview/configuration/] toc: true +aliases: [/overview/source-directory/,/overview/configuration/] --- ## Configuration file @@ -35,7 +35,7 @@ Multiple site configuration files can be specified as a comma-separated string t In Hugo 0.110.0 we changed the default configuration base file name to `hugo`, e.g. `hugo.toml`. We will still look for `config.toml` etc., but we recommend you eventually rename it (but you need to wait if you want to support older Hugo versions). The main reason we're doing this is to make it easier for code editors and build tools to identify this as a Hugo configuration file and project. -{{< new-in "0.110.0" >}} +{{< new-in 0.110.0 >}} ## Configuration directory @@ -44,12 +44,12 @@ In addition to using a single site configuration file, one can use the `configDi - Each file represents a configuration root object, such as `params.toml` for `[Params]`, `menu(s).toml` for `[Menu]`, `languages.toml` for `[Languages]` etc... - Each file's content must be top-level, for example: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [Params] foo = "bar" {{< /code-toggle >}} -{{< code-toggle file="params" >}} +{{< code-toggle file=params >}} foo = "bar" {{< /code-toggle >}} @@ -74,28 +74,56 @@ foo = "bar" Considering the structure above, when running `hugo --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those. -Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify `googleAnalytics = "G-XXXXXXXX"` in `hugo.toml`. Now consider the following scenario: -- You don't want the Analytics code to be loaded in development i.e. in your `localhost` -- You want to use separate googleAnalytics IDs for your production & staging environments (say): - - `G-PPPPPPPP` for production - - `G-SSSSSSSS` for staging +Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your site configuration: -This is how you need to configure your `hugo.toml` files considering the above scenario: -1. In `_default/hugo.toml` you don't need to mention `googleAnalytics` parameter at all. This ensures that no Google Analytics code is loaded in your development server i.e. when you run `hugo server`. This works since, by default Hugo sets `Environment=development` when you run `hugo server` which uses the configuration files from `_default` folder -2. In `production/hugo.toml` you just need to have one line: +[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en - ```googleAnalytics = "G-PPPPPPPP"``` +{{< code-toggle file=hugo >}} +[services.googleAnalytics] +ID = 'G-XXXXXXXXX' +{{< /code-toggle >}} - You don't need to mention all other parameters like `title`, `baseURL`, `theme` etc. again in this configuration file. You need to mention only those parameters which are different or new for the production environment. This is due to the fact that Hugo is going to __merge__ this on top of `_default/hugo.toml`. Now when you run `hugo` (build command), by default hugo sets `Environment=production`, so the `G-PPPPPPPP` analytics code will be there in your production website -3. Similarly in `staging/hugo.toml` you just need to have one line: +Now consider the following scenario: - ```googleAnalytics = "G-SSSSSSSS"``` +1. You don't want to load the analytics code when running `hugo server`. +2. You want to use different Google tag IDs for your production and staging environments. For example: - Now you need to tell Hugo that you are using the staging environment. So your build command should be `hugo --environment staging` which will load the `G-SSSSSSSS` analytics code in your staging website + - `G-PPPPPPPPP` for production + - `G-SSSSSSSSS` for staging -{{% note %}} -Default environments are __development__ with `hugo server` and __production__ with `hugo`. -{{%/ note %}} +To satisfy these requirements, configure your site as follows: + +1. `config/_default/hugo.toml` + + Exclude the `services.googleAnalytics` section. This will prevent loading of the analytics code when you run `hugo server`. + + By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory. + +2. `config/production/hugo.toml` + + Include this section only: + + {{< code-toggle file=hugo >}} + [services.googleAnalytics] + ID = 'G-PPPPPPPPP' + {{< /code-toggle >}} + + You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration. + + By default, Hugo sets its `environment` to `production` when running `hugo`. The analytics code will use the `G-PPPPPPPPP` tag ID. + +3. `config/staging/hugo.toml` + + Include this section only: + + {{< code-toggle file=hugo >}} + [services.googleAnalytics] + ID = 'G-SSSSSSSSS' + {{< /code-toggle >}} + + You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration. + + To build your staging site, run `hugo --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID. ## Merge configuration from themes @@ -112,7 +140,7 @@ deep Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set. -{{< code-toggle file="hugo" dataKey="config_helpers.mergeStrategy" skipHeader=true />}} +{{< code-toggle file=hugo dataKey="config_helpers.mergeStrategy" skipHeader=true />}} ## All configuration settings @@ -162,13 +190,19 @@ See [Configure File Caches](#configure-file-caches) ### cascade -Pass down default configuration values (front matter) to pages in the content tree. The options in site configuration is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade). +Pass down down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade). + +{{% note %}} +For a website in a single language, define the `[[cascade]]` in [Front Matter](/content-management/front-matter#front-matter-cascade). For a multilingual website, define the `[[cascade]]` in [Site Config](../../getting-started/configuration/#cascade). + +To remain consistent and prevent unexpected behaviour, do not mix these strategies. +{{% /note %}} ### canonifyURLs **Default value:** false -Enable to turn relative URLs into absolute. See [details](/content-management/urls/#canonical-urls). +Enable to turn relative URLs into absolute. See [details](/content-management/urls/#canonical-urls). ### cleanDestinationDir @@ -240,7 +274,7 @@ Do not convert the url/path to lowercase. **Default value:** false -Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/). +Enable Emoji emoticons support for page content; see the [emoji shortcode quick reference guide](/quick-reference/emojis/). ### enableGitInfo @@ -270,12 +304,6 @@ Enable generation of `robots.txt` file. See [Front matter Configuration](#configure-front-matter). -### googleAnalytics - -**Default value:** "" - -Google Analytics tracking ID. - ### hasCJKLanguage **Default value:** false @@ -355,7 +383,7 @@ Default number of elements per page in [pagination](/templates/pagination/). **Default value:** "page" -The path element used during pagination (`https://example.com/page/2`). +The path element used during pagination (`https://example.org/page/2`). ### permalinks @@ -381,7 +409,7 @@ See [Related Content](/content-management/related/#configure-related-content). **Default value:** false -Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. See [details](/content-management/urls/#relative-urls). +Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. See [details](/content-management/urls/#relative-urls). ### refLinksErrorLevel @@ -403,12 +431,6 @@ Removes [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from content/post/hügó.md → https://example.org/post/hugo/ ``` -### rssLimit - -**Default value:** -1 (unlimited) - -Maximum number of items in the RSS feed. - ### sectionPagesMenu See [Menus](/content-management/menus/#define-automatically). @@ -491,9 +513,9 @@ enableemoji: true The `build` configuration section contains global build-related configuration options. -{{< code-toggle config="build" />}} +{{< code-toggle config=build />}} -buildStats {{< new-in "0.115.1" >}} +buildStats {{< new-in 0.115.1 >}} : When enabled, creates a `hugo_stats.json` file in the root of your project. This file contains arrays of the `class` attributes, `id` attributes, and tags of every HTML element within your published site. Use this file as data source when [removing unused CSS] from your site. This process is also known as pruning, purging, or tree shaking. [removing unused CSS]: /hugo-pipes/postprocess/#css-purging-with-postcss @@ -523,11 +545,11 @@ useResourceCacheWhen ## Configure cache busters -{{< new-in "0.112.0" >}} +{{< new-in 0.112.0 >}} The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [build] [build.buildStats] enable = true @@ -557,8 +579,7 @@ target This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slightly more powerful [Glob matching](https://github.com/gobwas/glob): - -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [server] [[server.headers]] for = "/**" @@ -573,7 +594,7 @@ Content-Security-Policy = "script-src localhost:1313" Since this is "development only", it may make sense to put it below the `development` environment: -{{< code-toggle file="config/development/server">}} +{{< code-toggle file=config/development/server >}} [[headers]] for = "/**" @@ -589,7 +610,7 @@ You can also specify simple redirects rules for the server. The syntax is again Note that a `status` code of 200 will trigger a [URL rewrite](https://docs.netlify.com/routing/redirects/rewrites-proxies/), which is what you want in SPA situations, e.g: -{{< code-toggle file="config/development/server">}} +{{< code-toggle file=config/development/server >}} [[redirects]] from = "/myspa/**" to = "/myspa/" @@ -601,11 +622,11 @@ Setting `force=true` will make a redirect even if there is existing content in t ## 404 server error page {#_404-server-error-page} -{{< new-in "0.103.0" >}} +{{< new-in 0.103.0 >}} Hugo will, by default, render all 404 errors when running `hugo server` with the `404.html` template. Note that if you have already added one or more redirects to your [server configuration](#configure-server), you need to add the 404 redirect explicitly, e.g: -{{< code-toggle file="config/development/server" copy=false >}} +{{< code-toggle file=config/development/server >}} [[redirects]] from = "/**" to = "/404.html" @@ -614,17 +635,27 @@ status = 404 ## Configure title case -Set `titleCaseStyle` to specify the title style used by the [title](/functions/strings/title) template function and the automatic section titles in Hugo. +By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook] when creating automatic section titles, and when transforming strings with the [`strings.Title`] function. -Can be one of: +Change this behavior by setting `titleCaseStyle` in your site configuration to any of the values below: -* `ap` (default), the capitalization rules in the [Associated Press (AP) Stylebook] -* `chicago`, the [Chicago Manual of Style] -* `go`, Go's convention of capitalizing every word. -* `firstupper`, capitalize the first letter of the first word. -* `none`, no capitalization. +ap +: Use the capitalization rules published in the [Associated Press Stylebook]. -[Associated Press (AP) Stylebook]: https://www.apstylebook.com/ +chicago +: Use the capitalization rules published in the [Chicago Manual of Style]. + +go +: Capitalize the first letter of every word. + +firstupper +: Capitalize the first letter of the first word. + +none +: Disable transformation of automatic section titles, and disable the transformation performed by the `strings.Title` function. This is useful if you would prefer to manually capitalize section titles as needed, and to bypass opinionated theme usage of the `strings.Title` function. + +[`strings.Title`]: /functions/strings/title +[Associated Press Stylebook]: https://www.apstylebook.com/ [Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html [site configuration]: /getting-started/configuration/#configure-title-case @@ -647,7 +678,7 @@ In your configuration file, you can direct Hugo as to how you want your website The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`] variable for use in [templates]: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} baseURL: "https://yoursite.example.com/" title: "My Hugo Site" permalinks: @@ -684,19 +715,21 @@ If you are using snake_cased variable names, the above will not work. Hugo deter ## Ignore content and data files when rendering -**Note:** This works, but we recommend you use the newer and more powerful [includeFiles and excludeFiles](/hugo-modules/configuration/#module-configuration-mounts) mount options. +{{% note %}} +This works, but we recommend you use the newer and more powerful [includeFiles and excludeFiles](/hugo-modules/configuration/#module-configuration-mounts) mount options. +{{% /note %}} To exclude specific files from the `content`, `data`, and `i18n` directories when rendering your site, set `ignoreFiles` to one or more regular expressions to match against the absolute file path. To ignore files ending with `.foo` or `.boo`: -{{< code-toggle copy=false file="hugo" >}} +{{< code-toggle file=hugo >}} ignoreFiles = ['\.foo$', '\.boo$'] {{< /code-toggle >}} To ignore a file using the absolute file path: -{{< code-toggle copy=false file="hugo" >}} +{{< code-toggle file=hugo >}} ignoreFiles = ['^/home/user/project/content/test\.md$'] {{< /code-toggle >}} @@ -708,11 +741,11 @@ Dates are important in Hugo, and you can configure how Hugo assigns dates to you The default configuration is: -{{< code-toggle config="frontmatter" />}} +{{< code-toggle config=frontmatter />}} If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [frontmatter] date = ["myDate", ":default"] {{< /code-toggle >}} @@ -728,7 +761,7 @@ The special date handlers are: An example: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [frontmatter] lastmod = ["lastmod", ":fileModTime", ":default"] {{< /code-toggle >}} @@ -740,7 +773,7 @@ The above will try first to extract the value for `.Lastmod` starting with the ` An example: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [frontmatter] date = [":filename", ":default"] {{< /code-toggle >}} @@ -758,32 +791,32 @@ Hugo v0.20 introduced the ability to render your content to multiple output form Default configuration: -{{< code-toggle config="minify" />}} +{{< code-toggle config=minify />}} ## Configure file caches Since Hugo 0.52 you can configure more than just the `cacheDir`. This is the default configuration: -{{< code-toggle config="caches" />}} +{{< code-toggle config=caches />}} You can override any of these cache settings in your own `hugo.toml`. ### The keywords explained -`:cacheDir` -: See [Configure cacheDir](#configure-cachedir). +cacheDir +: (`string`) See [Configure cacheDir](#configure-cachedir). -`:project` -: The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC. +project +: (`string`) The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC. -`:resourceDir` -: This is the value of the `resourceDir` configuration option. +resourceDir +: (`string`) This is the value of the `resourceDir` configuration option. maxAge -: This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours). +: (`string`) This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours). dir -: The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above). +: (`string`) The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above). ## Configuration format specs @@ -801,7 +834,6 @@ dir [yaml]: https://yaml.org/spec/ [static-files]: /content-management/static-files/ - ## Configure cacheDir This is the directory where Hugo by default will store its file caches. See [Configure File Caches](#configure-file-caches). @@ -811,10 +843,9 @@ This can be set using the `cacheDir` config option or via the OS env variable `H If this is not set, Hugo will use, in order of preference: 1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml). -1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir](https://pkg.go.dev/os#UserCacheDir). On Unix systems, this is `$XDG_CACHE_HOME` as specified by [basedir-spec-latest](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. {{< new-in "0.116.0" >}} +1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir](https://pkg.go.dev/os#UserCacheDir). On Unix systems, this is `$XDG_CACHE_HOME` as specified by [basedir-spec-latest](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. {{< new-in 0.116.0 >}} 1. In a `hugo_cache_$USER` directory below the OS temp dir. If you want to know the current value of `cacheDir`, you can run `hugo config`, e.g: `hugo config | grep cachedir`. - [`time`]: /functions/time/astime diff --git a/content/en/getting-started/directory-structure.md b/content/en/getting-started/directory-structure.md index ecdda25cd..f91849375 100644 --- a/content/en/getting-started/directory-structure.md +++ b/content/en/getting-started/directory-structure.md @@ -1,22 +1,22 @@ --- title: Directory structure description: Each Hugo project is a directory, with subdirectories that contribute to the content, structure, behavior, and presentation of your site. -categories: [fundamentals,getting started] +categories: [getting started,fundamentals] keywords: [source, organization, directories] menu: docs: parent: getting-started weight: 30 weight: 30 -aliases: [/overview/source-directory/] toc: true +aliases: [/overview/source-directory/] --- ## Site skeleton Hugo generates a project skeleton when you create a new site. For example, this command: -```text +```sh hugo new site my-site ``` @@ -25,7 +25,7 @@ Creates this directory structure: ```txt my-site/ ├── archetypes/ -│ └── default.md +│ └── default.md ├── assets/ ├── content/ ├── data/ @@ -41,11 +41,11 @@ Depending on requirements, you may wish to organize your site configuration into ```txt my-site/ ├── archetypes/ -│ └── default.md +│ └── default.md ├── assets/ ├── config/ <-- site configuration -│ └── _default/ -│ └── hugo.toml +│ └── _default/ +│ └── hugo.toml ├── content/ ├── data/ ├── i18n/ @@ -59,11 +59,11 @@ When you build your site, Hugo creates a `public` directory, and typically a `re ```txt my-site/ ├── archetypes/ -│ └── default.md +│ └── default.md ├── assets/ ├── config/ -│ └── _default/ -│ └── hugo.toml +│ └── _default/ +│ └── hugo.toml ├── content/ ├── data/ ├── i18n/ @@ -119,15 +119,15 @@ Hugo creates a union file system, allowing you to mount two or more directories home/ └── user/ ├── my-site/ - │ ├── content/ - │ │ ├── books/ - │ │ │ ├── _index.md - │ │ │ ├── book-1.md - │ │ │ └── book-2.md - │ │ └── _index.md - │ ├── themes/ - │ │ └── my-theme/ - │ └── hugo.toml + │ ├── content/ + │ │ ├── books/ + │ │ │ ├── _index.md + │ │ │ ├── book-1.md + │ │ │ └── book-2.md + │ │ └── _index.md + │ ├── themes/ + │ │ └── my-theme/ + │ └── hugo.toml └── shared-content/ └── films/ ├── _index.md @@ -137,7 +137,7 @@ home/ You can include the shared content when you build your site using mounts. In your site configuration: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} [[module.mounts]] source = 'content' target = 'content' @@ -160,17 +160,17 @@ home/ └── user/ └── my-site/ ├── content/ - │ ├── books/ - │ │ ├── _index.md - │ │ ├── book-1.md - │ │ └── book-2.md - │ ├── films/ - │ │ ├── _index.md - │ │ ├── film-1.md - │ │ └── film-2.md - │ └── _index.md + │ ├── books/ + │ │ ├── _index.md + │ │ ├── book-1.md + │ │ └── book-2.md + │ ├── films/ + │ │ ├── _index.md + │ │ ├── film-1.md + │ │ └── film-2.md + │ └── _index.md ├── themes/ - │ └── my-theme/ + │ └── my-theme/ └── hugo.toml ``` @@ -182,7 +182,6 @@ You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, You can also mount directories from Git repositories using Hugo Modules. See [details](/hugo-modules/). - ## Theme skeleton Hugo generates a functional theme skeleton when you create a new theme. For example, this command: diff --git a/content/en/getting-started/external-learning-resources/index.md b/content/en/getting-started/external-learning-resources/index.md index 4337c51a4..634439bc6 100644 --- a/content/en/getting-started/external-learning-resources/index.md +++ b/content/en/getting-started/external-learning-resources/index.md @@ -1,6 +1,7 @@ --- title: External learning resources description: A list of tutorials and books on Hugo. +categories: [getting started] keywords: [books, tutorials, learning, usage] menu: docs: diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md index 759cb1cd1..edf64ab89 100644 --- a/content/en/getting-started/glossary.md +++ b/content/en/getting-started/glossary.md @@ -1,274 +1,375 @@ --- title: Glossary of terms description: Terms commonly used throughout the documentation. +categories: [getting started] keywords: [glossary] menu: docs: parent: getting-started weight: 60 weight: 60 -type: glossary +# Use level 6 headings for each term in the glossary. --- -<!-- Use level 3 headings for each term in the glossary. --> - -### action +###### action See [template action](#template-action). -### archetype +###### archetype -A template for new content. See [details](/content-management/archetypes/). +A template for new content. See [details](/content-management/archetypes/). -### argument +###### argument A [scalar](#scalar), [array](#array), [slice](#slice), [map](#map), or [object](#object) passed to a [function](#function), [method](#method), or [shortcode](#shortcode). -### array +###### array -A numbered sequence of elements. Unlike Go's [slice](#slice) data type, an array has a fixed length. See the [Go documentation](https://go.dev/ref/spec#Array_types) for details. +A numbered sequence of elements. Unlike Go's [slice](#slice) data type, an array has a fixed length. [Elements](#element) within an array can be [scalars](#scalar), slices, [maps](#map), pages, or other arrays. See the [Go documentation](https://go.dev/ref/spec#Array_types) for details. -### bool +###### bool See [boolean](#boolean). -### boolean +###### boolean A data type with two possible values, either `true` or `false`. -### branch bundle +###### branch bundle -A [page bundle](#page-bundle) with an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including regular pages, [leaf bundles](/getting-started/glossary/#leaf-bundle), and other branch bundles. See [details](/content-management/page-bundles/). +A [page bundle](#page-bundle) with an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including regular pages, [leaf bundles](/getting-started/glossary/#leaf-bundle), and other branch bundles. See [details](/content-management/page-bundles/). -### build +###### build To generate a static site that includes HTML files and assets such as images, CSS, and JavaScript. The build process includes rendering and resource transformations. -### bundle +###### bundle See [page bundle](#page-bundle). -### cache +###### cache A software component that stores data so that future requests for the same data are faster. -### collection +###### chain + +Within a template, to connect one or more [identifiers](#identifier) with a dot. An identifier can represent a method, object, or field. For example, `.Site.Params.author.name` or `.Date.UTC.Hour`. -Typically, a collection of pages, but may also refer to an [array](#array), [slice](#slice), or [map](#map). For example, the pages within a site's "articles" section are a page collection. +###### collection -### content format +An [array](#array), [slice](#slice), or [map](#map). -A markup language for creating content. Typically markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/). +###### content format -### content type +A markup language for creating content. Typically markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/). + +###### content type A classification of content inferred from the top-level directory name or the `type` set in [front matter](#front-matter). Pages in the root of the content directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](#template). See [details](/content-management/types/). -### content view +###### content view A template called with the `.Page.Render` method. See [details](/templates/views/). -### context +###### context + +Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#the-dot). + +###### default sort order + +The default sort order for page collections. Hugo sorts by [weight](#weight), then by date (descending), then by link title, and then by file path. + +###### element + +A member of a slice or array. + +###### environment + +Typically one of `development`, `staging`, or `production`, each environment may exhibit different behavior depending on configuration and template logic. For example, in a production environment you might minify and fingerprint CSS, but that probably doesn't make sense in a development environment. + +When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your site with the `hugo` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag. + +To determine the current environment within a template, use the [`hugo.Environment`] function. + +[`hugo.Environment`]: /functions/hugo/environment -Represented by a period "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#the-dot). +###### field -### flag +A predefined key/value pair in front matter such as `date` or `title`. See also [parameter](#parameter). -An option passed to a command-line program, beginning with one or two hyphens. See [details](/commands/hugo/). -### float +###### flag + +An option passed to a command-line program, beginning with one or two hyphens. See [details](/commands/hugo/). + +###### float See [floating point](#floating-point). -### floating point +###### floating point A numeric data type with a fractional component. For example, `3.14159`. -### function +###### fragment -Used within a [template action](#template-action), a function takes one or more [arguments](#argument) and returns a value. Unlike [methods](#method), functions are not associated with an [object](#object). See [details](/functions/). +The final segment of a URL, beginning with a hash (`#`) mark, that references an `id` attribute of an HTML element on the page. -### front matter +###### front matter Metadata at the beginning of each content page, separated from the content by format-specific delimiters. See [details](/content-management/front-matter/). -### identifier +###### function + +Used within a [template action](#template-action), a function takes one or more [arguments](#argument) and returns a value. Unlike [methods](#method), functions are not associated with an [object](#object). See [details](/functions/). + +###### global resource + +A file within the assets directory, or within any directory [mounted](/hugo-modules/configuration/#module-configuration-mounts) to the assets directory. Capture one or more global resources using the [`resources.Get`], [`resources.GetMatch`], [`resources.Match`], or [`resources.ByType`] functions. + +[`resources.Get`]: /functions/resources/get +[`resources.GetMatch`]: /functions/resources/getmatch +[`resources.Match`]: /functions/resources/match +[`resources.ByType`]: /functions/resources/byType + +###### identifier A string that represents a variable, method, object, or field. It must conform to Go's [language specification](https://go.dev/ref/spec#Identifiers), beginning with a letter or underscore, followed by zero or more letters, digits, or underscores. -### int +###### int See [integer](#integer). -### integer +###### integer A numeric data type without a fractional component. For example, `42`. -### internationalization +###### internationalization Software design and development efforts that enable [localization](#localization). See the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated i18n. -### kind +###### kind See [page kind](#page-kind). -### layout +###### layout See [template](#template). -### leaf bundle +###### leaf bundle -A [page bundle](#page-bundle) with an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. Hugo ignores content (but not resources) beneath the leaf bundle. See [details](/content-management/page-bundles/). +A [page bundle](#page-bundle) with an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. Hugo ignores content (but not resources) beneath the leaf bundle. See [details](/content-management/page-bundles/). -### list page +###### list page Any [page kind](#page-kind) that receives a page [collection](#collection) in [context](#context). This includes the home page, [section pages](#section-page), [taxonomy pages](#taxonomy-page), and [term pages](#term-page). -### localization +###### localization -Adaptation of a site to meet language and regional requirements. This includes translations, language-specific media, date and currency formats, etc. See [details](/content-management/multilingual/) and the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated l10n. +Adaptation of a site to meet language and regional requirements. This includes translations, language-specific media, date and currency formats, etc. See [details](/content-management/multilingual/) and the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated l10n. -### map +###### map An unordered group of elements, each indexed by a unique key. See the [Go documentation](https://go.dev/ref/spec#Map_types) for details. -### method +###### markdown attribute + +A list of attributes, containing one or more key/value pairs, separated by spaces or commas, and wrapped by braces. Apply markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See [details](/getting-started/configuration-markup/#goldmark). + +###### marshal + +To transform a data structure into a serialized object. For example, transforming a [map](#map) into a JSON string. See [unmarshal](#unmarshal). + +###### method Used within a [template action](#template-action) and associated with an [object](#object), a method takes zero or more [arguments](#argument) and either returns a value or performs an action. For example, `.IsHome` is a method on the `.Page` object which returns `true` if the current page is the home page. See also [function](#function). -### module +###### module -Like a [theme](#theme), a module is a packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. See [details](/hugo-modules/). +Like a [theme](#theme), a module is a packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. See [details](/hugo-modules/). -### object +###### object A data structure with or without associated [methods](#method). -### page bundle +###### ordered taxonomy + +Created by invoking the [`Alphabetical`] or [`ByCount`] method on a [taxonomy object](#taxonomy-object), which is a [map](#map), an ordered taxonomy is a [slice](#slice), where each element is an object that contains the [term](#term) and a slice of its [weighted pages](#weighted-page). + +[`Alphabetical`]: /methods/taxonomy/alphabetical +[`ByCount`]: /methods/taxonomy/bycount -A directory that encapsulates both content and associated [resources](#resource). There are two types of page bundles: [leaf bundles](/getting-started/glossary/#leaf-bundle) and [branch bundles](/getting-started/glossary/#branch-bundle). See [details](/content-management/page-bundles/). +###### output format -### page kind +{{% include "methods/page/_common/output-format-definition.md" %}} -A classification of rendered pages, one of "home", "page", "section", "taxonomy", or "term". Accessed via `.Page.Kind` in [templates](#template). See [details](/templates/section-templates/#page-kinds). +###### page bundle -### pager +A directory that encapsulates both content and associated [resources](#resource). There are two types of page bundles: [leaf bundles](#leaf-bundle) and [branch bundles](#branch-bundle). See [details](/content-management/page-bundles/). + +###### page kind + +A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See [details](/templates/section-templates/#page-kinds). + +Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` page 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. + +###### page resource + +A file within a [page bundle](#page-bundle). Capture one or more page resources using any of the [`Resources`] methods on a `Page` object. + +[`Resources`]: /methods/page/resources/#methods + +###### pager Created during [pagination](#pagination), a pager contains a subset of a section list, and navigation links to other pagers. -### paginate +###### paginate To split a [section](#section) list into two or more [pagers](#pager) See [details](/templates/pagination/). -### pagination +###### pagination The process of [paginating](#paginate) a [section](#section) list. -### parameter +###### parameter -Typically, a user-defined key/value pair at the site or page level, but may also refer to a configuration setting or an [argument](#argument). +Typically, a user-defined key/value pair at the site or page level, but may also refer to a configuration setting or an [argument](#argument). See also [field](#field). -### partial +###### partial A [template](#template) called from any other template including [shortcodes](#shortcode), [render hooks](#render-hook), and other partials. A partial either renders something or returns something. A partial can also call itself, for example, to [walk](#walk) a data structure. -### permalink +###### permalink -The absolute URL of a rendered page, including scheme and host. +The absolute URL of a published resource or a rendered page, including scheme and host. -### pipe +###### pipe See [pipeline](#pipeline). -### pipeline +###### pipeline Within a [template action](#template-action), a pipeline is a possibly chained sequence of values, [function](#function) calls, or [method](#method) calls. Functions and methods in the pipeline may take multiple [arguments](#argument). A pipeline may be *chained* by separating a sequence of commands with pipeline characters "|". In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline. See the [Go documentation](https://pkg.go.dev/text/template#hdr-Pipelines) for details. -### publish +###### publish See [build](#build). -### regular page +###### regular page Content with the "page" [page kind](#page-kind). See also [section page](#section-page). -### render hook +###### relative permalink -A [template](#template) that overrides standard markdown rendering. See [details](/templates/render-hooks/). +The host-relative URL of a published resource or a rendered page. -### resource +###### render hook + +A [template](#template) that overrides standard markdown rendering. See [details](/templates/render-hooks/). + +###### remote resource + +A file on a remote server, accessible via HTTP or HTTPS with the [`resources.GetRemote`](/functions/resources/getremote) function. + +###### resource Any file consumed by the build process to augment or generate content, structure, behavior, or presentation. For example: images, videos, content snippets, CSS, Sass, JavaScript, and data. -Hugo supports three types of resources: page resources (located in a [page bundle](/getting-started/glossary/#page-bundle)), global resources (located in the assets directory), and remote resources (typically accessed via HTTPS). +Hugo supports three types of resources: [global](#global-resource), [page](#page-resource), and [remote](#remote-resource) -### scalar +###### scalar A single value, one of [string](#string), [integer](#integer), [floating point](#floating-point), or [boolean](#boolean). -### section +###### scratch pad + +Conceptually, a [map](#map) with [methods](#method) to set, get, update, and delete values. Attach the data structure to a `Page` object using the [`Scratch`] or [`Store`] methods, or created a locally scoped scratch pad using the [`newScratch`] function. + +[`Scratch`]: /methods/page/scratch +[`Store`]: /methods/page/store +[`newScratch`]: /functions/collections/newscratch -A top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](#collection) in [context](#context). See [details](/content-management/sections/). +###### section -### section page +A top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](#collection) in [context](#context). See [details](/content-management/sections/). + +###### section page Content with the "section" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and/or [section pages](#section-page) within the current [section](#section). See also [regular page](#regular-page). -### shortcode +###### shortcode -A [template](#template) called from within markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/). +A [template](#template) called from within markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/). -### slice +###### slice -A numbered sequence of elements. Unlike Go's [array](#array) data type, slices are dynamically sized. See the [Go documentation](https://go.dev/ref/spec#Slice_types) for details. +A numbered sequence of elements. Unlike Go's [array](#array) data type, slices are dynamically sized. [Elements](#element) within a slice can be [scalars](#scalar), [arrays](#array), [maps](#map), pages, or other slices. See the [Go documentation](https://go.dev/ref/spec#Slice_types) for details. -### string +###### string A sequence of bytes. For example, `"What is 6 times 7?"` . -### taxonomy +###### taxonomic weight + +Defined in front matter and unique to each taxonomy, this [weight](#weight) determines the sort order of page collections contained within a [taxonomy object](#taxonomy-object). See [details](/templates/taxonomy-templates/#assign-weight). + +###### taxonomy A group of related [terms](#term) used to classify content. For example, a "colors" taxonomy might include the terms "red", "green", and "blue". See [details](/content-management/taxonomies/). -### taxonomy page +###### taxonomy object + +A [map](#map) of [terms](#term) and the [weighted pages](#weighted-page) associated with each term. + +###### taxonomy page Content with the "taxonomy" [page kind](#page-kind). Typically a listing of [terms](#term) within a given [taxonomy](#taxonomy). -### template +###### template A file with [template actions](#template-action), located within the layouts directory of a project, theme, or module. See [details](/templates/). -### template action +###### template action A data evaluation or control structure within a [template](#template), delimited by "{{" and "}}". See the [Go documentation](https://pkg.go.dev/text/template#hdr-Actions) for details. -### term +###### term A member of a [taxonomy](#taxonomy), used to classify content. See [details](/content-management/taxonomies/). -### term page +###### term page Content with the "term" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and [section pages](#section-page) with a given [term](#term). -### theme +###### theme A packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A theme may serve as the basis for a new site, or to augment an existing site. See also [module](#module). -### token +###### token An identifier within a format string, beginning with a colon and replaced with a value when rendered. For example, use tokens in format strings for both [permalinks](/content-management/urls/#permalinks) and [dates](/functions/time/format/#localization). - -### type +###### type See [content type](#content-type). -### variable +###### unmarshal -A variable initialized within a [template action](#template-action). +To transform a serialized object into a data structure. For example, transforming a JSON file into a [map](#map) that you can access within a template. See [marshal](#marshal). -### walk +###### variable + +A user-defined [identifier](#identifier) prefaced with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](#template-action). For example, `$foo` and `$bar` are variables. + +###### walk To recursively traverse a nested data structure. For example, rendering a multilevel menu. + +###### weight + +Used to position an element within a collection 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. Weights are typically assigned to pages, menu entries, languages, and output formats. + +###### weighted page + +Contained within a [taxonomy object](#taxonomy-object), a weighted page is a [map](#map) with two elements: a `Page` object, and its [taxonomic weight](#taxonomic-weight) as defined in front matter. Access the elements using the `Page` and `Weight` keys. diff --git a/content/en/getting-started/quick-start.md b/content/en/getting-started/quick-start.md index 24f2ba1fc..ce4312455 100644 --- a/content/en/getting-started/quick-start.md +++ b/content/en/getting-started/quick-start.md @@ -156,7 +156,7 @@ Hugo's rendering engine conforms to the CommonMark [specification] for markdown. With your editor, open the [site configuration] file (`hugo.toml`) in the root of your project. ```text -baseURL = 'http://example.org/' +baseURL = 'https://example.org/' languageCode = 'en-us' title = 'My New Hugo Site' theme = 'ananke' diff --git a/content/en/getting-started/usage.md b/content/en/getting-started/usage.md index 11f28c6b2..f1d26edc2 100644 --- a/content/en/getting-started/usage.md +++ b/content/en/getting-started/usage.md @@ -8,15 +8,15 @@ menu: parent: getting-started weight: 30 weight: 30 -aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/] toc: true +aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/] --- ## Test your installation After [installing] Hugo, test your installation by running: -```bash +```sh hugo version ``` @@ -30,13 +30,13 @@ hugo v0.105.0-0e3b42b4a9bdeb4d866210819fc6ddcf51582ffa+extended linux/amd64 Buil To see a list of the available commands and flags: -```bash +```sh hugo help ``` To get help with a subcommand, use the `--help` flag. For example: -```bash +```sh hugo server --help ``` @@ -44,7 +44,7 @@ hugo server --help To build your site, `cd` into your project directory and run: -```bash +```sh hugo ``` @@ -60,7 +60,6 @@ Depending on your needs, you may wish to manually clear the contents of the publ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [front matter] of your content. By default, Hugo will not publish content when: - - The `draft` value is `true` - The `date` is in the future - The `publishDate` is in the future @@ -68,7 +67,7 @@ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [ You can override the default behavior when running `hugo` or `hugo server` with command line flags: -```bash +```sh hugo --buildDrafts # or -D hugo --buildExpired # or -E hugo --buildFuture # or -F @@ -86,7 +85,7 @@ A common practice is to manually clear the contents of the `public` directory be To view your site while developing layouts or creating content, `cd` into your project directory and run: -```bash +```sh hugo server ``` @@ -108,7 +107,7 @@ While the server is running, Hugo injects JavaScript into the generated HTML pag When editing content, if you want your browser to automatically redirect to the page you last modified, run: -```bash +```sh hugo server --navigateToChanged ``` @@ -120,7 +119,7 @@ As noted above, Hugo does not clear the public directory before building your si When you are ready to deploy your site, run: -```bash +```sh hugo ``` @@ -129,16 +128,16 @@ This builds your site, publishing the files to the public directory. The directo ```text public/ ├── categories/ -│ ├── index.html -│ └── index.xml <-- RSS feed for this section +│ ├── index.html +│ └── index.xml <-- RSS feed for this section ├── post/ -│ ├── my-first-post/ -│ │ └── index.html -│ ├── index.html -│ └── index.xml <-- RSS feed for this section +│ ├── my-first-post/ +│ │ └── index.html +│ ├── index.html +│ └── index.xml <-- RSS feed for this section ├── tags/ -│ ├── index.html -│ └── index.xml <-- RSS feed for this section +│ ├── index.html +│ └── index.xml <-- RSS feed for this section ├── index.html ├── index.xml <-- RSS feed for the site └── sitemap.xml diff --git a/content/en/hosting-and-deployment/_index.md b/content/en/hosting-and-deployment/_index.md index 4329469a5..35fd3cf05 100644 --- a/content/en/hosting-and-deployment/_index.md +++ b/content/en/hosting-and-deployment/_index.md @@ -2,7 +2,7 @@ title: Hosting and deployment linkTitle: Overview description: Site builds, automated deployments, and popular hosting solutions. -categories: [hosting and deployment] +categories: [] keywords: [] menu: docs: diff --git a/content/en/hosting-and-deployment/deployment-with-rclone.md b/content/en/hosting-and-deployment/deployment-with-rclone.md index 6d45a0883..410851553 100644 --- a/content/en/hosting-and-deployment/deployment-with-rclone.md +++ b/content/en/hosting-and-deployment/deployment-with-rclone.md @@ -2,12 +2,12 @@ title: Deploy with Rclone description: If you have access to your web host with SFTP/FTP/SSH/HTTP(DAV), you can use rclone to incrementally deploy your entire Hugo website. categories: [hosting and deployment] -keywords: [rclone,sftp,deployment] +keywords: [deployment,rclone,sftp] menu: docs: parent: hosting-and-deployment -aliases: [/tutorials/deployment-with-rclone/] toc: true +aliases: [/tutorials/deployment-with-rclone/] --- ## Assumptions diff --git a/content/en/hosting-and-deployment/deployment-with-rsync.md b/content/en/hosting-and-deployment/deployment-with-rsync.md index 7c4cbda07..f341ad618 100644 --- a/content/en/hosting-and-deployment/deployment-with-rsync.md +++ b/content/en/hosting-and-deployment/deployment-with-rsync.md @@ -2,12 +2,12 @@ title: Deploy with Rsync description: If you have access to your web host with SSH, you can use a simple rsync one-liner to incrementally deploy your entire Hugo website. categories: [hosting and deployment] -keywords: [rsync,deployment] +keywords: [deployment,rsync] menu: docs: parent: hosting-and-deployment -aliases: [/tutorials/deployment-with-rsync/] toc: true +aliases: [/tutorials/deployment-with-rsync/] --- ## Assumptions @@ -30,7 +30,7 @@ To make logging in to your server more secure and less interactive, you can uplo First, install the ssh client. On Debian distributions, use the following command: -{{< code file="install-openssh.sh" >}} +{{< code file=install-openssh.sh >}} sudo apt-get install openssh-client {{< /code >}} @@ -85,7 +85,7 @@ Create a new script called `deploy` the root of your Hugo tree: Add the following content. Replace the `USER`, `HOST`, and `DIR` values with your own values: -```bash +```sh #!/bin/sh USER=my-user HOST=my-server.com @@ -136,4 +136,4 @@ sent 9,550 bytes received 1,708 bytes 7,505.33 bytes/sec total size is 966,557 speedup is 85.86 ``` -You can incorporate other proprocessing tasks into this deployment script as well. +You can incorporate other processing tasks into this deployment script as well. diff --git a/content/en/hosting-and-deployment/hosting-on-21yunbox.md b/content/en/hosting-and-deployment/hosting-on-21yunbox.md index d6dfb666d..2ab0a1964 100644 --- a/content/en/hosting-and-deployment/hosting-on-21yunbox.md +++ b/content/en/hosting-and-deployment/hosting-on-21yunbox.md @@ -2,7 +2,7 @@ title: Host on 21YunBox description: Host your Hugo site with 21YunBox's blazing fast Chinese CDN, fully-managed SSL and auto deploys from Gitee. categories: [hosting and deployment] -keywords: [21yunbox,hosting,deployment] +keywords: [hosting,21yunbox] menu: docs: parent: hosting-and-deployment diff --git a/content/en/hosting-and-deployment/hosting-on-aws-amplify.md b/content/en/hosting-and-deployment/hosting-on-aws-amplify.md index 0255c1723..43d75312a 100644 --- a/content/en/hosting-and-deployment/hosting-on-aws-amplify.md +++ b/content/en/hosting-and-deployment/hosting-on-aws-amplify.md @@ -2,7 +2,7 @@ title: Host on AWS Amplify description: Develop and deploy a cloud-powered web app with AWS Amplify. categories: [hosting and deployment] -keywords: [amplify,hosting,deployment] +keywords: [hosting,amplify] menu: docs: parent: hosting-and-deployment diff --git a/content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md b/content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md index ec8cd996f..922cbfef2 100644 --- a/content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md +++ b/content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md @@ -2,7 +2,7 @@ title: Host on Azure Static Web Apps description: Publish a Hugo site to Azure Static Web Apps. categories: [hosting and deployment] -keywords: [hosting,Azure Static Web Apps] +keywords: [hosting,azure] menu: docs: parent: hosting-and-deployment diff --git a/content/en/hosting-and-deployment/hosting-on-cloudflare-pages.md b/content/en/hosting-and-deployment/hosting-on-cloudflare-pages.md index 5c927ec99..e50143db7 100644 --- a/content/en/hosting-and-deployment/hosting-on-cloudflare-pages.md +++ b/content/en/hosting-and-deployment/hosting-on-cloudflare-pages.md @@ -2,6 +2,7 @@ title: Host on Cloudflare Pages description: Cloudflare Pages can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own environment variables. categories: [hosting and deployment] +keywords: [hosting,cloudflare] menu: docs: parent: hosting-and-deployment diff --git a/content/en/hosting-and-deployment/hosting-on-firebase.md b/content/en/hosting-and-deployment/hosting-on-firebase.md index c58f4b752..028964bcf 100644 --- a/content/en/hosting-and-deployment/hosting-on-firebase.md +++ b/content/en/hosting-and-deployment/hosting-on-firebase.md @@ -1,6 +1,6 @@ --- title: Host on Firebase -description: You can use Firebase's free tier to host your static website; this also gives you access to Firebase's NOSQL API. +description: You can use Firebase's free tier to host your static website; this also gives you access to Firebase's NoSQL API. categories: [hosting and deployment] keywords: [hosting,firebase] menu: @@ -18,20 +18,19 @@ toc: true Go to the [Firebase console][console] and create a new project (unless you already have a project). You will need to globally install `firebase-tools` (node.js): -```txt +```sh npm install -g firebase-tools ``` Log in to Firebase (setup on your local machine) using `firebase login`, which opens a browser where you can select your account. Use `firebase logout` in case you are already logged in but to the wrong account. - -```txt +```sh firebase login ``` In the root of your Hugo project, initialize the Firebase project with the `firebase init` command: -```txt +```sh firebase init ``` @@ -78,7 +77,7 @@ Don't forget to update your static pages before push! To deploy your Hugo site, execute the `firebase deploy` command, and your site will be up in no time: -```txt +```sh hugo && firebase deploy ``` @@ -86,7 +85,7 @@ hugo && firebase deploy You can generate a deploy token using -```txt +```sh firebase login:ci ``` @@ -98,7 +97,7 @@ This is a private secret and it should not appear in a public repository. Make s You can then add a step in your build to do the deployment using the token: -```txt +```sh firebase deploy --token $FIREBASE_DEPLOY_TOKEN ``` diff --git a/content/en/hosting-and-deployment/hosting-on-github/index.md b/content/en/hosting-and-deployment/hosting-on-github/index.md index 4dc88faf1..f41250279 100644 --- a/content/en/hosting-and-deployment/hosting-on-github/index.md +++ b/content/en/hosting-and-deployment/hosting-on-github/index.md @@ -2,7 +2,7 @@ title: Host on GitHub Pages description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with GitHub Actions categories: [hosting and deployment] -keywords: [github,git,deployment,hosting] +keywords: [hosting,github] menu: docs: parent: hosting-and-deployment @@ -32,7 +32,6 @@ See the [GitHub Pages documentation] to understand the requirements for reposito [GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites {{% /note %}} - [GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites ## Procedure @@ -44,7 +43,7 @@ Step 2 : Push your local repository to GitHub. Step 3 -: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In then center of your screen you will see this: +: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this:  {style="max-width: 280px"} @@ -65,7 +64,7 @@ Step 5 Step 6 : Copy and paste the YAML below into the file you created. Change the branch name and Hugo version as needed. -{{< code file=".github/workflows/hugo.yaml" >}} +{{< code file=.github/workflows/hugo.yaml copy=true >}} # Sample workflow for building and deploying a Hugo site to GitHub Pages name: Deploy Hugo site to Pages @@ -100,7 +99,7 @@ jobs: build: runs-on: ubuntu-latest env: - HUGO_VERSION: 0.115.4 + HUGO_VERSION: 0.120.2 steps: - name: Install Hugo CLI run: | @@ -109,7 +108,7 @@ jobs: - name: Install Dart Sass run: sudo snap install dart-sass - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: submodules: recursive fetch-depth: 0 @@ -129,7 +128,7 @@ jobs: --minify \ --baseURL "${{ steps.pages.outputs.base_url }}/" - name: Upload artifact - uses: actions/upload-pages-artifact@v1 + uses: actions/upload-pages-artifact@v2 with: path: ./public diff --git a/content/en/hosting-and-deployment/hosting-on-gitlab.md b/content/en/hosting-and-deployment/hosting-on-gitlab.md index 964e656ed..dce306253 100644 --- a/content/en/hosting-and-deployment/hosting-on-gitlab.md +++ b/content/en/hosting-and-deployment/hosting-on-gitlab.md @@ -2,7 +2,7 @@ title: Host on GitLab Pages description: GitLab makes it easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides native support for Hugo. categories: [hosting and deployment] -keywords: [hosting,deployment,git,gitlab] +keywords: [hosting,gitlab] menu: docs: parent: hosting-and-deployment @@ -25,7 +25,7 @@ The `baseURL` in your [site configuration](/getting-started/configuration/) must Define your [CI/CD](https://docs.gitlab.com/ee/ci/quick_start/) jobs by creating a `.gitlab-ci.yml` file in the root of your project. -{{< code file=".gitlab-ci.yml" >}} +{{< code file=.gitlab-ci.yml copy=true >}} variables: DART_SASS_VERSION: 1.64.1 HUGO_VERSION: 0.115.4 @@ -74,7 +74,7 @@ pages: Next, create a new repository on GitLab. It is *not* necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control. -```bash +```sh # initialize new git repository git init diff --git a/content/en/hosting-and-deployment/hosting-on-keycdn.md b/content/en/hosting-and-deployment/hosting-on-keycdn.md index 87f66acf5..e81129981 100644 --- a/content/en/hosting-and-deployment/hosting-on-keycdn.md +++ b/content/en/hosting-and-deployment/hosting-on-keycdn.md @@ -2,7 +2,7 @@ title: Host on KeyCDN description: "Accelerate your Hugo site globally with a KeyCDN integration. This tutorial shows you how to set up your static site as a GitLab page behind a KeyCDN pull zone." categories: [hosting and deployment] -keywords: [keycdn,hosting,deployment,cdn] +keywords: [hosting,keycdn] menu: docs: parent: hosting-and-deployment @@ -58,8 +58,8 @@ pages: - public only: - master - ``` + Using this integration method, you will have to specify the Zone ID and your [KeyCDN API](https://www.keycdn.com/api) key as secret variables. To do this, navigate to the top-left menu bar in GitLab and select Projects. Then, select your project and click on the Settings page. Finally, select Pipelines from the sub-menu and scroll down to the Secret Variable section. The Secret Variable for your Zone ID should look similar to: @@ -76,7 +76,7 @@ The Zone ID and API key are used to purge your zone – it’s not strictly need Now it’s time to push the newly created repository to GitLab: -```bash +```sh git remote add origin [email protected]:youruser/ci-example.git git push -u origin master ``` diff --git a/content/en/hosting-and-deployment/hosting-on-netlify.md b/content/en/hosting-and-deployment/hosting-on-netlify.md index 91d044755..9b01f4cd8 100644 --- a/content/en/hosting-and-deployment/hosting-on-netlify.md +++ b/content/en/hosting-and-deployment/hosting-on-netlify.md @@ -2,7 +2,7 @@ title: Host on Netlify description: Netlify can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own CLI. categories: [hosting and deployment] -keywords: [netlify,hosting,deployment] +keywords: [hosting,netlify] menu: docs: parent: hosting-and-deployment @@ -19,7 +19,7 @@ toc: true ## Create a Netlify account -Go to [app.netlify.com] and select your preferred signup method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address. +Go to [app.netlify.com] and select your preferred sign up method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address. The following examples use GitHub, but other git providers will follow a similar process. @@ -55,21 +55,21 @@ You can [set Hugo version](https://www.netlify.com/blog/2017/04/11/netlify-plus- For production: -{{< code file="netlify.toml" >}} +{{< code file=netlify.toml >}} [context.production.environment] HUGO_VERSION = "0.115.4" {{< /code >}} For testing: -{{< code file="netlify.toml" >}} +{{< code file=netlify.toml >}} [context.deploy-preview.environment] HUGO_VERSION = "0.115.4" {{< /code >}} The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`: -{{< readfile file="netlify.toml" highlight="toml" >}} +{{< readfile file=netlify.toml highlight=toml >}} ## Build and deploy site diff --git a/content/en/hosting-and-deployment/hosting-on-render.md b/content/en/hosting-and-deployment/hosting-on-render.md index 8965ad786..b43261c8d 100644 --- a/content/en/hosting-and-deployment/hosting-on-render.md +++ b/content/en/hosting-and-deployment/hosting-on-render.md @@ -2,7 +2,7 @@ title: Host on Render description: Host your Hugo site for free with Render's global CDN, fully-managed SSL and auto deploys from GitHub. categories: [hosting and deployment] -keywords: [hosting,deployment] +keywords: [hosting] menu: docs: parent: hosting-and-deployment diff --git a/content/en/hosting-and-deployment/hugo-deploy.md b/content/en/hosting-and-deployment/hugo-deploy.md index ed603012b..45b917f1e 100644 --- a/content/en/hosting-and-deployment/hugo-deploy.md +++ b/content/en/hosting-and-deployment/hugo-deploy.md @@ -1,8 +1,8 @@ --- title: Hugo Deploy -description: You can upload your site to GCS, S3, or Azure using the Hugo CLI. +description: Upload your site to GCS, S3, or Azure categories: [hosting and deployment] -keywords: [s3,gcs,azure,hosting,deployment] +keywords: [deployment,s3,gcs,azure] menu: docs: parent: hosting-and-deployment @@ -13,6 +13,7 @@ toc: true You can use the "hugo deploy" command to upload your site directly to a Google Cloud Storage (GCS) bucket, an AWS S3 bucket, and/or an Azure Storage container. + ## Assumptions * You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world. @@ -22,73 +23,202 @@ You can use the "hugo deploy" command to upload your site directly to a Google C * AWS: [Install the CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and run [`aws configure`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). * Azure: [Install the CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and run [`az login`](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). * NOTE: Each service supports alternatives for authentication, including using environment variables. See [here](https://gocloud.dev/howto/blob/#services) for more details. +* You have created a bucket to deploy to. If you want your site to be + public, be sure to configure the bucket to be publicly readable as a static website. + * Google Cloud: [create a bucket](https://cloud.google.com/storage/docs/creating-buckets) and [host a static website](https://cloud.google.com/storage/docs/hosting-static-website) + * Amazon S3: [create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) and [host a static website](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html) + * Microsoft Azure: [create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal) and [host a static website](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website) + + +## Configuring your first deployment + +In the configuration file for your site, add a `[deployment]` section +and a `[[deployment.targets]]` subsection. The only required parameters are +the name and URL: + +```toml +[deployment] + +[[deployment.targets]] +# An arbitrary name for this target. +name = "production" + +# URL specifies the Go Cloud Development Kit URL to deploy to. Examples: +URL = "<FILL ME IN>" + +# Google Cloud Storage -- see https://gocloud.dev/howto/blob/#gcs +#URL = "gs://<Bucket Name>" + +# Amazon Web Services S3; see https://gocloud.dev/howto/blob/#s3 +# For S3-compatible endpoints, see https://gocloud.dev/howto/blob/#s3-compatible +#URL = "s3://<Bucket Name>?region=<AWS region>" + +# Microsoft Azure Blob Storage; see https://gocloud.dev/howto/blob/#azure +#URL = "azblob://$web" + +``` + +## Deploy + +To deploy to a target: + +```bash +hugo deploy [--target=<target name>] +``` + +The deploy process recursively walks through your local publish directory +(`public` by default) and syncs it to the destination bucket, to ensure +that the local and remote contents match. + +If you don't specify a target, Hugo will deploy to the first target in your +configuration. + +See `hugo help deploy` or [the deploy command-line documentation][commandline] for more command-line options. + + +### How the file list works -## Create a bucket to deploy to +The first thing `hugo deploy` does is create file lists for local and remote by +traversing the local publish directory and remote bucket. -Create a storage bucket to deploy your site to. If you want your site to be -public, be sure to configure the bucket to be publicly readable. +For both local and remote, the file list includes and excludes files according to +the [deployment target's configuration][config] -- +* If the configuration specifies an `include` pattern, all files + are skipped by default except those matching the pattern. +* If the configuration specifies an `exclude` pattern, files matching the + pattern are skipped. -### Google Cloud Storage (GCS) -Follow the [GCS instructions for how to create a bucket](https://cloud.google.com/storage/docs/creating-buckets). +{{% note %}} +When creating the local file list, a few additional skips apply: first, Hugo always +skips files named `.DS_Store`. -### AWS S3 +Second, Hugo always skips local hidden directories +(directories with names starting with a period, e.g. `.git`) and does not +traverse into them, except for the special [hidden directory named +`.well-known`](https://en.wikipedia.org/wiki/Well-known_URI), which is +traversed if it exists. +{{% /note %}} -Follow the [AWS instructions for how to create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html). -### Azure Storage -Follow the [Azure instructions for how to create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal). +### How the local and remote file lists are compared -## Configure the deployment +In the second step, Hugo compares the two file lists to figure out what changes +actually need to be made on the remote. File names are compared first; if the +local and remote files both exist then the sizes and md5sums are compared. Any +difference means that the file will be (re-)uploaded. -In the configuration file for your site, add a `[deployment]` section with one -or more `[[deployment.targets]]` section, one for each deployment target. Here's -a detailed example: +Specifying the `--force` flag will ensure all files are re-uploaded even +if Hugo cannot detect any differences between local and remote. + +Files are deleted from the remote bucket if they are not present in the local +file list. + +{{% note %}} +If a remote file is excluded from the file list generation using the +exclude/include configs, then the comparison step will not know to delete the +file -- so it will remain on the remote even if it isn't present locally. +{{% /note %}} + +If the [`--confirm` or `--dryRun` flags][commandline] are given, Hugo displays +what differences it has found and either pauses or stops here. + +### How synchronization works + +Hugo applies the list of changes to the remote storage bucket. Missing and/or +changed files are uploaded, and files missing locally but present remotely are +deleted. As files are uploaded, their headers are also configured on the remote +according to the matchers configuration. + +{{% note %}} +As a safety measure to help prevent accidents, if there are more than 256 files +to delete, Hugo won't delete any files from the remote. Use the `--maxDeletes` +command line flag to override this. +{{% /note %}} + +## Advanced configuration + +Here's a full example deployment configuration: ```toml [deployment] + # By default, files are uploaded in an arbitrary order. -# Files that match the regular expressions in the "Order" list -# will be uploaded first, in the listed order. +# If you specify an `order` list, files that match regular expressions +# in this list will be uploaded first, in the specified order. order = [".jpg$", ".gif$"] - [[deployment.targets]] +# Define one or more targets, e.g., staging and production. +# Each target gets its own [[deployment.targets]] section. + # An arbitrary name for this target. name = "mydeployment" # The Go Cloud Development Kit URL to deploy to. Examples: +URL = "<FILL ME IN>" + # GCS; see https://gocloud.dev/howto/blob/#gcs -# URL = "gs://<Bucket Name>" +#URL = "gs://<Bucket Name>" # S3; see https://gocloud.dev/howto/blob/#s3 # For S3-compatible endpoints, see https://gocloud.dev/howto/blob/#s3-compatible -# URL = "s3://<Bucket Name>?region=<AWS region>" +#URL = "s3://<Bucket Name>?region=<AWS region>" # Azure Blob Storage; see https://gocloud.dev/howto/blob/#azure -# URL = "azblob://$web" +#URL = "azblob://$web" # You can use a "prefix=" query parameter to target a subfolder of the bucket: -# URL = "gs://<Bucket Name>?prefix=a/subfolder/" +#URL = "gs://<Bucket Name>?prefix=a/subfolder/" # If you are using a CloudFront CDN, deploy will invalidate the cache as needed. -cloudFrontDistributionID = <ID> +#cloudFrontDistributionID = "<FILL ME IN>" -# Optionally, you can include or exclude specific files. -# See https://godoc.org/github.com/gobwas/glob#Glob for the glob pattern syntax. -# If non-empty, the pattern is matched against the local path. -# All paths are matched against in their filepath.ToSlash form. +# Include or exclude specific files when deploying to this target: # If exclude is non-empty, and a local or remote file's path matches it, that file is not synced. # If include is non-empty, and a local or remote file's path does not match it, that file is not synced. -# As a result, local files that don't pass the include/exclude filters are not uploaded to remote, +# Note: local files that don't pass the include/exclude filters are not uploaded to remote, # and remote files that don't pass the include/exclude filters are not deleted. -# include = "**.html" # would only include files with ".html" suffix -# exclude = "**.{jpg, png}" # would exclude files with ".jpg" or ".png" suffix +# +# The pattern syntax is documented here: https://godoc.org/github.com/gobwas/glob#Glob +# Patterns should be written with forward slashes as separator. +# +#include = "**.html" # would only include files with ".html" suffix +#exclude = "**.{jpg, png}" # would exclude files with ".jpg" or ".png" suffix + +####################### +[[deployment.matchers]] +# Matchers enable special caching, content type and compression behavior for +# specified file types. You can include any number of matcher blocks; the first one +# matching a given file pattern will be used. -# [[deployment.matchers]] configure behavior for files that match the Pattern. # See https://golang.org/pkg/regexp/syntax/ for pattern syntax. # Pattern searching is stopped on first match. +pattern = "<FILL ME IN>" + +# If true, Hugo will gzip the file before uploading it to the bucket. +# With many storage services, this will save on storage and bandwidth costs +# for uncompressed file types. +#gzip = false + +# If true, Hugo always re-uploads this file even if size and md5 match. +# This is useful if Hugo isn't reliably able to determine whether to re-upload +# the file on its own. +#force = false + +# Content-type header to configure for this file when served. +# By default this can be determined from the file extension. +#contentType = "" + +# Cache-control header to configure for this file when served. +# The default is the empty string. +#cacheControl = "" + +# Content-encoding header to configure for this file when served. +# By default, if gzip is True, this will be filled with "gzip". +#contentEncoding = "" + # Samples: @@ -114,21 +244,6 @@ pattern = "^.+\\.(html|xml|json)$" gzip = true ``` -## Deploy - -To deploy to a target: - -```bash -hugo deploy [--target=<target name>, defaults to first target] -``` - -Hugo will identify and apply any local changes that need to be reflected to the -remote target. You can use `--dryRun` to see the changes without applying them, -or `--confirm` to be prompted before making changes. - -See `hugo help deploy` for more command-line options. - [Quick Start]: /getting-started/quick-start/ -[Google Cloud]: [https://cloud.google.com] -[AWS]: [https://aws.amazon.com] -[Azure]: [https://azure.microsoft.com] +[commandline]: /commands/hugo_deploy/ +[config]: #advanced-configuration diff --git a/content/en/hugo-modules/_index.md b/content/en/hugo-modules/_index.md index 87dca37b8..cbff13ad0 100644 --- a/content/en/hugo-modules/_index.md +++ b/content/en/hugo-modules/_index.md @@ -2,16 +2,16 @@ title: Hugo Modules linkTitle: Overview description: How to use Hugo Modules. +categories: [] +keywords: [] menu: docs: identifier: hugo-modules-overview parent: modules weight: 10 weight: 10 -categories: [hugo modules] -keywords: [themes,modules] -aliases: [/themes/overview/,/themes/] toc: true +aliases: [/themes/overview/,/themes/] --- **Hugo Modules** are the core building blocks in Hugo. A _module_ can be your main project or a smaller module providing one or more of the 7 component types defined in Hugo: **static**, **content**, **layouts**, **data**, **assets**, **i18n**, and **archetypes**. diff --git a/content/en/hugo-modules/configuration.md b/content/en/hugo-modules/configuration.md index b1a3f4bf8..d707e7498 100644 --- a/content/en/hugo-modules/configuration.md +++ b/content/en/hugo-modules/configuration.md @@ -2,7 +2,7 @@ title: Configure Hugo modules description: This page describes the configuration options for a module. categories: [hugo modules] -keywords: [themes, source, organization, directories] +keywords: [modules,themes] menu: docs: parent: modules @@ -13,7 +13,7 @@ toc: true ## Module configuration: top level -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [module] noVendor = "" proxy = "direct" @@ -56,7 +56,7 @@ env HUGO_MODULE_PROXY=https://proxy.example.org hugo If your module requires a particular version of Hugo to work, you can indicate that in the `module` section and the user will be warned if using a too old/new version. -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [module] [module.hugoVersion] min = "" @@ -78,7 +78,7 @@ extended ## Module configuration: imports -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [module] [[module.imports]] path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v" @@ -120,7 +120,7 @@ When you add a mount, the default mount for the concerned target root is ignored {{% /note %}} **Default mounts** -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [module] [[module.mounts]] source="content" @@ -165,7 +165,7 @@ excludeFiles (string or slice) : One or more glob patterns matching files to exclude. **Example** -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [module] [[module.mounts]] source="content" diff --git a/content/en/hugo-modules/theme-components.md b/content/en/hugo-modules/theme-components.md index d0a986b7e..947a0ff79 100644 --- a/content/en/hugo-modules/theme-components.md +++ b/content/en/hugo-modules/theme-components.md @@ -2,7 +2,7 @@ title: Theme components description: Hugo provides advanced theming support with Theme Components. categories: [hugo modules] -keywords: [themes, theme, source, organization, directories] +keywords: [modules,themes] menu: docs: parent: modules @@ -12,15 +12,12 @@ aliases: [/themes/customize/,/themes/customizing/] toc: true --- - - - {{% note %}} This section contain information that may be outdated and is in the process of being rewritten. {{% /note %}} Since Hugo `0.42` a project can configure a theme as a composite of as many theme components you need: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} theme = ["my-shortcodes", "base-theme", "hyde"] {{< /code-toggle >}} @@ -30,7 +27,7 @@ The theme definition example above in `hugo.toml` creates a theme with 3 theme c For any given file, data entry, etc., Hugo will look first in the project and then in `my-shortcodes`, `base-theme`, and lastly `hyde`. -Hugo uses two different algorithms to merge the filesystems, depending on the file type: +Hugo uses two different algorithms to merge the file systems, depending on the file type: * For `i18n` and `data` files, Hugo merges deeply using the translation ID and data key inside the files. * For `static`, `layouts` (templates), and `archetypes` files, these are merged on file level. So the left-most file will be chosen. diff --git a/content/en/hugo-modules/use-modules.md b/content/en/hugo-modules/use-modules.md index db269a5db..9e8f1d4d0 100644 --- a/content/en/hugo-modules/use-modules.md +++ b/content/en/hugo-modules/use-modules.md @@ -2,7 +2,7 @@ title: Use Hugo Modules description: How to use Hugo Modules to build and manage your site. categories: [hugo modules] -keywords: [install, themes, source, organization, directories,usage,modules] +keywords: [modules,themes] menu: docs: parent: modules @@ -20,7 +20,7 @@ toc: true Use `hugo mod init` to initialize a new Hugo Module. If it fails to guess the module path, you must provide it as an argument, e.g.: -```bash +```sh hugo mod init github.com/gohugoio/myShortcodes ``` @@ -33,7 +33,7 @@ The easiest way to use a Module for a theme is to import it in the configuration 1. Initialize the hugo module system: `hugo mod init github.com/<your_user>/<your_project>` 2. Import the theme: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [module] [[module.imports]] path = "github.com/spf13/hyde" @@ -49,25 +49,25 @@ Some examples: ### Update all modules -```bash +```sh hugo mod get -u ``` ### Update all modules recursively -```bash +```sh hugo mod get -u ./... ``` ### Update one module -```bash +```sh hugo mod get -u github.com/gohugoio/myShortcodes ``` ### Get a specific version -```bash +```sh hugo mod get github.com/gohugoio/[email protected] ``` @@ -77,7 +77,7 @@ Also see the [CLI Doc](/commands/hugo_mod_get/). One way to do local development of a module imported in a project is to add a replace directive to a local directory with the source in `go.mod`: -```bash +```sh replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials ``` @@ -101,7 +101,6 @@ github.com/bep/hugotestmods/[email protected] github.com/bep/hugotestmods/myv2@v DISABLED github.com/bep/my-modular-site github.com/spf13/[email protected] github.com/bep/my-modular-site github.com/bep/[email protected] github.com/bep/my-modular-site in-themesdir - ``` Also see the [CLI Doc](/commands/hugo_mod_graph/). @@ -134,7 +133,7 @@ Also see the [CLI Doc](/commands/hugo_mod_clean/). ## Module workspaces -{{< new-in "0.109.0" >}} +{{< new-in 0.109.0 >}} Workspace support was added in [Go 1.18](https://go.dev/blog/get-familiar-with-workspaces) and Hugo got solid support for it in the `v0.109.0` version. @@ -155,7 +154,7 @@ Using the `use` directive, list all the modules you want to work on, pointing to With that you can start the Hugo server with that workspace enabled: -```bash +```sh HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**" ``` diff --git a/content/en/hugo-pipes/_index.md b/content/en/hugo-pipes/_index.md index b649a5bf6..edc41b7a2 100755 --- a/content/en/hugo-pipes/_index.md +++ b/content/en/hugo-pipes/_index.md @@ -1,7 +1,7 @@ --- title: Hugo Pipes linkTitle: Overview -categories: [asset management] +categories: [] keywords: [] menu: docs: diff --git a/content/en/hugo-pipes/babel.md b/content/en/hugo-pipes/babel.md index 44b4e670e..73ccf01d4 100755 --- a/content/en/hugo-pipes/babel.md +++ b/content/en/hugo-pipes/babel.md @@ -8,14 +8,16 @@ menu: parent: hugo-pipes weight: 70 weight: 70 -signatures: ["resources.Babel RESOURCE [OPTIONS]", "babel RESOURCE [OPTIONS]"] +function: + aliases: [babel] + returnType: resource.Resource + signatures: ['resources.Babel [OPTIONS] RESOURCE'] --- ## Usage Any JavaScript resource file can be transpiled to another JavaScript version using `resources.Babel` which takes for argument the resource object and an optional dict of options listed below. Babel uses the [babel cli](https://babeljs.io/docs/en/babel-cli). - {{% note %}} Hugo Pipe's Babel requires the `@babel/cli` and `@babel/core` JavaScript packages to be installed in the project or globally (`npm install -g @babel/cli @babel/core`) along with any Babel plugin(s) or preset(s) used (e.g., `npm install @babel/preset-env --save-dev`). @@ -26,7 +28,6 @@ If you are using the Hugo Snap package, Babel and plugin(s) need to be installed 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: [ @@ -43,24 +44,23 @@ module.exports = { ### 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 +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). -noComments [bool] -: Write comments to generated output (true by default) +minified +: (`bool`) Save as many bytes as possible when printing -compact [bool] -: Do not include superfluous whitespace characters and line terminators. Defaults to `auto` if not set. +noComments +: (`bool`) Write comments to generated output (true by default) -verbose [bool] -: Log everything +compact +: (`bool`) Do not include superfluous whitespace characters and line terminators. Defaults to `auto` if not set. -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. +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. ### Examples diff --git a/content/en/hugo-pipes/bundling.md b/content/en/hugo-pipes/bundling.md index f3ff42f9c..7fc9fc9df 100755 --- a/content/en/hugo-pipes/bundling.md +++ b/content/en/hugo-pipes/bundling.md @@ -9,7 +9,10 @@ menu: parent: hugo-pipes weight: 90 weight: 90 -signatures: ["resources.Concat TARGET_PATH SLICE_RESOURCES"] +action: + aliases: [] + returnType: resource.Resource + signatures: ['resources.Concat TARGETPATH [RESOURCE...]'] --- ## Usage diff --git a/content/en/hugo-pipes/fingerprint.md b/content/en/hugo-pipes/fingerprint.md index c492d4c70..68e41acd1 100755 --- a/content/en/hugo-pipes/fingerprint.md +++ b/content/en/hugo-pipes/fingerprint.md @@ -9,7 +9,10 @@ menu: parent: hugo-pipes weight: 100 weight: 100 -signatures: ["resources.Fingerprint RESOURCE [ALGORITHM]", "fingerprint RESOURCE [ALGORITHM]"] +action: + aliases: [fingerprint] + returnType: resource.Resource + signatures: ['resources.Fingerprint [ALGORITHM] RESOURCE'] --- ## Usage diff --git a/content/en/hugo-pipes/introduction.md b/content/en/hugo-pipes/introduction.md index 2cbb85e32..c993377f8 100755 --- a/content/en/hugo-pipes/introduction.md +++ b/content/en/hugo-pipes/introduction.md @@ -13,139 +13,47 @@ toc: true aliases: [/assets/] --- -## Find resources in /assets +## Find resources in assets -This is about the global Resources mounted inside `/assets`. For the `.Page` scoped Resources, see [Page Resources](/content-management/page-resources/). +This is about global and remote resources. -Note that you can mount any directory into Hugo's virtual `assets` folder using the [Mount Configuration](/hugo-modules/configuration/#module-configuration-mounts). +global resource +: A file within the assets directory, or within any directory [mounted] to the assets directory. -| Function | Description | -| ------------- | ------------- | -| `resources.Get` | Get locates the file name given in Hugo's assets filesystem and creates a `Resource` object that can be used for further transformations. See [Get a resource](#get-a-resource). | -| `resources.GetRemote` | Same as `Get`, but it accepts remote URLs. See [Get a resource](#get-a-resource).| -| `resources.GetMatch` | `GetMatch` finds the first Resource matching the given pattern, or nil if none found. See Match for a more complete explanation about the rules used. | -| `resources.Match` | `Match` gets all resources matching the given base path prefix, e.g "*.png" will match all png files. The "*" does not match path delimiters (/), so if you organize your resources in sub-folders, you need to be explicit about it, e.g.: "images/*.png". To match any PNG image anywhere in the bundle you can do "\*\*.png", and to match all PNG images below the images folder, use "images/\*\*.jpg". The matching is case insensitive. Match matches by using the files name with path relative to the file system root with Unix style slashes (/) and no leading slash, e.g. "images/logo.png". See https://github.com/gobwas/glob for the full rules set.| +remote resource +: A file on a remote server, accessible via HTTP or HTTPS. -See the [GoDoc Page](https://pkg.go.dev/github.com/gohugoio/hugo/tpl/resources) for the `resources` package for an up to date overview of all template functions in this namespace. - -## Get a resource - -In order to process an asset with Hugo Pipes, it must be retrieved as a `Resource` using `resources.Get` or `resources.GetRemote`. - -With `resources.Get`, the first argument is a local path relative to the `assets` directory/directories: - -```go-html-template -{{ $local := resources.Get "sass/main.scss" }} -``` - -With `resources.GetRemote`, the first argument is a remote URL: - -```go-html-template -{{ $remote := resources.GetRemote "https://www.example.com/styles.scss" }} -``` - -`resources.Get` and `resources.GetRemote` return `nil` if the resource is not found. - -{{< new-in "0.110.0" >}} You can get information about the HTTP Response using `.Data` in the returned `Resource`. This is especially useful for HEAD request without any body. The Data object contains: - -StatusCode -: The HTTP status code, e.g. 200 - -Status -: The HTTP status text, e.g. "200 OK" - -TransferEncoding -: The transfer encoding, e.g. "chunked" - -ContentLength -: The content length, e.g. 1234 - -ContentType -: The content type, e.g. "text/html" - -### Caching - -By default, Hugo calculates a cache key based on the `URL` and the `options` (e.g. headers) given. - -{{< new-in "0.97.0" >}} You can override this by setting a `key` in the options map. This can be used to get more fine grained control over how often a remote resource is fetched, e.g.: - - -```go-html-template -{{ $cacheKey := print $url (now.Format "2006-01-02") }} -{{ $resource := resource.GetRemote $url (dict "key" $cacheKey) }} -``` - -### Error handling +For `.Page` scoped resources, see the [page resources] section. -The return value from `resources.GetRemote` includes an `.Err` method that will return an error if the call failed. If you want to just log any error as a `WARNING` you can use a construct similar to the one below. +[mounted]: /hugo-modules/configuration/#module-configuration-mounts +[page resources]: /content-management/page-resources/ -```go-html-template -{{ with resources.GetRemote "https://gohugo.io/images/gohugoio-card-1.png" }} - {{ with .Err }} - {{ warnf "%s" . }} - {{ else }} - <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> - {{ end }} -{{ end }} -``` - -Note that if you do not handle `.Err` yourself, Hugo will fail the build the first time you start using the `Resource` object. - -### Remote options - -When fetching a remote `Resource`, `resources.GetRemote` takes an optional options map as the second argument, e.g.: - -```go-html-template -{{ $resource := resources.GetRemote "https://example.org/api" (dict "headers" (dict "Authorization" "Bearer abcd")) }} -``` +## Get a resource -If you need multiple values for the same header key, use a slice: +In order to process an asset with Hugo Pipes, it must be retrieved as a resource. -```go-html-template -{{ $resource := resources.GetRemote "https://example.org/api" (dict "headers" (dict "X-List" (slice "a" "b" "c"))) }} -``` +For global resources, use: -You can also change the request method and set the request body: +- [`resources.ByType`](/functions/resources/bytype/) +- [`resources.Get`](/functions/resources/get/) +- [`resources.GetMatch`](/functions/resources/getmatch/) +- [`resources.Match`](/functions/resources/match/) -```go-html-template -{{ $postResponse := resources.GetRemote "https://example.org/api" (dict - "method" "post" - "body" `{"complete": true}` - "headers" (dict - "Content-Type" "application/json" - ) -)}} -``` +For remote resources, use: -### Caching of remote resources +- [`resources.GetRemote`](/functions/resources/getremote/) -Remote resources fetched with `resources.GetRemote` will be cached on disk. See [Configure File Caches](/getting-started/configuration/#configure-file-caches) for details. +See the [GoDoc Page](https://pkg.go.dev/github.com/gohugoio/hugo/tpl/resources) for the `resources` package for an up to date overview of all template functions in this namespace. ## Copy a resource -{{< new-in "0.100.0" >}} - -Use `resources.Copy` to copy a page resource or a global resource. Commonly used to change a resource's published path, `resources.Copy` takes two arguments: the target path relative to the root of the `publishDir` (with or without a leading `/`), and the resource to copy. - -```go-html-template -{{ with resources.Get "img/a.jpg" }} - {{ with .Resize "300x" }} - {{ with resources.Copy "img/a-new.jpg" . }} - <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> - {{ end }} - {{ end }} -{{ end }} -``` - -{{% note %}} -The target path must be different than the source path, as shown in the example above. See GitHub issue [#10412](https://github.com/gohugoio/hugo/issues/10412). -{{% /note %}} +See the [`resources.Copy`](/functions/resources/copy/) function. ## Asset directory Asset files must be stored in the asset directory. This is `/assets` by default, but can be configured via the configuration file's `assetDir` key. -### Asset publishing +## Asset publishing Hugo publishes assets to the `publishDir` (typically `public`) when you invoke `.Permalink`, `.RelPermalink`, or `.Publish`. You can use `.Content` to inline the asset. @@ -158,18 +66,6 @@ For improved readability, the Hugo Pipes examples of this documentation will be <link rel="stylesheet" href="{{ $style.Permalink }}"> ``` -## Method aliases - -Each Hugo Pipes `resources` transformation method uses a __camelCased__ alias (`toCSS` for `resources.ToCSS`). -Non-transformation methods deprived of such aliases are `resources.Get`, `resources.FromString`, `resources.ExecuteAsTemplate` and `resources.Concat`. - -The example above can therefore also be written as follows: - -```go-html-template -{{ $style := resources.Get "sass/main.scss" | toCSS | minify | fingerprint }} -<link rel="stylesheet" href="{{ $style.Permalink }}"> -``` - ## Caching Hugo Pipes invocations are cached based on the entire *pipe chain*. diff --git a/content/en/hugo-pipes/js.md b/content/en/hugo-pipes/js.md index ecf6dc33f..c9366ce8a 100644 --- a/content/en/hugo-pipes/js.md +++ b/content/en/hugo-pipes/js.md @@ -1,7 +1,7 @@ --- title: js.Build linkTitle: JavaScript building -description: Process a JavaScript file with [ESBuild](https://github.com/evanw/esbuild). +description: Bundle, transpile, tree shake, and minify JavaScript resources. categories: [asset management] keywords: [] menu: @@ -9,7 +9,10 @@ menu: parent: hugo-pipes weight: 60 weight: 60 -signatures: ["js.Build RESOURCE [OPTIONS]"] +action: + aliases: [] + returnType: resource.Resource + signatures: ['js.Build [OPTIONS] RESOURCE'] --- ## Usage @@ -18,12 +21,12 @@ Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build ### Options -targetPath [string] -: If not set, the source path will be used as the base target path. +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] -: Params that can be imported as JSON in your JS files, e.g.: +params +: (`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")) }} @@ -36,14 +39,14 @@ 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. +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 +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: +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" }} @@ -69,29 +72,28 @@ import * as React from 'react' import * as ReactDOM from 'react-dom'; ``` -target [string] -: The language target. +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 +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. +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. +format +: (`string`) The output format. One of: `iife`, `cjs`, `esm`. - Default is `iife`, a self-executing function, suitable for inclusion as a <script> tag. + Default is `iife`, a self-executing function, suitable for inclusion as a `<script>` tag. -sourceMap [string] -: Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created. +sourceMap +: (`string`) Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created. ### Import JS code from /assets @@ -121,7 +123,7 @@ For other files (e.g. `JSON`, `CSS`) you need to use the relative path including import * as data from 'my/module/data.json'; ``` -Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. +Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. Also note the new `params` option that can be passed from template to your JS files, e.g.: @@ -136,15 +138,15 @@ import * as params from '@params'; Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/getting-started/configuration/#configure-build). - ### Include dependencies In package.json / node_modules -Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. +Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. The start directory for resolving npm packages (aka. packages that live inside a `node_modules` folder) is always the main project folder. -**Note:** If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project. - +{{% note %}} +If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project. +{{% /note %}} ### Examples diff --git a/content/en/hugo-pipes/minification.md b/content/en/hugo-pipes/minification.md index 74ddfaa89..f8cedcde5 100755 --- a/content/en/hugo-pipes/minification.md +++ b/content/en/hugo-pipes/minification.md @@ -9,7 +9,10 @@ menu: parent: hugo-pipes weight: 80 weight: 80 -signatures: ["resources.Minify RESOURCE", "minify RESOURCE"] +action: + aliases: [minify] + returnType: resource.Resource + signatures: [resources.Minify RESOURCE] --- ## Usage diff --git a/content/en/hugo-pipes/postcss.md b/content/en/hugo-pipes/postcss.md index 2a08c7ad4..148b30a7e 100755 --- a/content/en/hugo-pipes/postcss.md +++ b/content/en/hugo-pipes/postcss.md @@ -7,9 +7,12 @@ menu: docs: parent: hugo-pipes weight: 40 -toc: true weight: 40 -signatures: ["resources.PostCSS RESOURCE [OPTIONS]", "postCSS RESOURCE [OPTIONS]"] +toc: true +action: + aliases: [postCSS] + returnType: resource.Resource + signatures: ['resources.PostCSS [OPTIONS] RESOURCE'] --- ## Setup @@ -22,8 +25,8 @@ Step 1 Step 2 : Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to CSS rules: -```bash -npm install postcss postcss-cli autoprefixer +```sh +npm i -D postcss postcss-cli autoprefixer ``` Step 3 @@ -31,7 +34,7 @@ Step 3 [supported file names]: https://github.com/postcss/postcss-load-config#usage -{{< code file="postcss.config.js" >}} +{{< code file=postcss.config.js >}} module.exports = { plugins: [ require('autoprefixer') @@ -49,7 +52,7 @@ Step 4 Step 5 : Capture the CSS file as a resource and pipe it through `resources.PostCSS` (alias `postCSS`): -{{< code file="layouts/partials/css.html" >}} +{{< code file=layouts/partials/css.html >}} {{ with resources.Get "css/main.css" | postCSS }} <link rel="stylesheet" href="{{ .RelPermalink }}"> {{ end }} @@ -57,7 +60,7 @@ Step 5 If starting with a Sass file within the `assets` directory: -{{< code file="layouts/partials/css.html" >}} +{{< code file=layouts/partials/css.html >}} {{ with resources.Get "sass/main.scss" | toCSS | postCSS }} <link rel="stylesheet" href="{{ .RelPermalink }}"> {{ end }} @@ -79,10 +82,10 @@ URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+San 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 {{< new-in "0.99.0" >}} +skipInlineImportsNotFound {{< new-in 0.99.0 >}} : (`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. -{{< code file="layouts/partials/css.html" >}} +{{< code file=layouts/partials/css.html >}} {{ $opts := dict "config" "config-directory" "noMap" true }} {{ with resources.Get "css/main.css" | postCSS $opts }} <link rel="stylesheet" href="{{ .RelPermalink }}"> @@ -105,7 +108,7 @@ stringifier syntax : (`string`) Custom postcss syntax. -{{< code file="layouts/partials/css.html" >}} +{{< code file=layouts/partials/css.html >}} {{ $opts := dict "use" "autoprefixer postcss-color-alpha" }} {{ with resources.Get "css/main.css" | postCSS $opts }} <link rel="stylesheet" href="{{ .RelPermalink }}"> @@ -116,7 +119,7 @@ syntax 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: -{{< code file="postcss.config.js" >}} +{{< code file=postcss.config.js >}} module.exports = { plugins: [ require('autoprefixer'), diff --git a/content/en/hugo-pipes/postprocess.md b/content/en/hugo-pipes/postprocess.md index 4b3cb8ad4..e84c6d72d 100755 --- a/content/en/hugo-pipes/postprocess.md +++ b/content/en/hugo-pipes/postprocess.md @@ -8,7 +8,10 @@ menu: parent: hugo-pipes weight: 50 weight: 50 -signatures: ["resources.PostProcess RESOURCE"] +action: + aliases: [] + returnType: postpub.PostPublishedResource + signatures: [resources.PostProcess RESOURCE] --- ## Usage @@ -36,7 +39,7 @@ There are several ways to set up CSS purging with PostCSS in Hugo. If you have a The below configuration will write a `hugo_stats.json` file to the project root as part of the build. If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory). -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [build.buildStats] enable = true {{< /code-toggle >}} @@ -74,7 +77,6 @@ Note that in the example above, the "CSS purge step" will only be applied to the <link href="{{ $css.RelPermalink }}" rel="stylesheet" /> ``` - ## Hugo environment variables available in PostCSS These are the environment variables Hugo passes down to PostCSS (and Babel), which allows you do do `process.env.HUGO_ENVIRONMENT === 'production' ? [autoprefixer] : []` and similar: @@ -86,9 +88,9 @@ HUGO_ENVIRONMENT : The value e.g. set with `hugo -e production` (defaults to `production` for `hugo` and `development` for `hugo server`). HUGO_PUBLISHDIR -: {{< new-in "0.109.0" >}} 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: +: {{< new-in 0.109.0 >}} 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: -```text +```sh hugo server --renderToDisk hugo server --renderStaticToDisk ``` diff --git a/content/en/hugo-pipes/resource-from-string.md b/content/en/hugo-pipes/resource-from-string.md index fa472715c..53bcfff74 100755 --- a/content/en/hugo-pipes/resource-from-string.md +++ b/content/en/hugo-pipes/resource-from-string.md @@ -9,7 +9,10 @@ menu: parent: hugo-pipes weight: 110 weight: 110 -signatures: ["resources.FromString TARGET_PATH CONTENT"] +action: + aliases: [] + returnType: resource.Resource + signatures: [resources.FromString TARGETPATH STRING] --- ## Usage diff --git a/content/en/hugo-pipes/resource-from-template.md b/content/en/hugo-pipes/resource-from-template.md index c1c4cb316..1627fa7d4 100755 --- a/content/en/hugo-pipes/resource-from-template.md +++ b/content/en/hugo-pipes/resource-from-template.md @@ -9,7 +9,10 @@ menu: parent: hugo-pipes weight: 120 weight: 120 -signatures: ["resources.ExecuteAsTemplate TARGET_PATH CONTEXT RESOURCE"] +action: + aliases: [] + returnType: resource.Resource + signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE] --- ## Usage diff --git a/content/en/hugo-pipes/transpile-sass-to-css.md b/content/en/hugo-pipes/transpile-sass-to-css.md index b09cc165b..7ddbe573d 100644 --- a/content/en/hugo-pipes/transpile-sass-to-css.md +++ b/content/en/hugo-pipes/transpile-sass-to-css.md @@ -7,9 +7,13 @@ keywords: [] menu: docs: parent: hugo-pipes + returnType: resource.Resource weight: 30 weight: 30 -signatures: ["resources.ToCSS RESOURCE [OPTIONS]", "toCSS RESOURCE [OPTIONS]"] +action: + aliases: [toCSS] + returnType: resource.Resource + signatures: ['resources.ToCSS [OPTIONS] RESOURCE'] toc: true aliases: [/hugo-pipes/transform-to-css/] --- @@ -19,8 +23,8 @@ aliases: [/hugo-pipes/transform-to-css/] 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. ```go-html-template -{{ $options := dict "transpiler" "libsass" "targetPath" "css/style.css" }} -{{ with resources.Get "sass/main.scss" | toCSS $options | minify | fingerprint }} +{{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }} +{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }} <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> {{ end }} ``` @@ -30,7 +34,6 @@ 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 @@ -39,7 +42,7 @@ transpiler 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 {{< new-in "0.109.0" >}} +vars {{< new-in 0.109.0 >}} : (`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 @@ -59,21 +62,21 @@ precision enableSourceMap : (`bool`) If `true`, generates a source map. -sourceMapIncludeSources {{< new-in "0.108.0" >}} +sourceMapIncludeSources {{< new-in 0.108.0 >}} : (`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 -{{ $options := dict +{{ $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 $options | minify | fingerprint }} +{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }} <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> {{ end }} ``` @@ -187,8 +190,8 @@ command = """\ To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `resources.ToCSS`. For example: ```go-html-template -{{ $options := dict "transpiler" "dartsass" "targetPath" "css/style.css" }} -{{ with resources.Get "sass/main.scss" | toCSS $options | minify | fingerprint }} +{{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }} +{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }} <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> {{ end }} ``` diff --git a/content/en/installation/_common/01-editions.md b/content/en/installation/_common/01-editions.md index cbc338665..deec8cc83 100644 --- a/content/en/installation/_common/01-editions.md +++ b/content/en/installation/_common/01-editions.md @@ -1,3 +1,7 @@ +--- +# Do not remove front matter. +--- + ## Editions Hugo is available in two editions: standard and extended. With the extended edition you can: diff --git a/content/en/installation/_common/02-prerequisites.md b/content/en/installation/_common/02-prerequisites.md index 423950113..ea6eaa8fe 100644 --- a/content/en/installation/_common/02-prerequisites.md +++ b/content/en/installation/_common/02-prerequisites.md @@ -1,3 +1,7 @@ +--- +# Do not remove front matter. +--- + ## Prerequisites Although not required in all cases, [Git], [Go], and [Dart Sass] are commonly used when working with Hugo. diff --git a/content/en/installation/_common/03-prebuilt-binaries.md b/content/en/installation/_common/03-prebuilt-binaries.md index 884869e1e..d3465fa5d 100644 --- a/content/en/installation/_common/03-prebuilt-binaries.md +++ b/content/en/installation/_common/03-prebuilt-binaries.md @@ -1,9 +1,12 @@ +--- +# Do not remove front matter. +--- + ## Prebuilt binaries Prebuilt binaries are available for a variety of operating systems and architectures. Visit the [latest release] page, and scroll down to the Assets section. -<!-- markdownlint-disable-next-line MD051 --> -1. Download the archive for the desired [edition], operating system, and architecture +1. Download the archive for the desired edition, operating system, and architecture 1. Extract the archive 1. Move the executable to the desired directory 1. Add this directory to the PATH environment variable @@ -14,7 +17,6 @@ Please consult your operating system documentation if you need help setting file If you do not see a prebuilt binary for the desired edition, operating system, and architecture, install Hugo using one of the methods described below. [commit information]: /variables/git -[edition]: #editions [Git]: https://git-scm.com/ [Go]: https://go.dev/ [Hugo Modules]: /hugo-modules/ diff --git a/content/en/installation/_common/04-build-from-source.md b/content/en/installation/_common/04-build-from-source.md index 7537882fd..f670a5752 100644 --- a/content/en/installation/_common/04-build-from-source.md +++ b/content/en/installation/_common/04-build-from-source.md @@ -1,3 +1,7 @@ +--- +# Do not remove front matter. +--- + ## Build from source To build the extended edition of Hugo from source you must: diff --git a/content/en/installation/_common/_index.md b/content/en/installation/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/installation/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/content/en/installation/_common/homebrew.md b/content/en/installation/_common/homebrew.md index 7178a9f4f..8d6ff90fc 100644 --- a/content/en/installation/_common/homebrew.md +++ b/content/en/installation/_common/homebrew.md @@ -1,6 +1,10 @@ +--- +# Do not remove front matter. +--- + ### Homebrew -[Homebrew] is a free and open source package manager for macOS and Linux. This will install the extended edition of Hugo: +[Homebrew] is a free and open-source package manager for macOS and Linux. This will install the extended edition of Hugo: ```sh brew install hugo diff --git a/content/en/installation/_common/index.md b/content/en/installation/_common/index.md deleted file mode 100644 index cbb7365a6..000000000 --- a/content/en/installation/_common/index.md +++ /dev/null @@ -1,3 +0,0 @@ -+++ -headless = true -+++ diff --git a/content/en/installation/_index.md b/content/en/installation/_index.md index e2d2c96a3..ca405b755 100644 --- a/content/en/installation/_index.md +++ b/content/en/installation/_index.md @@ -3,8 +3,8 @@ title: Installation linkTitle: Overview description: Install Hugo on macOS, Linux, Windows, BSD, and on any machine that can run the Go compiler tool chain. aliases: [/getting-started/installing/] -categories: [installation] -keywords: [installation] +categories: [] +keywords: [] menu: docs: identifier: installation-overview @@ -13,4 +13,4 @@ menu: weight: 10 --- -{{% param "description" %}} +Install Hugo on macOS, Linux, Windows, BSD, and on any machine that can run the Go compiler tool chain. diff --git a/content/en/installation/bsd.md b/content/en/installation/bsd.md index 999e52ad6..a3b179d25 100644 --- a/content/en/installation/bsd.md +++ b/content/en/installation/bsd.md @@ -2,18 +2,19 @@ title: BSD description: Install Hugo on BSD derivatives. categories: [installation] +keywords: [] menu: docs: parent: installation weight: 50 -toc: true weight: 50 +toc: true --- -{{% readfile file="/installation/_common/01-editions.md" %}} +{{% include "installation/_common/01-editions.md" %}} -{{% readfile file="/installation/_common/02-prerequisites.md" %}} +{{% include "installation/_common/02-prerequisites.md" %}} -{{% readfile file="/installation/_common/03-prebuilt-binaries.md" %}} +{{% include "installation/_common/03-prebuilt-binaries.md" %}} ## Repository packages @@ -61,7 +62,7 @@ doas pkg_add hugo [OpenBSD]: https://www.openbsd.org/ -{{% readfile file="/installation/_common/04-build-from-source.md" %}} +{{% include "installation/_common/04-build-from-source.md" %}} ## Comparison diff --git a/content/en/installation/linux.md b/content/en/installation/linux.md index 2dbbd3720..bb8f4b555 100644 --- a/content/en/installation/linux.md +++ b/content/en/installation/linux.md @@ -2,24 +2,25 @@ title: Linux description: Install Hugo on Linux. categories: [installation] +keywords: [] menu: docs: parent: installation weight: 30 -toc: true weight: 30 +toc: true --- -{{% readfile file="/installation/_common/01-editions.md" %}} +{{% include "installation/_common/01-editions.md" %}} -{{% readfile file="/installation/_common/02-prerequisites.md" %}} +{{% include "installation/_common/02-prerequisites.md" %}} -{{% readfile file="/installation/_common/03-prebuilt-binaries.md" %}} +{{% include "installation/_common/03-prebuilt-binaries.md" %}} ## Package managers ### Snap -[Snap] is a free and open source package manager for Linux. Available for [most distributions], snap packages are simple to install and are automatically updated. +[Snap] is a free and open-source package manager for Linux. Available for [most distributions], snap packages are simple to install and are automatically updated. The Hugo snap package is [strictly confined]. Strictly confined snaps run in complete isolation, up to a minimal access level that’s deemed always safe. The sites you create and build must be located within your home directory, or on removable media. @@ -47,13 +48,17 @@ sudo snap disconnect hugo:ssh-keys [strictly confined]: https://snapcraft.io/docs/snap-confinement [Snap]: https://snapcraft.io/ -{{% readfile file="/installation/_common/homebrew.md" %}} +{{% include "installation/_common/homebrew.md" %}} ## Repository packages -Most Linux distributions maintain a repository for commonly installed applications. Please note that these repositories may not contain the [latest release]. +Most Linux distributions maintain a repository for commonly installed applications. + +{{% note %}} +Due to Long Term Release (LTR) guidelines, most Linux package repositories will not contain the [latest release]. [latest release]: https://github.com/gohugoio/hugo/releases/latest +{{% /note %}} ### Arch Linux @@ -92,7 +97,6 @@ You can also download Debian packages from the [latest release] page. Derivatives of the [Fedora] distribution of Linux include [CentOS], [Red Hat Enterprise Linux], and others. This will install the extended edition of Hugo: - ```sh sudo dnf install hugo ``` @@ -105,7 +109,6 @@ sudo dnf install hugo Derivatives of the [openSUSE] distribution of Linux include [GeckoLinux], [Linux Karmada], and others. This will install the extended edition of Hugo: - ```sh sudo zypper install hugo ``` @@ -124,7 +127,7 @@ sudo eopkg install hugo [Solus]: https://getsol.us/ -{{% readfile file="/installation/_common/04-build-from-source.md" %}} +{{% include "installation/_common/04-build-from-source.md" %}} ## Comparison diff --git a/content/en/installation/macos.md b/content/en/installation/macos.md index ccae90b36..eba977481 100644 --- a/content/en/installation/macos.md +++ b/content/en/installation/macos.md @@ -2,26 +2,27 @@ title: macOS description: Install Hugo on macOS. categories: [installation] +keywords: [] menu: docs: parent: installation weight: 20 -toc: true weight: 20 +toc: true --- -{{% readfile file="/installation/_common/01-editions.md" %}} +{{% include "installation/_common/01-editions.md" %}} -{{% readfile file="/installation/_common/02-prerequisites.md" %}} +{{% include "installation/_common/02-prerequisites.md" %}} -{{% readfile file="/installation/_common/03-prebuilt-binaries.md" %}} +{{% include "installation/_common/03-prebuilt-binaries.md" %}} ## Package managers -{{% readfile file="/installation/_common/homebrew.md" %}} +{{% include "installation/_common/homebrew.md" %}} ### MacPorts -[MacPorts] is a free and open source package manager for macOS. This will install the extended edition of Hugo: +[MacPorts] is a free and open-source package manager for macOS. This will install the extended edition of Hugo: ```sh sudo port install hugo @@ -29,7 +30,7 @@ sudo port install hugo [MacPorts]: https://www.macports.org/ -{{% readfile file="/installation/_common/04-build-from-source.md" %}} +{{% include "installation/_common/04-build-from-source.md" %}} ## Comparison diff --git a/content/en/installation/windows.md b/content/en/installation/windows.md index 48c5f7006..97e767af8 100644 --- a/content/en/installation/windows.md +++ b/content/en/installation/windows.md @@ -2,24 +2,25 @@ title: Windows description: Install Hugo on Windows. categories: [installation] +keywords: [] menu: docs: parent: installation weight: 40 -toc: true weight: 40 +toc: true --- -{{% readfile file="/installation/_common/01-editions.md" %}} +{{% include "installation/_common/01-editions.md" %}} -{{% readfile file="/installation/_common/02-prerequisites.md" %}} +{{% include "installation/_common/02-prerequisites.md" %}} -{{% readfile file="/installation/_common/03-prebuilt-binaries.md" %}} +{{% include "installation/_common/03-prebuilt-binaries.md" %}} ## Package managers ### Chocolatey -[Chocolatey] is a free and open source package manager for Windows. This will install the extended edition of Hugo: +[Chocolatey] is a free and open-source package manager for Windows. This will install the extended edition of Hugo: ```sh choco install hugo-extended @@ -29,7 +30,7 @@ choco install hugo-extended ### Scoop -[Scoop] is a free and open source package manager for Windows. This will install the extended edition of Hugo: +[Scoop] is a free and open-source package manager for Windows. This will install the extended edition of Hugo: ```sh scoop install hugo-extended @@ -39,7 +40,7 @@ scoop install hugo-extended ### Winget -[Winget] is Microsoft's official free and open source package manager for Windows. This will install the extended edition of Hugo: +[Winget] is Microsoft's official free and open-source package manager for Windows. This will install the extended edition of Hugo: ```sh winget install Hugo.Hugo.Extended @@ -47,7 +48,7 @@ winget install Hugo.Hugo.Extended [Winget]: https://learn.microsoft.com/en-us/windows/package-manager/ -{{% readfile file="/installation/_common/04-build-from-source.md" %}} +{{% include "installation/_common/04-build-from-source.md" %}} {{% note %}} See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows. diff --git a/content/en/maintenance/_index.md b/content/en/maintenance/_index.md index fd8828bb2..aaee3987d 100644 --- a/content/en/maintenance/_index.md +++ b/content/en/maintenance/_index.md @@ -1,8 +1,8 @@ --- title: Maintenance description: Some lists useful for the maintenance of the Hugo docs site. -categories: [maintenance] -keywords: [maintenance] +categories: [] +keywords: [] menu: docs: weight: 200 diff --git a/content/en/methods/_common/_index.md b/content/en/methods/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/methods/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md b/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md new file mode 100644 index 000000000..4ae3a0f39 --- /dev/null +++ b/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md @@ -0,0 +1,37 @@ +--- +# Do not remove front matter. +--- + +The `Next` and `Prev` methods on a `Pages` object are more flexible than the `Next` and `Prev` methods on a `Page` object. + +||Page collection|Custom sort order +:--|:--|:-: +[`PAGES.Next`] and [`PAGES.Prev`]|locally defined|✔️ +[`PAGE.Next`] and [`PAGE.Prev`]|globally defined|❌ + +[`PAGES.Next`]: /methods/pages/next +[`PAGES.Prev`]: /methods/pages/prev +[`PAGE.Next`]: /methods/page/next +[`PAGE.Prev`]: /methods/page/prev + +locally defined +: Build the page collection every time you call `PAGES.Next` and `PAGES.Prev`. Navigation between pages is relative to the current page's position within the local collection, independent of the global collection. + +With a local collection, the navigation sort order is the same as the collection sort order. + +globally defined +: Build the page collection once, on a list page. Navigation between pages is relative to the current page's position within the global collection. + +With a global collection, 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 global 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 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/_index.md b/content/en/methods/_index.md new file mode 100644 index 000000000..c12bd9d4d --- /dev/null +++ b/content/en/methods/_index.md @@ -0,0 +1,16 @@ +--- +title: Methods +linkTitle: Overview +description: A list of Hugo template methods including examples. +categories: [] +keywords: [] +menu: + docs: + identifier: methods-overview + parent: methods + weight: 10 +weight: 10 +showSectionMenu: true +--- + +Use these methods within your templates. diff --git a/content/en/methods/duration/Abs.md b/content/en/methods/duration/Abs.md new file mode 100644 index 000000000..d035f97b6 --- /dev/null +++ b/content/en/methods/duration/Abs.md @@ -0,0 +1,17 @@ +--- +title: Abs +description: Returns the absolute value of the given time.Duration value. +categories: [] +keywords: [] +action: + related: + - functions/time/Duration + - functions/time/ParseDuration + returnType: time.Duration + signatures: [DURATION.Abs] +--- + +```go-html-template +{{ $d = time.ParseDuration "-3h" }} +{{ $d.Abs }} → 3h0m0s +``` diff --git a/content/en/methods/duration/Hours.md b/content/en/methods/duration/Hours.md new file mode 100644 index 000000000..5b2d893b9 --- /dev/null +++ b/content/en/methods/duration/Hours.md @@ -0,0 +1,17 @@ +--- +title: Hours +description: Returns the time.Duration value as a floating point number of hours. +categories: [] +keywords: [] +action: + related: + - functions/time/Duration + - functions/time/ParseDuration + returnType: float64 + signatures: [DURATION.Hours] +--- + +```go-html-template +{{ $d = time.ParseDuration "3.5h2.5m1.5s" }} +{{ $d.Hours }} → 3.5420833333333333 +``` diff --git a/content/en/methods/duration/Microseconds.md b/content/en/methods/duration/Microseconds.md new file mode 100644 index 000000000..c8b210c94 --- /dev/null +++ b/content/en/methods/duration/Microseconds.md @@ -0,0 +1,17 @@ +--- +title: Microseconds +description: Returns the time.Duration value as an integer microsecond count. +categories: [] +keywords: [] +action: + related: + - functions/time/Duration + - functions/time/ParseDuration + returnType: int64 + signatures: [DURATION.Microseconds] +--- + +```go-html-template +{{ $d = time.ParseDuration "3.5h2.5m1.5s" }} +{{ $d.Microseconds }} → 12751500000 +``` diff --git a/content/en/methods/duration/Milliseconds.md b/content/en/methods/duration/Milliseconds.md new file mode 100644 index 000000000..32809027a --- /dev/null +++ b/content/en/methods/duration/Milliseconds.md @@ -0,0 +1,17 @@ +--- +title: Milliseconds +description: Returns the time.Duration value as an integer millisecond count. +categories: [] +keywords: [] +action: + related: + - functions/time/Duration + - functions/time/ParseDuration + returnType: int64 + signatures: [DURATION.Milliseconds] +--- + +```go-html-template +{{ $d = time.ParseDuration "3.5h2.5m1.5s" }} +{{ $d.Milliseconds }} → 12751500 +``` diff --git a/content/en/methods/duration/Minutes.md b/content/en/methods/duration/Minutes.md new file mode 100644 index 000000000..d3e57fba5 --- /dev/null +++ b/content/en/methods/duration/Minutes.md @@ -0,0 +1,17 @@ +--- +title: Minutes +description: Returns the time.Duration value as a floating point number of minutes. +categories: [] +keywords: [] +action: + related: + - functions/time/Duration + - functions/time/ParseDuration + returnType: float64 + signatures: [DURATION.Minutes] +--- + +```go-html-template +{{ $d = time.ParseDuration "3.5h2.5m1.5s" }} +{{ $d.Minutes }} → 212.525 +``` diff --git a/content/en/methods/duration/Nanoseconds.md b/content/en/methods/duration/Nanoseconds.md new file mode 100644 index 000000000..66d2981f2 --- /dev/null +++ b/content/en/methods/duration/Nanoseconds.md @@ -0,0 +1,17 @@ +--- +title: Nanoseconds +description: Returns the time.Duration value as an integer nanosecond count. +categories: [] +keywords: [] +action: + related: + - functions/time/Duration + - functions/time/ParseDuration + returnType: int64 + signatures: [DURATION.Nanoseconds] +--- + +```go-html-template +{{ $d = time.ParseDuration "3.5h2.5m1.5s" }} +{{ $d.Nanoseconds }} → 12751500000000 +``` diff --git a/content/en/methods/duration/Round.md b/content/en/methods/duration/Round.md new file mode 100644 index 000000000..0722a6076 --- /dev/null +++ b/content/en/methods/duration/Round.md @@ -0,0 +1,20 @@ +--- +title: Round +description: Returns the result of rounding DURATION1 to the nearest multiple of DURATION2. +categories: [] +keywords: [] +action: + related: + - functions/time/Duration + - functions/time/ParseDuration + returnType: + signatures: [DURATION1.Round DURATION2] +--- + +```go-html-template +{{ $d = time.ParseDuration "3.5h2.5m1.5s" }} + +{{ $d.Round (time.ParseDuration "2h") }} → 4h0m0s +{{ $d.Round (time.ParseDuration "3m") }} → 3h33m0s +{{ $d.Round (time.ParseDuration "4s") }} → 3h32m32s +``` diff --git a/content/en/methods/duration/Seconds.md b/content/en/methods/duration/Seconds.md new file mode 100644 index 000000000..d23d5ec15 --- /dev/null +++ b/content/en/methods/duration/Seconds.md @@ -0,0 +1,17 @@ +--- +title: Seconds +description: Returns the time.Duration value as a floating point number of seconds. +categories: [] +keywords: [] +action: + related: + - functions/time/Duration + - functions/time/ParseDuration + returnType: float64 + signatures: [DURATION.Seconds] +--- + +```go-html-template +{{ $d = time.ParseDuration "3.5h2.5m1.5s" }} +{{ $d.Seconds }} → 12751.5 +``` diff --git a/content/en/methods/duration/Truncate.md b/content/en/methods/duration/Truncate.md new file mode 100644 index 000000000..795fcad76 --- /dev/null +++ b/content/en/methods/duration/Truncate.md @@ -0,0 +1,21 @@ +--- +title: Truncate +description: Returns the result of rounding DURATION1 toward zero to a multiple of DURATION2. +categories: [] +keywords: [] +action: + related: + related: + - functions/time/Duration + - functions/time/ParseDuration + returnType: time.Duration + signatures: [DURATION1.Truncate DURATION2] +--- + +```go-html-template +{{ $d = time.ParseDuration "3.5h2.5m1.5s" }} + +{{ $d.Truncate (time.ParseDuration "2h") }} → 2h0m0s +{{ $d.Truncate (time.ParseDuration "3m") }} → 3h30m0s +{{ $d.Truncate (time.ParseDuration "4s") }} → 3h32m28s +``` diff --git a/content/en/methods/duration/_index.md b/content/en/methods/duration/_index.md new file mode 100644 index 000000000..9fc4f814c --- /dev/null +++ b/content/en/methods/duration/_index.md @@ -0,0 +1,12 @@ +--- +title: Duration methods +linkTitle: Duration +description: Use these methods with time.Duration values. +categories: [] +keywords: [] +menu: + docs: + parent: methods +--- + +Use these methods with time.Duration values. diff --git a/content/en/methods/menu-entry/Children.md b/content/en/methods/menu-entry/Children.md new file mode 100644 index 000000000..af2af6dce --- /dev/null +++ b/content/en/methods/menu-entry/Children.md @@ -0,0 +1,67 @@ +--- +title: Children +description: Returns a collection of child menu entries, if any, under the given menu entry. +categories: [] +keywords: [] +action: + related: + - methods/menu-entry/HasChildren + returnType: navigation.Menu + signatures: [MENUENTRY.Children] +--- + +Use the `Children` method when rendering a nested menu. + +With this site configuration: + +{{< code-toggle file=hugo >}} +[[menu.main]] +name = 'Products' +pageRef = '/product' +weight = 10 + +[[menu.main]] +name = 'Product 1' +pageRef = '/products/product-1' +parent = 'Products' +weight = 1 + +[[menu.main]] +name = 'Product 2' +pageRef = '/products/product-2' +parent = 'Products' +weight = 2 +{{< /code-toggle >}} + +And this template: + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + <li> + <a href="{{ .URL }}">{{ .Name }}</a> + {{ if .HasChildren }} + <ul> + {{ range .Children }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} + </ul> + {{ end }} + </li> + {{ end }} +</ul> +``` + +Hugo renders this HTML: + +```html +<ul> + <li> + <a href="/products/">Products</a> + <ul> + <li><a href="/products/product-1/">Product 1</a></li> + <li><a href="/products/product-2/">Product 2</a></li> + </ul> + </li> +</ul> +``` diff --git a/content/en/methods/menu-entry/HasChildren.md b/content/en/methods/menu-entry/HasChildren.md new file mode 100644 index 000000000..d906987e8 --- /dev/null +++ b/content/en/methods/menu-entry/HasChildren.md @@ -0,0 +1,67 @@ +--- +title: HasChildren +description: Reports whether the given menu entry has child menu entries. +categories: [] +keywords: [] +action: + related: + - methods/menu-entry/Children + returnType: bool + signatures: [MENUENTRY.HasChildren] +--- + +Use the `HasChildren` method when rendering a nested menu. + +With this site configuration: + +{{< code-toggle file=hugo >}} +[[menu.main]] +name = 'Products' +pageRef = '/product' +weight = 10 + +[[menu.main]] +name = 'Product 1' +pageRef = '/products/product-1' +parent = 'Products' +weight = 1 + +[[menu.main]] +name = 'Product 2' +pageRef = '/products/product-2' +parent = 'Products' +weight = 2 +{{< /code-toggle >}} + +And this template: + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + <li> + <a href="{{ .URL }}">{{ .Name }}</a> + {{ if .HasChildren }} + <ul> + {{ range .Children }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} + </ul> + {{ end }} + </li> + {{ end }} +</ul> +``` + +Hugo renders this HTML: + +```html +<ul> + <li> + <a href="/products/">Products</a> + <ul> + <li><a href="/products/product-1/">Product 1</a></li> + <li><a href="/products/product-2/">Product 2</a></li> + </ul> + </li> +</ul> +``` diff --git a/content/en/methods/menu-entry/Identifier.md b/content/en/methods/menu-entry/Identifier.md new file mode 100644 index 000000000..a4d7e129e --- /dev/null +++ b/content/en/methods/menu-entry/Identifier.md @@ -0,0 +1,44 @@ +--- +title: Identifier +description: Returns the `identifier` property of the given menu entry. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [MENUENTRY.Identifier] +--- + +The `Identifier` method returns the `identifier` property of the menu entry. If you define the menu entry [automatically], it returns the page's section. + +[automatically]: /content-management/menus/#define-automatically + +{{< code-toggle file=hugo >}} +[[menu.main]] +identifier = 'about' +name = 'About' +pageRef = '/about' +weight = 10 + +[[menu.main]] +identifier = 'contact' +name = 'Contact' +pageRef = '/contact' +weight = 20 +{{< /code-toggle >}} + +This example uses the `Identifier` method when querying the translation table on a multilingual site, falling back the `name` property if a matching key in the translation table does not exist: + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + <li><a href="{{ .URL }}">{{ or (T .Identifier) .Name }}</a></li> + {{ end }} +</ul> +``` + +{{% note %}} +In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. + +[details]: /content-management/menus/#properties-front-matter +{{% /note %}} diff --git a/content/en/methods/menu-entry/KeyName.md b/content/en/methods/menu-entry/KeyName.md new file mode 100644 index 000000000..8031441b9 --- /dev/null +++ b/content/en/methods/menu-entry/KeyName.md @@ -0,0 +1,39 @@ +--- +title: KeyName +description: Returns the `identifier` property of the given menu entry, falling back to its `name` property. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [MENUENTRY.KeyName] +--- + +In this menu definition, the second entry does not contain an `identifier`, so the `Identifier` method returns its `name` property instead: + +{{< code-toggle file=hugo >}} +[[menu.main]] +identifier = 'about' +name = 'About' +pageRef = '/about' +weight = 10 + +[[menu.main]] +name = 'Contact' +pageRef = '/contact' +weight = 20 +{{< /code-toggle >}} + +This example uses the `KeyName` method when querying the translation table on a multilingual site, falling back the `name` property if a matching key in the translation table does not exist: + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + <li><a href="{{ .URL }}">{{ or (T (.KeyName | lower)) .Name }}</a></li> + {{ end }} +</ul> +``` + +In the example above, we need to pass the value returned by `.KeyName` through the [`lower`] function because the keys in the translation table are lowercase. + +[`lower`]: functions/strings/tolower diff --git a/content/en/methods/menu-entry/Menu.md b/content/en/methods/menu-entry/Menu.md new file mode 100644 index 000000000..6827519bd --- /dev/null +++ b/content/en/methods/menu-entry/Menu.md @@ -0,0 +1,24 @@ +--- +title: Menu +description: Returns the identifier of the menu that contains the given menu entry. +categories: [] +keywords: [] +action: + related: + - methods/page/IsMenuCurrent + - methods/page/HasMenuCurrent + returnType: string + signatures: [MENUENTRY.Menu] +--- + +```go-html-template +{{ range .Site.Menus.main }} + {{ .Menu }} → main +{{ end }} +``` + +Use this method with the [`IsMenuCurrent`] and [`HasMenuCurrent`] methods on a `Page` object to set "active" and "ancestor" classes on a rendered entry. See [this example]. + +[`HasMenuCurrent`]: /methods/page/hasmenucurrent +[`IsMenuCurrent`]: /methods/page/ismenucurrent +[this example]: /templates/menu-templates/#example diff --git a/content/en/methods/menu-entry/Name.md b/content/en/methods/menu-entry/Name.md new file mode 100644 index 000000000..d722da07c --- /dev/null +++ b/content/en/methods/menu-entry/Name.md @@ -0,0 +1,28 @@ +--- +title: Name +description: Returns the `name` property of the given menu entry. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [MENUENTRY.Name] +--- + +If you define the menu entry [automatically], the `Name` method returns the page’s [`LinkTitle`], falling back to its [`Title`]. + +If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property, falling back to the page’s `LinkTitle`, then to its `Title`. + +[`LinkTitle`]: /methods/page/linktitle +[`Title`]: /methods/page/title +[automatically]: /content-management/menus/#define-automatically +[in front matter]: /content-management/menus/#define-in-front-matter +[in site configuration]: /content-management/menus/#define-in-site-configuration + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} +</ul> +``` diff --git a/content/en/methods/menu-entry/Page.md b/content/en/methods/menu-entry/Page.md new file mode 100644 index 000000000..9b23f7b73 --- /dev/null +++ b/content/en/methods/menu-entry/Page.md @@ -0,0 +1,53 @@ +--- +title: Page +description: Returns the Page object associated with the given menu entry. +categories: [] +keywords: [] +action: + related: [] + returnType: hugolib.pageState + signatures: [MENUENTRY.Page] +--- + +Regardless of how you [define menu entries], an entry associated with a page has access to its [methods]. + +In this menu definition, the first two entries are associated with a page, the last entry is not: + +{{< code-toggle file=hugo >}} +[[menu.main]] +pageRef = '/about' +weight = 10 + +[[menu.main]] +pageRef = '/contact' +weight = 20 + +[[menu.main]] +name = 'Hugo' +url = 'https://gohugo.io' +weight = 30 +{{< /code-toggle >}} + +In this example, if the menu entry is associated with a page, we use page's [`RelPermalink`] and [`LinkTitle`] when rendering the anchor element. + +If the entry is not associated with a page, we use its `url` and `name` properties. + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + {{ with .Page }} + <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + {{ else }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} + {{ end }} +</ul> +``` + +See the [menu templates] section for more information. + +[`LinkTitle`]: /methods/page/linktitle +[`RelPermalink`]: /methods/page/relpermalink +[define menu entries]: /content-management/menus/ +[menu templates]: /templates/menu-templates/#page-references +[methods]: /methods/page diff --git a/content/en/methods/menu-entry/Params.md b/content/en/methods/menu-entry/Params.md new file mode 100644 index 000000000..1486c12cb --- /dev/null +++ b/content/en/methods/menu-entry/Params.md @@ -0,0 +1,62 @@ +--- +title: Params +description: Returns the `params` property of the given menu entry. +categories: [] +keywords: [] +action: + related: [] + returnType: maps.Params + signatures: [MENUENTRY.Params] +--- + +When you define menu entries [in site configuration] or [in front matter], you can include a `params` key to attach additional information to the entry. For example: + +{{< code-toggle file=hugo >}} +[[menu.main]] +name = 'About' +pageRef = '/about' +weight = 10 + +[[menu.main]] +name = 'Contact' +pageRef = '/contact' +weight = 20 + +[[menu.main]] +name = 'Hugo' +url = 'https://gohugo.io' +weight = 30 +[menu.main.params] + rel = 'external' +{{< /code-toggle >}} + +With this template: + + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + <li> + <a href="{{ .URL }}" {{ with .Params.rel }}rel="{{ . }}"{{ end }}> + {{ .Name }} + </a> + </li> + {{ end }} +</ul> +``` + +Hugo renders: + +```html +<ul> + <li><a href="/about/">About</a></li> + <li><a href="/contact/">Contact</a></li> + <li><a href="https://gohugo.io" rel="external">Hugo</a></li> +</ul> +``` + +See the [menu templates] section for more information. + +[menu templates]: /templates/menu-templates/#menu-entry-parameters +[in front matter]: /content-management/menus/#define-in-front-matter +[in site configuration]: /content-management/menus/ diff --git a/content/en/methods/menu-entry/Parent.md b/content/en/methods/menu-entry/Parent.md new file mode 100644 index 000000000..897712831 --- /dev/null +++ b/content/en/methods/menu-entry/Parent.md @@ -0,0 +1,51 @@ +--- +title: Parent +description: Returns the `parent` property of the given menu entry. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [MENUENTRY.Parent] +--- + +With this menu definition: + +{{< code-toggle file=hugo >}} +[menu] +[[menu.main]] +name = 'Products' +pageRef = '/product' +weight = 10 + +[[menu.main]] +name = 'Product 1' +pageRef = '/products/product-1' +parent = 'Products' +weight = 1 + +[[menu.main]] +name = 'Product 2' +pageRef = '/products/product-2' +parent = 'Products' +weight = 2 +{{< /code-toggle >}} + +This template renders the nested menu, listing the `parent` property next each of the child entries: + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + <li> + <a href="{{ .URL }}">{{ .Name }}</a> + {{ if .HasChildren }} + <ul> + {{ range .Children }} + <li><a href="{{ .URL }}">{{ .Name }}</a> ({{ .Parent }})</li> + {{ end }} + </ul> + {{ end }} + </li> + {{ end }} +</ul> +``` diff --git a/content/en/methods/menu-entry/Post.md b/content/en/methods/menu-entry/Post.md new file mode 100644 index 000000000..b2fa2da5b --- /dev/null +++ b/content/en/methods/menu-entry/Post.md @@ -0,0 +1,13 @@ +--- +title: Post +description: Returns the `post` property of the given menu entry. +categories: [] +keywords: [] +action: + related: + - methods/menu-entry/Pre + returnType: template.HTML + signatures: [MENUENTRY.Post] +--- + +{{% include "methods/menu-entry/_common/pre-post.md" %}} diff --git a/content/en/methods/menu-entry/Pre.md b/content/en/methods/menu-entry/Pre.md new file mode 100644 index 000000000..df7c8f16e --- /dev/null +++ b/content/en/methods/menu-entry/Pre.md @@ -0,0 +1,13 @@ +--- +title: Pre +description: Returns the `pre` property of the given menu entry. +categories: [] +keywords: [] +action: + related: + - methods/menu-entry/Post + returnType: template.HTML + signatures: [MENUENTRY.Pre] +--- + +{{% include "methods/menu-entry/_common/pre-post.md" %}} diff --git a/content/en/methods/menu-entry/Title.md b/content/en/methods/menu-entry/Title.md new file mode 100644 index 000000000..c1eec2cc0 --- /dev/null +++ b/content/en/methods/menu-entry/Title.md @@ -0,0 +1,28 @@ +--- +title: Title +description: Returns the `title` property of the given menu entry. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [MENUENTRY.Title] +--- + +If you define the menu entry [automatically], the `Title` method returns the page’s [`LinkTitle`], falling back to its [`Title`]. + +If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `title` property, falling back to the page’s `LinkTitle`, then to its `Title`. + +[`LinkTitle`]: /methods/page/linktitle +[`Title`]: /methods/page/title +[automatically]: /content-management/menus/#define-automatically +[in front matter]: /content-management/menus/#define-in-front-matter +[in site configuration]: /content-management/menus/#define-in-site-configuration + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + <li><a href="{{ .URL }}">{{ .Title }}</a></li> + {{ end }} +</ul> +``` diff --git a/content/en/methods/menu-entry/URL.md b/content/en/methods/menu-entry/URL.md new file mode 100644 index 000000000..c2b314b58 --- /dev/null +++ b/content/en/methods/menu-entry/URL.md @@ -0,0 +1,23 @@ +--- +title: URL +description: Returns the relative permalink of the page associated with the given menu entry, else its `url` property. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [MENUENTRY.URL] +--- + +For menu entries associated with a page, the `URL` method returns the page's [`RelPermalink`], otherwise it returns the entry's `url` property. + + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} +</ul> +``` + +[`RelPermalink`]: /methods/page/relpermalink diff --git a/content/en/methods/menu-entry/Weight.md b/content/en/methods/menu-entry/Weight.md new file mode 100644 index 000000000..7b0c24ae8 --- /dev/null +++ b/content/en/methods/menu-entry/Weight.md @@ -0,0 +1,31 @@ +--- +title: Weight +description: Returns the `weight` property of the given menu entry. +categories: [] +keywords: [] +action: + related: [] + returnType: int + signatures: [MENUENTRY.Weight] +--- + +If you define the menu entry [automatically], the `Weight` method returns the page’s [`Weight`]. + +If you define the menu entry [in front matter] or [in site configuration], the `Weight` method returns the `weight` property, falling back to the page’s `Weight`. + +[`Weight`]: /methods/page/weight +[automatically]: /content-management/menus/#define-automatically +[in front matter]: /content-management/menus/#define-in-front-matter +[in site configuration]: /content-management/menus/#define-in-site-configuration + +In this contrived example, we limit the number of menu entries based on weight: + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + {{ if le .Weight 42 }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} + {{ end }} +</ul> +``` diff --git a/content/en/methods/menu-entry/_common/_index.md b/content/en/methods/menu-entry/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/methods/menu-entry/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/content/en/methods/menu-entry/_common/pre-post.md b/content/en/methods/menu-entry/_common/pre-post.md new file mode 100644 index 000000000..8cc787ea9 --- /dev/null +++ b/content/en/methods/menu-entry/_common/pre-post.md @@ -0,0 +1,39 @@ +--- +# Do not remove front matter. +--- + +In this site configuration we enable rendering of [emoji shortcodes], and add emoji shortcodes before (pre) and after (post) each menu entry: + +{{< code-toggle file=hugo >}} +enableEmoji = true + +[[menu.main]] +name = 'About' +pageRef = '/about' +post = ':point_left:' +pre = ':point_right:' +weight = 10 + +[[menu.main]] +name = 'Contact' +pageRef = '/contact' +post = ':arrow_left:' +pre = ':arrow_right:' +weight = 20 +{{< /code-toggle >}} + +To render the menu: + +```go-html-template +<ul> + {{ range .Site.Menus.main }} + <li> + {{ .Pre | markdownify }} + <a href="{{ .URL }}">{{ .Name }}</a> + {{ .Post | markdownify }} + </li> + {{ end }} +</ul> +``` + +[emoji shortcodes]: /quick-reference/emojis/ diff --git a/content/en/methods/menu-entry/_index.md b/content/en/methods/menu-entry/_index.md new file mode 100644 index 000000000..d89663593 --- /dev/null +++ b/content/en/methods/menu-entry/_index.md @@ -0,0 +1,12 @@ +--- +title: Menu entry methods +linkTitle: Menu entry +description: Use these methods in your menu templates. +categories: [] +keywords: [] +menu: + docs: + parent: methods +--- + +Use these methods in your menu templates. diff --git a/content/en/methods/menu/ByName.md b/content/en/methods/menu/ByName.md new file mode 100644 index 000000000..3f1c52b2e --- /dev/null +++ b/content/en/methods/menu/ByName.md @@ -0,0 +1,65 @@ +--- +title: ByName +description: Returns the given menu with its entries sorted by name. +categories: [] +keywords: [] +action: + related: [] + returnType: navigation.Menu + signatures: [MENU.ByName] +--- + +The `Sort` method returns the given menu with its entries sorted by `name`. + +Consider this menu definition: + +{{< code-toggle file=hugo >}} +[[menu.main]] +name = 'Services' +pageRef = '/services' +weight = 10 + +[[menu.main]] +name = 'About' +pageRef = '/about' +weight = 20 + +[[menu.main]] +name = 'Contact' +pageRef = '/contact' +weight = 30 +{{< /code-toggle >}} + +To sort the entries by `name`: + +```go-html-template +<ul> + {{ range .Site.Menus.main.ByName }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} +</ul> +``` + +Hugo renders this to: + +```html +<ul> + <li><a href="/about/">About</a></li> + <li><a href="/contact">Contact</a></li> + <li><a href="/services/">Services</a></li> +</ul> +``` + +You can also sort menu entries using the [`sort`] function. For example, to sort by `name` in descending order: + +```go-html-template +<ul> + {{ range sort .Site.Menus.main "Name" "desc" }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} +</ul> +``` + +When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`. + +[`sort`]: /functions/collections/sort diff --git a/content/en/methods/menu/ByWeight.md b/content/en/methods/menu/ByWeight.md new file mode 100644 index 000000000..c915914db --- /dev/null +++ b/content/en/methods/menu/ByWeight.md @@ -0,0 +1,76 @@ +--- +title: ByWeight +description: Returns the given menu with its entries sorted by weight, then by name, then by identifier. +categories: [] +keywords: [] +action: + related: [] + returnType: navigation.Menu + signatures: [MENU.ByWeight] +--- + +The `ByWeight` method returns the given menu with its entries sorted by [`weight`], then by `name`, then by `identifier`. This is the default sort order. + +[`weight`]: /getting-started/glossary/#weight + +Consider this menu definition: + +{{< code-toggle file=hugo >}} +[[menu.main]] +identifier = 'about' +name = 'About' +pageRef = '/about' +weight = 20 + +[[menu.main]] +identifier = 'services' +name = 'Services' +pageRef = '/services' +weight = 10 + +[[menu.main]] +identifier = 'contact' +name = 'Contact' +pageRef = '/contact' +weight = 30 +{{< /code-toggle >}} + +To sort the entries by `weight`, then by `name`, then by `identifier`: + +```go-html-template +<ul> + {{ range .Site.Menus.main.ByWeight }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} +</ul> +``` + +Hugo renders this to: + +```html +<ul> + <li><a href="/services/">Services</a></li> + <li><a href="/about/">About</a></li> + <li><a href="/contact">Contact</a></li> +</ul> +``` + +{{% note %}} +In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. + +[details]: /content-management/menus/#properties-front-matter +{{% /note %}} + +You can also sort menu entries using the [`sort`] function. For example, to sort by `weight` in descending order: + +```go-html-template +<ul> + {{ range sort .Site.Menus.main "Weight" "desc" }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} +</ul> +``` + +When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`. + +[`sort`]: /functions/collections/sort diff --git a/content/en/methods/menu/Limit.md b/content/en/methods/menu/Limit.md new file mode 100644 index 000000000..12263e811 --- /dev/null +++ b/content/en/methods/menu/Limit.md @@ -0,0 +1,50 @@ +--- +title: Limit +description: Returns the given menu, limited to the first N entries. +categories: [] +keywords: [] +action: + related: [] + returnType: navigation.Menu + signatures: [MENU.Limit N] +--- + +The `Limit` method returns the given menu, limited to the first N entries. + +Consider this menu definition: + +{{< code-toggle file=hugo >}} +[[menu.main]] +name = 'Services' +pageRef = '/services' +weight = 10 + +[[menu.main]] +name = 'About' +pageRef = '/about' +weight = 20 + +[[menu.main]] +name = 'Contact' +pageRef = '/contact' +weight = 30 +{{< /code-toggle >}} + +To sort the entries by name, and limit to the first 2 entries: + +```go-html-template +<ul> + {{ range .Site.Menus.main.ByName.Limit 2 }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} +</ul> +``` + +Hugo renders this to: + +```html +<ul> + <li><a href="/about/">About</a></li> + <li><a href="/contact">Contact</a></li> +</ul> +``` diff --git a/content/en/methods/menu/Reverse.md b/content/en/methods/menu/Reverse.md new file mode 100644 index 000000000..989132d60 --- /dev/null +++ b/content/en/methods/menu/Reverse.md @@ -0,0 +1,51 @@ +--- +title: Reverse +description: Returns the given menu, reversing the sort order of its entries. +categories: [] +keywords: [] +action: + related: [] + returnType: navigation.Menu + signatures: [MENU.Reverse] +--- + +The `Reverse` method returns the given menu, reversing the sort order of its entries. + +Consider this menu definition: + +{{< code-toggle file=hugo >}} +[[menu.main]] +name = 'Services' +pageRef = '/services' +weight = 10 + +[[menu.main]] +name = 'About' +pageRef = '/about' +weight = 20 + +[[menu.main]] +name = 'Contact' +pageRef = '/contact' +weight = 30 +{{< /code-toggle >}} + +To sort the entries by name in descending order: + +```go-html-template +<ul> + {{ range .Site.Menus.main.ByName.Reverse }} + <li><a href="{{ .URL }}">{{ .Name }}</a></li> + {{ end }} +</ul> +``` + +Hugo renders this to: + +```html +<ul> + <li><a href="/services/">Services</a></li> + <li><a href="/contact">Contact</a></li> + <li><a href="/about/">About</a></li> +</ul> +``` diff --git a/content/en/methods/menu/_index.md b/content/en/methods/menu/_index.md new file mode 100644 index 000000000..f5b925fd6 --- /dev/null +++ b/content/en/methods/menu/_index.md @@ -0,0 +1,12 @@ +--- +title: Menu methods +linkTitle: Menu +description: Use these methods when ranging through menu entries. +categories: [] +keywords: [] +menu: + docs: + parent: methods +--- + +Use these methods when ranging through menu entries. diff --git a/content/en/methods/page/Aliases.md b/content/en/methods/page/Aliases.md new file mode 100644 index 000000000..15e73384b --- /dev/null +++ b/content/en/methods/page/Aliases.md @@ -0,0 +1,29 @@ +--- +title: Aliases +description: Returns the URL aliases as defined in front matter. +categories: [] +keywords: [] +action: + related: [] + returnType: '[]string' + signatures: [PAGE.Aliases] +--- + +The `Aliases` method on a `Page` object returns the URL [aliases] as defined in front matter. + +For example: + +{{< code-toggle file=content/about.md fm=true >}} +title = 'About' +aliases = ['/old-url','/really-old-url'] +{{< /code-toggle >}} + +To list the aliases: + +```go-html-template +{{ range .Aliases }} + {{ . }} +{{ end }} +``` + +[aliases]: /content-management/urls/#aliases diff --git a/content/en/methods/page/AllTranslations.md b/content/en/methods/page/AllTranslations.md new file mode 100644 index 000000000..b9c156127 --- /dev/null +++ b/content/en/methods/page/AllTranslations.md @@ -0,0 +1,90 @@ +--- +title: AllTranslations +description: Returns all translation of the given page, including the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Translations + - methods/page/IsTranslated + - methods/page/TranslationKey + returnType: page.Pages + signatures: [PAGE.AllTranslations] +--- + +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 .AllTranslations }} + <ul> + {{ range . }} + {{ $lang := .Language.LanguageName}} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }} ({{ $lang }})</a></li> + {{ end }} + </ul> +{{ end }} +``` + +Hugo will render this list on the "Book 1" page of each site: + +```html +<ul> + <li><a href="/books/book-1/">Book 1 (English)</a></li> + <li><a href="/de/books/book-1/">Book 1 (Deutsch)</a></li> + <li><a href="/fr/books/book-1/">Book 1 (Français)</a></li> +</ul> +``` + +On the "Book 2" page of the English and German sites, Hugo will render this: + +```html +<ul> + <li><a href="/books/book-1/">Book 1 (English)</a></li> + <li><a href="/de/books/book-1/">Book 1 (Deutsch)</a></li> +</ul> +``` diff --git a/content/en/methods/page/AlternativeOutputFormats.md b/content/en/methods/page/AlternativeOutputFormats.md new file mode 100644 index 000000000..b48d1adf4 --- /dev/null +++ b/content/en/methods/page/AlternativeOutputFormats.md @@ -0,0 +1,43 @@ +--- +title: AlternativeOutputFormats +description: Returns a slice of OutputFormat objects, excluding the current output format, each representing one of the output formats enabled for the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/OutputFormats + returnType: page.OutputFormats + signatures: [PAGE.AlternativeOutputFormats] +--- + +{{% include "methods/page/_common/output-format-definition.md" %}} + +The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, 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 + +Generate a `link` element in the `<head>` of each page for each of the alternative output formats: + +```go-html-template +<head> + ... + {{ $title := printf "%s | %s" .Title site.Title }} + {{ if .IsHome }} + {{ $title = site.Title }} + {{ end }} + {{ range .AlternativeOutputFormats -}} + {{ printf `<link rel=%q type=%q href=%q title=%q>` .Rel .MediaType.Type .Permalink $title | safeHTML }} + {{ end }} + ... +</head> +``` + +On the site's home page, Hugo renders this to: + +```html +<link rel="alternate" type="application/rss+xml" href="https://example.org/index.xml" title="ABC Widgets, Inc."> +``` diff --git a/content/en/methods/page/Ancestors.md b/content/en/methods/page/Ancestors.md new file mode 100644 index 000000000..3bf36d9aa --- /dev/null +++ b/content/en/methods/page/Ancestors.md @@ -0,0 +1,87 @@ +--- +title: Ancestors +description: Returns a collection of Page objects, one for each ancestor section of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/CurrentSection + - methods/page/FirstSection + - methods/page/InSection + - methods/page/IsAncestor + - methods/page/IsDescendant + - methods/page/Parent + - methods/page/Sections + returnType: page.Pages + signatures: [PAGE.Ancestors] +--- + +{{< new-in 0.109.0 >}} + +{{% include "methods/page/_common/definition-of-section.md" %}} + +With this content structure: + +```text +content/ +├── auctions/ +│ ├── 2023-11/ +│ │ ├── _index.md <-- front matter: weight = 202311 +│ │ ├── 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 .Ancestors }} + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> +{{ end }} +``` + +On the November 2023 auctions page, Hugo renders: + +```html +<a href="/auctions/2023-11/">Auctions in November 2023</a> +<a href="/auctions/">Auctions</a> +<a href="/">Home</a> +``` + +In the example above, notice that Hugo orders the ancestors from closest to furthest. This makes breadcrumb navigation simple: + +```go-html-template +<nav aria-label="breadcrumb" class="breadcrumb"> + <ol> + {{ range .Ancestors.Reverse }} + <li> + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> + </li> + {{ end }} + <li class="active"> + <a aria-current="page" href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> + </li> + </ol> +</nav> +``` + +With some CSS, the code above renders something like this, where each breadcrumb links to its page: + +```text +Home > Auctions > Auctions in November 2023 > Auction 1 +``` diff --git a/content/en/methods/page/BundleType.md b/content/en/methods/page/BundleType.md new file mode 100644 index 000000000..77d1d72eb --- /dev/null +++ b/content/en/methods/page/BundleType.md @@ -0,0 +1,37 @@ +--- +title: BundleType +description: Returns the bundle type of the given page, or an empty string if the page is not a page bundle. +categories: [] +keywords: [] +action: + related: [] + returnType: files.ContentClass + signatures: [PAGE.BundleType] +--- + +A page bundle is a directory that encapsulates both content and associated [resources]. There are two types of page bundles: [leaf bundles] and [branch bundles]. See [details](/content-management/page-bundles/). + +The `BundleType` method on a `Page` object returns `branch` for branch bundles, `leaf` for leaf bundles, and an empty string if the page is not a page bundle. + +```text +content/ +├── films/ +│ ├── film-1/ +│ │ ├── a.jpg +│ │ └── index.md <-- leaf bundle +│ ├── _index.md <-- branch bundle +│ ├── b.jpg +│ ├── film-2.md +│ └── film-3.md +└── _index.md <-- branch bundle +``` + +To get the value within a template: + +```go-html-template +{{ .BundleType }} +``` + +[resources]: /getting-started/glossary/#resource +[leaf bundles]: /getting-started/glossary/#leaf-bundle +[branch bundles]: /getting-started/glossary/#branch-bundle diff --git a/content/en/methods/page/CodeOwners.md b/content/en/methods/page/CodeOwners.md new file mode 100644 index 000000000..ec7e5c8bf --- /dev/null +++ b/content/en/methods/page/CodeOwners.md @@ -0,0 +1,66 @@ +--- +title: CodeOwners +description: Returns of slice of code owners for the given page, derived from the CODEOWNERS file in the root of the project directory. +categories: [] +keywords: [] +action: + related: + - methods/page/GitInfo + returnType: '[]string' + signatures: [PAGE.CodeOwners] +--- + +GitHub and GitLab support CODEOWNERS files. This file specifies the users responsible for developing and maintaining software and documentation. This definition can apply to the entire repository, specific directories, or to individual files. To learn more: + +- [GitHub CODEOWNERS documentation] +- [GitLab CODEOWNERS documentation] + +Use the `CodeOwners` method on a `Page` object to determine the code owners for the given page. + +[GitHub CODEOWNERS documentation]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners +[GitLab CODEOWNERS documentation]: https://docs.gitlab.com/ee/user/project/code_owners.html + +To use the `CodeOwners` method you must enable access to your local Git repository: + +{{< code-toggle file=hugo >}} +enableGitInfo = true +{{< /code-toggle >}} + +Consider this project structure: + +```text +hugo-testing/ +├── content/ +│ ├── books/ +│ │ └── les-miserables.md +│ └── films/ +│ └── the-hunchback-of-notre-dame.md +└── CODEOWNERS +``` + +And this CODEOWNERS file: + +```text +* @jdoe +/content/books/ @tjones +/content/films/ @mrichards @rsmith +``` + +The table below shows the slice of code owners returned for each file: + +Path|Code owners +:--|:-- +`books/les-miserables.md`|`[@tjones]` +`films/the-hunchback-of-notre-dame.md`|`[@mrichards @rsmith]` + +Render the code owners for each content page: + +```go-html-template +{{ range .CodeOwners }} + {{ . }} +{{ end }} +``` + +Combine this method with [`resources.GetRemote`] to retrieve names and avatars from your Git provider by querying their API. + +[`resources.GetRemote`]: functions/resources/getremote diff --git a/content/en/methods/page/Content.md b/content/en/methods/page/Content.md new file mode 100644 index 000000000..40a057f02 --- /dev/null +++ b/content/en/methods/page/Content.md @@ -0,0 +1,22 @@ +--- +title: Content +description: Returns the rendered content of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/RawContent + - methods/page/Plain + - methods/page/PlainWords + - methods/page/RenderShortcodes + returnType: template.HTML + signatures: [PAGE.Content] +--- + +The `Content` method on a `Page` object renders markdown and shortcodes to HTML. The content does not include front matter. + +[shortcodes]: /getting-started/glossary/#shortcode + +```go-html-template +{{ .Content }} +``` diff --git a/content/en/methods/page/CurrentSection.md b/content/en/methods/page/CurrentSection.md new file mode 100644 index 000000000..03cb9eb3d --- /dev/null +++ b/content/en/methods/page/CurrentSection.md @@ -0,0 +1,60 @@ +--- +title: CurrentSection +description: Returns the Page object of the section in which the given page resides. +categories: [] +keywords: [] +action: + related: + - methods/page/Ancestors + - methods/page/FirstSection + - methods/page/InSection + - methods/page/IsAncestor + - methods/page/IsDescendant + - methods/page/Parent + - methods/page/Sections + returnType: hugolib.pageState + signatures: [PAGE.CurrentSection] +--- + +{{% include "methods/page/_common/definition-of-section.md" %}} + +{{% note %}} +The current section of a [section] page, [taxonomy] page, [term] page, or the home page, is itself. + +[section]: /getting-started/glossary/#section +[taxonomy]: /getting-started/glossary/#taxonomy +[term]: /getting-started/glossary/#term +{{% /note %}} + +Consider this content structure: + +```text +content/ +├── auctions/ +│ ├── 2023-11/ +│ │ ├── _index.md <-- current section: 2023-11 +│ │ ├── auction-1.md +│ │ └── auction-2.md <-- current section: 2023-11 +│ ├── 2023-12/ +│ │ ├── _index.md +│ │ ├── auction-3.md +│ │ └── auction-4.md +│ ├── _index.md <-- current section: auctions +│ ├── bidding.md +│ └── payment.md <-- current section: auctions +├── books/ +│ ├── _index.md <-- current section: books +│ ├── book-1.md +│ └── book-2.md <-- current section: books +├── films/ +│ ├── _index.md <-- current section: films +│ ├── film-1.md +│ └── film-2.md <-- current section: films +└── _index.md <-- current section: home +``` + +To create a link to the current section page: + +```go-html-template +<a href="{{ .CurrentSection.RelPermalink }}">{{ .CurrentSection.LinkTitle }}</a> +``` diff --git a/content/en/methods/page/Data.md b/content/en/methods/page/Data.md new file mode 100644 index 000000000..4eccde6ff --- /dev/null +++ b/content/en/methods/page/Data.md @@ -0,0 +1,111 @@ +--- +title: Data +description: Returns a unique data object for each page kind. +categories: [] +keywords: [] +action: + related: [] + returnType: page.Data + signatures: [PAGE.Data] +toc: true +--- + +The `Data` method on a `Page` object returns a unique data object for each [page kind]. + +[page kind]: /getting-started/glossary/#page-kind + +{{% note %}} +The `Data` method is only useful within [taxonomy] and [term] templates. + +Themes that are not actively maintained may still use `.Data.Pages` in list templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`] + +[`Pages`]: /methods/page/pages/ +[`RegularPages`]: /methods/page/regularpages/ +[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/ +[term]: /getting-started/glossary/#term +[taxonomy]: /getting-started/glossary/#taxonomy +{{% /note %}} + +The examples that follow are based on 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 +``` + +## In a taxonomy template + +Use these methods on the `Data` object within a taxonomy template. + +Singular +: (`string`) Returns the singular name of the taxonomy. + +```go-html-template +{{ .Data.Singular }} → genre +``` + +Plural +: (`string`) Returns the plural name of the taxonomy. + +```go-html-template +{{ .Data.Plural }} → genres +``` + +Terms +: (`page.Taxonomy`) Returns the taxonomy object, consisting of a map of terms and the [weighted pages] associated with each term. + +```go-html-template +{{ $taxonomyObject := .Data.Terms }} +``` + +{{% note %}} +Once you have captured the taxonomy object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages. + +[taxonomy methods]: /methods/taxonomy +{{% /note %}} + +Learn more about [taxonomy templates]. + +## In a term template + +Use these methods on the `Data` object within a term template. + +Singular +: (`string`) Returns the singular name of the taxonomy. + +```go-html-template +{{ .Data.Singular }} → genre +``` + +Plural +: (`string`) Returns the plural name of the taxonomy. + +```go-html-template +{{ .Data.Plural }} → genres +``` + +Term +: (`string`) Returns the name of the term. + +```go-html-template +{{ .Data.Term }} → suspense +``` + +Learn more about [term templates]. + +[taxonomy templates]: /templates/taxonomy-templates/ +[term templates]: /templates/taxonomy-templates/ +[weighted pages]: /getting-started/glossary/#weighted-page diff --git a/content/en/methods/page/Date.md b/content/en/methods/page/Date.md new file mode 100644 index 000000000..83192f94c --- /dev/null +++ b/content/en/methods/page/Date.md @@ -0,0 +1,39 @@ +--- +title: Date +description: Returns the date of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/ExpiryDate + - methods/page/LastMod + - methods/page/PublishDate + returnType: time.Time + signatures: [PAGE.Date] +--- + +Set the date in front matter: + +{{< code-toggle file=content/news/article-1.md fm=true >}} +title = 'Article 1' +date = 2023-10-19T00:40:04-07:00 +{{< /code-toggle >}} + +{{% note %}} +The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your site, in the site configuration. See [details]. + +[details]: /getting-started/configuration/#configure-dates +{{% /note %}} + +The 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 +{{ .Date | time.Format ":date_medium" }} → Oct 19, 2023 +``` + +In the example above we explicitly set the date in front matter. With Hugo's default configuration, the `Date` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the 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/Description.md b/content/en/methods/page/Description.md new file mode 100644 index 000000000..fbb43b8b5 --- /dev/null +++ b/content/en/methods/page/Description.md @@ -0,0 +1,28 @@ +--- +title: Description +description: Returns the description of the given page as defined in front matter. +categories: [] +keywords: [] +action: + related: + - methods/page/Summary + returnType: string + signatures: [PAGE.Description] +--- + +Conceptually different that a [content summary], a page description is typically used in metadata about the page. + +{{< code-toggle file=content/recipes/sushi.md fm=true >}} +title = 'How to make spicy tuna hand rolls' +description = 'Instructions for making spicy tuna hand rolls.' +{{< /code-toggle >}} + +{{< code file=layouts/baseof.html >}} +<head> + ... + <meta name="description" content="{{ .Description }}"> + ... +</head> +{{< /code >}} + +[content summary]: /content-management/summaries diff --git a/content/en/methods/page/Draft.md b/content/en/methods/page/Draft.md new file mode 100644 index 000000000..fd55a9bc9 --- /dev/null +++ b/content/en/methods/page/Draft.md @@ -0,0 +1,21 @@ +--- +title: Draft +description: Reports whether the given page is a draft as defined in front matter. +categories: [] +keywords: [] +action: + related: [] + returnType: bool + signatures: [PAGE.Draft] +--- + +By default, Hugo does not publish draft pages when you build your site. To include draft pages when you build your site, use the `--buildDrafts` command line flag. + +{{< code-toggle file=content/posts/post-1.md fm=true >}} +title = 'Post 1' +draft = true +{{< /code-toggle >}} + +```go-html-template +{{ .Draft }} → true +``` diff --git a/content/en/methods/page/Eq.md b/content/en/methods/page/Eq.md new file mode 100644 index 000000000..1be416295 --- /dev/null +++ b/content/en/methods/page/Eq.md @@ -0,0 +1,21 @@ +--- +title: Eq +description: Reports whether two Page objects are equal. +categories: [] +keywords: [] +action: + related: [] + returnType: bool + signatures: [PAGE1.Eq PAGE2] +--- + +In this contrived example from a single page template, we list all pages in the current section except for the current page. + +```go-html-template +{{ $currentPage := . }} +{{ range .CurrentSection.Pages }} + {{ if not (.Eq $currentPage) }} + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> + {{ end }} +{{ end }} +``` diff --git a/content/en/methods/page/ExpiryDate.md b/content/en/methods/page/ExpiryDate.md new file mode 100644 index 000000000..353546449 --- /dev/null +++ b/content/en/methods/page/ExpiryDate.md @@ -0,0 +1,35 @@ +--- +title: ExpiryDate +description: Returns the expiry date of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Date + - methods/page/LastMod + - methods/page/PublishDate + returnType: time.Time + signatures: [PAGE.ExpiryDate] +--- + +By default, Hugo excludes expired pages when building your site. To include expired pages, use the `--buildExpired` command line flag. + +Set the expiry date in front matter: + +{{< code-toggle file=content/news/article-1.md fm=true >}} +title = 'Article 1' +expiryDate = 2024-10-19T00:32:13-07:00 +{{< /code-toggle >}} + +The expiry 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 +{{ .ExpiryDate | time.Format ":date_medium" }} → Oct 19, 2024 +``` + +In the example above we explicitly set the expiry date in front matter. With Hugo's default configuration, the `ExpiryDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the expiry 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/File.md b/content/en/methods/page/File.md new file mode 100644 index 000000000..c39d1a64d --- /dev/null +++ b/content/en/methods/page/File.md @@ -0,0 +1,180 @@ +--- +title: File +description: For pages backed by a file, returns file information for the given page. +categories: [] +keywords: [] +action: + related: [] + returnType: hugolib.fileInfo + signatures: [PAGE.File] +toc: true +--- + +By default, not all pages are backed by a file, including top level [section] pages, [taxonomy] pages, and [term] pages. By definition, you cannot retrieve file information when the file does not exist. + +To back one of the pages above with a file, create an _index.md file in the corresponding directory. For example: + +```text +content/ +└── books/ + ├── _index.md <-- the top level section page + ├── book-1.md + └── book-2.md +``` + +Code defensively by verifying file existence as shown in each of the examples below. + +## Methods + +{{% note %}} +The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system. +{{% /note %}} + +BaseFileName +: (`string`) The file name, excluding the extension. + +```go-html-template +{{ with .File }} + {{ .BaseFileName }} +{{ end }} +``` + +ContentBaseName +: (`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `TranslationBaseName`. + +```go-html-template +{{ with .File }} + {{ .ContentBaseName }} +{{ end }} +``` + +Dir +: (`string`) The file path, excluding the file name, relative to the `content` directory. + +```go-html-template +{{ with .File }} + {{ .Dir }} +{{ end }} +``` + +Ext +: (`string`) The file extension. + +```go-html-template +{{ with .File }} + {{ .Ext }} +{{ end }} +``` + +Filename +: (`string`) The absolute file path. + +```go-html-template +{{ with .File }} + {{ .Filename }} +{{ end }} +``` + +Lang +: (`string`) The language associated with the given file. + +```go-html-template +{{ with .File }} + {{ .Lang }} +{{ end }} +``` + +LogicalName +: (`string`) The file name. + +```go-html-template +{{ with .File }} + {{ .LogicalName }} +{{ end }} +``` + +Path +: (`string`) The file path, relative to the `content` directory. + +```go-html-template +{{ with .File }} + {{ .Path }} +{{ end }} +``` + +TranslationBaseName +: (`string`) The file name, excluding the extension and language identifier. + +```go-html-template +{{ with .File }} + {{ .TranslationBaseName }} +{{ end }} +``` + +UniqueID +: (`string`) The MD5 hash of `.File.Path`. + +```go-html-template +{{ with .File }} + {{ .UniqueID }} +{{ end }} +``` + +## Examples + +Consider this content structure in a multilingual project: + +```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 English language site: + + |regular content|leaf bundle|branch bundle +:--|:--|:--|:-- +BaseFileName|a.en|index.en|_index.en +ContentBaseName|a|b|news +Dir|news/|news/b/|news/ +Ext|md|md|md +Filename|/home/user/...|/home/user/...|/home/user/... +Lang|en|en|en +LogicalName|a.en.md|index.en.md|_index.en.md +Path|news/a.en.md|news/b/index.en.md|news/_index.en.md +TranslationBaseName|a|index|_index +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, first check for file existence: + +```go-html-template +{{ with .File }} + {{ .ContentBaseName }} +{{ end }} +``` + +[section]: /getting-started/glossary/#section +[taxonomy]: /getting-started/glossary/#taxonomy +[term]: /getting-started/glossary/#term diff --git a/content/en/methods/page/FirstSection.md b/content/en/methods/page/FirstSection.md new file mode 100644 index 000000000..f757aa2d2 --- /dev/null +++ b/content/en/methods/page/FirstSection.md @@ -0,0 +1,56 @@ +--- +title: FirstSection +description: Returns the Page object of the top level section of which the given page is a descendant. +categories: [] +keywords: [] +action: + related: + - methods/page/Ancestors + - methods/page/CurrentSection + - methods/page/InSection + - methods/page/IsAncestor + - methods/page/IsDescendant + - methods/page/Parent + - methods/page/Sections + returnType: hugolib.pageState + signatures: [PAGE.FirstSection] +--- + +{{% include "methods/page/_common/definition-of-section.md" %}} + +{{% note %}} +When called on the home page, the `FirstSection` method returns the `Page` object of the home page itself. +{{% /note %}} + +Consider this content structure: + +```text +content/ +├── auctions/ +│ ├── 2023-11/ +│ │ ├── _index.md <-- first section: auctions +│ │ ├── auction-1.md +│ │ └── auction-2.md <-- first section: auctions +│ ├── 2023-12/ +│ │ ├── _index.md +│ │ ├── auction-3.md +│ │ └── auction-4.md +│ ├── _index.md <-- first section: auctions +│ ├── bidding.md +│ └── payment.md <-- first section: auctions +├── books/ +│ ├── _index.md <-- first section: books +│ ├── book-1.md +│ └── book-2.md <-- first section: books +├── films/ +│ ├── _index.md <-- first section: films +│ ├── film-1.md +│ └── film-2.md <-- first section: films +└── _index.md <-- first section: home +``` + +To link to the top level section of which the current page is a descendant: + +```go-html-template +<a href="{{ .FirstSection.RelPermalink }}">{{ .FirstSection.LinkTitle }}</a> +``` diff --git a/content/en/methods/page/Fragments.md b/content/en/methods/page/Fragments.md new file mode 100644 index 000000000..bae1c7d03 --- /dev/null +++ b/content/en/methods/page/Fragments.md @@ -0,0 +1,106 @@ +--- +title: Fragments +description: Returns a data structure of the fragments in the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/TableOfContents + returnType: tableofcontents.Fragments + signatures: [PAGE.Fragments] +toc: true +--- + +{{< new-in 0.111.0 >}} + +In a URL, whether absolute or relative, the [fragment] links to an `id` attribute of an HTML element on the page. + +```text +/articles/article-1#section-2 +------------------- --------- + path fragment +``` + +Hugo assigns an `id` attribute to each markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [markdown attribute] as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page. + +Use the `Fragments` method on a `Page` object to create a table of contents with the `Fragments.ToHTML` method, or by [walking] the `Fragments.Map` data structure. + +## Methods + +Headings +: (`map`) A nested map of all headings on the page. Each map contains the following keys: `ID`, `Title` and `Headings`. To inspect the data structure: + +```go-html-template +<pre>{{ .Fragments.Headings | jsonify (dict "indent" " ") }}</pre> +``` + +HeadingsMap +: (`slice`) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys: `ID`, `Title` and `Headings`. To inspect the data structure: + +```go-html-template +<pre>{{ .Fragments.HeadingsMap | jsonify (dict "indent" " ") }}</pre> +``` + +Identifiers +: (`slice`) A slice containing the `id` of each heading on the page. To inspect the data structure: + +```go-html-template +<pre>{{ .Fragments.Identifiers | jsonify (dict "indent" " ") }}</pre> +``` + +Identifiers.Contains ID +: (`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook]. + +```go-html-template +{{ .Fragments.Identifiers.Contains "section-2" }} → true +``` + +Identifiers.Count ID +: (`int`) The number of headings on a page with the given `id` attribute, useful for detecting duplicates. + +```go-html-template +{{ .Fragments.Identifiers.Count "section-2" }} → 1 +``` + +ToHTML +: (`template.HTML`) Returns a TOC as a nested list, either ordered or unordered, identical to the HTML returned by the [`TableOfContents`] method. This method take three arguments: the start level (`int`), the end level (`int`), and a boolean (`true` to return an ordered list, `false` to return an unordered list). + +Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your site configuration. + +```go-html-template +{{ $startLevel := 2 }} +{{ $endLevel := 3 }} +{{ $ordered := true }} +{{ .Fragments.ToHTML $startLevel $endLevel $ordered }} +``` + +Hugo renders this to: + +```html +<nav id="TableOfContents"> + <ol> + <li><a href="#section-1">Section 1</a> + <ol> + <li><a href="#section-11">Section 1.1</a></li> + <li><a href="#section-12">Section 1.2</a></li> + </ol> + </li> + <li><a href="#section-2">Section 2</a></li> + </ol> +</nav> +``` + +{{% note %}} +It is safe to use the `Fragments` methods within a render hook, even for the current page. + +When using the `Fragments` methods within a shortcode, call the shortcode using the `{{</* */>}}` notation. If you use the `{{%/* */%}}` notation, the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop. +{{% /note %}} + +[atx]: https://spec.commonmark.org/0.30/#atx-headings +[fragment]: /getting-started/glossary/#fragment +[markdown attribute]: /getting-started/glossary/#markdown-attribute +[setext]: https://spec.commonmark.org/0.30/#setext-headings +[table of contents]: /methods/page/tableofcontents +[walking]: /getting-started/glossary/#walk +[`tableofcontents`]: /methods/page/tableofcontents +[render hook]: /getting-started/glossary/#render-hook diff --git a/content/en/methods/page/FuzzyWordCount.md b/content/en/methods/page/FuzzyWordCount.md new file mode 100644 index 000000000..600ad48d5 --- /dev/null +++ b/content/en/methods/page/FuzzyWordCount.md @@ -0,0 +1,20 @@ +--- +title: FuzzyWordCount +description: Returns the number of words in the content of the given page, rounded up to the nearest multiple of 100. +categories: [] +keywords: [] +action: + related: + - methods/page/WordCount + - methods/page/ReadingTime + returnType: int + signatures: [PAGE.FuzzyWordCount] +--- + +```go-html-template +{{ .FuzzyWordCount }} → 200 +``` + +To get the exact word count, use the [`WordCount`] method. + +[`WordCount`]: /methods/page/wordcount diff --git a/content/en/methods/page/GetPage.md b/content/en/methods/page/GetPage.md new file mode 100644 index 000000000..ed072932a --- /dev/null +++ b/content/en/methods/page/GetPage.md @@ -0,0 +1,65 @@ +--- +title: GetPage +description: Returns a Page object from the given path. +categories: [] +keywords: [] +action: + related: + - methods/site/GetPage + returnType: hugolib.pageState + signatures: [PAGE.GetPage PATH] +aliases: [/functions/getpage] +--- + +The `GetPage` method is also available on a `Site` object. See [details]. + +[details]: /methods/site/getpage + +When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the content directory. + +If Hugo cannot resolve the path to a page, the method returns nil. If the path is ambiguous, Hugo throws an error and fails the build. + +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 +``` + +The examples below depict the result of rendering works/paintings/the-mona-list.md with a single page template: + +```go-html-template +{{ with .GetPage "starry-night" }} + {{ .Title }} → Starry Night +{{ end }} + +{{ with .GetPage "./starry-night" }} + {{ .Title }} → Starry Night +{{ end }} + +{{ with .GetPage "../paintings/starry-night" }} + {{ .Title }} → Starry Night +{{ end }} + +{{ with .GetPage "/works/paintings/starry-night" }} + {{ .Title }} → Starry Night +{{ end }} + +{{ with .GetPage "../sculptures/david" }} + {{ .Title }} → David +{{ end }} + +{{ with .GetPage "/works/sculptures/david" }} + {{ .Title }} → David +{{ end }} +``` diff --git a/content/en/methods/page/GetTerms.md b/content/en/methods/page/GetTerms.md new file mode 100644 index 000000000..3020e4c2e --- /dev/null +++ b/content/en/methods/page/GetTerms.md @@ -0,0 +1,41 @@ +--- +title: GetTerms +description: Returns a collection of term pages for terms defined on the given page in the given taxonomy, ordered according to the sequence in which they appear in front matter. +categories: [] +keywords: [] +action: + related: [] + returnType: page.Pages + signatures: [PAGE.GetTerms TAXONOMY] +--- + +Given this front matter: + +{{< code-toggle file=content/books/les-miserables.md fm=true >}} +title = 'Les Misérables' +tags = ['historical','classic','fiction'] +{{< /code-toggle >}} + +This template code: + +```go-html-template +{{ with .GetTerms "tags" }} + <p>Tags</p> + <ul> + {{ range . }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +``` + +Is rendered to: + +```html +<p>Tags</p> +<ul> + <li><a href="/tags/historical/">historical</a></li> + <li><a href="/tags/classic/">classic</a></li> + <li><a href="/tags/fiction/">fiction</a></li> +</ul> +``` diff --git a/content/en/methods/page/GitInfo.md b/content/en/methods/page/GitInfo.md new file mode 100644 index 000000000..88137614c --- /dev/null +++ b/content/en/methods/page/GitInfo.md @@ -0,0 +1,130 @@ +--- +title: GitInfo +description: Returns Git information related to the last commit of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/CodeOwners + returnType: source.GitInfo + signatures: [PAGE.GitInfo] +toc: true +--- + +The `GitInfo` method on a `Page` object returns an object with additional methods. + +{{% note %}} +Hugo's Git integration is performant, but may increase build times on large sites. +{{% /note %}} + +## Prerequisites + +Install [Git], create a repository, and commit your project files. + +You must also allow Hugo to access your repository. In your site configuration: + +{{< code-toggle file=hugo >}} +enableGitInfo = true +{{< /code-toggle >}} + +Alternatively, use the command line flag when building your site: + +```sh +hugo --enableGitInfo +``` + +{{% note %}} +When you set `enableGitInto` to `true`, or enable the feature with the command line flag, the last modification date for each content page will be the Author Date of the last commit for that file. + +This is configurable. See [details]. + +[details]: /getting-started/configuration/#configure-dates +{{% /note %}} + +## Methods + +AbbreviatedHash +: (`string`) The abbreviated commit hash. + +```go-html-template +{{ with .GitInfo }} + {{ .AbbreviatedHash }} → aab9ec0b3 +{{ end }} +``` + +AuthorDate +: (`time.Time`) The author date. + +```go-html-template +{{ with .GitInfo }} + {{ .AuthorDate.Format "2006-01-02" }} → 2023-10-09 +{{ end }} +``` + +AuthorEmail +: (`string`) The author's email address, respecting [gitmailmap]. + +```go-html-template +{{ with .GitInfo }} + {{ .AuthorEmail }} → [email protected] +{{ end }} +``` + +AuthorName +: (`string`) The author's name, respecting [gitmailmap]. + +```go-html-template +{{ with .GitInfo }} + {{ .AuthorName }} → John Smith +{{ end }} +``` + +Hash +: (`string`) The commit hash. + +```go-html-template +{{ with .GitInfo }} + {{ .Hash }} → aab9ec0b31ebac916a1468c4c9c305f2bebf78d4 +{{ end }} +``` + +Subject +: (`string`) The commit message subject. + +```go-html-template +{{ with .GitInfo }} + {{ .Subject }} → Add tutorials +{{ end }} +``` + +## Last modified date + +By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` object returns the Git AuthorDate of the last commit that included the file. + +You can change this behavior in your [site configuration]. + +[git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[gitmailmap]: https://git-scm.com/docs/gitmailmap +[site configuration]: /getting-started/configuration/#configure-front-matter + +## Hosting considerations + +When hosting your site in a CI/CD environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may not be accurate---it may reflect the most recent repository commit, not the commit that last modified the file. + +Some providers perform deep clones by default, others allow you to configure the clone depth, and some providers only perform shallow clones. + +Hosting service | Default clone depth | Configurable +:-- | :-- | :-- +Cloudflare Pages | Shallow | Yes [^CFP] +DigitalOcean App Platform | Deep | N/A +GitHub Pages | Shallow | Yes [^GHP] +GitLab Pages | Shallow | Yes [^GLP] +Netlify | Deep | N/A +Render | Shallow | No +Vercel | Shallow | No + +[^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](/hosting-and-deployment/hosting-on-gitlab/#configure-gitlab-cicd). diff --git a/content/en/functions/HasMenuCurrent.md b/content/en/methods/page/HasMenuCurrent.md index 5b4200c56..68b645905 100644 --- a/content/en/functions/HasMenuCurrent.md +++ b/content/en/methods/page/HasMenuCurrent.md @@ -1,18 +1,14 @@ --- -title: .HasMenuCurrent +title: HasMenuCurrent description: Reports whether the given page object matches the page object associated with one of the child menu entries under the given menu entry in the given menu. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] +action: + related: + - methods/page/IsMenuCurrent returnType: bool signatures: [PAGE.HasMenuCurrent MENU MENUENTRY] -relatedFunctions: - - .HasMenuCurrent - - .IsMenuCurrent +aliases: [/functions/hasmenucurrent] --- If the page object associated with the menu entry is a section, this method also returns `true` for any descendant of that section. diff --git a/content/en/methods/page/HasShortcode.md b/content/en/methods/page/HasShortcode.md new file mode 100644 index 000000000..81268ecba --- /dev/null +++ b/content/en/methods/page/HasShortcode.md @@ -0,0 +1,50 @@ +--- +title: HasShortcode +description: Reports whether the given shortcode is called by the given page. +categories: [] +keywords: [] +action: + related: [] + returnType: bool + signatures: [PAGE.HasShortcode NAME] +--- + +By example, let's use [MathJax] to render a LaTeX mathematical expression: + +[MathJax]: https://www.mathjax.org/ + +{{< code file=contents/physics/lesson-1.md lang=markdown >}} +Albert Einstein’s theory of special relativity expresses +the fact that mass and energy are the same physical entity +and can be changed into each other. + +{{</* math */>}} +$$ +E=mc^2 +$$ +{{</* /math */>}} + +In the equation, the increased relativistic mass (m) of a +body times the speed of light squared (c2) is equal to +the kinetic energy (E) of that body. +{{< /code >}} + +The shortcode is simple: + +{{< code file=layouts/shortcodes/math.html >}} +{{ trim .Inner "\r\n" }} +{{< /code >}} + +Now we can selectively load the required CSS and JavaScript on pages that call the "math" shortcode: + + +{{< code file=layouts/baseof.html >}} +<head> + ... + {{ if .HasShortcode "math" }} + <script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script> + <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script> + {{ end }} + ... +</head> +{{< /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 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/Len.md b/content/en/methods/page/Len.md new file mode 100644 index 000000000..d4270bda3 --- /dev/null +++ b/content/en/methods/page/Len.md @@ -0,0 +1,15 @@ +--- +title: Len +description: Returns the length, in bytes, of the rendered content of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Content + returnType: int + signatures: [PAGE.Len] +--- + +```go-html-template +{{ .Len }} → 42 +``` 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 +<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> +``` 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 }} + <a href="{{ .RelPermalink }}">Prev</a> +{{ end }} + +{{ with .Prev }} + <a href="{{ .RelPermalink }}">Next</a> +{{ 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..b48ddcc62 --- /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 }} + <a href="{{ .RelPermalink }}">Previous in section</a> +{{ end }} + +{{ with .PrevInSection }} + <a href="{{ .RelPermalink }}">Next in section</a> +{{ 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 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" -}} + <a href="{{ .RelPermalink }}">RSS Feed</a> +{{ end }} +``` + +On the site's home page, Hugo renders this to: + +```html +<a href="/index.xml">RSS Feed</a> +``` + +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..2c0536bee --- /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 >}} +{{ 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 >}} +{{ 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 >}} +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..2f329eeec --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> +{{ 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> +{{ 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..6b43b99dd --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> +{{ 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ 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..b2932d981 --- /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..ce624c394 --- /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 = '[email protected]' + 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 }} + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> +{{ 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..4bc79d241 --- /dev/null +++ b/content/en/methods/page/PlainWords.md @@ -0,0 +1,36 @@ +--- +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._ + +[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace +{{% /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 }} + <a href="{{ .RelPermalink }}">Prev</a> +{{ end }} + +{{ with .Prev }} + <a href="{{ .RelPermalink }}">Next</a> +{{ 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..30b813350 --- /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 }} + <a href="{{ .RelPermalink }}">Previous in section</a> +{{ end }} + +{{ with .PrevInSection }} + <a href="{{ .RelPermalink }}">Next in section</a> +{{ 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 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..258a294d0 --- /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 [output 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 %}} + +[output 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..e3c5569a4 --- /dev/null +++ b/content/en/methods/page/Ref.md @@ -0,0 +1,44 @@ +--- +title: Ref +description: Returns the absolute URL of the 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 }} → https://example.org/en/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" }} +{{ .Ref $opts }} → https://example.org/de/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }} +{{ .Ref $opts }} → https://example.org/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..b0ca7b1e1 --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> +{{ 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> +{{ 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..3dac8c85e --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> +{{ 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..4c635e0e2 --- /dev/null +++ b/content/en/methods/page/RelRef.md @@ -0,0 +1,44 @@ +--- +title: RelRef +description: Returns the relative URL of the 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> + {{ .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 +<ul> + {{ range site.RegularPages.ByDate }} + {{ .Render "li" }} + {{ end }} +</ul> +``` + +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..4636bf8f5 --- /dev/null +++ b/content/en/methods/page/RenderShortcodes.md @@ -0,0 +1,78 @@ +--- +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 +--- + +{{< new-in 0.117.0 >}} + +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: + +- `{{</* myshortcode */>}}` 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 ++++ + +{{</* ref "privacy" */>}} + +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 <em>emphasized</em> 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 <em>emphasized</em> word + +{{ $opts := dict "display" "block" }} +{{ $s | .RenderString $opts }} → <p>An <em>emphasized</em> word</p> +``` + +Render with [Pandoc]: + +```go-html-template +{{ $s := "H~2~O" }} + +{{ $opts := dict "markup" "pandoc" }} +{{ $s | .RenderString $opts }} → H<sub>2</sub>O + +{{ $opts := dict "display" "block" "markup" "pandoc" }} +{{ .RenderString $opts $s }} → <p>H<sub>2</sub>O</p> +``` + +[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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ 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" }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +This is similar to using the [`Type`] method with the `where` function + +```go-html-template +{{ range where .Site.RegularPages "Type" "lessons" }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ 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..d64440038 --- /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/ +│ │ ├── _index.md <-- front matter: weight = 202311 +│ │ ├── 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +On the home page, Hugo renders: + +```html +<h2><a href="/films/">Films</a></h2> +<h2><a href="/books/">Books</a></h2> +<h2><a href="/auctions/">Auctions</a></h2> +``` + +On the auctions page, Hugo renders: + +```html +<h2><a href="/auctions/2023-11/">Auctions in November 2023</a></h2> +<h2><a href="/auctions/2023-12/">Auctions in December 2023</a></h2> +``` 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 "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }} +<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" + xmlns:xhtml="http://www.w3.org/1999/xhtml"> + {{ range .Pages }} + <url> + <loc>{{ .Permalink }}</loc> + {{ if not .Lastmod.IsZero }} + <lastmod>{{ .Lastmod.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</lastmod> + {{ end }} + {{ with .Sitemap.ChangeFreq }} + <changefreq>{{ . }}</changefreq> + {{ end }} + </url> + {{ end }} +</urlset> +{{< /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 +<ul> + {{ range .Sites }} + <li><a href="{{ .Home.Permalink }}">{{ .Title }}</a></li> + {{ end }} +</ul> +``` + +Produces a list of links to each home page: + +```html +<ul> + <li><a href="https://example.org/de/">Projekt Dokumentation</a></li> + <li><a href="https://example.org/en/">Project Documentation</a></li> +</ul> +``` + +To render a link to home page of the primary (first) language: + +```go-html-template +{{ with .Sites.First }} + <a href="{{ .Home.Permalink }}">{{ .Title }}</a> +{{ end }} +``` + +This is equivalent to: + +```go-html-template +{{ with index .Sites 0 }} + <a href="{{ .Home.Permalink }}">{{ .Title }}</a> +{{ 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> + {{ .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 +<nav id="TableOfContents"> + <ul> + <li><a href="#section-1">Section 1</a> + <ul> + <li><a href="#section-11">Section 1.1</a></li> + <li><a href="#section-12">Section 1.2</a></li> + </ul> + </li> + <li><a href="#section-2">Section 2</a></li> + </ul> +</nav> +``` + +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..52e46ff44 --- /dev/null +++ b/content/en/methods/page/Title.md @@ -0,0 +1,38 @@ +--- +title: Title +description: Returns the title of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/LinkTitle + returnType: string + signatures: [PAGE.Title] +--- + +With pages backed by a file, the `Title` method returns the `title` field as defined in front matter: + +{{< code-toggle file=content/about.md fm=true >}} +title = 'About us' +{{< /code-toggle >}} + +```go-html-template +{{ .Title }} → About us +``` + +With section pages not backed by a file, the `Title` method returns the section name, pluralized and converted to title case. + +To disable [pluralization]: + +{{< code-toggle file=hugo >}} +pluralizeListTitles = false +{{< /code-toggle >}} + +To change the [title case style], specify one of `ap`, `chicago`, `go`, `firstupper`, or `none`: + +{{< code-toggle file=hugo >}} +titleCaseStyle = "ap" +{{< /code-toggle >}} + +[pluralization]: /functions/inflect/pluralize +[title case style]: /getting-started/configuration/#configure-title-case diff --git a/content/en/methods/page/TranslationKey.md b/content/en/methods/page/TranslationKey.md new file mode 100644 index 000000000..a9e4b97e9 --- /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 }} + <ul> + {{ range . }} + {{ $lang := .Language.LanguageName}} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }} ({{ $lang }})</a></li> + {{ end }} + </ul> +{{ end }} +``` + +Hugo will render this list on the "Book 1" page of the English site: + +```html +<ul> + <li><a href="/de/books/book-1/">Book 1 (Deutsch)</a></li> + <li><a href="/fr/books/book-1/">Book 1 (Français)</a></li> +</ul> +``` + +Hugo will render this list on the "Book 2" page of the English site: + +```html +<ul> + <li><a href="/de/books/book-1/">Book 1 (Deutsch)</a></li> +</ul> +``` 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> + {{ .Summary }} + {{ if .Truncated }} + <a href="{{ .RelPermalink }}">Read more...</a> + {{ 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..b7c62372b --- /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" }} + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> +{{ end }} +``` + +Hugo renders this to; + +```html +<h2><a href="/books/book-1/">Book 1</a></h2> +<h2><a href="/books/book-2/">Book 2</a></h2> +<h2><a href="/auction/item-2/">Item 2</a></h2> +``` + +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 +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/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..eb4e86535 --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByDate.Reverse }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` diff --git a/content/en/methods/pages/ByExpiryDate.md b/content/en/methods/pages/ByExpiryDate.md new file mode 100644 index 000000000..41753c340 --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByExpiryDate.Reverse }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` diff --git a/content/en/methods/pages/ByLanguage.md b/content/en/methods/pages/ByLanguage.md new file mode 100644 index 000000000..30d87f954 --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Site.AllPages.ByLanguage.Reverse }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` diff --git a/content/en/methods/pages/ByLastmod.md b/content/en/methods/pages/ByLastmod.md new file mode 100644 index 000000000..385093134 --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByLastmod.Reverse }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` diff --git a/content/en/methods/pages/ByLength.md b/content/en/methods/pages/ByLength.md new file mode 100644 index 000000000..602b548c2 --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByLength.Reverse }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByLinkTitle.Reverse }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` diff --git a/content/en/methods/pages/ByParam.md b/content/en/methods/pages/ByParam.md new file mode 100644 index 000000000..9a919cc88 --- /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" }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range (.Pages.ByParam "author").Reverse }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +If the targeted parameter is nested, access the field using dot notation: + +```go-html-template +{{ range .Pages.ByParam "author.last_name" }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` diff --git a/content/en/methods/pages/ByPublishDate.md b/content/en/methods/pages/ByPublishDate.md new file mode 100644 index 000000000..e622636a2 --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByPublishDate.Reverse }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> +{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByTitle.Reverse }} + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> +{{ end }} +``` diff --git a/content/en/methods/pages/ByWeight.md b/content/en/methods/pages/ByWeight.md new file mode 100644 index 000000000..4eafee11f --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +To sort in descending order: + +```go-html-template +{{ range .Pages.ByWeight.Reverse }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` diff --git a/content/en/methods/pages/GroupBy.md b/content/en/methods/pages/GroupBy.md new file mode 100644 index 000000000..b46a39bdf --- /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" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +``` + +To sort the groups in descending order: + +```go-html-template +{{ range .Pages.GroupBy "Section" "desc" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/content/en/methods/pages/GroupByDate.md b/content/en/methods/pages/GroupByDate.md new file mode 100644 index 000000000..8b5fcd6f1 --- /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" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +``` + +To sort the groups in ascending order: + +```go-html-template +{{ range .Pages.GroupByDate "January 2006" "asc" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ 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" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages.ByTitle }} + <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + {{ end }} + </ul> +{{ 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..a9b248297 --- /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" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +``` + +To sort the groups in ascending order: + +```go-html-template +{{ range .Pages.GroupByExpiryDate "January 2006" "asc" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ 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" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages.ByTitle }} + <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + {{ end }} + </ul> +{{ 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..877692521 --- /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" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +``` + +To sort the groups in ascending order: + +```go-html-template +{{ range .Pages.GroupByLastmod "January 2006" "asc" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ 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" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages.ByTitle }} + <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + {{ end }} + </ul> +{{ 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..9c63ab902 --- /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" }} + <p>{{ .Key | title }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +``` + +To sort the groups in descending order: + +```go-html-template +{{ range .Pages.GroupByParam "color" "desc" }} + <p>{{ .Key | title }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/content/en/methods/pages/GroupByParamDate.md b/content/en/methods/pages/GroupByParamDate.md new file mode 100644 index 000000000..c7fedbb1a --- /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" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +``` + +To sort the groups in ascending order: + +```go-html-template +{{ range .Pages.GroupByParamDate "eventDate" "January 2006" "asc" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ 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" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages.ByTitle }} + <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + {{ end }} + </ul> +{{ 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..f6603e858 --- /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" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +``` + +To sort the groups in ascending order: + +```go-html-template +{{ range .Pages.GroupByPublishDate "January 2006" "asc" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ 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" }} + <p>{{ .Key }}</p> + <ul> + {{ range .Pages.ByTitle }} + <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + {{ end }} + </ul> +{{ 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..bf889fd7e --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ 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 . }} + <a href="{{ .RelPermalink }}">Previous</a> +{{ end }} + +{{ with $pages.Prev . }} + <a href="{{ .RelPermalink }}">Next</a> +{{ 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 . }} + <a href="{{ .RelPermalink }}">Previous</a> +{{ end }} + +{{ with $pages.Prev . }} + <a href="{{ .RelPermalink }}">Next</a> +{{ 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..1cee88745 --- /dev/null +++ b/content/en/methods/pages/Related.md @@ -0,0 +1,79 @@ +--- +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 + - PAGES.Related 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 >}} +{{ with .Site.RegularPages.Related . | first 5 }} + <p>Related pages:</p> + <ul> + {{ range . }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +{{< /code >}} + +To pass an options map: + +{{< code file=layouts/_default/single.html >}} +{{ $opts := dict + "document" . + "indices" (slice "tags" "keywords") +}} +{{ with .Site.RegularPages.Related $opts | first 5 }} + <p>Related pages:</p> + <ul> + {{ range . }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ 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..e03e0ea47 --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ 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 +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/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..1452d558f --- /dev/null +++ b/content/en/methods/resource/Colors.md @@ -0,0 +1,22 @@ +--- +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] +--- + +{{< new-in 0.104.0 >}} + +```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..a5945ff65 --- /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" }} + <img src="data:{{ .MediaType.Type }};base64,{{ .Content | base64Encode }}"> +{{ end }} +``` + +To create inline CSS: + +```go-html-template +{{ with resources.Get "css/style.css" }} + <style>{{ .Content | safeCSS }}</style> +{{ end }} +``` + +To create inline JavaScript: + +```go-html-template +{{ with resources.Get "js/script.js" }} + <script>{{ .Content | safeJS }}</script> +{{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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..75071153a --- /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 metadata. +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 metadata. + +## 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 }} + <p>Date: {{ .Date }}</p> + <p>Lat/Long: {{ .Lat }}/{{ .Long }}</p> + {{ with .Tags }} + <p>Tags</p> + <table> + <thead> + <tr><th>Tag</th><th>Value</th></tr> + </thead> + <tbody> + {{ range $k, $v := . }} + <tr><td>{{ $k }}</td><td>{{ $v }}</td></tr> + {{ end }} + </tbody> + </table> + {{ end }} + {{ end }} +{{ end }} +``` + +To list specific values: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with .Exif }} + <ul> + {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }} + {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }} + {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }} + {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }} + {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }} + {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }} + {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }} + {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }} + </ul> + {{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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 }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}"> +{{ 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..15927aea9 --- /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 >}} +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..01b75e5b2 --- /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..275182c46 --- /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 >}} +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" }} + <figure> + <img alt="{{ .Params.alt }}" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}"> + <figcaption>{{ .Title }} is {{ .Params.temperament }}</figcaption> + </figure> +{{ end }} +``` + +Hugo renders: + +```html +<figure> + <img alt="Photograph of black cat" src="/posts/post-1/images/a.jpg" width="600" height="400"> + <figcaption>Felix the cat is vicious</figcaption> +</figure> +``` + +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..3c88492df --- /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 `crop`, `fill`, `fit`, or `resize`. 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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..db52e7b10 --- /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 >}} +{{ 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..e30f86d2e --- /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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}"> +{{ 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 +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/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..b12a21d3a --- /dev/null +++ b/content/en/methods/resource/_common/processing-spec.md @@ -0,0 +1,36 @@ +--- +# 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 `crop`, `fill`, `fit`, or `resize`. 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 and equivalent to the `-preset` flag for the [`cwebp`] encoder. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint). + +[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp + +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..cd674614f --- /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 >}} +{{</* myshortcode "Hello" "world" */>}} +{{< /code >}} + +To retrieve parameters by position: + +{{< code file=layouts/shortcodes/myshortcode.html >}} +{{ 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 >}} +{{</* myshortcode greeting="Hello" firstName="world" */>}} +{{< /code >}} + +To retrieve parameters by name: + +{{< code file=layouts/shortcodes/myshortcode.html >}} +{{ 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..de7c284cb --- /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 >}} +{{</* card title="Product Design" */>}} +We design the **best** widgets in the world. +{{</* /card */>}} +{{< /code >}} + +With this shortcode: + +{{< code file=layouts/shortcodes/card.html >}} +<div class="card"> + {{ with .Get "title" }} + <div class="card-title">{{ . }}</div> + {{ end }} + <div class="card-content"> + {{ trim .Inner "\r\n" }} + </div> +</div> +{{< /code >}} + +Is rendered to: + +```html +<div class="card"> + <div class="card-title">Product Design</div> + <div class="card-content"> + We design the **best** widgets in the world. + </div> +</div> +``` + +{{% 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 >}} +<div class="card"> + {{ with .Get "title" }} + <div class="card-title">{{ . }}</div> + {{ end }} + <div class="card-content"> + {{ trim .Inner "\r\n" | .Page.RenderString }} + </div> +</div> +{{< /code >}} + +Hugo renders this to: + +```html +<div class="card"> + <div class="card-title">Product design</div> + <div class="card-content"> + We produce the <strong>best</strong> widgets in the world. + </div> +</div> +``` + +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 >}} +{{%/* 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 >}} +[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 >}} +<div class="card"> + {{ with .Get "title" }} + <div class="card-title">{{ . }}</div> + {{ end }} + <div class="card-content"> + + {{ trim .Inner "\r\n" }} + </div> +</div> +{{< /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 @@ + <div class="card"> + {{ with .Get "title" }} +- <div class="card-title">{{ . }}</div> ++ <div class="card-title">{{ . }}</div> + {{ end }} + <div class="card-content"> +- {{ trim .Inner "\r\n" | .Page.RenderString }} ++ ++ {{ trim .Inner "\r\n" }} + </div> + </div> +``` + +{{% 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..136412bc7 --- /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 >}} +- Gallery one + + {{</* gallery */>}} +  +  + {{</* /gallery */>}} + +- Gallery two + + {{</* gallery */>}} +  +  + {{</* /gallery */>}} +{{< /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 >}} +<div class="gallery"> + {{ trim .Inner "\r\n" | .Page.RenderString }} +</div> +{{< /code >}} + +Hugo renders the markdown to: + +```html +<ul> + <li> + <p>Gallery one</p> + <div class="gallery"> + <pre><code> +  + </code></pre> + </div> + </li> + <li> + <p>Gallery two</p> + <div class="gallery"> + <pre><code> +  + </code></pre> + </div> + </li> +</ul> +``` + +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 >}} +<div class="gallery"> + {{ trim .InnerDeindent "\r\n" | .Page.RenderString }} +</div> +{{< /code >}} + +Hugo renders the markdown to: + +```html +<ul> + <li> + <p>Gallery one</p> + <div class="gallery"> + <img src="images/a.jpg" alt="kitten a"> + <img src="images/b.jpg" alt="kitten b"> + </div> + </li> + <li> + <p>Gallery two</p> + <div class="gallery"> + <img src="images/c.jpg" alt="kitten c"> + <img src="images/d.jpg" alt="kitten d"> + </div> + </li> +</ul> +``` + +[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..83eeb2f74 --- /dev/null +++ b/content/en/methods/shortcode/IsNamedParams.md @@ -0,0 +1,30 @@ +--- +title: IsNamedParams +description: Reports whether the shortcode call uses named 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 >}} +{{ 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 >}} +{{</* myshortcode greeting="Hello" firstName="world" */>}} +{{</* myshortcode "Hello" "world" */>}} +{{< /code >}} diff --git a/content/en/methods/shortcode/Name.md b/content/en/methods/shortcode/Name.md new file mode 100644 index 000000000..18bddfe1f --- /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 >}} +{{ $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..954940258 --- /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 >}} +{{</* img src="images/a.jpg" */>}} + +{{</* img src="images/b.jpg" */>}} +{{< /code >}} + +This shortcode performs error checking, then renders an HTML `img` element with a unique `id` attribute: + +{{< code file=layouts/shortcodes/img.html >}} +{{ $src := "" }} +{{ with .Get "src" }} + {{ $src = . }} + {{ with resources.Get $src }} + {{ $id := printf "img-%03d" $.Ordinal }} + <img id="{{ $id }}" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ 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 +<img id="img-000" src="/images/a.jpg" width="600" height="400" alt=""> +<img id="img-001" src="/images/b.jpg" width="600" height="400" alt=""> +``` + +{{% 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..c9262ab48 --- /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 fm=true >}} +title = 'Les Misérables' +author = 'Victor Hugo' +published = 1862 +isbn = '978-0451419439' +{{< /code-toggle >}} + +Calling this shortcode: + +```text +{{</* book-details */>}} +``` + +We can access the front matter values using the `Page` method: + +{{< code file=layouts/shortcodes/book-details.html >}} +<ul> + <li>Title: {{ .Page.Title }}</li> + <li>Author: {{ .Page.Params.author }}</li> + <li>Published: {{ .Page.Params.publication_year }}</li> + <li>ISBN: {{ .Page.Params.isbn }}</li> +</ul> +{{< /code >}} diff --git a/content/en/methods/shortcode/Params.md b/content/en/methods/shortcode/Params.md new file mode 100644 index 000000000..63df768a6 --- /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 >}} +{{</* myshortcode "Hello" "world" */>}} +{{< /code >}} + +{{< code file=layouts/shortcodes/myshortcode.html >}} +{{ 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 >}} +{{</* myshortcode greeting="Hello" name="world" */>}} +{{< /code >}} + +{{< code file=layouts/shortcodes/myshortcode.html >}} +{{ .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..50ae521da --- /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 >}} +{{</* greeting dateFormat="Jan 2, 2006" */>}} +Welcome. Today is {{</* now */>}}. +{{</* /greeting */>}} +{{< /code >}} + +{{< code file=layouts/shortcodes/greeting.html >}} +<div class="greeting"> + {{ trim .Inner "\r\n" | .Page.RenderString }} +</div> +{{< /code >}} + +{{< code file=layouts/shortcodes/now.html >}} +{{- $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..565a158bf --- /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 >}} +{{ $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 be expensive to calculate. Limit its use to error reporting. +{{% /note %}} diff --git a/content/en/methods/shortcode/Ref.md b/content/en/methods/shortcode/Ref.md new file mode 100644 index 000000000..293c772d9 --- /dev/null +++ b/content/en/methods/shortcode/Ref.md @@ -0,0 +1,44 @@ +--- +title: Ref +description: Returns the absolute URL of the page with the given path, language, and output format. +categories: [] +keywords: [] +action: + related: + - methods/shortcode/RelRef + - functions/urls/RelRef + - functions/urls/Ref + returnType: string + signatures: [SHORTCODE.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 }} → https://example.org/en/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" }} +{{ .Ref $opts }} → https://example.org/de/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }} +{{ .Ref $opts }} → https://example.org/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/shortcode/RelRef.md b/content/en/methods/shortcode/RelRef.md new file mode 100644 index 000000000..07f221a99 --- /dev/null +++ b/content/en/methods/shortcode/RelRef.md @@ -0,0 +1,44 @@ +--- +title: RelRef +description: Returns the relative URL of the page with the given path, language, and output format. +categories: [] +keywords: [] +action: + related: + - methods/shortcode/Ref + - functions/urls/Ref + - functions/urls/RelRef + returnType: string + signatures: [SHORTCODE.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/shortcode/Scratch.md b/content/en/methods/shortcode/Scratch.md new file mode 100644 index 000000000..3ab195a3f --- /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 template 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/Site.md b/content/en/methods/shortcode/Site.md new file mode 100644 index 000000000..fa2d274de --- /dev/null +++ b/content/en/methods/shortcode/Site.md @@ -0,0 +1,19 @@ +--- +title: Site +description: Returns the Site object. +categories: [] +keywords: [] +action: + related: + - methods/page/Sites + returnType: page.siteWrapper + signatures: [SHORTCODE.Site] +--- + +See [Site methods]. + +[Site methods]: /methods/site + +```go-html-template +{{ .Site.Title }} +``` 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ 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..0ff4cddec --- /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..b78caddec --- /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 }} + <p>{{ $category | title }}</p> + <ul> + {{ range $books }} + <li>{{ .title }} ({{ .isbn }})</li> + {{ end }} + </ul> +{{ end }} +``` + +Hugo renders this to: + +```html +<p>Fiction</p> +<ul> + <li>The Hunchback of Notre Dame (978-0140443530)</li> + <li>Les Misérables (978-0451419439)</li> +</ul> +<p>Nonfiction</p> +<ul> + <li>The Ancien Régime and the Revolution (978-0141441641)</li> + <li>Interpreting the French Revolution (978-0521280495)</li> +</ul> +``` + +To limit the listing to fiction, and sort by title: + +```go-html-template +<ul> + {{ range sort .Site.Data.books.fiction "title" }} + <li>{{ .title }} ({{ .author }})</li> + {{ end }} +</ul> +``` + +To find a fiction book by ISBN: + +```go-html-template +{{ range where .Site.Data.books.fiction "isbn" "978-0140443530" }} + <li>{{ .title }} ({{ .author }})</li> +{{ 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/DisqusShortname.md b/content/en/methods/site/DisqusShortname.md new file mode 100644 index 000000000..359b836af --- /dev/null +++ b/content/en/methods/site/DisqusShortname.md @@ -0,0 +1,20 @@ +--- +title: DisqusShortname +description: Returns the Disqus shortname as defined in the site configuration. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [SITE.DisqusShortname] +# deprecated 2023-10-30 +expiryDate: 2024-10-30 +_build: + list: never +--- + +{{% deprecated-in 0.120.0 %}} +Use [`Site.Config.Services.Disqus.Shortname`] instead. + +[`Site.Config.Services.Disqus.Shortname`]: /methods/site/config +{{% /deprecated-in %}} 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" }} + <ul> + {{ range .Pages }} + <li>{{ .Title }} by {{ .Params.artist }}</li> + {{ end }} + </ul> +{{ end }} +``` + +Is rendered to: + +```html +<ul> + <li>Starry Night by Vincent van Gogh</li> + <li>The Mona Lisa by Leonardo da Vinci</li> +</ul> +``` + +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" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +``` + +[page bundle]: /getting-started/glossary/#page-bundle diff --git a/content/en/methods/site/GoogleAnalytics.md b/content/en/methods/site/GoogleAnalytics.md new file mode 100644 index 000000000..405cf0de5 --- /dev/null +++ b/content/en/methods/site/GoogleAnalytics.md @@ -0,0 +1,20 @@ +--- +title: GoogleAnalytics +description: Returns the Google Analytics tracking ID as defined in the site configuration. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [SITE.GoogleAnalytics] +# deprecated 2023-10-30 +expiryDate: 2024-10-30 +_build: + list: never +--- + +{{% deprecated-in 0.120.0 %}} +Use [`Site.Config.Services.GoogleAnalytics.ID`] instead. + +[`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config +{{% /deprecated-in %}} 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/IsDevelopment.md b/content/en/methods/site/IsDevelopment.md new file mode 100644 index 000000000..fdeae15fa --- /dev/null +++ b/content/en/methods/site/IsDevelopment.md @@ -0,0 +1,20 @@ +--- +title: IsDevelopment +description: Reports whether the current running environment is “development”. +categories: [] +keywords: [] +action: + related: [] + returnType: bool + signatures: [SITE.IsDevelopment] +# deprecated 2023-10-30 +expiryDate: 2024-10-30 +_build: + list: never +--- + +{{% deprecated-in 0.120.0 %}} +Use [`hugo.IsDevelopment`] instead. + +[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment +{{% /deprecated-in %}} 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/IsServer.md b/content/en/methods/site/IsServer.md new file mode 100644 index 000000000..c19a84bc9 --- /dev/null +++ b/content/en/methods/site/IsServer.md @@ -0,0 +1,20 @@ +--- +title: IsServer +description: Reports whether the built-in development server is running. +categories: [] +keywords: [] +action: + related: [] + returnType: bool + signatures: [SITE.IsServer] +# deprecated 2023-10-30 +expiryDate: 2024-10-30 +_build: + list: never +--- + +{{% deprecated-in 0.120.0 %}} +Use [`hugo.IsServer`] instead. + +[`hugo.IsServer`]: /functions/hugo/isserver +{{% /deprecated-in %}} 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 +<html + lang="{{ or site.Language.LanguageCode site.Language.Lang }}" + dir="{{ or site.Language.LanguageDirection `ltr` }} +> +``` + +The example above uses the global [`site`] function instead of accessing the `Site` object via the `.Site` notation. + +Also note that each attribute has a fallback value assigned via the [`or`] operator. + +[details]: /methods/page/language +[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 +[`or`]: /functions/go-template/or +[`site`]: /functions/global/site diff --git a/content/en/methods/site/LanguagePrefix.md b/content/en/methods/site/LanguagePrefix.md new file mode 100644 index 000000000..88808eda0 --- /dev/null +++ b/content/en/methods/site/LanguagePrefix.md @@ -0,0 +1,53 @@ +--- +title: LanguagePrefix +description: Returns the URL language prefix, if any, for the given site. +categories: [] +keywords: [] +action: + related: + - functions/urls/AbsLangURL + - functions/urls/RelLangURL + returnType: string + signatures: [SITE.LanguagePrefix] +--- + +Consider 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 >}} + +When visiting the German language site: + +```go-html-template +{{ .Site.LanguagePrefix }} → "" +``` + +When visiting the English language site: + +```go-html-template +{{ .Site.LanguagePrefix }} → /en +``` + +If you change `defaultContentLanguageInSubdir` to `true`, when visiting the German language site: + +```go-html-template +{{ .Site.LanguagePrefix }} → /de +``` + +You may use the `LanguagePrefix` method with both monolingual and multilingual sites. diff --git a/content/en/methods/site/Languages.md b/content/en/methods/site/Languages.md new file mode 100644 index 000000000..26bdefc21 --- /dev/null +++ b/content/en/methods/site/Languages.md @@ -0,0 +1,59 @@ +--- +title: Languages +description: Returns a collection of language objects for all sites, ordered by language weight. +categories: [] +keywords: [] +action: + related: + - methods/site/Language + returnType: langs.Languages + signatures: [SITE.Languages] +--- + +The `Languages` method on a `Site` object returns a collection of language objects for all sites, ordered by language weight. Each language object points to its language definition in the site configuration. + +To view the data structure: + +```go-html-template +<pre>{{ jsonify (dict "indent" " ") .Site.Languages }}</pre> +``` + +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 +<ul> + {{ range .Site.Languages }} + <li>{{ .Title }} ({{ .LanguageName }})</li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li>Projekt Dokumentation (Deutsch)</li> + <li>Project Documentation (English)</li> +</ul> +``` 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ 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 }} + <nav class="menu"> + {{ range . }} + {{ if $.IsMenuCurrent .Menu . }} + <a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a> + {{ else }} + <a href="{{ .URL }}">{{ .Name }}</a> + {{ end }} + {{ end }} + </nav> +{{ end }} +``` + +When viewing the home page, the result is: + +```html +<nav class="menu"> + <a class="active" aria-current="page" href="/">Home</a> + <a href="/books/">Books</a> + <a href="/films/">Films</a> +</nav> +``` + +When viewing the "books" page, the result is: + +```html +<nav class="menu"> + <a href="/">Home</a> + <a class="active" aria-current="page" href="/books/">Books</a> + <a href="/films/">Films</a> +</nav> +``` + +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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` diff --git a/content/en/methods/site/Param.md b/content/en/methods/site/Param.md new file mode 100644 index 000000000..b699ef2d4 --- /dev/null +++ b/content/en/methods/site/Param.md @@ -0,0 +1,29 @@ +--- +title: Param +description: Returns the site parameter with the given key. +categories: [] +keywords: [] +action: + related: [] + returnType: any + signatures: [SITE.Param KEY] +--- + +The `Param` method on a `Site` object is a convenience method to return the value of a user-defined parameter in the site configuration. + +{{< code-toggle file=hugo >}} +[params] +display_toc = true +{{< /code-toggle >}} + + +```go-html-template +{{ .Site.Param "display_toc" }} → true +``` + +The above is equivalent to either of these: + +```go-html-template +{{ .Site.Params.display_toc }} +{{ index .Site.Params "display_toc" }} +``` 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 = '[email protected]' + 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..b163ad919 --- /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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> +{{ 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 }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +Is rendered to: + +```html +<h2><a href="/books/">Books</a></h2> +<h2><a href="/films/">Films</a></h2> +``` 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 +<ul> + {{ range .Site.Sites }} + <li><a href="{{ .Home.Permalink }}">{{ .Title }}</a></li> + {{ end }} +</ul> +``` + +Produces a list of links to each home page: + +```html +<ul> + <li><a href="https://example.org/de/">Projekt Dokumentation</a></li> + <li><a href="https://example.org/en/">Project Documentation</a></li> +</ul> +``` + +To render a link to home page of the primary (first) language: + +```go-html-template +{{ with .Site.Sites.First }} + <a href="{{ .Home.Permalink }}">{{ .Title }}</a> +{{ end }} +``` + +This is equivalent to: + +```go-html-template +{{ with index .Site.Sites 0 }} + <a href="{{ .Home.Permalink }}">{{ .Title }}</a> +{{ 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 +<ul> + {{ range .Site.Taxonomies.genres.suspense }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Hugo renders this to: + +```html +<ul> + <li><a href="/books/and-then-there-were-none/">And Then There Were None</a></li> + <li><a href="/books/death-on-the-nile/">Death on the Nile</a></li> + <li><a href="/books/jamaica-inn/">Jamaica Inn</a></li> +</ul> +``` + +{{% 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..7845dbf3d --- /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 +<pre>{{ jsonify (dict "indent" " ") $taxonomyObject.Alphabetical }}</pre> +``` + +{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}} + +## Example + +With this template: + +```go-html-template +{{ range $taxonomyObject.Alphabetical }} + <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2> + <ul> + {{ range .Pages.ByTitle }} + <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + {{ end }} + </ul> +{{ end }} +``` + +Hugo renders: + +```html +<h2><a href="/genres/romance/">romance</a> (2)</h2> +<ul> + <li><a href="/books/jamaica-inn/">Jamaica inn</a></li> + <li><a href="/books/pride-and-prejudice/">Pride and prejudice</a></li> +</ul> +<h2><a href="/genres/suspense/">suspense</a> (3)</h2> +<ul> + <li><a href="/books/and-then-there-were-none/">And then there were none</a></li> + <li><a href="/books/death-on-the-nile/">Death on the nile</a></li> + <li><a href="/books/jamaica-inn/">Jamaica inn</a></li> +</ul> +``` + +[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..40f58420a --- /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 +<pre>{{ jsonify (dict "indent" " ") $taxonomyObject.ByCount }}</pre> +``` + +{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}} + +## Example + +With this template: + +```go-html-template +{{ range $taxonomyObject.ByCount }} + <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2> + <ul> + {{ range .Pages.ByTitle }} + <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + {{ end }} + </ul> +{{ end }} +``` + +Hugo renders: + +```html +<h2><a href="/genres/suspense/">suspense</a> (3)</h2> +<ul> + <li><a href="/books/and-then-there-were-none/">And then there were none</a></li> + <li><a href="/books/death-on-the-nile/">Death on the nile</a></li> + <li><a href="/books/jamaica-inn/">Jamaica inn</a></li> +</ul> +<h2><a href="/genres/romance/">romance</a> (2)</h2> +<ul> + <li><a href="/books/jamaica-inn/">Jamaica inn</a></li> + <li><a href="/books/pride-and-prejudice/">Pride and prejudice</a></li> +</ul> +``` + +[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 +<pre>{{ jsonify (dict "indent" " ") $weightedPages }}</pre> +``` + +## Example + +With this template: + +```go-html-template +{{ $weightedPages := $taxonomyObject.Get "suspense" }} +{{ range $weightedPages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +``` + +Hugo renders: + +```html +<h2><a href="/books/jamaica-inn/">Jamaica inn</a></h2> +<h2><a href="/books/death-on-the-nile/">Death on the nile</a></h2> +<h2><a href="/books/and-then-there-were-none/">And then there were none</a></h2> +``` + +[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 +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/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..4c4fc42c9 --- /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 >}} +{{ $taxonomyObject := .Data.Terms }} +{{< /code >}} + +To inspect the data structure: + +```go-html-template +<pre>{{ jsonify (dict "indent" " ") $taxonomyObject }}</pre> +``` + +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 }} + <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a></h2> + <ul> + {{ range $weightedPages }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ 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 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 index e679cb2c4..fc3e2635c 100644 --- a/content/en/functions/Format.md +++ b/content/en/methods/time/Format.md @@ -1,17 +1,18 @@ --- -title: .Format -description: Returns a formatted time.Time value. -categories: [functions] +title: Format +description: Returns a textual representation of the time.Time value formatted according to the layout string. +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 @@ -23,12 +24,13 @@ toc: true ``` {{% note %}} -To return a formatted and localized `time.Time` value, use the [`time.Format`] function instead. +To [localize] the return value, use the [`time.Format`] function instead. +[localize]: /getting-started/glossary/#localization [`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" }} @@ -39,15 +41,21 @@ Use the `.Format` method with any `time.Time` value, including the four predefin {{ .Lastmod.Format $format }} ``` +{{% note %}} +Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset. + +[`time.Format`]: /functions/time/format +{{% /note %}} + ## 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..0a01d1a70 --- /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..b2a95fe9c --- /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/news/_index.md b/content/en/news/_index.md index 353accc3d..e37c33a3c 100644 --- a/content/en/news/_index.md +++ b/content/en/news/_index.md @@ -1,4 +1,4 @@ --- -title: "Hugo News" +title: Hugo News aliases: [/release-notes/] --- diff --git a/content/en/quick-reference/_index.md b/content/en/quick-reference/_index.md new file mode 100644 index 000000000..492cfa09b --- /dev/null +++ b/content/en/quick-reference/_index.md @@ -0,0 +1,16 @@ +--- +title: Quick reference guides +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..e6b1ed415 --- /dev/null +++ b/content/en/quick-reference/emojis.md @@ -0,0 +1,1624 @@ +--- +title: Emojis +description: Include emoji shortcodes in your markdown or templates. +categories: [quick reference] +keywords: [emoji] +menu: + docs: + parent: quick-reference + weight: 20 +weight: 20 +toc: true +--- + +Configure Hugo to enable emoji processing in markdown: + +{{< code-toggle file=hugo >}} +enableEmoji = true +{{< /code-toggle >}} + +With emoji processing enabled, this markdown: + +```md +Hello! :wave: +``` + +Is rendered to: + +```html +Hello! 👋 +``` + +And in your browser... Hello! :wave: + +To process an emoji shortcode from within a template, use the [`emojify`] function or pass the string through the [`RenderString`] method on a `Page` object: + +```go-html-template +{{ "Hello! :wave:" | .RenderString }} +``` + +[`emojify`]: /functions/transform/emojify +[`RenderString`]: /methods/page/renderstring + +## 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..42eafedd3 --- /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: [quick reference] +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..abd1db709 --- /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: [quick reference] +keywords: [] +menu: + docs: + parent: quick-reference + weight: 40 +weight: 40 +toc: true +--- + +{{% quick-reference section="methods" %}} diff --git a/content/en/quick-reference/page-collections.md b/content/en/quick-reference/page-collections.md new file mode 100644 index 000000000..795eb494d --- /dev/null +++ b/content/en/quick-reference/page-collections.md @@ -0,0 +1,46 @@ +--- +title: Page collections +description: A quick reference guide to Hugo's page collections. +categories: [quick reference] +keywords: [] +menu: + docs: + parent: quick-reference + weight: 50 +weight: 50 +toc: true +--- + +## Page + +Use these `Page` methods when rendering lists on [section] pages, [taxonomy] pages, [term] pages, and the home page. + +[section]: /getting-started/glossary/#section +[taxonomy]: /getting-started/glossary/#taxonomy +[term]: /getting-started/glossary/#term + +{{< list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include omitElementIDs=true titlePrefix=PAGE. >}} + +## Site + +Use these `Site` methods when rendering lists on any page. + +{{< list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include omitElementIDs=true titlePrefix=SITE. >}} + +## Filter + +Use the [`where`] function to filter page collections. + +[`where`]: /functions/collections/where + +## Sort + +Use these methods to sort page collections. + +{{< list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. omitElementIDs=true titlePrefix=PAGES. >}} + +## Group + +Use these methods to group page collections. + +{{< list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. omitElementIDs=true titlePrefix=PAGES. >}} 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..559169319 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 tool belt 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..2daafbbe1 100644 --- a/content/en/showcase/ampio-help/index.md +++ b/content/en/showcase/ampio-help/index.md @@ -33,7 +33,7 @@ The turning point was the introduction of a new key requirement---each document On top of that new development, we had to remember another one of our key requirements, namely, that mostly non-programmers were to be responsible for the service maintenance and content creation. Initially, we were leaning towards headless CMS-based solutions, but finally we made a bold move and decided to create a Git-managed Jamstack service and see what happens. -## Hugo to the rescue! +## Hugo to the rescue Hugo was our first choice of SSG. The multilingualism support was the primary feature that convinced us. Later on, going through the documentation, we continued to discover new exciting features that we didn't even know we needed when we started. @@ -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 [[email protected]](mailto:[email protected]) :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/hartwell-insurance/index.md b/content/en/showcase/hartwell-insurance/index.md index 66fc46f44..ef0587e41 100644 --- a/content/en/showcase/hartwell-insurance/index.md +++ b/content/en/showcase/hartwell-insurance/index.md @@ -62,7 +62,7 @@ The most encouraging result is how quick the site is around the world. Most Toma --- -This project was such a blast to develop, it’s a real pleasure to put new technologies to good use in production, and to see real performance and usability benefits from them. Even using classic web methods of serving folders with files is fun when you’ve been databasing for a while – there’s something really ‘pure’ about it. +This project was such a blast to develop, it’s a real pleasure to put new technologies to good use in production, and to see real performance and usability benefits from them. Even using classic web methods of serving folders with files is fun when you’ve been using dynamic systems for a while – there’s something really pure about it. --- 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..d324833c9 100644 --- a/content/en/showcase/pharmaseal/index.md +++ b/content/en/showcase/pharmaseal/index.md @@ -11,20 +11,18 @@ 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: **Make it fast** -We wanted to optimise the site as much as possible, so we opted for using Cloudinary, enabling us to take advantage of on-the-fly image manipulation, and thanks to the sheer speed of static sites, we achieved a perfect optimisation score with Google audits. +We wanted to optimize the site as much as possible, so we opted for using Cloudinary, enabling us to take advantage of on-the-fly image manipulation, and thanks to the sheer speed of static sites, we achieved a perfect optimization score with Google audits. Because we're hosting the site through Netlify and our target audience is in America, we are taking advantage of Netlify edge (Their alternative to a CDN). We're talking blazing fast. @@ -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/404.md b/content/en/templates/404.md index 3650d5a07..7fd27a358 100644 --- a/content/en/templates/404.md +++ b/content/en/templates/404.md @@ -3,7 +3,7 @@ title: Custom 404 page linkTitle: 404 page description: If you know how to create a single page template, you have unlimited options for creating a custom 404. categories: [templates] -keywords: [404, page not found] +keywords: ['404',page not found] menu: docs: parent: templates @@ -26,7 +26,7 @@ In addition to the standard page variables, the 404 page has access to all site This is a basic example of a 404.html template: -{{< code file="layouts/404.html" >}} +{{< code file=layouts/404.html >}} {{ define "main" }} <main id="main"> <div> diff --git a/content/en/templates/_index.md b/content/en/templates/_index.md index 30243e63c..b2197d162 100644 --- a/content/en/templates/_index.md +++ b/content/en/templates/_index.md @@ -2,14 +2,14 @@ title: Templates linkTitle: Overview description: Go templating, template types and lookup order, shortcodes, and data. +categories: [] +keywords: [] menu: docs: identifier: templates-overview parent: templates weight: 10 weight: 10 -categories: [templates] -keywords: [] aliases: [/templates/overview/,/templates/content] --- diff --git a/content/en/templates/base.md b/content/en/templates/base.md index ec84f1a22..63bf2f9b2 100644 --- a/content/en/templates/base.md +++ b/content/en/templates/base.md @@ -1,15 +1,15 @@ --- title: Base templates and blocks description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page). -categories: [fundamentals,templates] +categories: [templates,fundamentals] keywords: [blocks,base] menu: docs: parent: templates weight: 40 weight: 40 -aliases: [/templates/blocks/,/templates/base-templates-and-blocks/] toc: true +aliases: [/templates/blocks/,/templates/base-templates-and-blocks/] --- The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary. @@ -26,7 +26,7 @@ See [Template Lookup Order](/templates/lookup-order/) for details and examples. The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order. -{{< code file="layouts/_default/baseof.html" >}} +{{< code file=layouts/_default/baseof.html >}} <!DOCTYPE html> <html> <head> @@ -52,7 +52,7 @@ The following defines a simple base template at `_default/baseof.html`. As a def From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from: -{{< code file="layouts/_default/list.html" >}} +{{< code file=layouts/_default/list.html >}} {{ define "main" }} <h1>Posts</h1> {{ range .Pages }} @@ -80,7 +80,7 @@ Code that you put outside the block definitions *can* break your layout. This ev The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]: -{{< code file="layouts/_default/single.html" >}} +{{< code file=layouts/_default/single.html >}} {{ define "title" }} <!-- This will override the default value set in baseof.html; i.e., "{{ .Site.Title }}" in the original example--> {{ .Title }} – {{ .Site.Title }} diff --git a/content/en/templates/data-templates.md b/content/en/templates/data-templates.md index cf835af44..b862f727e 100644 --- a/content/en/templates/data-templates.md +++ b/content/en/templates/data-templates.md @@ -8,24 +8,22 @@ menu: parent: templates weight: 150 weight: 150 -aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/] toc: true +aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/] --- -<!-- begin data files --> - 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. @@ -69,7 +69,7 @@ The example below is a bit contrived, but it illustrates the flexibility of data `jacopastorius.toml` contains the content below. `johnpatitucci.toml` contains a similar list: -{{< code-toggle file="jacopastorius" >}} +{{< code-toggle file=data/jazz/bass/jacopastorius >}} discography = [ "1974 - Modern American Music … Period! The Criteria Sessions", "1974 - Jaco", @@ -95,7 +95,7 @@ You can now render the list of recordings for all the bass players in a template ```go-html-template {{ range $.Site.Data.jazz.bass }} - {{ partial "artist.html" . }} + {{ partial "artist.html" . }} {{ end }} ``` @@ -111,11 +111,11 @@ 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/`: +Assume you have the following data structure in your `user0123` data file located directly in `data/`: -{{< code-toggle file="User0123" >}} +{{< code-toggle file=data/user0123 >}} Name: User0123 "Short Description": "He is a **jolly good** fellow." Achievements: @@ -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 - -Use `getJSON` or `getCSV` to get remote data: - -```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.: +## Remote data -```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" >}} - <table> - <thead> - <tr> - <th>Name</th> - <th>Position</th> - <th>Salary</th> - </tr> - </thead> - <tbody> - {{ $url := "https://example.com/finance/employee-salaries.csv" }} - {{ $sep := "," }} - {{ range $i, $r := getCSV $sep $url }} - <tr> - <td>{{ index $r 0 }}</td> - <td>{{ index $r 1 }}</td> - <td>{{ index $r 2 }}</td> - </tr> - {{ end }} - </tbody> - </table> -{{< /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. +Retrieve remote data using these template functions: -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/<THEME>/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/files.md b/content/en/templates/files.md index 2e82688c0..1847af9bc 100644 --- a/content/en/templates/files.md +++ b/content/en/templates/files.md @@ -8,8 +8,8 @@ menu: parent: templates weight: 180 weight: 180 -aliases: [/extras/localfiles/,/templates/local-files/] toc: true +aliases: [/extras/localfiles/,/templates/local-files/] --- ## Traverse local files diff --git a/content/en/templates/homepage.md b/content/en/templates/homepage.md index a176a51f2..59b7472fb 100644 --- a/content/en/templates/homepage.md +++ b/content/en/templates/homepage.md @@ -8,8 +8,8 @@ menu: parent: templates weight: 70 weight: 70 -aliases: [/layout/homepage/,/templates/homepage-template/] toc: true +aliases: [/layout/homepage/,/templates/homepage-template/] --- Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use. @@ -34,7 +34,7 @@ See the homepage template below or [Content Organization][contentorg] for more i The following is an example of a homepage template that uses [partial][partials], [base] templates, and a content file at `content/_index.md` to populate the `{{ .Title }}` and `{{ .Content }}` [page variables][pagevars]. -{{< code file="layouts/index.html" >}} +{{< code file=layouts/index.html >}} {{ define "main" }} <main aria-role="main"> <header class="homepage-header"> diff --git a/content/en/templates/internal.md b/content/en/templates/internal.md index cdac50478..2e73455f0 100644 --- a/content/en/templates/internal.md +++ b/content/en/templates/internal.md @@ -10,8 +10,6 @@ menu: weight: 190 toc: true --- -<!-- reference: https://discourse.gohugo.io/t/lookup-order-for-partials/5705/6 -code: https://github.com/gohugoio/hugo/blob/e445c35d6a0c7f5fc2f90f31226cd1d46e048bbc/tpl/template_embedded.go#L147 --> {{% note %}} While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order. @@ -19,20 +17,17 @@ While the following internal templates are called similar to partials, they do * ## Google Analytics -Hugo ships with an internal template supporting [Google Analytics 4][GA4] (GA4). +Hugo ships with an internal template supporting [Google Analytics 4]. -**Note:** Universal Analytics are [deprecated]. - -[GA4]: https://support.google.com/analytics/answer/10089681 -[deprecated]: https://support.google.com/analytics/answer/11583528 +[Google Analytics 4]: https://support.google.com/analytics/answer/10089681 ### Configure Google Analytics Provide your tracking ID in your configuration file: -**Google Analytics 4 (gtag.js)** -{{< code-toggle file="hugo" >}} -googleAnalytics = "G-MEASUREMENT_ID" +{{< code-toggle file=hugo >}} +[services.googleAnalytics] +ID = "G-MEASUREMENT_ID" {{</ code-toggle >}} ### Use the Google Analytics template @@ -53,10 +48,17 @@ 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" >}} -disqusShortname = "your-disqus-shortname" +{{< code-toggle file=hugo >}} +[services.disqus] +shortname = 'your-disqus-shortname' {{</ code-toggle >}} +Hugo's Disqus template accesses this value with: + +```go-html-template +{{ .Site.Config.Services.Disqus.Shortname }} +``` + You can also set the following in the front matter for a given piece of content: * `disqus_identifier` @@ -71,15 +73,13 @@ To add Disqus, include the following line in the templates where you want your c {{ template "_internal/disqus.html" . }} ``` -A `.Site.DisqusShortname` variable is also exposed from the configuration. - ### Conditional loading of Disqus comments Users have noticed that enabling Disqus comments when running the Hugo web server on `localhost` (i.e. via `hugo server`) causes the creation of unwanted discussions on the associated Disqus account. You can create the following `layouts/partials/disqus.html`: -{{< code file="layouts/partials/disqus.html" >}} +{{< code file=layouts/partials/disqus.html >}} <div id="disqus_thread"></div> <script type="text/javascript"> @@ -90,7 +90,7 @@ You can create the following `layouts/partials/disqus.html`: return; var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; - var disqus_shortname = '{{ .Site.DisqusShortname }}'; + var disqus_shortname = '{{ .Site.Config.Services.Disqus.Shortname }}'; dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js'; (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); })(); @@ -116,7 +116,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"] @@ -125,7 +125,7 @@ Hugo's Open Graph template is configured using a mix of configuration variables series = "series" {{</ code-toggle >}} -{{< code-toggle file="content/blog/my-post" >}} +{{< code-toggle file=content/blog/my-post.md >}} title = "Post title" description = "Text about this post" date = "2006-01-02" @@ -166,13 +166,13 @@ 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" {{</ code-toggle >}} -{{< code-toggle file="content/blog/my-post" >}} +{{< code-toggle file=content/blog/my-post.md >}} title = "Post title" description = "Text about this post" images = ["post-cover.png"] @@ -184,11 +184,11 @@ If no images are found at all, then an image-less Twitter `summary` card is used Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given. -The `.Site.Social.twitter` variable is exposed from the configuration as the value for `twitter:site`. +Set the value of `twitter:site` in your site configuration: -{{< code-toggle file="hugo" >}} -[social] - twitter = "GoHugoIO" +{{< code-toggle file=hugo >}} +[params.social] +twitter = "GoHugoIO" {{</ code-toggle >}} NOTE: The `@` will be added for you diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md index 2eb436f82..7fb0ddecf 100644 --- a/content/en/templates/introduction.md +++ b/content/en/templates/introduction.md @@ -2,15 +2,15 @@ title: Templating linkTitle: Templating description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. -categories: [fundamentals,templates] +categories: [templates,fundamentals] keywords: [go] menu: docs: parent: templates weight: 20 weight: 20 -aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/] toc: true +aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/] --- {{% note %}} @@ -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 }} @@ -80,7 +79,7 @@ Line two.` }} ## Variables Each Go Template gets a data object. In Hugo, each template is passed -a `Page`. In the below example, `.Title` is one of the elements +a `Page`. In the below example, `.Title` is one of the elements accessible in that [`Page` variable][pagevars]. With the `Page` being the default scope of a template, the `Title` @@ -216,7 +215,7 @@ element's index. ```go-html-template {{ range $elem_index, $elem_val := $array }} - {{ $elem_index }} -- {{ $elem_val }} + {{ $elem_index }} -- {{ $elem_val }} {{ end }} ``` @@ -227,7 +226,7 @@ key. ```go-html-template {{ range $elem_key, $elem_val := $map }} - {{ $elem_key }} -- {{ $elem_val }} + {{ $elem_key }} -- {{ $elem_val }} {{ end }} ``` @@ -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 }} ``` @@ -398,7 +395,7 @@ following: The following shows how to define a variable independent of the context. -{{< code file="tags-range-with-page-variable.html" >}} +{{< code file=tags-range-with-page-variable.html >}} {{ $title := .Site.Title }} <ul> {{ range .Params.tags }} @@ -418,7 +415,7 @@ Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` `$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context: -{{< code file="range-through-tags-w-global.html" >}} +{{< code file=range-through-tags-w-global.html >}} <ul> {{ range .Params.tags }} <li> @@ -429,7 +426,7 @@ Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` </ul> {{< /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 %}} @@ -469,9 +466,9 @@ Which then outputs: Go considers the following characters _whitespace_: -* <kbd>space</kbd> -* horizontal <kbd>tab</kbd> -* carriage <kbd>return</kbd> +* space +* horizontal tab +* carriage return * newline ## Comments @@ -535,14 +532,14 @@ 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 >}} Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]: -{{< code file="layouts/partials/toc.html" >}} +{{< code file=layouts/partials/toc.html >}} {{ if not .Params.notoc }} <aside> <header> @@ -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" @@ -583,7 +580,7 @@ Within a footer layout, you might then declare a `<footer>` that is only rendere An alternative way of writing the "`if`" 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: -{{< code file="layouts/partials/twitter.html" >}} +{{< code file=layouts/partials/twitter.html >}} {{ with .Site.Params.twitteruser }} <div> <a href="https://twitter.com/{{ . }}" rel="author"> @@ -599,7 +596,7 @@ Finally, you can pull "magic constants" out of your layouts as well. The followi <h1>Recent Posts</h1> <ul> {{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}} - <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> {{- end -}} </ul> </nav> @@ -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 @@ -627,7 +624,7 @@ end_date = 2021-12-05T11:00:00-08:00 This [partial template][partials] renders future events: -{{< code file="layouts/partials/future-events.html" >}} +{{< code file=layouts/partials/future-events.html >}} <h2>Future Events</h2> <ul> {{ range where site.RegularPages "Type" "events" }} @@ -643,7 +640,7 @@ This [partial template][partials] renders future events: If you restrict front matter to the TOML format, and omit quotation marks surrounding date fields, you can perform date comparisons without casting. -{{< code file="layouts/partials/future-events.html" >}} +{{< code file=layouts/partials/future-events.html >}} <h2>Future Events</h2> <ul> {{ range where (where site.RegularPages "Type" "events") "Params.start_date" "gt" now }} @@ -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..c26174974 100644 --- a/content/en/templates/lists/index.md +++ b/content/en/templates/lists/index.md @@ -9,8 +9,8 @@ menu: parent: templates weight: 60 weight: 60 -aliases: [/templates/list/,/layout/indexes/] toc: true +aliases: [/templates/list/,/layout/indexes/] --- ## What is a list page template? @@ -72,7 +72,7 @@ The following is an example of a typical Hugo project directory's content: Using the above example, let's assume you have the following in `content/posts/_index.md`: -{{< code file="content/posts/_index.md" >}} +{{< code file=content/posts/_index.md >}} --- title: My Go Journey date: 2017-03-23 @@ -86,7 +86,7 @@ Follow my journey through this new blog. You can now access this `_index.md`'s' content in your list template: -{{< code file="layouts/_default/list.html" >}} +{{< code file=layouts/_default/list.html >}} {{ define "main" }} <main> <article> @@ -100,7 +100,7 @@ You can now access this `_index.md`'s' content in your list template: <!-- Ranges through content/posts/*.md --> {{ range .Pages }} <li> - <a href="{{ .Permalink }}">{{ .Date.Format "2006-01-02" }} | {{ .Title }}</a> + <a href="{{ .RelPermalink }}">{{ .Date.Format "2006-01-02" }} | {{ .LinkTitle }}</a> </li> {{ end }} </ul> @@ -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 >}} <!--top of your baseof code--> <main> <article> @@ -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 >}} <!--baseof--> <main> <article> @@ -144,8 +144,8 @@ Using this same `layouts/_default/list.html` template and applying it to the `qu </header> </article> <ul> - <li><a href="https://example.com/quote/quotes-01/">Quote 1</a></li> - <li><a href="https://example.com/quote/quotes-02/">Quote 2</a></li> + <li><a href="https://example.org/quote/quotes-01/">Quote 1</a></li> + <li><a href="https://example.org/quote/quotes-02/">Quote 2</a></li> </ul> </main> <!--baseof--> @@ -161,7 +161,7 @@ The default behavior of Hugo is to pluralize list titles; hence the inflection o This list template has been modified slightly from a template originally used in [spf13.com](https://spf13.com/). It makes use of [partial templates][partials] for the chrome of the rendered page rather than using a [base template][base]. The examples that follow also use the [content view templates][views] `li.html` or `summary.html`. -{{< code file="layouts/section/posts.html" >}} +{{< code file=layouts/section/posts.html >}} {{ partial "header.html" . }} {{ partial "subheader.html" . }} <main> @@ -180,7 +180,7 @@ This list template has been modified slightly from a template originally used in ### Taxonomy template -{{< code file="layouts/_default/taxonomy.html" >}} +{{< code file=layouts/_default/taxonomy.html >}} {{ define "main" }} <main> <div> @@ -194,374 +194,29 @@ This list template has been modified slightly from a template originally used in {{ end }} {{< /code >}} -## Order 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: - -### Default: Weight > Date > LinkTitle > FilePath - -{{< code file="layouts/partials/default-order.html" >}} -<ul> - {{ range .Pages }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By weight - -Lower weight gets higher precedence. So content with lower weight will come first. +## Sort content -{{< code file="layouts/partials/by-weight.html" >}} -<ul> - {{ range .Pages.ByWeight }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By date - -{{< code file="layouts/partials/by-date.html" >}} -<ul> - <!-- orders content according to the "date" field in front matter --> - {{ range .Pages.ByDate }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} +By default, Hugo sorts page collections by: -### By publish date - -{{< code file="layouts/partials/by-publish-date.html" >}} -<ul> - <!-- orders content according to the "publishdate" field in front matter --> - {{ range .Pages.ByPublishDate }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} +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 -### By expiration date - -{{< code file="layouts/partials/by-expiry-date.html" >}} -<ul> - {{ range .Pages.ByExpiryDate }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} +[date]: /methods/page/date +[weight]: /methods/page/weight +[linkTitle]: /methods/page/linktitle +[title]: /methods/page/title -### By last modified date - -{{< code file="layouts/partials/by-last-mod.html" >}} -<ul> - <!-- orders content according to the "lastmod" field in front matter --> - {{ range .Pages.ByLastmod }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} +Change the sort order using any of the methods below. -### By length - -{{< code file="layouts/partials/by-length.html" >}} -<ul> - <!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) --> - {{ range .Pages.ByLength }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By title - -{{< code file="layouts/partials/by-title.html" >}} -<ul> - <!-- ranges through content in ascending order according to the "title" field set in front matter --> - {{ range .Pages.ByTitle }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /code >}} - -### By link title - -{{< code file="layouts/partials/by-link-title.html" >}} -<ul> - <!-- ranges through content in ascending order according to the "linktitle" field in front matter. If a "linktitle" field is not set, the range will start with content that only has a "title" field and use that value for .LinkTitle --> - {{ range .Pages.ByLinkTitle }} - <li> - <h1><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /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" >}} -<!-- Ranges through content according to the "rating" field set in front matter --> -{{ 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" >}} -<ul> - {{ range .Pages.ByDate.Reverse }} - <li> - <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> - <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> - </li> - {{ end }} -</ul> -{{< /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. - -### By page field - -{{< code file="layouts/partials/by-page-field.html" >}} -<!-- Groups content according to content section. The ".Key" in this instance will be the section's title. --> -{{ range .Pages.GroupBy "Section" }} - <h3>{{ .Key }}</h3> - <ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} - </ul> -{{ 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" >}} -<!-- Groups content according to content section.--> -{{ range .Pages.GroupBy "Section" }} - <!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter --> - {{ with $.Site.GetPage "section" .Key }} - <h3>{{ .Title }}</h3> - {{ else }} - <!-- If no _index.md is available, ".Key" defaults to the section title and filters to title casing --> - <h3>{{ .Key | title }}</h3> - {{ end }} - <ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} - </ul> -{{ end }} -{{< /code >}} - -### By date +Group your content by field, parameter, or date using any of the methods below. -{{< code file="layouts/partials/by-page-date.html" >}} -<!-- Groups content by month according to the "date" field in front matter --> -{{ range .Pages.GroupByDate "2006-01" }} - <h3>{{ .Key }}</h3> - <ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} - </ul> -{{ 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" >}} -<!-- Groups content by month according to the "publishDate" field in front matter --> -{{ range .Pages.GroupByPublishDate "2006-01" }} - <h3>{{ .Key }}</h3> - <ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} - </ul> -{{ 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" >}} -<!-- Groups content by month according to the "expiryDate" field in front matter --> -{{ range .Pages.GroupByExpiryDate "2006-01" }} - <h3>{{ .Key }}</h3> - <ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} - </ul> -{{ 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" >}} -<!-- Groups content by month according to the "lastMod" field in front matter --> -{{ range .Pages.GroupByLastmod "2006-01" }} - <h3>{{ .Key }}</h3> - <ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Lastmod.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} - </ul> -{{ 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" >}} -<!-- Groups content according to the "param_key" field in front matter --> -{{ range .Pages.GroupByParam "param_key" }} - <h3>{{ .Key }}</h3> - <ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} - </ul> - {{ 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" >}} -<!-- Groups content by month according to the "param_key" field in front matter --> -{{ range .Pages.GroupByParamDate "param_key" "2006-01" }} - <h3>{{ .Key }}</h3> - <ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} - </ul> -{{ 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" }} - <h3>{{ .Key }}</h3> - <ul> - {{ range .Pages.ByTitle }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> - </li> - {{ end }} - </ul> -{{ 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/ -[main sections]: /functions/collections/where#mainsections +[`first`]: /functions/collections/first/ +[main sections]: /methods/site/mainsections [`time.Format`]: /functions/time/format diff --git a/content/en/templates/lookup-order.md b/content/en/templates/lookup-order.md index c36956cb9..2a24c03ac 100644 --- a/content/en/templates/lookup-order.md +++ b/content/en/templates/lookup-order.md @@ -1,7 +1,7 @@ --- title: Template lookup order description: Hugo uses the rules below to select a template for a given page, starting from the most specific. -categories: [fundamentals,templates] +categories: [templates,fundamentals] keywords: [templates] menu: docs: @@ -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..8dab65abf 100644 --- a/content/en/templates/menu-templates.md +++ b/content/en/templates/menu-templates.md @@ -7,8 +7,8 @@ menu: docs: parent: templates weight: 140 -toc: true weight: 140 +toc: true aliases: [/templates/menus/] --- @@ -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 }} @@ -75,7 +75,7 @@ This partial template recursively "walks" a menu structure, rendering a localize Call the partial above, passing a menu ID and the current page in context. -{{< code file="layouts/_default/single.html" >}} +{{< code file=layouts/_default/single.html >}} {{ partial "menu.html" (dict "menuID" "main" "page" .) }} {{ partial "menu.html" (dict "menuID" "footer" "page" .) }} {{< /code >}} @@ -86,7 +86,7 @@ Regardless of how you [define menu entries], an entry associated with a page has This simplistic example renders a page parameter named `version` next to each entry's `name`. Code defensively using `with` or `if` to handle entries where (a) the entry points to an external resource, or (b) the `version` parameter is not defined. -{{< code file="layouts/_default/single.html" >}} +{{< code file=layouts/_default/single.html >}} {{- range site.Menus.main }} <a href="{{ .URL }}"> {{ .Name }} @@ -108,7 +108,7 @@ When you define menu entries [in site configuration] or [in front matter], you c This simplistic example renders a `class` attribute for each anchor element. Code defensively using `with` or `if` to handle entries where `params.class` is not defined. -{{< code file="layouts/partials/menu.html" >}} +{{< code file=layouts/partials/menu.html >}} {{- range site.Menus.main }} <a {{ with .Params.class -}} class="{{ . }}" {{ end -}} href="{{ .URL }}"> {{ .Name }} @@ -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..23a420882 100644 --- a/content/en/templates/output-formats.md +++ b/content/en/templates/output-formats.md @@ -1,15 +1,15 @@ --- title: Custom output formats description: Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format. -categories: [fundamentals,templates] +categories: [templates,fundamentals] keywords: ["amp", "outputs", "rss"] menu: docs: parent: templates weight: 210 weight: 210 -aliases: [/templates/outputs/,/extras/output-formats/,/content-management/custom-outputs/] toc: true +aliases: [/templates/outputs/,/extras/output-formats/,/content-management/custom-outputs/] --- This page describes how to properly configure your site with the media types and output formats, as well as where to create your templates for your custom outputs. @@ -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"] @@ -53,7 +53,9 @@ The above example adds one new media type, `text/enriched`, and changes the suff mediaType = "text/html" {{</ code-toggle >}} -**Note** that for the above to work, you also need to add an `outputs` definition in your site configuration. +{{% note %}} +For the above to work, you also need to add an `outputs` definition in your site configuration. +{{% /note %}} ## Output format definitions @@ -69,7 +71,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" @@ -83,40 +85,40 @@ The above example is fictional, but if used for the homepage on a site with `bas The following is the full list of configuration options for output formats and their default values: -`name` +name : the output format identifier. This is used to define what output format(s) you want for your pages. -`mediaType` +mediaType : this must match the `Type` of a defined media type. -`path` +path : sub path to save the output files. -`baseName` +baseName : the base file name for the list file names (homepage, etc.). **Default:** `index`. -`rel` +rel : can be used to create `rel` values in `link` tags. **Default:** `alternate`. -`protocol` +protocol : will replace the "http://" or "https://" in your `baseURL` for this output format. -`isPlainText` +isPlainText : use Go's plain text templates parser for the templates. **Default:** `false`. -`isHTML` +isHTML : used in situations only relevant for `HTML`-type formats; e.g., page aliases. **Default:** `false`. -`noUgly` +noUgly : used to turn off ugly URLs If `uglyURLs` is set to `true` in your site. **Default:** `false`. -`notAlternative` +notAlternative : enable if it doesn't make sense to include this format in an `AlternativeOutputFormats` format listing on `Page` (e.g., with `CSS`). Note that we use the term _alternative_ and not _alternate_ here, as it does not necessarily replace the other format. **Default:** `false`. -`permalinkable` +permalinkable : make `.Permalink` and `.RelPermalink` return the rendering Output Format rather than main ([see below](#link-to-output-formats)). This is enabled by default for `HTML` and `AMP`. **Default:** `false`. -`weight` +weight : Setting this to a non-zero value will be used as the first sort criteria. ## Output formats for pages @@ -129,7 +131,7 @@ system. Every `Page` has a [`Kind`][page_kinds] attribute, and the default Output Formats are set based on that. -{{< code-toggle config="outputs" />}} +{{< code-toggle config=outputs />}} ### Customizing output formats @@ -139,7 +141,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 +155,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/pagination.md b/content/en/templates/pagination.md index 6cd7f7435..0854a6844 100644 --- a/content/en/templates/pagination.md +++ b/content/en/templates/pagination.md @@ -8,8 +8,8 @@ menu: parent: templates weight: 100 weight: 100 -aliases: [/extras/pagination,/doc/pagination/] toc: true +aliases: [/extras/pagination,/doc/pagination/] --- The real power of Hugo pagination shines when combined with the [`where`] function and its SQL-like operators: [`first`], [`last`], and [`after`]. You can even [order the content][lists] the way you've become used to with Hugo. @@ -18,10 +18,10 @@ The real power of Hugo pagination shines when combined with the [`where`] functi Pagination can be configured in your [site configuration][configuration]: -`paginate` +paginate : default = `10`. This setting can be overridden within the template. -`paginatePath` +paginatePath : default = `page`. Allows you to set a different path for your pagination pages. Setting `paginate` to a positive value will split the list pages for the homepage, sections and taxonomies into chunks of that size. But note that the generation of the pagination pages for sections, taxonomies and homepage is *lazy* --- the pages will not be created if not referenced by a `.Paginator` (see below). @@ -78,7 +78,7 @@ The following example shows how to create `.Paginator` before its used: {{ $paginator := .Paginate (where .Pages "Type" "posts") }} {{ template "_internal/pagination.html" . }} {{ range $paginator.Pages }} - {{ .Title }} + {{ .Title }} {{ end }} ``` @@ -87,52 +87,52 @@ Without the `where` filter, the above example is even simpler: ```go-html-template {{ template "_internal/pagination.html" . }} {{ range .Paginator.Pages }} - {{ .Title }} + {{ .Title }} {{ end }} ``` If you want to build custom navigation, you can do so using the `.Paginator` object, which includes the following properties: -`PageNumber` +PageNumber : The current page's number in the pager sequence -`URL` +URL : The relative URL to the current pager -`Pages` +Pages : The pages in the current pager -`NumberOfElements` +NumberOfElements : The number of elements on this page -`HasPrev` +HasPrev : Whether there are page(s) before the current -`Prev` +Prev : The pager for the previous page -`HasNext` +HasNext : Whether there are page(s) after the current -`Next` +Next : The pager for the next page -`First` +First : The pager for the first page -`Last` +Last : The pager for the last page -`Pagers` +Pagers : A list of pagers that can be used to build a pagination menu -`PageSize` +PageSize : Size of each pager -`TotalPages` +TotalPages : The number of pages in the paginator -`TotalNumberOfElements` +TotalNumberOfElements : The number of elements on all pages in this paginator ## Additional information diff --git a/content/en/templates/partials.md b/content/en/templates/partials.md index 97cf93f71..35ba2ee9e 100644 --- a/content/en/templates/partials.md +++ b/content/en/templates/partials.md @@ -8,8 +8,8 @@ menu: parent: templates weight: 120 weight: 120 -aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/] toc: true +aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/] --- {{< youtube pjS4pOLyB7c >}} @@ -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 @@ -136,7 +136,7 @@ The `partialCached` template function provides significant performance gains for The following `header.html` partial template is used for [spf13.com](https://spf13.com/): -{{< code file="layouts/partials/header.html" >}} +{{< code file=layouts/partials/header.html >}} <!DOCTYPE html> <html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#"> <head> @@ -161,7 +161,7 @@ The `header.html` example partial was built before the introduction of block tem The following `footer.html` partial template is used for [spf13.com](https://spf13.com/): -{{< code file="layouts/partials/footer.html" >}} +{{< code file=layouts/partials/footer.html >}} <footer> <div> <p> diff --git a/content/en/templates/render-hooks.md b/content/en/templates/render-hooks.md index 13106b7f7..8e174bdee 100644 --- a/content/en/templates/render-hooks.md +++ b/content/en/templates/render-hooks.md @@ -23,7 +23,7 @@ The hook kinds currently supported are: * `image` * `link` * `heading` -* `codeblock`{{< new-in "0.93.0" >}} +* `codeblock`{{< new-in 0.93.0 >}} You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this: @@ -91,13 +91,12 @@ Attributes (map) The `render-image` templates will also receive: -IsBlock {{< new-in "0.108.0" >}} +IsBlock {{< new-in 0.108.0 >}} : Returns true if this is a standalone image and the configuration option [markup.goldmark.parser.wrapStandAloneImageWithinParagraph](/getting-started/configuration-markup/#goldmark) is disabled. -Ordinal {{< 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 @@ -106,7 +105,7 @@ Ordinal {{< new-in "0.108.0" >}} Here is a code example for how the render-link.html template could look: -{{< code file="layouts/_default/_markup/render-link.html" >}} +{{< code file=layouts/_default/_markup/render-link.html >}} <a href="{{ .Destination | safeURL }}"{{ with .Title }} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a> {{< /code >}} @@ -118,7 +117,7 @@ Here is a code example for how the render-link.html template could look: Here is a code example for how the render-image.html template could look: -{{< code file="layouts/_default/_markup/render-image.html" >}} +{{< code file=layouts/_default/_markup/render-image.html >}} <p class="md__image"> <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title }} title="{{ . }}"{{ end }} /> </p> @@ -128,7 +127,7 @@ Here is a code example for how the render-image.html template could look: Given this template file -{{< code file="layouts/_default/_markup/render-heading.html" >}} +{{< code file=layouts/_default/_markup/render-heading.html >}} <h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}> {{< /code >}} @@ -146,7 +145,7 @@ The rendered html will be ## Render hooks for code blocks -{{< new-in "0.93.0" >}} +{{< new-in 0.93.0 >}} You can add a hook template for either all code blocks or for a specific type/language (`bash` in the example below): diff --git a/content/en/templates/robots.md b/content/en/templates/robots.md index b9cdb76dd..0efd85ba2 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 >}} @@ -35,7 +35,7 @@ You may overwrite the internal template with a custom template. Hugo selects the ## robots.txt template example -{{< code file="layouts/robots.txt" >}} +{{< code file=layouts/robots.txt >}} User-agent: * {{ range .Pages }} Disallow: {{ .RelPermalink }} @@ -47,7 +47,7 @@ This template creates a robots.txt file with a `Disallow` directive for each pag {{% note %}} To create a robots.txt file without using a template: -1. Set `enableRobotsTXT` to `false` in the [site configuration]. +1. Set `enableRobotsTXT` to `false` in the site configuration. 2. Create a robots.txt file in the `static` directory. Remember that Hugo copies everything in the [static directory][static] to the root of `publishDir` (typically `public`) when you build your site. diff --git a/content/en/templates/rss.md b/content/en/templates/rss.md index 0250e8f54..9a2ce9b3c 100644 --- a/content/en/templates/rss.md +++ b/content/en/templates/rss.md @@ -1,8 +1,8 @@ --- title: RSS templates description: Use the built-in RSS template, or create your own. -keywords: [rss, xml, templates] categories: [templates] +keywords: [rss,xml,templates] menu: docs: parent: templates @@ -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,9 +40,9 @@ 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.' -[author] +[params.author] name = 'John Doe' email = '[email protected]' {{< /code-toggle >}} diff --git a/content/en/templates/section-templates.md b/content/en/templates/section-templates.md index b35009a2f..42eb12bec 100644 --- a/content/en/templates/section-templates.md +++ b/content/en/templates/section-templates.md @@ -9,8 +9,8 @@ menu: parent: templates weight: 80 weight: 80 -aliases: [/templates/sections/] toc: true +aliases: [/templates/sections/] --- ## Add content and front matter to section templates @@ -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 @@ -43,7 +43,7 @@ Examples: ## Example: creating a default section template -{{< code file="layouts/_default/section.html" >}} +{{< code file=layouts/_default/section.html >}} {{ define "main" }} <main> {{ .Content }} @@ -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..4606369b6 100644 --- a/content/en/templates/shortcode-templates.md +++ b/content/en/templates/shortcode-templates.md @@ -9,6 +9,7 @@ menu: parent: templates weight: 130 weight: 130 +aliases: [/functions/get] toc: true --- @@ -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 `{{</* myshortcode /*/>}}` 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 {{</* boxes/square */>}} @@ -117,13 +118,13 @@ Any shortcode that refers to `.Inner` must be closed or self-closed. The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic: -`$.Params` +$.Params : these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID) -`$.Page.Params` +$.Page.Params : refers to the page's parameters; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`). -`$.Page.Site.Params` +$.Page.Site.Params : refers to global variables as defined in your [site's configuration file][config]. #### `.IsNamedParams` @@ -172,7 +173,7 @@ Let's assume you would like to keep mentions of your copyright year current in y {{</* year */>}} ``` -{{< code file="/layouts/shortcodes/year.html" >}} +{{< code file=layouts/shortcodes/year.html >}} {{ now.Format "2006" }} {{< /code >}} @@ -186,14 +187,14 @@ Embedded videos are a common addition to Markdown content that can quickly becom Would load the template at `/layouts/shortcodes/youtube.html`: -{{< code file="/layouts/shortcodes/youtube.html" >}} +{{< code file=layouts/shortcodes/youtube.html >}} <div class="embed video-player"> <iframe class="youtube-player" type="text/html" width="640" height="385" src="https://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0"> </iframe> </div> {{< /code >}} -{{< code file="youtube-embed.html" copy=false >}} +{{< code file=youtube-embed.html >}} <div class="embed video-player"> <iframe class="youtube-player" type="text/html" width="640" height="385" @@ -207,13 +208,13 @@ Would load the template at `/layouts/shortcodes/youtube.html`: Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files: -{{< code file="content-image.md" >}} +{{< code file=content-image.md >}} {{</* img src="/media/spf13.jpg" title="Steve Francia" */>}} {{< /code >}} You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template: -{{< code file="/layouts/shortcodes/img.html" >}} +{{< code file=layouts/shortcodes/img.html >}} <!-- image --> <figure {{ with .Get "class" }}class="{{ . }}"{{ end }}> {{ with .Get "link" }}<a href="{{ . }}">{{ end }} @@ -236,7 +237,7 @@ You have created the shortcode at `/layouts/shortcodes/img.html`, which loads th Would be rendered as: -{{< code file="img-output.html" copy=false >}} +{{< code file=img-output.html >}} <figure> <img src="/media/spf13.jpg" /> <figcaption> @@ -254,7 +255,7 @@ Would be rendered as: Would load the template found at `/layouts/shortcodes/vimeo.html`: -{{< code file="/layouts/shortcodes/vimeo.html" >}} +{{< code file=layouts/shortcodes/vimeo.html >}} {{ if .IsNamedParams }} <div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}"> <iframe src="https://player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe> @@ -268,7 +269,7 @@ Would load the template found at `/layouts/shortcodes/vimeo.html`: Would be rendered as: -{{< code file="vimeo-iframes.html" copy=false >}} +{{< code file=vimeo-iframes.html >}} <div class="vimeo-container"> <iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe> </div> @@ -281,7 +282,7 @@ Would be rendered as: The following is taken from `highlight`, which is a [built-in shortcode] that ships with Hugo. -{{< code file="highlight-example.md" >}} +{{< code file=highlight-example.md >}} {{</* highlight html */>}} <html> <body> This HTML </body> @@ -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 >}} <div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672"><html></span> <span style="color: #f92672"><body></span> This HTML <span style="color: #f92672"></body></span> <span style="color: #f92672"></html></span> @@ -310,7 +311,7 @@ Hugo's [`.Parent` shortcode variable][parent] provides access to the parent shor The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter: -{{< code file="layouts/shortcodes/gallery.html" >}} +{{< code file=layouts/shortcodes/gallery.html >}} <div class="{{ .Get "class" }}"> {{ .Inner }} </div> @@ -318,7 +319,7 @@ The following example is contrived but demonstrates the concept. Assume you have You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`: -{{< code file="layouts/shortcodes/img.html" >}} +{{< code file=layouts/shortcodes/img.html >}} {{- $src := .Get "src" -}} {{- with .Parent -}} <img src="{{ $src }}" class="{{ .Get "class" }}-image"> @@ -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,21 +361,17 @@ 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" ``` -## More shortcode examples - -More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes]. - ## Inline shortcodes You can also implement your shortcodes inline -- e.g. where you use them in the content file. This can be useful for scripting that you only need in one place. 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 +379,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 {{</* time.inline */>}}{{ now }}{{</* /time.inline */>}} ``` @@ -394,7 +391,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 {{</* time.inline /*/>}} ``` @@ -408,8 +405,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..cd8a2715c 100644 --- a/content/en/templates/single-page-templates.md +++ b/content/en/templates/single-page-templates.md @@ -8,8 +8,8 @@ menu: parent: templates weight: 50 weight: 50 -aliases: [/layout/content/] toc: true +aliases: [/layout/content/] --- ## Single page template lookup order @@ -24,7 +24,7 @@ Content pages are of the type `page` and will therefore have all the [page varia This single page template makes use of Hugo [base templates], the [`.Format` function] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`] is also used to check whether the taxonomies are set in the front matter. -{{< code file="layouts/posts/single.html" >}} +{{< code file=layouts/posts/single.html >}} {{ define "main" }} <section id="main"> <h1 id="title">{{ .Title }}</h1> @@ -38,7 +38,7 @@ This single page template makes use of Hugo [base templates], the [`.Format` fun <div> <section> <h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4> - <h5 id="wordcount"> {{ .WordCount }} Words </h5> + <h5 id="wordcount"> {{ .WordCount }} Words</h5> </section> {{ with .GetTerms "topics" }} <ul id="topics"> @@ -57,10 +57,10 @@ This single page template makes use of Hugo [base templates], the [`.Format` fun </div> <div> {{ with .PrevInSection }} - <a class="previous" href="{{ .Permalink }}"> {{ .Title }}</a> + <a class="previous" href="{{ .RelPermalink }}"> {{ .LinkTitle }}</a> {{ end }} {{ with .NextInSection }} - <a class="next" href="{{ .Permalink }}"> {{ .Title }}</a> + <a class="next" href="{{ .RelPermalink }}"> {{ .LinkTitle }}</a> {{ end }} </div> </aside> @@ -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..07acfdb63 100644 --- a/content/en/templates/sitemap-template.md +++ b/content/en/templates/sitemap-template.md @@ -2,14 +2,14 @@ title: Sitemap templates description: Hugo provides built-in sitemap templates. categories: [templates] -keywords: [sitemap, xml, templates] +keywords: [sitemap,xml,templates] menu: docs: parent: templates weight: 170 weight: 170 -aliases: [/layout/sitemap/,/templates/sitemap/] toc: true +aliases: [/layout/sitemap/,/templates/sitemap/] --- ## Overview @@ -27,7 +27,7 @@ With a multilingual project, Hugo generates: Set the default values for [change frequency] and [priority], and the name of the generated file, in your site configuration. -{{< code-toggle config="sitemap" />}} +{{< code-toggle config=sitemap />}} changefreq : 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). @@ -42,7 +42,7 @@ priority Override the default values for a given page in front matter. -{{< code-toggle file="news.md" fm=true >}} +{{< code-toggle file=news.md fm=true >}} title = 'News' [sitemap] changefreq = 'weekly' @@ -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'] {{</ code-toggle >}} diff --git a/content/en/templates/taxonomy-templates.md b/content/en/templates/taxonomy-templates.md index 1b15bd4ef..ff149e940 100644 --- a/content/en/templates/taxonomy-templates.md +++ b/content/en/templates/taxonomy-templates.md @@ -8,13 +8,10 @@ menu: parent: templates weight: 90 weight: 90 -aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/] toc: true +aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/] --- -<!-- NOTE! Check on https://github.com/gohugoio/hugo/issues/2826 for shifting of terms' pages to .Data.Pages AND -https://discourse.gohugo.io/t/how-to-specify-category-slug/4856/15 for original discussion.--> - Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature. Hugo provides multiple ways to use taxonomies throughout your project templates: @@ -111,15 +108,13 @@ If you need to display custom metadata for each taxonomy term, you will need to <ul> {{ range .Pages }} <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> {{ .Params.wikipedia }} </li> {{ end }} </ul> ``` -<!-- Begin /taxonomies/ordering/ --> - ## Order taxonomies Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key. @@ -134,8 +129,6 @@ Taxonomies can be ordered by either alphabetical key or by the number of content </ul> ``` -<!-- [See Also Taxonomy Lists](/templates/list/) --> - ## Order content within taxonomies Hugo uses both `date` and `weight` to order content within taxonomies. @@ -152,7 +145,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"] @@ -170,8 +163,6 @@ With this the same piece of content can appear in different positions in differe Currently taxonomies only support the default ordering of content which is weight -> date. -<!-- Begin /taxonomies/templates/ --> - There are two different templates that the use of taxonomies will require you to provide. Both templates are covered in detail in the templates section. @@ -181,8 +172,6 @@ A [list template](/templates/lists/) is any template that will be used to render A [taxonomy template](/templates/taxonomy-templates/) is a template used to generate the list of terms for a given template. -<!-- Begin /taxonomies/displaying/ --> - There are four common ways you can display the data in your taxonomies in addition to the automatic taxonomy pages created by hugo using the [list templates](/templates/lists/): @@ -253,7 +242,7 @@ This would be very useful in a sidebar as “featured content”. You could even <li>{{ $key }}</li> <ul> {{ range $taxonomy.Pages }} - <li hugo-nav="{{ .RelPermalink }}"><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li> + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> {{ end }} </ul> {{ end }} @@ -283,7 +272,7 @@ The following example displays all terms in a site's tags taxonomy: This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms. -{{< code file="layouts/partials/all-taxonomies.html" >}} +{{< code file=layouts/partials/all-taxonomies.html >}} <ul> {{ range $taxonomy, $terms := site.Taxonomies }} <li> @@ -311,19 +300,18 @@ This example will list all taxonomies and their terms, as well as all the conten Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above](#example-list-all-site-tags): -{{< code file="links-to-all-tags.html" >}} +{{< code file=links-to-all-tags.html >}} {{ $taxo := "tags" }} <ul class="{{ $taxo }}"> {{ with ($.Site.GetPage (printf "/%s" $taxo)) }} {{ range .Pages }} - <li><a href="{{ .Permalink }}">{{ .Title }}</a></li> + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> {{ end }} {{ end }} </ul> {{< /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/template-debugging.md b/content/en/templates/template-debugging.md deleted file mode 100644 index fd400018b..000000000 --- a/content/en/templates/template-debugging.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Template debugging -description: You can use Go templates' `printf` function to debug your Hugo templates. These snippets provide a quick and easy visualization of the variables available to you in different contexts. -categories: [templates] -keywords: [debugging,troubleshooting] -menu: - docs: - parent: templates - weight: 240 -weight: 240 ---- - -Here are some snippets you can add to your template to answer some common questions. - -These snippets use the `printf` function available in all Go templates. This function is an alias to the Go function, [fmt.Printf](https://pkg.go.dev/fmt). - -## What variables are available in this context? - -You can use the template syntax, `$.`, to get the top-level template context from anywhere in your template. This will print out all the values under, `.Site`. - -```go-html-template -{{ printf "%#v" $.Site }} -``` - -This will print out the value of `.Permalink`: - -```go-html-template -{{ printf "%#v" .Permalink }} -``` - -This will print out a list of all the variables scoped to the current context -(`.`, aka ["the dot"][tempintro]). - -```go-html-template -{{ printf "%#v" . }} -``` - -When developing a [homepage], what does one of the pages you're looping through look like? - -```go-html-template -{{ range .Pages }} - {{/* The context, ".", is now each one of the pages as it goes through the loop */}} - {{ printf "%#v" . }} -{{ end }} -``` - -In some cases it might be more helpful to use the following snippet on the current context to get a pretty printed view of what you're able to work with: - -```go-html-template -<pre>{{ . | jsonify (dict "indent" " ") }}</pre> -``` - -Note that Hugo will throw an error if you attempt to use this construct to display context that includes a page collection (e.g., the context passed to home, section, taxonomy, and term templates). - -## Why am I showing no defined variables? - -Check that you are passing variables in the `partial` function: - -```go-html-template -{{ partial "header.html" }} -``` - -This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example, note the addition of ["the dot"][tempintro]. - -```go-html-template -{{ partial "header.html" . }} -``` - -The dot (`.`) is considered fundamental to understanding Hugo templating. For more information, see [Introduction to Hugo Templating][tempintro]. - -[homepage]: /templates/homepage/ -[tempintro]: /templates/introduction/ diff --git a/content/en/templates/views.md b/content/en/templates/views.md index 3d00a4ed6..e49f1debb 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/ @@ -62,7 +61,7 @@ The following example demonstrates how to use content views inside your [list te In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows: -{{< code file="layouts/_default/list.html" >}} +{{< code file=layouts/_default/list.html >}} <main id="main"> <div> <h1 id="title">{{ .Title }}</h1> @@ -77,15 +76,15 @@ In this example, `.Render` is passed into the template to call the [render funct Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.) -{{< code file="layouts/_default/summary.html" >}} +{{< code file=layouts/_default/summary.html >}} <article class="post"> <header> - <h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2> + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> <div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div> </header> {{ .Summary }} <footer> - <a href='{{ .Permalink }}'><nobr>Read more →</nobr></a> + <a href='{{ .RelPermalink }}'>Read more »</a> </footer> </article> {{< /code >}} @@ -94,9 +93,9 @@ Hugo will pass the entire page object to the following `summary.html` view templ Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`). -{{< code file="layouts/_default/li.html" >}} +{{< code file=layouts/_default/li.html >}} <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li> {{< /code >}} @@ -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/_index.md b/content/en/tools/_index.md index 6cc8c44d7..006bed053 100644 --- a/content/en/tools/_index.md +++ b/content/en/tools/_index.md @@ -2,7 +2,7 @@ title: Developer tools linkTitle: Overview description: In addition to Hugo's powerful CLI, there is a large number of community-developed tool chains for Hugo developers. -categories: [developer tools] +categories: [] keywords: [] menu: docs: diff --git a/content/en/tools/editors.md b/content/en/tools/editors.md index ea83f37c6..d94b7af0f 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 +## Visual Studio Code -* [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. +[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. -## Visual Studio Code +[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). -* [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 -Hugo Helper -Hugo Language and Syntax Support -Hugo Themer -Hugofy -Syntax Highlighting for Hugo Shortcodes +[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/front-ends.md b/content/en/tools/front-ends.md new file mode 100644 index 000000000..acce84d8d --- /dev/null +++ b/content/en/tools/front-ends.md @@ -0,0 +1,30 @@ +--- +title: Front-end interfaces +linkTitle: Front-ends +description: Do you prefer a graphical user interface over a text editor? Give these front-ends a try. +categories: [developer tools] +keywords: [frontend, gui] +menu: + docs: + parent: developer-tools + weight: 30 +weight: 30 +toc: true +aliases: [/tools/frontends/] +--- + +## Commercial + +[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. + +[Sveltia CMS](https://github.com/sveltia/sveltia-cms/) +: Sveltia CMS is a drop-in replacement for Decap CMS which is built from the ground up with powerful and performant modern UI library Svelte. Sveltia CMS incorporates i18n into every corner of the product, while striving to radically improve UX, performance and productivity. diff --git a/content/en/tools/frontends.md b/content/en/tools/frontends.md deleted file mode 100644 index bc4df22b5..000000000 --- a/content/en/tools/frontends.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Frontend interfaces with Hugo -linkTitle: Frontends -description: Do you prefer a graphical user interface over a text editor? Give these frontends a try. -categories: [developer tools] -keywords: [frontend, gui] -menu: - docs: - parent: developer-tools - weight: 30 -weight: 30 ---- - -- [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 services - -- [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. diff --git a/content/en/tools/migrations.md b/content/en/tools/migrations.md index 8ba01f927..0e61274c4 100644 --- a/content/en/tools/migrations.md +++ b/content/en/tools/migrations.md @@ -2,75 +2,101 @@ title: Migrate to Hugo linkTitle: Migrations description: A list of community-developed tools for migrating from your existing static site generator or content management system to Hugo. -keywords: [migrations, jekyll, wordpress, drupal, ghost, contentful] +categories: [developer tools] +keywords: [migrations,jekyll,wordpress,drupal,ghost,contentful] menu: docs: parent: developer-tools weight: 50 weight: 50 -aliases: [/developer-tools/migrations/, /developer-tools/migrated/] toc: true +aliases: [/developer-tools/migrations/, /developer-tools/migrated/] --- 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..f5243632c 100644 --- a/content/en/tools/other.md +++ b/content/en/tools/other.md @@ -3,7 +3,7 @@ title: Other community projects linkTitle: Other projects description: Some interesting projects developed by the Hugo community that don't quite fit into our other developer tool categories. categories: [developer tools] -keywords: [frontend, gui] +keywords: [frontend,gui] menu: docs: parent: developer-tools @@ -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..041174118 100644 --- a/content/en/tools/search.md +++ b/content/en/tools/search.md @@ -1,7 +1,9 @@ --- -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. +categories: [developer tools] +keywords: [search] menu: docs: parent: developer-tools @@ -12,19 +14,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/_index.md b/content/en/troubleshooting/_index.md index 01b38ecdb..65263ab32 100644 --- a/content/en/troubleshooting/_index.md +++ b/content/en/troubleshooting/_index.md @@ -1,16 +1,16 @@ --- -title: Troubleshoot +title: Troubleshooting linkTitle: Overview -description: Frequently asked questions and known issues pulled from the Hugo Discuss forum. +description: Use these techniques when troubleshooting your site. +categories: [] +keywords: [] menu: docs: identifier: troubleshooting-overview parent: troubleshooting weight: 10 weight: 10 -aliases: [/troubleshooting/faqs/,/faqs/] +aliases: [/templates/template-debugging/] --- -The Troubleshooting section includes known issues, recent workarounds, and FAQs pulled from the [Hugo Discussion Forum][forum]. - -[forum]: https://discourse.gohugo.io +Use these techniques when troubleshooting your site. diff --git a/content/en/troubleshooting/audit/index.md b/content/en/troubleshooting/audit/index.md new file mode 100644 index 000000000..f00ed8f8d --- /dev/null +++ b/content/en/troubleshooting/audit/index.md @@ -0,0 +1,73 @@ +--- +title: Site audit +linkTitle: Audit +description: Run this audit before deploying your production site. +categories: [troubleshooting] +keywords: [] +menu: + docs: + parent: troubleshooting + weight: 20 +weight: 20 +--- + +There are several conditions that can produce errors in your published site which are not detected during the build. Run this audit before your final build. + +{{< code copy=true >}} +HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true hugo && grep -inorE "<\!-- raw HTML omitted -->|ZgotmplZ|\[i18n\]|\(<nil>\)|(<nil>)|hahahugo" public/ +{{< /code >}} + +_Tested with GNU Bash 5.1 and GNU grep 3.7._ + +## Example output + + + +## Explanation + +### Environment variables + +`HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true` +: Retain HTML comments even if minification is enabled. This takes precedence over `minify.tdewolff.html.keepComments` in the site configuration. If you minify without keeping HTML comments when performing this audit, you will not be able to detect when raw HTML has been omitted. + +`HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true` +: Show a placeholder instead of the default value or an empty string if a translation is missing. This takes precedence over `enableMissingTranslationPlaceholders` in the site configuration. + +### Grep options + +`-i, --ignore-case` +: Ignore case distinctions in patterns and input data, so that characters that differ only in case match each other. + +`-n, --line-number` +: Prefix each line of output with the 1-based line number within its input file. + +`-o, --only-matching` +: Print only the matched (non-empty) parts of a matching line, with each such part on a separate output line. + +`-r, --recursive` +: Read all files under each directory, recursively, following symbolic links only if they are on the command line. + +`-E, --extended-regexp` +: Interpret PATTERNS as extended regular expressions. + +### Patterns + +`<!-- raw HTML omitted -->` +: By default, Hugo strips raw HTML from your markdown prior to rendering, and leaves this HTML comment in its place. + +`ZgotmplZ` +: ZgotmplZ is a special value that indicates that unsafe content reached a CSS or URL context at runtime. See [details]. + +[details]: https://pkg.go.dev/html/template + +`[i18n]` +: This is the placeholder produced instead of the default value or an empty string if a translation is missing. + +`(<nil>)` +: This string will appear in the rendered HTML when passing a nil value to the `printf` function. + +`(<nil>)` +: Same as above when the value returned from the `printf` function has not been passed through `safeHTML`. + +`HAHAHUGO` +: Under certain conditions a rendered shortcode may include all or a portion of the string HAHAHUGOSHORTCODE in either uppercase or lowercase. This is difficult to detect in all circumstances, but a case-insensitive search of the output for `HAHAHUGO` is likely to catch the majority of cases without producing false positives. diff --git a/content/en/troubleshooting/audit/screen-capture.png b/content/en/troubleshooting/audit/screen-capture.png Binary files differnew file mode 100644 index 000000000..221abfff0 --- /dev/null +++ b/content/en/troubleshooting/audit/screen-capture.png diff --git a/content/en/troubleshooting/build-performance.md b/content/en/troubleshooting/build-performance.md deleted file mode 100644 index a0fd98e49..000000000 --- a/content/en/troubleshooting/build-performance.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Build performance -description: An overview of features used for diagnosing and improving performance issues in site builds. -menu: - docs: - parent: troubleshooting - weight: 30 -weight: 30 -toc: true ---- - -## Template metrics - -Hugo is a very fast static site generator, but it is possible to write -inefficient templates. Hugo's _template metrics_ feature is extremely helpful -in pinpointing which templates are executed most often and how long those -executions take **in terms of CPU time**. - -| Metric Name | Description | -| ------------------- | -------------------------------------------------------------- | -| cumulative duration | The cumulative time spent executing a given template. | -| average duration | The average time spent executing a given template. | -| maximum duration | The maximum time a single execution took for a given template. | -| count | The number of times a template was executed. | -| template | The template name. | - -```txt -▶ hugo --templateMetrics -Started building sites ... - -Built site for language en: -0 draft content -0 future content -0 expired content -2 regular pages created -22 other pages created -0 non-page files copied -0 paginator pages created -4 tags created -3 categories created -total in 18 ms - -Template Metrics: - - cumulative average maximum - duration duration duration count template - ---------- -------- -------- ----- -------- - 6.419663ms 583.605µs 994.374µs 11 _internal/_default/rss.xml - 4.718511ms 1.572837ms 3.880742ms 3 indexes/category.html - 4.642666ms 2.321333ms 3.282842ms 2 posts/single.html - 4.364445ms 396.767µs 2.451372ms 11 partials/header.html - 2.346069ms 586.517µs 903.343µs 4 indexes/tag.html - 2.330919ms 211.901µs 2.281342ms 11 partials/header.includes.html - 1.238976ms 103.248µs 446.084µs 12 posts/li.html - 972.16µs 972.16µs 972.16µs 1 _internal/_default/sitemap.xml - 953.597µs 953.597µs 953.597µs 1 index.html - 822.263µs 822.263µs 822.263µs 1 indexes/post.html - 567.498µs 51.59µs 112.205µs 11 partials/navbar.html - 348.22µs 31.656µs 88.249µs 11 partials/meta.html - 346.782µs 173.391µs 276.176µs 2 posts/summary.html - 235.184µs 21.38µs 124.383µs 11 partials/footer.copyright.html - 132.003µs 12µs 117.999µs 11 partials/menu.html - 72.547µs 6.595µs 63.764µs 11 partials/footer.html -``` - -{{% note %}} -**A note about parallelism** - -Hugo builds pages in parallel where multiple pages are generated -simultaneously. Because of this parallelism, the sum of "cumulative duration" -values is usually greater than the actual time it takes to build a site. -{{% /note %}} - -## Cached partials - -Some `partial` templates such as sidebars or menus are executed many times -during a site build. Depending on the content within the `partial` template and -the desired output, the template may benefit from caching to reduce the number -of executions. The [`partialCached`][partialcached] template function provides -caching capabilities for `partial` templates. - -{{% note %}} -Note that you can create cached variants of each `partial` by passing additional -parameters to `partialCached` beyond the initial context. See the -`partialCached` documentation for more details. -{{% /note %}} - -[partialCached]: /functions/partials/includecached diff --git a/content/en/troubleshooting/deprecation.md b/content/en/troubleshooting/deprecation.md new file mode 100644 index 000000000..9aef54e8a --- /dev/null +++ b/content/en/troubleshooting/deprecation.md @@ -0,0 +1,50 @@ +--- +title: Deprecation +description: The Hugo project follows a formal and consistent process to deprecate functions, methods, and configuration settings. +categories: [troubleshooting] +keywords: [] +menu: + docs: + parent: troubleshooting + weight: 50 +weight: 50 +--- + +When a project _deprecates_ something, they are telling its users: + +1. Don't use Thing One anymore. +2. Use Thing Two instead. +3. We're going to remove Thing One at some point in the future. + +[article]: https://en.wikipedia.org/wiki/Deprecation + +Think of deprecation as a statement of intent. This Wikipedia [article] describes common reasons for deprecation: + +- The feature has been replaced by a more powerful alternative. +- The feature contains a design flaw. +- The feature is considered extraneous, and will be removed in the future in order to simplify the system as a whole. +- A future version of the software will make major structural changes, making it impossible or impractical to support older features. +- Standardization or increased consistency in naming. +- A feature that once was available only independently is now combined with its co-feature. + +After the project team deprecates something in code, Hugo will: + +1. Log an INFO message for 6 minor releases[^1] +2. Log a WARN message for another 6 minor releases +3. Log an ERROR message and fail the build thereafter + +To see the INFO messages, you must use the `--logLevel` command line flag: + +```text +hugo --logLevel info +``` + +To limit the output to deprecation notices: + +```text +hugo --logLevel info | grep deprecate +``` + +Run the above command every time you upgrade Hugo. + +[^1]: For example, v0.1.1 => v0.2.0 is a minor release. diff --git a/content/en/troubleshooting/faq.md b/content/en/troubleshooting/faq.md index bc29bfba1..dc6204777 100644 --- a/content/en/troubleshooting/faq.md +++ b/content/en/troubleshooting/faq.md @@ -1,62 +1,124 @@ --- title: Frequently asked questions -linkTitle: Frequently asked questions -description: Solutions to some common Hugo problems. +linkTitle: FAQs +description: These questions are frequently asked by new users. categories: [troubleshooting] +keywords: [faq] menu: docs: parent: troubleshooting - weight: 20 -weight: 20 -keywords: [faqs] -toc: true -aliases: [/faq/] + weight: 70 +weight: 70 +# Use level 6 headings for each question. --- -{{% note %}} -**Note:** The answers/solutions presented below are short, and may not be enough to solve your problem. Visit [Hugo Discourse](https://discourse.gohugo.io/) and use the search. It that does not help, start a new topic and ask your questions. -{{% /note %}} +Hugo’s [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question. + +These are just a few of the questions most frequently asked by new users. + +###### An error message indicates that a feature is not available. Why? + +Hugo is available in two editions: standard and extended. With the extended edition you can (a) encode to the WebP format when processing images, and (b) transpile Sass to CSS using the embedded LibSass transpiler. The extended edition is not required to use the Dart Sass transpiler. + +When you attempt to perform either of the operations above with the standard edition, Hugo throws this error: + +```go-html-template +Error: this feature is not available in your current Hugo version +``` + +To resolve, uninstall the standard edition, then install the extended edition. See the [installation] section for details. + +###### Why do I see "Page Not Found" when visiting the home page? + +In the content/_index.md file: -## I can't see my content + - Is `draft` set to `true`? + - Is the `date` in the future? + - Is the `publishDate` in the future? + - Is the `expiryDate` in the past? -Is your Markdown file [in draft mode](/content-management/front-matter/#front-matter-variables)? When testing, run `hugo server` with the `-D` or `--buildDrafts` [switch](/getting-started/usage/#draft-future-and-expired-content). +If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`. -Is your Markdown file part of a [leaf bundle](/content-management/page-bundles/)? If there is an `index.md` file in the same or any parent directory then other Markdown files will not be rendered as individual pages. +###### Why is a given section not published? -## Can I set configuration variables via OS environment? +In the content/section/_index.md file: -Yes you can! See [Configure with Environment Variables](/getting-started/configuration/#configure-with-environment-variables). + - Is `draft` set to `true`? + - Is the `date` in the future? + - Is the `publishDate` in the future? + - Is the `expiryDate` in the past? -## How do I schedule posts? +If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`. -1. Set `publishDate` in the page [front matter](/content-management/front-matter/) to a datetime in the future. If you want the creation and publication datetime to be the same, it's also sufficient to only set `date`[^date-hierarchy]. -2. Build and publish at intervals. +###### Why is a given page not published? -How to automate the "publish at intervals" part depends on your situation: +In the content/section/page.md file, or in the content/section/page/index.md file: -* If you deploy from your own PC/server, you can automate with [Cron](https://en.wikipedia.org/wiki/Cron) or similar. -* If your site is hosted on a service similar to [Netlify](https://www.netlify.com/) you can: - * Use a service such as [ifttt](https://ifttt.com/date_and_time) to schedule the updates; or - * Set up a deploy hook which you can run with a cron service to deploy your site at intervals, such as [cron-job.org](https://cron-job.org/) (both Netlify and Cloudflare Pages support deploy hooks) + - Is `draft` set to `true`? + - Is the `date` in the future? + - Is the `publishDate` in the future? + - Is the `expiryDate` in the past? -Also see this Twitter thread: +If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`. -{{< tweet user="ChrisShort" id="962380712027590657" >}} +###### Why can't I see any of a page's descendants? -[^date-hierarchy]: See [Configure Dates](/getting-started/configuration/#configure-dates) for the order in which the different date variables are complemented by each other when not explicitly set. +You may have an index.md file instead of an _index.md file. See [details](/content-management/page-bundles/). -## Can I use the latest Hugo version on Netlify? +###### What is the difference between an index.md file and an _index.md file? -[Yes you can](/hosting-and-deployment/hosting-on-netlify/#configure-hugo-version-in-netlify)!. +A directory with an index.md file is a [leaf bundle]. A directory with an _index.md file is a [branch bundle]. See [details](/content-management/page-bundles/). -## I get "... this feature is not available in your current Hugo version" +[branch bundle]: /getting-started/glossary/#branch-bundle +[leaf bundle]: /getting-started/glossary/#leaf-bundle -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: +###### Why is my partial template not rendered as expected? {#foo} -```bash -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 +You may have neglected to pass the required [context] when calling the partial. For example: + +```go-html-template +{{/* incorrect */}} +{{ partial "_internal/pagination.html" }} + +{{/* correct */}} +{{ partial "_internal/pagination.html" . }} ``` -We release two set of binaries for technical reasons. The extended version is not what you get by default for some installation methods. On the [release page](https://github.com/gohugoio/hugo/releases), look for archives with `extended` in the name. To build `hugo-extended`, use `go install --tags extended` +###### In a template, what's the difference between `:=` and `=` when assigning values to variables? + +Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. See [details](https://pkg.go.dev/text/template#hdr-Variables). + +###### When I paginate a list page, why is the page collection not filtered as specified? + +You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/#list-paginator-pages). + +###### Why are there two ways to call a shortcode? + +Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains markdown. Otherwise use the\ +`{{</* shortcode */>}}` notation. See [details](/content-management/shortcodes/). + +###### Can I use environment variables to control configuration? + +Yes. See [details](/getting-started/configuration/#configure-with-environment-variables). + +###### Why am I seeing inconsistent output from one build to the next? + +The most common causes are page collisions (publishing two pages to the same path) and the effects of concurrency. Use the `--printPathWarnings` command line flag to check for page collisions, and create a topic on the [forum] if you suspect concurrency problems. + +###### Which page methods trigger content rendering? + +The following methods on a `Page` object triggering content rendering: `Content`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`. + +{{% note %}} +For other questions please visit the [forum]. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question. + +[forum]: https://discourse.gohugo.io +[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132 +{{% /note %}} -To confirm, run `hugo version` and look for the word `extended`. +[`Paginate`]: /methods/page/paginate +[`Paginator`]: /methods/page/paginator +[context]: /getting-started/glossary/#context +[forum]: https://discourse.gohugo.io +[installation]: /installation +[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132 diff --git a/content/en/troubleshooting/inspection.md b/content/en/troubleshooting/inspection.md new file mode 100644 index 000000000..826229153 --- /dev/null +++ b/content/en/troubleshooting/inspection.md @@ -0,0 +1,72 @@ +--- +title: Data inspection +linkTitle: Inspection +description: Use template functions to inspect values and data structures. +categories: [troubleshooting] +keywords: [] +menu: + docs: + parent: troubleshooting + weight: 40 +weight: 40 +--- + +Use the [`jsonify`] function to inspect a data structure: + +```go-html-template +<pre>{{ jsonify (dict "indent" " ") .Params }}</pre> +``` + +```text +{ + "date": "2023-11-10T15:10:42-08:00", + "draft": false, + "iscjklanguage": false, + "lastmod": "2023-11-10T15:10:42-08:00", + "publishdate": "2023-11-10T15:10:42-08:00", + "tags": [ + "foo", + "bar" + ], + "title": "My first post" +} +``` + +{{% note %}} +Hugo will throw an error if you attempt to use the construct above to display context that includes a page collection. For example, in a home page template, this will fail: + +`{{ jsonify (dict "indent" " ") . }}` +{{% /note %}} + +Use the [`debug.Dump`] function to inspect data types: + +```go-html-template +<pre>{{ debug.Dump .Params }}</pre> +``` + +```text +maps.Params{ + "date": time.Time{}, + "draft": false, + "iscjklanguage": false, + "lastmod": time.Time{}, + "publishdate": time.Time{}, + "tags": []string{ + "foo", + "bar", + }, + "title": "My first post", +} +``` + +Use the [`printf`] function (render) or [`warnf`] function (log to console) to inspect simple data structures. The layout string below displays both value and data type. + +```go-html-template +{{ $value := 42 }} +{{ printf "%[1]v (%[1]T)" $value }} → 42 (int) +``` + +[`jsonify`]: /functions/encoding/jsonify +[`debug.Dump`]: /functions/debug/dump +[`printf`]: /functions/fmt/printf +[`warnf`]: /functions/fmt/warnf diff --git a/content/en/troubleshooting/logging.md b/content/en/troubleshooting/logging.md new file mode 100644 index 000000000..8879c1846 --- /dev/null +++ b/content/en/troubleshooting/logging.md @@ -0,0 +1,56 @@ +--- +title: Logging +description: Enable logging to inspect events while building your site. +categories: [troubleshooting] +keywords: [] +menu: + docs: + parent: troubleshooting + weight: 30 +weight: 30 +toc: true +--- + +## Command line + +Enable console logging with the `--logLevel` command line flag. + +Hugo has four logging levels: + +error +: Display error messages only. + +```sh +hugo --logLevel error +``` + +warn +: Display warning and error messages. + +```sh +hugo --logLevel warn +``` + +info +: Display information, warning, and error messages. + +```sh +hugo --logLevel info +``` + +debug +: Display debug, information, warning, and error messages. + +```sh +hugo --logLevel debug +``` + +{{% note %}} +If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed. +{{% /note %}} + +## Template functions + +You can also use template functions to print warnings or errors to the console. These functions are typically used to report data validation errors, missing files, etc. + +{{< list-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include >}} diff --git a/content/en/troubleshooting/performance.md b/content/en/troubleshooting/performance.md new file mode 100644 index 000000000..589d30df6 --- /dev/null +++ b/content/en/troubleshooting/performance.md @@ -0,0 +1,94 @@ +--- +title: Performance +description: Use template metrics and timers to identify opportunities to improve performance. +categories: [troubleshooting] +keywords: [] +menu: + docs: + parent: troubleshooting + weight: 60 +weight: 60 +toc: true +aliases: [/troubleshooting/build-performance/] +--- + +## Template metrics + +Hugo is fast, but inefficient templates impede performance. Enable template metrics to determine which templates take the most time, and to identify caching opportunties: + +```sh +hugo --templateMetrics --templateMetricsHints +``` + +The result will look something like this: + +```text +Template Metrics: + + cumulative average maximum cache percent cached total + duration duration duration potential cached count count template + ---------- -------- -------- --------- ------- ------ ----- -------- + 36.037476822s 135.990478ms 225.765245ms 11 0 0 265 partials/head.html + 35.920040902s 164.018451ms 233.475072ms 0 0 0 219 articles/single.html + 34.163268129s 128.917992ms 224.816751ms 23 0 0 265 partials/head/meta/opengraph.html + 1.041227437s 3.92916ms 186.303376ms 47 0 0 265 partials/head/meta/schema.html + 805.628827ms 27.780304ms 114.678523ms 0 0 0 29 _default/list.html + 624.08354ms 15.221549ms 108.420729ms 8 0 0 41 partials/utilities/render-page-collection.html + 545.968801ms 775.523µs 105.045775ms 0 0 0 704 _default/summary.html + 334.680981ms 1.262947ms 127.412027ms 100 0 0 265 partials/head/js.html + 272.763205ms 2.050851ms 24.371757ms 0 0 0 133 _default/_markup/render-codeblock.html + 230.490038ms 8.865001ms 177.4615ms 0 0 0 26 shortcodes/template.html + 176.921913ms 176.921913ms 176.921913ms 0 0 0 1 examples.tmpl + 163.951469ms 14.904679ms 70.267953ms 0 0 0 11 articles/list.html + 153.07021ms 577.623µs 73.593597ms 100 0 0 265 partials/head/init.html + 150.910984ms 150.910984ms 150.910984ms 0 0 0 1 _default/single.html + 146.785804ms 146.785804ms 146.785804ms 0 0 0 1 _default/contact.html + 115.364617ms 115.364617ms 115.364617ms 0 0 0 1 authors/term.html + 87.392071ms 329.781µs 10.687132ms 100 0 0 265 partials/head/css.html + 86.803122ms 86.803122ms 86.803122ms 0 0 0 1 _default/home.html +``` + +From left to right, the columns represent: + +cumulative duration +: The cumulative time spent executing the template. + +average duration +: The average time spent executing the template. + +maximum duration +: The maximum time spent executing the template. + +cache potential +: Displayed as a percentage, any partial template with a 100% cache potential should be called with the [`partialCached`] function instead of the [`partial`] function. See the [caching](#caching) section below. + +percent cached +: The number of times the rendered templated was cached divided by the number of times the template was executed. + +cached count +: The number of times the rendered templated was cached. + +total count +: The number of times the template was executed. + +template +: The path to the template, relative to the layouts directory. + +[`partial`]: /functions/partials/include +[`partialCached`]: /functions/partials/includecached + +{{% note %}} +Hugo builds pages in parallel where multiple pages are generated simultaneously. Because of this parallelism, the sum of "cumulative duration" values is usually greater than the actual time it takes to build a site. +{{% /note %}} + +## Caching + +Some partial templates such as sidebars or menus are executed many times during a site build. Depending on the content within the partial template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for partial templates. + +{{% note %}} +Note that you can create cached variants of each partial by passing additional parameters to `partialCached` beyond the initial context. See the `partialCached` documentation for more details. +{{% /note %}} + +## Timers + +Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottle necks in templates. See [details](/functions/debug/timer/). 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 +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/content/en/variables/_common/consistent-terminology.md b/content/en/variables/_common/consistent-terminology.md new file mode 100644 index 000000000..8774c817b --- /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], or the [methods quick reference guide]. + +[functions]: /getting-started/glossary/#function +[methods quick reference guide]: /quick-reference/methods +[methods section]: /methods +[methods]: /getting-started/glossary/#method +[object]: /getting-started/glossary/#object +[parameters]: /getting-started/glossary/#parameter +[terminology]: /getting-started/glossary/ +[variables]: /getting-started/glossary/#variable +{{% /note %}} diff --git a/content/en/variables/_index.md b/content/en/variables/_index.md index c1f80a62c..d8dbf9d67 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: [] +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..5b90dab6f --- /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: [] +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. - -<!-- This provides no value when rendering menu. Omitting to avoid confusion. -.PageRef -: (`string`) The `pageRef` property of 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..732cf5499 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: [] 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 `<head>`. (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_multilingual 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: `<a href="{{ .Sites.First.Home.RelPermalink }}">...</a>`. - -.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 <code><!--more--></code> 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): - -.Pages -: Regular pages within the current section (not recursive), and section pages for immediate descendant sections (not recursive). - -.RegularPages -: Regular pages within the current section (not recursive). - -.RegularPagesRecursive -: Regular pages within the current section, and regular pages within all descendant sections. - -## Writable page-scoped variables - -[.Scratch][scratch] -: Returns a Scratch to store and manipulate data. In contrast to the [`.Store`][store] method, this scratch is reset on server rebuilds. - -[.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. - -## Section variables and methods - -Also see [Sections](/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" }} - <p>Page contains identifier "my-identifier"</p> -{{ end }} - -{{ if gt (.Fragments.Identifiers.Count "my-identifier") 1 }} - <p>Page contains duplicate "my-identifier" fragments</p> -{{ 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/[email protected]/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: - -* `{{</* myshortcode */>}}` 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 -<h3><a href="{{ .Params.affiliatelink }}">Buy this book</a></h3> -<p>It was recommended by {{ .Params.recommendedby }}.</p> -``` - -This template would render as follows: - -```html -<h3><a href="http://www.my-book-link.here">Buy this book</a></h3> -<p>It was recommended by my Mother.</p> -``` - -{{% note %}} -See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content. -{{% /note %}} - -### The `.Param` method +Range through these collections when rendering lists on [section] pages, [taxonomy] pages, [term] pages, and the home page. -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): +[section]: /getting-started/glossary/#section +[taxonomy]: /getting-started/glossary/#taxonomy +[term]: /getting-started/glossary/#term +[context]: /getting-started/glossary/#context -```go-html-template -{{ $.Param "header_image" }} -``` +{{< list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=. omitElementIDs=true >}} -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). +## Parameters -### Access nested fields in front matter +Use these methods to access page parameters. -When front matter contains nested fields like the following: +{{< list-pages-in-section path=/methods/page filter=methods_page_parameters filterType=include titlePrefix=. omitElementIDs=true >}} -{{< 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 >}} +## Sections -`.Param` can access these fields by concatenating the field names together with a dot: +Use these methods to access section pages, and their ancestors and descendants. See [details]. -```go-html-template -{{ $.Param "author.display_name" }} -``` +[details]: /content-management/sections/ -[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..24b8fbbf4 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] -keywords: [pages] +title: Pages variables +description: Use these methods with a collection of Page objects. +categories: [variables] +keywords: [] menu: docs: parent: variables - weight: 21 -weight: 21 -aliases: [/pages] + weight: 60 +weight: 60 toc: true +aliases: [/variables/site-variables/] --- -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..57279b5de --- /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: [] +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 `{{</* highlight */>}}` 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 482bd520b..532357785 100644 --- a/content/en/variables/site.md +++ b/content/en/variables/site.md @@ -1,117 +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: [] menu: docs: parent: variables - weight: 10 -weight: 10 -aliases: [/variables/site-variables/] + weight: 80 +weight: 80 toc: true +aliases: [/variables/site-variables/] --- -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. - -## Get the site object from a partial - -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. - -## Site variables - -.Site.AllPages -: array of all pages, regardless of their translation. - -.Site.BaseURL -: the base URL for the site as defined in the site configuration. - -.Site.BuildDrafts -: a boolean (default: `false`) to indicate whether to build drafts as defined in the site configuration. - -.Site.Copyright -: a string representing the copyright of your website as defined in the site configuration. - -.Site.Data -: custom data, see [Data Templates](/templates/data-templates/). - -.Site.DisqusShortname -: a string representing the shortname of the Disqus shortcode as defined in the site configuration. - -.Site.GoogleAnalytics -: a string representing your tracking code for Google Analytics as defined in the site configuration. - -.Site.Home -: reference to the homepage's [page object](/variables/page/) - -.Site.IsMultiLingual -: whether there are more than one language in this site. See [Multilingual](/content-management/multilingual/) for more information. - -.Site.IsServer -: a boolean to indicate if the site is being served with Hugo's built-in server. See [`hugo server`](/commands/hugo_server/) for more information. - -.Site.Language.Lang -: the language code of the current locale (e.g., `en`). - -.Site.Language.LanguageName -: the full language name (e.g. `English`). - -.Site.Language.Weight -: the weight that defines the order in the `.Site.Languages` list. - -.Site.Language -: indicates the language currently being used to render the website. This object's attributes are set in site configurations' language definition. - -.Site.LanguageCode -: a string representing the language tag as defined in the site configuration. - -.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. +{{% include "variables/_common/consistent-terminology.md" %}} -.Site.LastChange -: a [time.Time](https://godoc.org/time#Time) value representing the date/time of the most recent change to your site. +## All methods -.Site.Menus -: all the menus in the site. +Use any of these methods in your templates. -.Site.Pages -: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. +{{< list-pages-in-section path=/methods/site titlePrefix=.Site. >}} -.Site.RegularPages -: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. +## Multilingual -.Site.Sections -: top-level directories of the site. +Use these methods with your multilingual projects. -.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). +{{< list-pages-in-section path=/methods/site filter=methods_site_multilingual filterType=include titlePrefix=.Site. omitElementIDs=true >}} -.Site.Title -: a string representing the title of the site. +[`site`]: /functions/global/site +[context]: /getting-started/glossary/#context +[configuration file]: /getting-started/configuration -## Site parameters +## Page collections -`.Site.Params` is a container holding the values from the `params` section of your site configuration. +Range through these collections when rendering lists on any page. -### Example: `.Site.Params` +{{< list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=.Site. omitElementIDs=true >}} -The following `config.[yaml|toml|json]` defines a site-wide parameter for `description`: +## Global site function -{{< code-toggle file="hugo" >}} -baseURL = "https://yoursite.example.com/" +Within a partial template, if you did not pass a `Page` or `Site` object in [context], you cannot use this syntax: -[params] - description = "Tesla's Awesome Hugo Site" - author = "Nikola Tesla" -{{</ code-toggle >}} +```go-html-template +{{ .Site.SomeMethod }} +``` -You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description: +Instead, use the global [`site`] function: -{{< code file="layouts/partials/head.html" >}} -<meta name="description" content="{{ if .IsHome }}{{ $.Site.Params.description }}{{ else }}{{ .Description }}{{ end }}" /> -{{< /code >}} +```go-html-template +{{ site.SomeMethod }} +``` -[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..ee6d73b2e 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] -keywords: [taxonomy,term] +description: Use these methods with Taxonomy objects. +categories: [variables] +keywords: [] 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 -<ul> - {{ range $taxonomy, $terms := site.Taxonomies }} - <li> - {{ with site.GetPage $taxonomy }} - <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> - {{ end }} - <ul> - {{ range $term, $weightedPages := $terms }} - <li> - {{ with site.GetPage (path.Join $taxonomy $term) }} - <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> - {{ end }} - </li> - <ul> - {{ range $weightedPages }} - <li> - <a href="{{ .RelPermalink }}"> {{ .LinkTitle }}</a> - </li> - {{ end }} - </ul> - {{ end }} - </ul> - </li> - {{ end }} -</ul> -``` - -See [Taxonomy Templates] for more examples. - -[Taxonomy Templates]: /templates/taxonomy-templates/ +[`Data`]: /methods/page/data +{{% /note %}} diff --git a/data/docs.yaml b/data/docs.yaml index f80c2b41e..2cdb0dd53 100644 --- a/data/docs.yaml +++ b/data/docs.yaml @@ -185,6 +185,9 @@ chroma: - css Name: CSS - Aliases: + - cue + Name: CUE + - Aliases: - cython - pyx - pyrex @@ -600,6 +603,9 @@ chroma: - proto Name: Protocol Buffer - Aliases: + - prql + Name: PRQL + - Aliases: - psl Name: PSL - Aliases: @@ -1021,6 +1027,7 @@ config: extensions: cjk: eastAsianLineBreaks: false + eastAsianLineBreaksStyle: simple enable: false escapedSpace: false definitionList: true @@ -2305,8 +2312,9 @@ tpl: - c - k Description: |- - EchoParam returns a the value in the collection c with key k if is set; otherwise, it returns an + EchoParam returns the value in the collection c with key k if is set; otherwise, it returns an empty string. + Deprecated: Use the index function instead. Examples: - - '{{ echoParam .Params "langCode" }}' - en @@ -2733,6 +2741,11 @@ tpl: map[string]interface {}{ "Hugo": "Rocks!", } + Timer: + Aliases: null + Args: null + Description: "" + Examples: null VisualizeSpaces: Aliases: null Args: null @@ -2877,6 +2890,11 @@ tpl: Args: null Description: "" Examples: null + IsDevelopment: + Aliases: null + Args: null + Description: "" + Examples: null IsExtended: Aliases: null Args: null @@ -2887,6 +2905,11 @@ tpl: Args: null Description: "" Examples: null + IsServer: + Aliases: null + Args: null + Description: "" + Examples: null Version: Aliases: null Args: null @@ -2967,6 +2990,11 @@ tpl: Args: null Description: "" Examples: null + Padding: + Aliases: null + Args: null + Description: "" + Examples: null Pixelate: Aliases: null Args: null diff --git a/data/page_filters.yaml b/data/page_filters.yaml new file mode 100644 index 000000000..2a3a8625d --- /dev/null +++ b/data/page_filters.yaml @@ -0,0 +1,93 @@ +# 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_fmt_logging: + - /functions/fmt/errorf + - /functions/fmt/erroridf + - /functions/fmt/warnf +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_multilingual: + - /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" @@ -2,4 +2,4 @@ module github.com/gohugoio/hugoDocs go 1.16 -require github.com/gohugoio/gohugoioTheme v0.0.0-20230927165800-342e2c850f18 // indirect +require github.com/gohugoio/gohugoioTheme v0.0.0-20231111235806-77931ac4875e // indirect @@ -1,79 +1,2 @@ -github.com/gohugoio/gohugoioTheme v0.0.0-20190808163145-07b3c0f73b02/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20191014144142-1f3a01deed7b h1:PWNjl46fvtz54PKO0BdiXOF6/4L/uCP0F3gtcCxGrJs= -github.com/gohugoio/gohugoioTheme v0.0.0-20191014144142-1f3a01deed7b/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20191021162625-2e7250ca437d h1:D3DcaYkuJbotdWNNAQpQl37txX4HQ6R5uMHoxVmTw0w= -github.com/gohugoio/gohugoioTheme v0.0.0-20191021162625-2e7250ca437d/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20200123151337-9475fd449324 h1:UZwHDYtGY0uOKIvcm2LWd+xfFxD3X5L222LIJdI5RE4= -github.com/gohugoio/gohugoioTheme v0.0.0-20200123151337-9475fd449324/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20200123204146-589b4c309025 h1:ScYFARz+bHX1rEr1donVknhRdxGY/cwqK1hHvWEfrlc= -github.com/gohugoio/gohugoioTheme v0.0.0-20200123204146-589b4c309025/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20200123205007-5d6620a0db26 h1:acXfduibbWxji9tW0WkLHbjcXFsnd5uIwXe0WfwOazg= -github.com/gohugoio/gohugoioTheme v0.0.0-20200123205007-5d6620a0db26/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20200128164921-1d0bc5482051 h1:cS14MnUGS6xwWYfPNshimm8HdMCZiYBxWkCD0VnvgVw= -github.com/gohugoio/gohugoioTheme v0.0.0-20200128164921-1d0bc5482051/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20200327225449-368f4cbef8d7 h1:cZ+ahAjSetbFv3aDJ9ipDbKyqaVlmkbSZ5cULgBTh+w= -github.com/gohugoio/gohugoioTheme v0.0.0-20200327225449-368f4cbef8d7/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20200327231942-7f80b3d02bfa h1:kG+O/wT9UXomzp5eQiUuFVZ0l7YylAW6EVPLyjMxi/c= -github.com/gohugoio/gohugoioTheme v0.0.0-20200327231942-7f80b3d02bfa/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20200328100657-2bfd5f8c6aee h1:PJZhCwnuVLyafDWNPSHk9iJvk6gEIvPRnycy7Pq3peA= -github.com/gohugoio/gohugoioTheme v0.0.0-20200328100657-2bfd5f8c6aee/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20200518164958-62cbad03c40f h1:Ge3JACszSUyJW2Az9cJzWdo4PUqdijJA1RxoQSVMBSI= -github.com/gohugoio/gohugoioTheme v0.0.0-20200518164958-62cbad03c40f/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20200518165806-0095b7b902a7 h1:Sy0hlWyZmFtdSY0Cobvw1ZYm3G1aR5+4DuFNRbMkh48= -github.com/gohugoio/gohugoioTheme v0.0.0-20200518165806-0095b7b902a7/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20200711112515-b0dfe471654f h1:BWJyycs4HD7tUbaU8RIGeMay84bIBWRVVLE3yajPas4= -github.com/gohugoio/gohugoioTheme v0.0.0-20200711112515-b0dfe471654f/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20210301124928-2c15837dfec3 h1:ShqzOFeeg54FPSuS6q8HSeTVgj2xNZRe/YS0jNbi21g= -github.com/gohugoio/gohugoioTheme v0.0.0-20210301124928-2c15837dfec3/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20210409065807-6383d8cbaf65 h1:EJzierSWKqwsrUXU6MaFe0J97c0e5pzl5dBNRRrV2Nc= -github.com/gohugoio/gohugoioTheme v0.0.0-20210409065807-6383d8cbaf65/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20210409071416-c88da48134b7 h1:uRCgPslaBgLYy4ANXBoPbBQVM8aNiHoxIZTKUXpkuUA= -github.com/gohugoio/gohugoioTheme v0.0.0-20210409071416-c88da48134b7/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20211211125852-b85e21c1f3d6 h1:lAgdWrn8VEg0PrNCPX4DflCg2msDKpSYV6E8RTNV3N0= -github.com/gohugoio/gohugoioTheme v0.0.0-20211211125852-b85e21c1f3d6/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20220228085601-7cfbda06d135 h1:6hVzfE9YhSsZP5t6jWjvVp7MoPm7Y5fEhH/ls4ahhKk= -github.com/gohugoio/gohugoioTheme v0.0.0-20220228085601-7cfbda06d135/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20220905093719-cb8b64046950 h1:Ovlh3nuy/aNptYZHmIra2MP+ZUEqiihY0HxvhdaMqGg= -github.com/gohugoio/gohugoioTheme v0.0.0-20220905093719-cb8b64046950/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20220912070954-88dcaf003b4d h1:UYJL6RmEepprvlgHvDnFCWtPOvjmqzFCQ90cRDRBO7U= -github.com/gohugoio/gohugoioTheme v0.0.0-20220912070954-88dcaf003b4d/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20220914071648-0ef1c51685bf h1:A8Ksnvp8reNt2Ap0mUK7gFkJkCjt9R60yopGsezcOBA= -github.com/gohugoio/gohugoioTheme v0.0.0-20220914071648-0ef1c51685bf/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20221116211530-5ae8dcdd68d6 h1:eG53kL1LkQuKmrDdzbvvx6d60qM07zp2Wjo/tYxkDOY= -github.com/gohugoio/gohugoioTheme v0.0.0-20221116211530-5ae8dcdd68d6/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20221118083537-967e29e21382 h1:e30rl1dxWkYOcgdl0omeOK0HBzgDLI/b9MfYHrINjzU= -github.com/gohugoio/gohugoioTheme v0.0.0-20221118083537-967e29e21382/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20221124154621-1451a01f406b h1:TRrIisSY7ckt9FVHOOQtmKG4jsnORCYn72UMvMu+IQ0= -github.com/gohugoio/gohugoioTheme v0.0.0-20221124154621-1451a01f406b/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20221206093948-1408550ab675 h1:wjpYa1cTELeceWndBDV7IG2vRxRWICBBO79HObOfTtk= -github.com/gohugoio/gohugoioTheme v0.0.0-20221206093948-1408550ab675/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20221217122332-1c1752ad8f14 h1:K6tPFpi7W0zb89QIf+lNdgdTXfDFemU6NKk46MlX9lQ= -github.com/gohugoio/gohugoioTheme v0.0.0-20221217122332-1c1752ad8f14/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= -github.com/gohugoio/gohugoioTheme v0.0.0-20221220160735-8ffa1ef883b6 h1:yEoQecRBoLGfc7yTybMD3Mhm03bTScZFYPvwe0p75vA= -github.com/gohugoio/gohugoioTheme v0.0.0-20221220160735-8ffa1ef883b6/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230109120406-12694c4a9456 h1:RSLItaapVjWkqSdQhumAmJkodFDbWMGNZmkVW/AFx0c= -github.com/gohugoio/gohugoioTheme v0.0.0-20230109120406-12694c4a9456/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230119103504-3bcd960d6f1b h1:i/iaEOOuR1mKRR0qUOET587ooVhG8c2tllpA5HsrWNU= -github.com/gohugoio/gohugoioTheme v0.0.0-20230119103504-3bcd960d6f1b/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230120185049-2c3c4d0ba232 h1:bEojKgKInbsLkID5Arh95vP4+0xydtn/+ayT6I8vkiU= -github.com/gohugoio/gohugoioTheme v0.0.0-20230120185049-2c3c4d0ba232/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230124135550-462d5fe4a87f h1:8wI3zOTWQG15aKkbAZQaoGnUQff46hO95opQndBHRE4= -github.com/gohugoio/gohugoioTheme v0.0.0-20230124135550-462d5fe4a87f/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230330081257-7a8c9614432c h1:TyHgmowfiMyxKrqTdRxm/yWIFeN7XRh7Hm6/dOG6yDA= -github.com/gohugoio/gohugoioTheme v0.0.0-20230330081257-7a8c9614432c/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230418063032-99f9185b8e11 h1:mDcricMewd66x8QjKqNun7Div7iYVLtl8s1dVs9VnB8= -github.com/gohugoio/gohugoioTheme v0.0.0-20230418063032-99f9185b8e11/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230527124826-78bc315d7b8a h1:ruyA3QZ4Ym0fBLhTW2eoUSvHUaj2xWqaPHIbaI+tbZo= -github.com/gohugoio/gohugoioTheme v0.0.0-20230527124826-78bc315d7b8a/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230615111426-c3725d921127 h1:LaOUdx1uo/Pr8Vr9KbqTwioia9OhNSiZDOHQGNHZiOs= -github.com/gohugoio/gohugoioTheme v0.0.0-20230615111426-c3725d921127/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230615131407-b3235557d2e6 h1:x/1M3CJRXCNfThsT+EeWrC2B1qFQZSCeOgA44RJJ5ds= -github.com/gohugoio/gohugoioTheme v0.0.0-20230615131407-b3235557d2e6/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230624091215-084560177ddc h1:BX7s0bvHFjx5Dll+9CBEiphSjWCDmZ1S+vOrB2wjpOg= -github.com/gohugoio/gohugoioTheme v0.0.0-20230624091215-084560177ddc/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230630055807-9874cd863bc5 h1:5QDXCq7G6Ak13EKF69QIJtH2YhidilBetNDgdoBYsWM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230630055807-9874cd863bc5/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230812102551-06f8256e7ee5 h1:QoImGtz9EWmovn3d0vfREKf1ybroA+oO/yFCW/BmWSE= -github.com/gohugoio/gohugoioTheme v0.0.0-20230812102551-06f8256e7ee5/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= -github.com/gohugoio/gohugoioTheme v0.0.0-20230927165800-342e2c850f18 h1:fwC86MGMw2yX2tIR+hc+58jlU4pjvc3HUDJ/mTB07Ig= -github.com/gohugoio/gohugoioTheme v0.0.0-20230927165800-342e2c850f18/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20231111235806-77931ac4875e h1:X4OxWNt7weGfmRHBAQWW1gsdZBd3V/6DJMNhrYS9ALE= +github.com/gohugoio/gohugoioTheme v0.0.0-20231111235806-77931ac4875e/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= @@ -69,10 +69,6 @@ ID = 'G-MBZGKNMDWC' includeNewer = true toLower = false [[related.indices]] - toLower = true - name = "relatedFunctions" - weight = 60 - [[related.indices]] name = "keywords" weight = 60 [[related.indices]] @@ -86,12 +82,6 @@ ID = 'G-MBZGKNMDWC' weight = 60 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 -# have been pulled into this repo. -[social] - twitter = "GoHugoIO" - [imaging] # See https://github.com/disintegration/imaging # CatmullRom is a sharp bicubic filter which should fit the docs site well with its many screenshots. diff --git a/layouts/_default/page.html b/layouts/_default/page.html deleted file mode 100644 index 2435e3ed7..000000000 --- a/layouts/_default/page.html +++ /dev/null @@ -1,34 +0,0 @@ -<header class="flex-none w-100"> - {{ if .Params.categories }} - {{ range .Params.categories }} - <a href="{{ "/categories/" | relLangURL }}{{ . | urlize }}" class="f6 fw8 mb0 link mid-gray dim mr3"> - {{ humanize . | upper }} - </a> - {{ end }} - {{end}} - <h1 class="lh-title mb3 mv0 pt3 primary-color-dark"> - {{ .Title }} - </h1> -</header> - -<aside class="bt bw1 pt3 mt2 mid-gray b--mid-gray fn w-100"> - {{ with .Params.description }} - <div class="f4 fw4 lh-copy"> - {{ . | markdownify }} - </div> - {{ end }} - - <!-- - NOTE: Removed to test builds without it. - partial "components/author-github-data" (dict "context" . "size" "110") --> -</aside> - -{{ with .Params.featured_image_path }} - <img src="{{ . }}" alt="Featured Image for {{ $.Title }}" class="mw-100"> -{{ end }} - -<div class="prose prose-{{ .Type }}" id="prose"> - {{- partial "docs/functions-signatures.html" . -}} - {{- partial "docs/functions-aliases.html" . -}} - {{ .Content }} -</div> diff --git a/layouts/news/list.html b/layouts/news/list.html deleted file mode 100644 index 32f72a446..000000000 --- a/layouts/news/list.html +++ /dev/null @@ -1,70 +0,0 @@ -{{ define "main" }} -<div class="w-100 ph4 ph5-ns pb5 pb6-ns pt1 pt3-ns "> - - <article class="cf pa3 pa4-m pa4-l nested-copy-line-height nested-img"> - <h1 class="primary-color-dark"> - {{ .Title }} - </h1> - <div class="nested-copy-line-height"> - {{ .Content }} - </div> - </article> - - <div class="flex flex-wrap"> - {{ $interior_classes := $.Site.Params.flex_box_interior_classes }} - <section class="flex-ns flex-wrap justify-between w-100 w-80-nsTK v-top"> - - {{ $news_items := slice }} - - {{/* Get releases from GitHub. */}} - {{ $u := "https://api.github.com/repos/gohugoio/hugo/releases" }} - {{ $releases := partial "inline/get-remote-data.html" $u }} - {{ $releases = where $releases "draft" false }} - {{ $releases = where $releases "prerelease" false }} - {{ range $releases | first 20 }} - {{ $ctx := dict - "Date" (.published_at | time.AsTime) - "Title" (printf "Release %s" .name) - "Permalink" .html_url - "Section" "news" - "Summary" "" - }} - {{ $news_items = $news_items | append $ctx }} - {{ end }} - - {{/* Get content pages from news section. */}} - {{ range .Pages }} - {{ $ctx := dict - "Date" .Date - "Title" .Title - "RelPermalink" .RelPermalink - "Section" "news" - "Summary" .Summary - "Params" (dict "description" .Description) - }} - {{ $news_items = $news_items | append $ctx }} - {{ end }} - - {{/* Sort by date (descending) and render. */}} - {{ range sort $news_items "Date" "desc" }} - {{ partial "boxes-section-summaries" (dict "context" . "classes" $interior_classes "fullcontent" false) }} - {{ end }} - - </section> - </div> - -</div> -{{ end }} - -{{ define "partials/inline/get-remote-data.html" }} - {{ $u := . }} - {{ $r := "" }} - {{ with $r = resources.GetRemote $u }} - {{ with .Err }} - {{ errorf "%s" . }} - {{ end }} - {{ else }} - {{ errorf "Unable to get remote resource %q" $u }} - {{ end }} - {{ return ($r | transform.Unmarshal) }} -{{ end }} diff --git a/layouts/partials/boxes-section-summaries.html b/layouts/partials/boxes-section-summaries.html deleted file mode 100644 index 268336cf5..000000000 --- a/layouts/partials/boxes-section-summaries.html +++ /dev/null @@ -1,38 +0,0 @@ -<div class="relative {{ .classes }} weight-{{ .context.Weight }}"> - <div class="bg-white mb2 pa3 pa4-l gray"> - - {{ $href := .context.RelPermalink }} - {{ if eq .context.Section "news" }} - {{ $href = .context.Permalink }} - <time class="f6 db" datetime="{{ .context.Date.Format `2006-01-02T15:04:05Z07:00` }}"> - {{ .context.Date.Format "January 2, 2006" }} - </time> - {{ end }} - - <h1 class="near-black f3"> - <a href="{{ $href }}" class="link primary-color dim"> - {{- if eq .context.Section "functions" -}} - {{ .context.LinkTitle }} - {{- else -}} - {{ .context.Title }} - {{- end -}} - </a> - </h1> - - <div class="lh-copy links"> - {{ if eq .context.Section "commands" }} - {{ replaceRE `(?s).*?##\s.*?\n\n(.*?)\n.*` "$1" .context.RawContent }} - {{ else }} - {{ if .context.Params.description }} - {{ .context.Params.description | markdownify }} - {{ else }} - {{ .context.Summary }} - {{ end }} - {{ end }} - <a href="{{ $href }}" class="f6 mt2 db link primary-color dim"> - Read More » - </a> - </div> - - </div> -</div> diff --git a/layouts/partials/boxes-small-news.html b/layouts/partials/boxes-small-news.html deleted file mode 100644 index 0d53c5465..000000000 --- a/layouts/partials/boxes-small-news.html +++ /dev/null @@ -1 +0,0 @@ -{{/* Empty for now. */}} diff --git a/layouts/partials/docs/functions-aliases.html b/layouts/partials/docs/functions-aliases.html deleted file mode 100644 index b0ba9be02..000000000 --- a/layouts/partials/docs/functions-aliases.html +++ /dev/null @@ -1,12 +0,0 @@ -{{- with .Params.function.aliases }} - {{- $label := "Alias" }} - {{- if gt (len .) 1 }} - {{- $label = "Aliases" }} - {{- end }} - <h2 class="minor mb1 primary-color-dark">{{ $label }}</h2> - {{- range . }} - <pre class="f5 mb4 ph3 pv2 bg-light-gray" style="border-left:4px solid #0594CB;"> - {{- . -}} - </pre> - {{- end }} -{{- end -}} diff --git a/layouts/partials/hooks/before-body-end.html b/layouts/partials/hooks/before-body-end.html deleted file mode 100644 index dab653508..000000000 --- a/layouts/partials/hooks/before-body-end.html +++ /dev/null @@ -1,7 +0,0 @@ -{{ if .Page.Store.Get "hasMermaid" }} - <script type="module" async> - import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9/+esm'; - - mermaid.initialize({ startOnLoad: true }); - </script> -{{ end }} diff --git a/layouts/partials/related.html b/layouts/partials/related.html deleted file mode 100644 index 05a2e9160..000000000 --- a/layouts/partials/related.html +++ /dev/null @@ -1,17 +0,0 @@ -{{- $heading := "See also" }} -{{- $related := site.RegularPages.Related . | first 5 }} - -{{- if eq .Type "functions" }} - {{- $heading = "Related functions" }} - {{- $opts := dict "document" . "indices" (slice "relatedFunctions") }} - {{- $related = site.RegularPages.Related $opts | first 7 }} -{{- end }} - -{{- with $related }} - <h2>{{ $heading }}</h2> - <ul> - {{- range . }} - <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> - {{- end }} - </ul> -{{- end }} diff --git a/layouts/shortcodes/code-toggle.html b/layouts/shortcodes/code-toggle.html deleted file mode 100644 index 6e0e3d73e..000000000 --- a/layouts/shortcodes/code-toggle.html +++ /dev/null @@ -1,101 +0,0 @@ -{{- /* - Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats. - - @param {string} [config] The section of site.Data.docs.config to render. - @param {bool} [copy=true] If true, display a copy to clipboard button. - @param {string} [file] The file name to display above the rendered code. - @param {bool} [fm=false] If true, render the code as front matter. - @param {bool} [skipHeader=false] If false, omit top level key(s) when rendering a section of site.Data.docs.config. - - @returns {template.HTML} -*/}} - -{{- /* Initialize. */}} -{{- $config := "" }} -{{- $dataKey := "" }} -{{- $copy := true }} -{{- $file := "" }} -{{- $fm := false }} -{{- $skipHeader := false }} - -{{- /* Get parameters. */}} -{{- $config = .Get "config" }} -{{- $dataKey = .Get "dataKey" }} -{{- $file = .Get "file" }} -{{- if in (slice "false" false 0) (.Get "copy") }} - {{- $copy = false }} -{{- else if in (slice "true" true 1) (.Get "copy") }} - {{- $copy = true }} -{{- end }} -{{- if in (slice "false" false 0) (.Get "fm") }} - {{- $fm = false }} -{{- else if in (slice "true" true 1) (.Get "fm") }} - {{- $fm = true }} -{{- end }} -{{- if in (slice "false" false 0) (.Get "skipHeader") }} - {{- $skipHeader = false }} -{{- else if in (slice "true" true 1) (.Get "skipHeader") }} - {{- $skipHeader = true }} -{{- end }} - -{{- /* Define constants. */}} -{{- $delimiters := dict "toml" "+++" "yaml" "---" }} -{{- $langs := slice "yaml" "toml" "json" }} -{{- $placeHolder := "#-hugo-placeholder-#" }} - -{{- /* Render. */}} -{{- $code := "" }} -{{- if $config }} - {{- $file = $file | default "hugo" }} - {{- $sections := (split $config ".") }} - {{- $configSection := index $.Site.Data.docs.config $sections }} - {{- $code = dict $sections $configSection }} - {{- if $skipHeader }} - {{- $code = $configSection }} - {{- end }} -{{- else if $dataKey }} - {{- $file = $file | default $dataKey }} - {{- $sections := (split $dataKey ".") }} - {{- $code = index $.Site.Data.docs $sections }} -{{- else }} - {{- $code = $.Inner }} -{{- end }} -<div class="code relative" {{ with $file }}id="{{ . | urlize }}"{{ end }}> - <div class="code-nav flex flex-nowrap items-stretch"> - {{- with $file }} - <div class="san-serif f6 dib lh-solid pl2 pv2 mr2"> - {{ . }}{{ if not $fm }}.{{ end }} - </div> - {{- end }} - {{- range $langs }} - <button - data-toggle-tab="{{ . }}" - class="tab-button {{ cond (eq . "yaml") "active" "" }} ba san-serif f6 dib lh-solid ph2 pv2"> - {{ . }} - </button> - - {{- end }} - </div> - <div class="tab-content"> - {{- range $langs }} - <div - data-pane="{{ . }}" - class="code-copy-content nt3 tab-pane {{ cond (eq . "yaml") "active" "" }}"> - {{- $hCode := $code | transform.Remarshal . }} - {{- if and $fm (in (slice "toml" "yaml") .) }} - {{- $hCode = printf "%s\n%s\n%s" $placeHolder $hCode $placeHolder }} - {{- end }} - {{- $hCode = $hCode | replaceRE `\n+` "\n" }} - {{ highlight $hCode . "" | replaceRE $placeHolder (index $delimiters .) | safeHTML }} - </div> - {{- if $copy }} - <button - class="needs-js copy copy-toggle bg-accent-color-dark f6 absolute top-0 right-0 lh-solid hover-bg-primary-color-dark bn white ph3 pv2" - title="Copy this code to your clipboard." - data-clipboard-action="copy" - aria-label="copy button"></button> - {{- /* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}} - {{- end }} - {{- end }} - </div> -</div> diff --git a/layouts/shortcodes/code.html b/layouts/shortcodes/code.html deleted file mode 100644 index 31ca27596..000000000 --- a/layouts/shortcodes/code.html +++ /dev/null @@ -1,39 +0,0 @@ -{{- /* -Renders syntax highlighted code. - -@param {bool} [copy=true] If true, display a copy to clipboard button. -@param {string} [file] The file name to display above the rendered code. -@param {string} [lang] The code language of the inner content. - -@returns {template.HTML} -*/}} - -{{- /* Initialize. */}} -{{- $copy := true }} -{{- $file := " " }} -{{- $lang := "" }} - -{{- /* Get parameters. */}} -{{- $file = .Get "file" }} -{{- $lang = or (.Get "lang") (path.Ext $file | strings.TrimPrefix ".") "text" }} -{{- if in (slice "false" false 0) (.Get "copy") }} - {{- $copy = false }} -{{- else if in (slice "true" true 1) (.Get "copy")}} - {{- $copy = true }} -{{- end }} - -{{- /* Use the go-html-template Chroma lexer for HTML. */}} -{{- if eq $lang "html" }} - {{- $lang = "go-html-template" }} -{{- end }} - -{{- /* Render. */}} -<div class="code relative" id="{{ $file | urlize }}"> - <div class="f6 dib lh-solid pl2 pv2">{{ or $file "nbsp;" }}</div> - {{- if $copy }} - <button class="needs-js copy bg-accent-color-dark f6 absolute top-0 right-0 lh-solid hover-bg-primary-color-dark bn white ph3 pv2" title="Copy this code to your clipboard." data-clipboard-action="copy" aria-label="copy button"></button> - {{- end }} - <div class="code-copy-content nt3"> - {{- highlight (trim .Inner "\n\r") $lang }} - </div> -</div> diff --git a/layouts/shortcodes/datatable.html b/layouts/shortcodes/datatable.html deleted file mode 100644 index 12054f89d..000000000 --- a/layouts/shortcodes/datatable.html +++ /dev/null @@ -1,33 +0,0 @@ -{{ $package := (index .Params 0) }} -{{ $listname := (index .Params 1) }} -{{ $list := (index (index .Site.Data.docs $package) $listname) }} -{{ $fields := after 2 .Params }} - - -<table class="table table-bordered"> - <tr> - {{ range $fields }} - {{ $s := . }} - {{ if eq $s "_key" }} - {{ $s = "Type" }} - {{ end }} - <th>{{ $s }}</th> - {{ end }} - </tr> - {{ range $k1, $v1 := $list }} - <tr> - {{ range $k2, $v2 := . }} - {{ $.Scratch.Set $k2 $v2 }} - {{ end }} - {{ range $fields }} - {{ $s := "" }} - {{ if eq . "_key" }} - {{ $s = $k1 }} - {{ else }} - {{ $s = $.Scratch.Get . }} - {{ end }} - <td>{{ $s }}</td> - {{ end }} - </tr> - {{ end }} -</table> diff --git a/layouts/shortcodes/getcontent.html b/layouts/shortcodes/getcontent.html deleted file mode 100644 index 6ae35dd6d..000000000 --- a/layouts/shortcodes/getcontent.html +++ /dev/null @@ -1,21 +0,0 @@ -<!-- {{/* -Insert `.Content` from a (headless) bundle. You can insert `.Content` from multiple page resources of the same bundle by specifying `glob`. - -Usage: {{< getcontent path="PATH/TO/FILE" >}} - {{< getcontent path="PATH/TO/BUNDLE/" glob="*_PATTERN.md" >}} -*/}} --> -{{- $path := .Get "path" -}} -{{ $glob := .Get "glob" -}} - -{{ $resources := slice -}} -{{ with $glob -}} - {{ $bundle := site.GetPage $path -}} - {{ $resources = $bundle.Resources.Match $glob -}} -{{ else -}} - {{ $bundle := site.GetPage (path.Dir $path) -}} - {{ $resources = $bundle.Resources.Match (path.Base $path) -}} -{{ end -}} - -{{ range $resources -}} - {{ .Content }} -{{ end -}} diff --git a/layouts/shortcodes/imgproc.html b/layouts/shortcodes/imgproc.html deleted file mode 100644 index f792702ce..000000000 --- a/layouts/shortcodes/imgproc.html +++ /dev/null @@ -1,26 +0,0 @@ -{{ $img := .Page.Resources.GetMatch (printf "*%s*" (.Get 0)) }} -{{ $command := .Get 1 }} -{{ $options := .Get 2 }} -{{ if eq $command "Fit"}} - {{ $img = $img.Fit $options }} -{{ else if eq $command "Resize"}} - {{ $img = $img.Resize $options }} -{{ else if eq $command "Fill"}} - {{ $img = $img.Fill $options }} -{{ else if eq $command "Crop"}} - {{ $img = $img.Crop $options }} -{{ else }} - {{ errorf "Invalid image processing command: Must be one of Crop, Fit, Fill or Resize."}} -{{ end }} -<figure style="padding: 0.25rem; margin: 2rem 0; background-color: #cccc"> - <img style="max-width: 100%; width: auto; height: auto;" src="{{ $img.RelPermalink }}" width="{{ $img.Width }}" height="{{ $img.Height }}"> - <figcaption> - <small> - {{ with .Inner }} - {{ . }} - {{ else }} - .{{ $command }} "{{ $options }}" - {{ end }} - </small> - </figcaption> -</figure> diff --git a/layouts/shortcodes/new-in.html b/layouts/shortcodes/new-in.html index 71d1abfdf..e22a91f3d 100644 --- a/layouts/shortcodes/new-in.html +++ b/layouts/shortcodes/new-in.html @@ -1,13 +1,36 @@ -{{ $version := .Get 0 }} -{{ if not $version }} - {{ errorf "Missing version in new-in shortcode " }} -{{ end }} -{{ $version = $version | strings.TrimPrefix "v" }} -<button - class="bg-white hover:bg-gray-100 text-gray-800 font-semibold py-2 mr2 ml2 px-4 border border-gray-400 rounded shadow"> - <a - href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}" - target="_blank" - >New in v{{ $version }}</a - > -</button> +{{- /* +Renders a "new in" button indicating the version in which a feature was added. + +When comparing the current version to the specified version, the "new in" +button will be hidden if any of the following conditions is true: + +- The major version difference exceeds the majorVersionDiffThreshold +- The minor version difference exceeds the minorVersionDiffThreshold + +@param {string} version The semantic version string, with or without a leading v. +@returns {template.HTML} + +@example {{< new-in 0.100.0 >}} +*/}} + +{{- /* Set defaults. */}} +{{- $majorVersionDiffThreshold := 0 }} +{{- $minorVersionDiffThreshold := 30 }} +{{- $displayExpirationWarning := true }} + +{{- /* Render. */}} +{{- with $version := .Get 0 | strings.TrimPrefix "v" }} + {{- $majorVersionDiff := sub (index (split hugo.Version ".") 0 | int) (index (split $version ".") 0 | int) }} + {{- $minorVersionDiff := sub (index (split hugo.Version ".") 1 | int) (index (split $version ".") 1 | int) }} + {{- if or (gt $majorVersionDiff $majorVersionDiffThreshold) (gt $minorVersionDiff $minorVersionDiffThreshold) }} + {{- if $displayExpirationWarning }} + {{- warnf "This call to the %q shortcode should be removed: %s. The button is now hidden because the specified version (%s) is older than the display threshold." $.Name $.Position $version }} + {{- end }} + {{- else }} + <button class="bg-white hover:bg-gray-100 text-gray-800 font-semibold py-2 mr2 px-4 border border-gray-400 rounded shadow"> + <a href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}">New in v{{ $version }}</a> + </button> + {{- end }} +{{- else }} + {{- errorf "The %q shortcode requires a positional parameter (version). See %s" .Name .Position }} +{{- end -}} diff --git a/layouts/shortcodes/readfile.html b/layouts/shortcodes/readfile.html deleted file mode 100644 index 36400ac55..000000000 --- a/layouts/shortcodes/readfile.html +++ /dev/null @@ -1,8 +0,0 @@ -{{$file := .Get "file"}} -{{- if eq (.Get "markdown") "true" -}} -{{- $file | readFile | markdownify -}} -{{- else if (.Get "highlight") -}} -{{- highlight ($file | readFile) (.Get "highlight") "" -}} -{{- else -}} -{{ $file | readFile | safeHTML }} -{{- end -}}
\ No newline at end of file diff --git a/netlify.toml b/netlify.toml index d65e08c25..cc46695a5 100644 --- a/netlify.toml +++ b/netlify.toml @@ -3,7 +3,7 @@ command = "hugo --gc --minify" [build.environment] - HUGO_VERSION = "0.119.0" + HUGO_VERSION = "0.120.4" [context.production.environment] HUGO_ENV = "production" |
