From: Bjørn Erik Pedersen Date: Sat, 29 Jul 2023 09:17:28 +0000 (+0200) Subject: Merge commit '87de22d7464e239c775fbd48ebce1665d5b1e80d' X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=8859be1c0;p=brevno-suite%2Fhugo Merge commit '87de22d7464e239c775fbd48ebce1665d5b1e80d' --- 8859be1c01eac8b7423b9ff515c2d8c5c3d9d754 diff --cc docs/.github/SUPPORT.md index cc9de09ff,000000000..96a4400c3 mode 100644,000000..100644 --- a/docs/.github/SUPPORT.md +++ b/docs/.github/SUPPORT.md @@@ -1,3 -1,0 +1,3 @@@ - ### Asking Support Questions ++### Asking support questions + +We have an active [discussion forum](https://discourse.gohugo.io) where users and developers can ask questions. Please don't use the GitHub issue tracker to ask questions. diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/bep-consulting.svg index 5b1170f9b,000000000..598a1eb71 mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/bep-consulting.svg +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/bep-consulting.svg @@@ -1,3 -1,0 +1,4 @@@ -

Hugo Sponsors

+ {{ range .banners }} +

+ {{ $query_params := .query_params | default "" }} - {{ $url := printf "%s?%s%s" .link $query_params (querify "utm_source" $utmSource "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor")) | safeURL }} ++ {{ $url := printf "%s?%s%s" .link $query_params (querify "utm_source" (.utm_source | default $utmSource ) "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor") "utm_content" (.utm_content | default "gohugoio")) | safeURL }} + {{ $logo := resources.Get .logo }} + {{ if hugo.IsProduction }} + {{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }} + - {{ $logo.Content | safeHTML }} ++ {{ with $logo }}{{ .Content | safeHTML }}{{ end }} + + {{ else }} + - {{ $logo.Content | safeHTML }} ++ {{ with $logo }}{{ .Content | safeHTML }}{{ end }} + + {{ end }} +

+ {{ end }} +

+ +{{ end }} diff --cc docs/_vendor/modules.txt index 1c7cac307,000000000..18258d30d mode 100644,000000..100644 --- a/docs/_vendor/modules.txt +++ b/docs/_vendor/modules.txt @@@ -1,1 -1,0 +1,1 @@@ - # github.com/gohugoio/gohugoioTheme v0.0.0-20230527124826-78bc315d7b8a ++# github.com/gohugoio/gohugoioTheme v0.0.0-20230630055807-9874cd863bc5 diff --cc docs/config/_default/menus/menus.en.toml index 7a956a47f,000000000..327a5777b mode 100644,000000..100644 --- a/docs/config/_default/menus/menus.en.toml +++ b/docs/config/_default/menus/menus.en.toml @@@ -1,142 -1,0 +1,142 @@@ +[[docs]] + name = "About Hugo" + weight = 10 + identifier = "about" + url = "/about/" + +[[docs]] + name = "Installation" + weight = 20 + identifier = "installation" + url = "/installation/" + +[[docs]] - name = "Getting Started" ++ name = "Getting started" + weight = 30 + identifier = "getting-started" + url = "/getting-started/" + +[[docs]] + name = "Hugo Modules" + weight = 40 + identifier = "modules" + post = "break" + url = "/hugo-modules/" + +# Core menus + +[[docs]] - name = "Content Management" ++ name = "Content management" + weight = 50 + identifier = "content-management" + post = "expanded" + url = "/content-management/" + +[[docs]] + name = "Templates" + weight = 60 + identifier = "templates" + url = "/templates/" + +[[docs]] + name = "Functions" + weight = 70 + identifier = "functions" + url = "/functions/" + +[[docs]] + name = "Variables" + weight = 80 + identifier = "variables" + url = "/variables/" + +[[docs]] + name = "Hugo Pipes" + weight = 90 - identifier = "pipes" ++ identifier = "hugo-pipes" + url = "/hugo-pipes/" + +[[docs]] + name = "CLI" + weight = 100 + post = "break" + identifier = "commands" + url = "/commands/" + +# Low level items + +[[docs]] + name = "Troubleshooting" + weight = 110 + identifier = "troubleshooting" + url = "/troubleshooting/" + +[[docs]] - name = "Tools" ++ name = "Developer tools" + weight = 120 - identifier = "tools" ++ identifier = "developer-tools" + url = "/tools/" + +[[docs]] - name = "Hosting & Deployment" ++ name = "Hosting and deployment" + weight = 130 + identifier = "hosting-and-deployment" + url = "/hosting-and-deployment/" + +[[docs]] + name = "Contribute" + weight = 140 + post = "break" + identifier = "contribute" + url = "/contribute/" + +######## QUICKLINKS + +[[quicklinks]] + name = "Fundamentals" + weight = 1 + identifier = "fundamentals" + url = "/tags/fundamentals/" + +######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES + +[[global]] + name = "News" + weight = 1 + identifier = "news" + url = "/news/" + +[[global]] + name = "Docs" + weight = 5 + identifier = "docs" + url = "/documentation/" + +[[global]] + name = "Themes" + weight = 10 + identifier = "themes" + url = "https://themes.gohugo.io/" + +[[global]] + name = "Showcase" + weight = 20 + identifier = "showcase" + url = "/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/" + +[[global]] + name = "GitHub" + weight = 200 + identifier = "github" + post = "external" + url = "https://github.com/gohugoio/hugo" diff --cc docs/content/en/_index.md index b4e602438,000000000..69d40ebcf mode 100644,000000..100644 --- a/docs/content/en/_index.md +++ b/docs/content/en/_index.md @@@ -1,49 -1,0 +1,49 @@@ +--- - title: "The worldâs fastest framework for building websites" ++title: The worldâs fastest framework for building websites +date: 2017-03-02T12:00:00-05:00 +features: + - heading: Blistering Speed + image_path: /images/icon-fast.svg + tagline: What's modern about waiting for your site to build? + copy: Hugo is the fastest tool of its kind. At <1 ms per page, the average site builds in less than a second. + + - heading: Robust Content Management + image_path: /images/icon-content-management.svg + tagline: Flexibility rules. Hugo is a content strategist's dream. + copy: Hugo supports unlimited content types, taxonomies, menus, dynamic API-driven content, and more, all without plugins. + + - heading: Shortcodes + image_path: /images/icon-shortcodes.svg + tagline: Hugo's shortcodes are Markdown's hidden superpower. + copy: We love the beautiful simplicity of markdownâs syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility. + + - heading: Built-in Templates + image_path: /images/icon-built-in-templates.svg + tagline: Hugo has common patterns to get your work done quickly. + copy: Hugo ships with pre-made templates to make quick work of SEO, commenting, analytics and other functions. One line of code, and you're done. + + - heading: Multilingual and i18n + image_path: /images/icon-multilingual2.svg + tagline: Polyglot baked in. + copy: Hugo provides full i18n support for multi-language sites with the same straightforward development experience Hugo users love in single-language sites. + + - heading: Custom Outputs + image_path: /images/icon-custom-outputs.svg + tagline: HTML not enough? + copy: Hugo allows you to output your content in multiple formats, including JSON or AMP, and makes it easy to create your own. +sections: + - heading: "300+ Themes" + cta: Check out the Hugo themes. + link: https://themes.gohugo.io/ + color_classes: bg-accent-color white + image: /images/homepage-screenshot-hugo-themes.jpg + copy: "Hugo provides a robust theming system that is easy to implement but capable of producing even the most complicated websites." + - heading: "Capable Templating" + cta: Get Started. + link: templates/ + color_classes: bg-primary-color-light black + image: /images/home-page-templating-example.png + copy: "Hugo's Go-based templating provides just the right amount of logic to build anything from the simple to complex." +--- + +Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again. diff --cc docs/content/en/about/_index.md index 91260a4a6,000000000..3a8319029 mode 100644,000000..100644 --- a/docs/content/en/about/_index.md +++ b/docs/content/en/about/_index.md @@@ -1,15 -1,0 +1,16 @@@ +--- +title: About Hugo - linktitle: Overview ++linkTitle: Overview +description: Hugo's features, roadmap, license, and motivation. +categories: [] +keywords: [] +menu: + docs: ++ identifier: about-hugo-overview + parent: about - weight: 1 - weight: 1 ++ weight: 10 ++weight: 10 +aliases: [/about-hugo/,/docs/] +--- + +Hugo is not your average static site generator. diff --cc docs/content/en/about/benefits.md index 91c243413,000000000..f1fc0cfb6 mode 100644,000000..100644 --- a/docs/content/en/about/benefits.md +++ b/docs/content/en/about/benefits.md @@@ -1,35 -1,0 +1,35 @@@ +--- - title: The Benefits of Static Site Generators - linktitle: The Benefits of Static ++title: Benefits of static site generators ++linkTitle: Static site generators +description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing. +keywords: [ssg,static,performance,security] +menu: + docs: + parent: about - weight: 30 - weight: 30 ++ weight: 40 ++weight: 40 +--- + +The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page. + +Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page. + +Hugo takes caching a step further and all HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*. + +This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site. + - ## More on Static Site Generators ++## More on static site generators + +* ["An Introduction to Static Site Generators", David Walsh] +* ["Hugo vs. WordPress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress] +* ["Static Site Generators", O'Reilly] +* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)] +* ["Top 10 Static Website Generators", Netlify blog] +* ["The Resurgence of Static", dotCMS][dotcms] + +["An Introduction to Static Site Generators", David Walsh]: https://davidwalsh.name/introduction-static-site-generators +["Static Site Generators", O'Reilly]: https://github.com/gohugoio/hugoDocs/files/1242701/static-site-generators.pdf +["Top 10 Static Website Generators", Netlify blog]: https://www.netlify.com/blog/2016/05/02/top-ten-static-website-generators/ +[hugovwordpress]: https://gettingthingstech.com/hugo-vs.-wordpress-page-load-speed-comparison-hugo-leaves-wordpress-in-its-dust/ +[StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]: https://www.staticgen.com/ +[dotcms]: https://dotcms.com/blog/post/the-resurgence-of-static diff --cc docs/content/en/about/features.md index 6fac68cdd,000000000..dcb85e8b5 mode 100644,000000..100644 --- a/docs/content/en/about/features.md +++ b/docs/content/en/about/features.md @@@ -1,78 -1,0 +1,78 @@@ +--- - title: Hugo Features ++title: Hugo features +description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites. +menu: + docs: + parent: about - weight: 20 - weight: 20 ++ weight: 30 ++weight: 30 +toc: true +--- + +## General + +* [Extremely fast] build times (< 1 ms per page) +* Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more +* Renders changes on the fly with [LiveReload] as you develop +* [Powerful theming] +* [Host your site anywhere][hostanywhere] + +## Organization + +* Straightforward [organization for your projects], including website sections +* Customizable [URLs] +* Support for configurable [taxonomies], including categories and tags +* [Sort content] as you desire through powerful template [functions] +* Automatic [table of contents] generation +* [Dynamic menu] creation +* [Pretty URLs] support +* [Permalink] pattern support +* Redirects via [aliases] + +## Content + +* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats]) +* TOML, YAML, and JSON metadata support in [front matter] +* Customizable [homepage] +* Multiple [content types] +* Automatic and user defined [content summaries] +* [Shortcodes] to enable rich content inside of Markdown +* ["Minutes to Read"][pagevars] functionality +* ["WordCount"][pagevars] functionality + - ## Additional Features ++## Additional features + +* Integrated [Disqus] comment support +* Integrated [Google Analytics] support +* Automatic [RSS] creation +* Support for [Go] HTML templates +* [Syntax highlighting] powered by [Chroma] + +[aliases]: /content-management/urls/#aliases +[Chroma]: https://github.com/alecthomas/chroma +[content summaries]: /content-management/summaries/ +[content types]: /content-management/types/ +[Disqus]: https://disqus.com/ +[Dynamic menu]: /templates/menu-templates/ +[Extremely fast]: https://github.com/bep/hugo-benchmark +[front matter]: /content-management/front-matter/ +[functions]: /functions/ +[Go]: https://pkg.go.dev/html/template +[Google Analytics]: https://google-analytics.com/ +[homepage]: /templates/homepage/ +[hostanywhere]: /hosting-and-deployment/ +[install]: /installation/ +[LiveReload]: /getting-started/usage/ +[organization for your projects]: /getting-started/directory-structure/ +[pagevars]: /variables/page/ +[Permalink]: /content-management/urls/#permalinks +[Powerful theming]: /hugo-modules/theme-components/ +[Pretty URLs]: /content-management/urls/ +[RSS]: /templates/rss/ +[Shortcodes]: /content-management/shortcodes/ +[sort content]: /templates/ +[supported formats]: /content-management/formats/ +[Syntax highlighting]: /content-management/syntax-highlighting/ +[table of contents]: /content-management/toc/ +[taxonomies]: /content-management/taxonomies/ +[URLs]: /content-management/urls/ diff --cc docs/content/en/about/hugo-and-gdpr.md index b028c4543,000000000..d82368afc mode 100644,000000..100644 --- a/docs/content/en/about/hugo-and-gdpr.md +++ b/docs/content/en/about/hugo-and-gdpr.md @@@ -1,134 -1,0 +1,134 @@@ +--- - title: Hugo and the General Data Protection Regulation (GDPR) - linktitle: Hugo and GDPR ++title: Hugo and the General Data Protection Regulation ++linkTitle: Hugo and the GDPR +description: About how to configure your Hugo site to meet the new regulations. +layout: single +keywords: ["GDPR", "Privacy", "Data Protection"] +menu: + docs: + parent: about - weight: 5 - weight: 5 ++ weight: 60 ++weight: 60 +aliases: [/privacy/,/gdpr/] +toc: true +--- + + 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. + + **Hugo is a static site generator. By using Hugo you are already standing on very solid ground. Static HTML files on disk are much easier to reason about compared to server and database driven web sites.** + - But even static websites can integrate with external services, so from version `0.41`, Hugo provides a **Privacy Config** that covers the relevant built-in templates. ++ But even static websites can integrate with external services, so from version `0.41`, Hugo provides a **privacy configuration** that covers the relevant built-in templates. + + Note that: + + * These settings have their defaults setting set to _off_, i.e. how it worked before Hugo `0.41`. You must do your own evaluation of your site and apply the appropriate settings. + * These settings work with the [internal templates](/templates/internal/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect. + * We will continue this work and improve this further in future Hugo versions. + - ## All Privacy Settings ++## All privacy settings + - Below are all privacy settings and their default value. These settings need to be put in your site config (e.g. `hugo.toml`). ++Below are all privacy settings and their default value. These settings need to be put in your site configuration (e.g. `hugo.toml`). + +{{< code-toggle file="hugo" >}} +[privacy] +[privacy.disqus] +disable = false +[privacy.googleAnalytics] +disable = false +respectDoNotTrack = false +anonymizeIP = false +useSessionStorage = false +[privacy.instagram] +disable = false +simple = false +[privacy.twitter] +disable = false +enableDNT = false +simple = false +[privacy.vimeo] +disable = false +enableDNT = false +simple = false +[privacy.youtube] +disable = false +privacyEnhanced = false +{{< /code-toggle >}} + - ## Disable All Services ++## Disable all services + - An example Privacy Config that disables all the relevant services in Hugo. With this configuration, the other settings will not matter. ++An example privacy configuration that disables all the relevant services in Hugo. With this configuration, the other settings will not matter. + - {{< code-toggle file="hugo" >}} ++{{< code-toggle file="hugo" >}} +[privacy] +[privacy.disqus] +disable = true +[privacy.googleAnalytics] +disable = true +[privacy.instagram] +disable = true +[privacy.twitter] +disable = true +[privacy.vimeo] +disable = true +[privacy.youtube] +disable = true +{{< /code-toggle >}} + - ## The Privacy Settings Explained ++## The privacy settings explained + +### GoogleAnalytics + +anonymizeIP +: Enabling this will make it so the users' IP addresses are anonymized within Google Analytics. + +respectDoNotTrack +: Enabling this will make the GA templates respect the "Do Not Track" HTTP header. + +useSessionStorage +: Enabling this will disable the use of Cookies and use Session Storage to Store the GA Client ID. + +{{% note %}} +`useSessionStorage` is not supported when using Google Analytics v4 (gtag.js). +{{% /note %}} + +### Instagram + +simple +: If simple mode is enabled, a static and no-JS version of the Instagram image card will be built. Note that this only supports image cards and the image itself will be fetched from Instagram's servers. + +**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" >}} +[services] +[services.instagram] +disableInlineCSS = true +{{< /code-toggle >}} + +### Twitter + +enableDNT +: Enabling this for the twitter/tweet shortcode, the tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads. + +simple +: If simple mode is enabled, a static and no-JS version of a tweet will be built. + +**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inline styles provided by Hugo: + + {{< code-toggle file="hugo" >}} +[services] +[services.twitter] +disableInlineCSS = true +{{< /code-toggle >}} + +### YouTube + +privacyEnhanced +: When you turn on privacy-enhanced mode, YouTube wonât store information about visitors on your website unless the user plays the embedded video. + +### Vimeo + +enableDNT +: Enabling this for the vimeo shortcode, the Vimeo player will be blocked from tracking any session data, including all cookies and stats. + +simple +: If simple mode is enabled, the video thumbnail is fetched from Vimeo's servers and it is overlayed with a play button. If the user clicks to play the video, it will open in a new tab directly on Vimeo's website. diff --cc docs/content/en/about/license.md index 267ec95a0,000000000..dc560b33f mode 100644,000000..100644 --- a/docs/content/en/about/license.md +++ b/docs/content/en/about/license.md @@@ -1,161 -1,0 +1,160 @@@ +--- - title: Apache License - linktitle: License ++title: License +description: Hugo v0.15 and later are released under the Apache 2.0 license. +categories: ["about hugo"] +keywords: ["License","apache"] +menu: + docs: + parent: about - weight: 60 - weight: 60 ++ weight: 70 ++weight: 70 +aliases: [/meta/license] +toc: true +--- + +{{% 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_
+ + +*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. + +{{< code file="apache-notice.txt" >}} +Copyright [yyyy] [name of copyright owner] + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +{{< /code >}} diff --cc docs/content/en/about/security-model/index.md index a909a4236,000000000..3b93167ab mode 100644,000000..100644 --- a/docs/content/en/about/security-model/index.md +++ b/docs/content/en/about/security-model/index.md @@@ -1,63 -1,0 +1,63 @@@ +--- - title: Hugo's Security Model ++title: Hugo's security model +description: A summary of Hugo's security model. +layout: single +keywords: ["Security", "Privacy"] +menu: + docs: + parent: about - weight: 4 - weight: 5 ++ weight: 50 ++weight: 50 +aliases: [/security/] +toc: true +--- + - ## Runtime Security ++## Runtime security + +Hugo produces static output, so once built, the runtime is the browser (assuming the output is HTML) and any server (API) that you integrate with. + +But when developing and building your site, the runtime is the `hugo` executable. Securing a runtime can be [a real challenge](https://blog.logrocket.com/how-to-protect-your-node-js-applications-from-malicious-dependencies-5f2e60ea08f9/). + +**Hugo's main approach is that of sandboxing and a security policy with strict defaults:** + +* Hugo has a virtual file system and only the main project (not third-party components) is allowed to mount directories or files outside the project root. +* Only the main project can walk symbolic links. +* User-defined components have read-only access to the filesystem. +* We shell out to some external binaries to support [Asciidoctor](/content-management/formats/#list-of-content-formats) and similar, but those binaries and their flags are predefined and disabled by default (see [Security Policy](#security-policy)). General functions to run arbitrary external OS commands have been [discussed](https://github.com/gohugoio/hugo/issues/796), but not implemented because of security concerns. + - ## Security Policy ++## Security policy + +Hugo has a built-in security policy that restricts access to [os/exec](https://pkg.go.dev/os/exec), remote communication and similar. + +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" />}} + - Note that these and other config settings in Hugo can be overridden by the OS environment. If you want to block all remote HTTP fetching of data: ++Note that these and other configuration settings in Hugo can be overridden by the OS environment. If you want to block all remote HTTP fetching of data: + +```txt +HUGO_SECURITY_HTTP_URLS=none hugo +``` + - ## Dependency Security ++## Dependency security + +Hugo is built as a static binary using [Go Modules](https://github.com/golang/go/wiki/Modules) to manage its dependencies. Go Modules have several safeguards, one of them being the `go.sum` file. This is a database of the expected cryptographic checksums of all of your dependencies, including transitive dependencies. + +[Hugo Modules](/hugo-modules/) is a feature built on top of the functionality of Go Modules. Like Go Modules, a Hugo project using Hugo Modules will have a `go.sum` file. We recommend that you commit this file to your version control system. The Hugo build will fail if there is a checksum mismatch, which would be an indication of [dependency tampering](https://julienrenaux.fr/2019/12/20/github-actions-security-risk/). + - ## Web Application Security ++## Web application security + +These are the security threats as defined by [OWASP](https://en.wikipedia.org/wiki/OWASP). + +For HTML output, this is the core security model: + + + +In short: + +Template and configuration authors (you) are trusted, but the data you send in is not. +This is why you sometimes need to use the _safe_ functions, such as `safeHTML`, to avoid escaping of data you know is safe. +There is one exception to the above, as noted in the documentation: If you enable inline shortcodes, you also say that the shortcodes and data handling in content files are trusted, as those macros are treated as pure text. +It may be worth adding that Hugo is a static site generator with no concept of dynamic user input. + +For content, the default Markdown renderer is [configured](/getting-started/configuration-markup) to remove or escape potentially unsafe content. This behavior can be reconfigured if you trust your content. diff --cc docs/content/en/about/what-is-hugo.md index 3097de50e,000000000..9e28346dd mode 100644,000000..100644 --- a/docs/content/en/about/what-is-hugo.md +++ b/docs/content/en/about/what-is-hugo.md @@@ -1,56 -1,0 +1,56 @@@ +--- +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 +menu: + docs: + parent: about - weight: 10 - weight: 10 ++ weight: 20 ++weight: 20 +aliases: [/overview/introduction/,/about/why-i-built-hugo/] +toc: true +--- + +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. + +Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify], [Heroku], [GoDaddy], [DreamHost], [GitHub Pages], [GitLab Pages], [Surge], [Firebase], [Google Cloud Storage], [Amazon S3], [Rackspace], [Azure], and [CloudFront] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP. + +We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made. + - ## How Fast is Hugo? ++## How fast is Hugo? + +{{< youtube "CdiDYZ51a2o" >}} + - ## What Does Hugo Do? ++## What does Hugo do? + +In technical terms, Hugo takes a source directory of files and templates and uses these as input to create a complete website. + - ## Who Should Use Hugo? ++## Who should use Hugo? + +Hugo is for people that prefer writing in a text editor over a browser. + +Hugo is for people who want to hand code their own website without worrying about setting up complicated runtimes, dependencies and databases. + +Hugo is for people building a blog, a company site, a portfolio site, documentation, a single landing page, or a website with thousands of pages. + +[@spf13]: https://twitter.com/spf13 +[Amazon S3]: https://aws.amazon.com/s3/ +[Azure]: https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website +[CloudFront]: https://aws.amazon.com/cloudfront/ "Amazon CloudFront" +[DreamHost]: https://www.dreamhost.com/ +[Firebase]: https://firebase.google.com/docs/hosting/ "Firebase static hosting" +[GitHub Pages]: https://pages.github.com/ +[GitLab Pages]: https://about.gitlab.com/features/pages/ +[Go language]: https://go.dev/ +[GoDaddy]: https://www.godaddy.com/ "GoDaddy.com Hosting" +[Google Cloud Storage]: https://cloud.google.com/storage/ +[Heroku]: https://www.heroku.com/ +[Jekyll]: https://jekyllrb.com/ +[Middleman]: https://middlemanapp.com/ +[Nanoc]: https://nanoc.ws/ +[Netlify]: https://netlify.com +[Rackspace]: https://www.rackspace.com/cloud/files +[Surge]: https://surge.sh +[contributing to it]: https://github.com/gohugoio/hugo +[rackspace]: https://www.rackspace.com/openstack/public/files +[static site generator]: /about/benefits/ diff --cc docs/content/en/commands/hugo_completion_bash.md index 875ecfc19,000000000..231804d09 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_completion_bash.md +++ b/docs/content/en/commands/hugo_completion_bash.md @@@ -1,65 -1,0 +1,64 @@@ +--- +title: "hugo completion bash" +slug: hugo_completion_bash +url: /commands/hugo_completion_bash/ +--- +## hugo completion bash + +Generate the autocompletion script for bash + +### Synopsis + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(hugo completion bash) + +To load completions for every new session, execute once: + +#### Linux: + + hugo completion bash > /etc/bash_completion.d/hugo + +#### macOS: + + hugo completion bash > $(brew --prefix)/etc/bash_completion.d/hugo + +You will need to start a new shell for this setup to take effect. + + +``` +hugo completion bash +``` + +### Options + +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --logLevel string log level (debug|info|warn|error) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell - diff --cc docs/content/en/commands/hugo_convert.md index a4d0e501b,000000000..07f7f9c13 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_convert.md +++ b/docs/content/en/commands/hugo_convert.md @@@ -1,51 -1,0 +1,47 @@@ +--- +title: "hugo convert" +slug: hugo_convert +url: /commands/hugo_convert/ +--- +## hugo convert + +Convert your content to different formats + +### Synopsis + +Convert your content (e.g. front matter) to different formats. + +See convert's subcommands toJSON, toTOML and toYAML for more information. + - ``` - hugo convert [command] [flags] - ``` - +### Options + +``` + -h, --help help for convert + -o, --output string filesystem path to write files to + --unsafe enable less safe operations, please backup first +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --logLevel string log level (debug|info|warn|error) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site +* [hugo convert toJSON](/commands/hugo_convert_tojson/) - Convert front matter to JSON +* [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML +* [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML + diff --cc docs/content/en/commands/hugo_gen.md index 620d60676,000000000..5c8bd6f2c mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_gen.md +++ b/docs/content/en/commands/hugo_gen.md @@@ -1,43 -1,0 +1,39 @@@ +--- +title: "hugo gen" +slug: hugo_gen +url: /commands/hugo_gen/ +--- +## hugo gen + +A collection of several useful generators. + - ``` - hugo gen [command] [flags] - ``` - +### Options + +``` + -h, --help help for gen +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --logLevel string log level (debug|info|warn|error) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site +* [hugo gen chromastyles](/commands/hugo_gen_chromastyles/) - Generate CSS stylesheet for the Chroma code highlighter +* [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI. +* [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI + diff --cc docs/content/en/commands/hugo_import.md index 570353d34,000000000..a6bd40f34 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_import.md +++ b/docs/content/en/commands/hugo_import.md @@@ -1,47 -1,0 +1,43 @@@ +--- +title: "hugo import" +slug: hugo_import +url: /commands/hugo_import/ +--- +## hugo import + +Import your site from others. + +### Synopsis + +Import your site from other web site generators like Jekyll. + +Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`. + - ``` - hugo import [command] [flags] - ``` - +### Options + +``` + -h, --help help for import +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --logLevel string log level (debug|info|warn|error) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site +* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll + diff --cc docs/content/en/commands/hugo_list.md index 7cd2b288d,000000000..294a8eaa4 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_list.md +++ b/docs/content/en/commands/hugo_list.md @@@ -1,50 -1,0 +1,46 @@@ +--- +title: "hugo list" +slug: hugo_list +url: /commands/hugo_list/ +--- +## hugo list + +Listing out various types of content + +### Synopsis + +Listing out various types of content. + +List requires a subcommand, e.g. hugo list drafts + - ``` - hugo list [command] [flags] - ``` - +### Options + +``` + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --logLevel string log level (debug|info|warn|error) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site +* [hugo list all](/commands/hugo_list_all/) - List all posts +* [hugo list drafts](/commands/hugo_list_drafts/) - List all drafts +* [hugo list expired](/commands/hugo_list_expired/) - List all posts already expired +* [hugo list future](/commands/hugo_list_future/) - List all posts dated in the future + diff --cc docs/content/en/commands/hugo_new.md index 267f6a426,000000000..ef0ff4cd4 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_new.md +++ b/docs/content/en/commands/hugo_new.md @@@ -1,54 -1,0 +1,50 @@@ +--- +title: "hugo new" +slug: hugo_new +url: /commands/hugo_new/ +--- +## hugo new + +Create new content for your site + +### Synopsis + +Create a new content file and automatically set the date and title. +It will guess which kind of file to create based on the path provided. + +You can also specify the kind with `-k KIND`. + +If archetypes are provided in your theme or site, they will be used. + +Ensure you run this within the root directory of your site. + - ``` - hugo new [command] [flags] - ``` - +### Options + +``` + -h, --help help for new +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --logLevel string log level (debug|info|warn|error) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site +* [hugo new content](/commands/hugo_new_content/) - Create new content for your site +* [hugo new site](/commands/hugo_new_site/) - Create a new site (skeleton) - * [hugo new theme](/commands/hugo_new_theme/) - Create a new site (skeleton) ++* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme (skeleton) + diff --cc docs/content/en/commands/hugo_new_content.md index 0aa897c64,000000000..c7f87631c mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_new_content.md +++ b/docs/content/en/commands/hugo_new_content.md @@@ -1,59 -1,0 +1,59 @@@ +--- +title: "hugo new content" +slug: hugo_new_content +url: /commands/hugo_new_content/ +--- +## hugo new content + +Create new content for your site + +### Synopsis + +Create a new content file and automatically set the date and title. - It will guess which kind of file to create based on the path provided. - - You can also specify the kind with `-k KIND`. - - If archetypes are provided in your theme or site, they will be used. - - Ensure you run this within the root directory of your site. ++It will guess which kind of file to create based on the path provided. ++ ++You can also specify the kind with `-k KIND`. ++ ++If archetypes are provided in your theme or site, they will be used. ++ ++Ensure you run this within the root directory of your site. + +``` +hugo new content [path] [flags] +``` + +### Options + +``` + -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/ + --cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache_$USER/ + -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/) +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --logLevel string log level (debug|info|warn|error) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo new](/commands/hugo_new/) - Create new content for your site + diff --cc docs/content/en/commands/hugo_new_site.md index fb465dc7d,000000000..f8a939df5 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_new_site.md +++ b/docs/content/en/commands/hugo_new_site.md @@@ -1,47 -1,0 +1,48 @@@ +--- +title: "hugo new site" +slug: hugo_new_site +url: /commands/hugo_new_site/ +--- +## hugo new site + +Create a new site (skeleton) + +### Synopsis + +Create a new site in the provided directory. +The new site will have the correct structure, but no content or theme yet. +Use `hugo new [contentPath]` to create new content. + +``` +hugo new site [path] [flags] +``` + +### Options + +``` - -f, --force init inside non-empty directory - -h, --help help for site ++ -f, --force init inside non-empty directory ++ --format string preferred file format (toml, yaml or json) (default "toml") ++ -h, --help help for site +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --logLevel string log level (debug|info|warn|error) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo new](/commands/hugo_new/) - Create new content for your site + diff --cc docs/content/en/commands/hugo_new_theme.md index 027f636f2,000000000..301c79e0c mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_new_theme.md +++ b/docs/content/en/commands/hugo_new_theme.md @@@ -1,46 -1,0 +1,47 @@@ +--- +title: "hugo new theme" +slug: hugo_new_theme +url: /commands/hugo_new_theme/ +--- +## hugo new theme + - Create a new site (skeleton) ++Create a new theme (skeleton) + +### Synopsis + - Create a new site in the provided directory. - The new site will have the correct structure, but no content or theme yet. - Use `hugo new [contentPath]` to create new content. ++Create a new theme (skeleton) called [name] in ./themes. ++New theme is a skeleton. Please add content to the touched files. Add your ++name to the copyright line in the license and adjust the theme.toml file ++according to your needs. + +``` - hugo new theme [path] [flags] ++hugo new theme [name] [flags] +``` + +### Options + +``` + -h, --help help for theme +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --logLevel string log level (debug|info|warn|error) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo new](/commands/hugo_new/) - Create new content for your site + diff --cc docs/content/en/content-management/_index.md index e87749d3a,000000000..35f85a641 mode 100644,000000..100644 --- a/docs/content/en/content-management/_index.md +++ b/docs/content/en/content-management/_index.md @@@ -1,15 -1,0 +1,16 @@@ +--- - title: Content Management - linkTitle: Content Management Overview ++title: Content management ++linkTitle: Overview +description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more. +menu: + docs: ++ identifier: content-management-overview + parent: content-management + weight: 10 +keywords: [source, organization] +categories: [content management] +weight: 10 +aliases: [/content/,/content/organization] +--- + +A static site generator needs to extend beyond front matter and a couple of templates to be both scalable and *manageable*. Hugo was designed with not only developers in mind, but also content managers and authors. diff --cc docs/content/en/content-management/archetypes.md index f2bc6a441,000000000..d8c864536 mode 100644,000000..100644 --- a/docs/content/en/content-management/archetypes.md +++ b/docs/content/en/content-management/archetypes.md @@@ -1,90 -1,0 +1,90 @@@ +--- +title: Archetypes +description: Archetypes are templates used when creating new content. +keywords: [archetypes,generators,metadata,front matter] +categories: [content management] +menu: + docs: + parent: content-management + weight: 140 + quicklinks: +toc: true +weight: 140 +aliases: [/content/archetypes/] +--- + - ## What are Archetypes? ++## What are archetypes? + +**Archetypes** are content template files in the [archetypes directory] of your project that contain preconfigured [front matter] and possibly also a content disposition for your website's [content types]. These will be used when you run `hugo new`. + + +The `hugo new` uses the `content-section` to find the most suitable archetype template in your project. If your project does not contain any archetype files, it will also look in the theme. + +{{< code file="archetype-example.sh" >}} +hugo new posts/my-first-post.md +{{< /code >}} + +The above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these: + +1. `archetypes/posts.md` +2. `archetypes/default.md` +3. `themes/my-theme/archetypes/posts.md` +4. `themes/my-theme/archetypes/default.md` + +The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example. + - ## Create a New Archetype Template ++## Create a new archetype template + +A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`. Create a new file in `archetypes/newsletter.md` and open it in a text editor. + +{{< code file="archetypes/newsletter.md" >}} +--- +title: "{{ replace .Name "-" " " | title }}" +date: {{ .Date }} +draft: true +--- + +**Insert Lead paragraph here.** + - ## New Cool Posts ++## New cool posts + +{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }} +* {{ .Title }} +{{ end }} +{{< /code >}} + +When you create a new newsletter with: + +```bash +hugo new newsletter/the-latest-cool.stuff.md +``` + +It will create a new newsletter type of content file based on the archetype template. + +**Note:** the site will only be built if the `.Site` is in use in the archetype file, and this can be time consuming for big sites. + +The above _newsletter type archetype_ illustrates the possibilities: The full Hugo `.Site` and all of Hugo's template funcs can be used in the archetype file. + +## Directory based archetypes + +Since Hugo `0.49` you can use complete directories as archetype templates. Given this archetype directory: + +```bash +archetypes +âââ default.md +âââ post-bundle + âââ bio.md + âââ images + â âââ featured.jpg + âââ index.md +``` + +```bash +hugo new --kind post-bundle posts/my-post +``` + +Will create a new folder in `/content/posts/my-post` with the same set of files as in the `post-bundle` archetypes folder. All content files (`index.md` etc.) can contain template logic, and will receive the correct `.Site` for the content's language. + +[archetypes directory]: /getting-started/directory-structure/ +[content types]: /content-management/types/ +[front matter]: /content-management/front-matter/ diff --cc docs/content/en/content-management/build-options.md index 4798f9b2b,000000000..378a31144 mode 100644,000000..100644 --- a/docs/content/en/content-management/build-options.md +++ b/docs/content/en/content-management/build-options.md @@@ -1,111 -1,0 +1,102 @@@ +--- - title: Build Options - linkTitle: Build Options ++title: Build options +description: Build options help define how Hugo must treat a given page when building the site. +keywords: [build,content,front matter, page resources] - categories: [content management] ++categories: [fundamentals,content management] +menu: + docs: + parent: content-management + weight: 70 +toc: true +weight: 70 +aliases: [/content/build-options/] +--- + - They are stored in a reserved Front Matter object named `_build` with the following defaults: ++They are stored in a reserved front matter object named `_build` with the following defaults: + +{{< code-toggle >}} +_build: + render: always + list: always + publishResources: true +{{< /code-toggle >}} + +#### render + +If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink. + - We extended this property from a boolean to an enum in Hugo 0.76.0. Valid values are: - - 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. ++Valid values are: + - link - : The page will be not be rendered to disk, but will get a `RelPermalink`. ++ - `never` ++ : The page will not be included in any page collection. ++ - `always (default)` ++ : The page will be rendered to disk and get a `RelPermalink` etc. ++ - `link` ++ : The page will be not be rendered to disk, but will get a `RelPermalink`. + +#### list + - Note that we extended this property from a boolean to an enum in Hugo 0.68.0. - +Valid values are: - - never - : The page will not be included in any page collection. - - always (default) - : The page will be included in all page collections, e.g. `site.RegularPages`, `$page.Pages`. - - local - : The page will be included in any _local_ page collection, e.g. `$page.RegularPages`, `$page.Pages`. One use case for this would be to create fully navigable, but headless content sections. - - If true, the page will be treated as part of the project's collections and, when appropriate, returned by Hugo's listing methods (`.Pages`, `.RegularPages` etc...). ++ ++ - `never` ++ : The page will not be included in any page collection. ++ - `always (default)` ++ : The page will be included in all page collections, e.g. `site.RegularPages`, `.Pages`. ++ - `local` ++ : The page will be included in any _local_ page collection, e.g. `.RegularPages`, `.Pages`. One use case for this would be to create fully navigable, but headless content sections. + +#### publishResources + - If set to true the [Bundle's Resources](/content-management/page-bundles) will be published. - Setting this to false will still publish Resources on demand (when a resource's `.Permalink` or `.RelPermalink` is invoked from the templates) but will skip the others. ++If set to `true` (default) the [Bundle's Resources](/content-management/page-bundles) will be published. ++Setting this to `false` will still publish Resources on demand (when a resource's `.Permalink` or `.RelPermalink` is invoked from the templates) but will skip the others. + +{{% note %}} +Any page, regardless of their build options, will always be available using the [`.GetPage`](/functions/getpage) methods. +{{% /note %}} + +### Illustrative use cases + +#### Not publishing a page + - Project needs a "Who We Are" content file for Front Matter and body to be used by the homepage but nowhere else. ++Project needs a "Who We Are" content file for front matter and body to be used by the homepage but nowhere else. + +{{< code-toggle file="content/who-we-are.md" fm=true copy=false >}} +title: Who we are +_build: + list: false + render: false +{{< /code-toggle >}} + +{{< code file="layouts/index.html" copy=false >}} +

+ {{ with site.GetPage "who-we-are" }} + {{ .Content }} + {{ end }} +

+{{< /code >}} + +#### Listing pages without publishing them + +Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them. + +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. + +{{< code-toggle >}} +title: Testimonials +_build: + render: true +cascade: + _build: + render: false + list: true # default +{{< /code-toggle >}} + +{{< code file="layouts/_defaults/testimonials.html" copy=false >}} +

+ {{ range first 5 .Pages }} +

+ {{ .Content }} +

+ {{ end }} +

+{{< /code >}} diff --cc docs/content/en/content-management/comments.md index 0543f47a7,000000000..751fb89bf mode 100644,000000..100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@@ -1,71 -1,0 +1,71 @@@ +--- +title: Comments +description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website. +keywords: [sections,content,organization] - categories: [project organization, fundamentals] ++categories: [project organization] +menu: + docs: + parent: content-management + weight: 220 +toc: true +weight: 220 +aliases: [/extras/comments/] +--- + +Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript. + +Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial]. + +## Add Disqus + +Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup]. + +### Configure Disqus + +Disqus comments require you set a single value in your [site's configuration file][configuration] like so: + +{{< code-toggle copy=false >}} +disqusShortname = "yourDisqusShortname" +{{}} + +For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter] of a single content file: + +* `disqus_identifier` +* `disqus_title` +* `disqus_url` + - ### Render Hugo's Built-in Disqus Partial Template ++### Render Hugo's built-in Disqus partial template + - Disqus has its own [internal template](https://gohugo.io/templates/internal/#disqus) available, to render it add the following code where you want comments to appear: ++Disqus has its own [internal template](/templates/internal/#disqus) available, to render it add the following code where you want comments to appear: + +```go-html-template +{{ template "_internal/disqus.html" . }} +``` + +## Alternatives + +These are some alternatives to Disqus: + +* [Cactus Comments](https://cactus.chat/docs/integrations/hugo/) (Open Source, Matrix appservice, Docker install) +* [Commento](https://commento.io/) (Open Source, available as a service, local install, or docker image) +* [Graph Comment](https://graphcomment.com/) +* [Hyvor Talk](https://talk.hyvor.com/) (Available as a service) +* [IntenseDebate](https://intensedebate.com/) +* [Isso](https://isso-comments.de/) (Self-hosted, Python) ([tutorial][issotutorial]) +* [Muut](https://muut.com/) +* [Remark42](https://remark42.com/) (Open source, Golang, Easy to run docker) +* [ReplyBox](https://getreplybox.com/) +* [Staticman](https://staticman.net/) +* [Talkyard](https://blog-comments.talkyard.io/) (Open source, & serverless hosting) +* [Utterances](https://utteranc.es/) (Open source, GitHub comments widget built on GitHub issues) + +[configuration]: /getting-started/configuration/ +[disquspartial]: /templates/internal/#disqus +[disqussetup]: https://disqus.com/profile/signup/ +[forum]: https://discourse.gohugo.io +[front matter]: /content-management/front-matter/ +[kaijuissue]: https://github.com/spf13/kaiju/issues/new +[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/ +[partials]: /templates/partials/ +[MongoDB]: https://www.mongodb.com/ +[tweet]: https://twitter.com/spf13 diff --cc docs/content/en/content-management/cross-references.md index a2b3f8e1c,000000000..c989cc560 mode 100644,000000..100644 --- a/docs/content/en/content-management/cross-references.md +++ b/docs/content/en/content-management/cross-references.md @@@ -1,153 -1,0 +1,152 @@@ +--- - title: Links and Cross References - linkTitle: Links and Cross References ++title: Links and cross references +description: Shortcodes for creating links to documents. +categories: [content management] +keywords: ["cross references","references", "anchors", "urls"] +menu: + docs: + parent: content-management + weight: 170 +toc: true +weight: 170 +aliases: [/extras/crossreferences/] +--- + +The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively. + +## Use of `ref` and `relref` + +The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site. + - ``` ++```text +. +âââ content + âââ about + | âââ _index.md + | âââ credits.md + âââ pages + | âââ document1.md + | âââ document2.md // has anchor #anchor + âââ products + | âââ index.md + âââ blog + âââ my-post.md +``` + +The pages can be referenced as follows: + + +```text +{{}} // <- From pages/document1.md, relative path +{{}} +{{}} +{{}} +{{}} // <- From pages/document2.md +{{}} // <- From anywhere, absolute path +{{}} +{{}} +{{}} +{{}} +{{}} +``` + +index.md can be reference either by its path or by its containing folder without the ending `/`. \_index.md can be referenced only by its containing folder: + +```text +{{}} // <- References /about/_index.md +{{}} // Raises REF_NOT_FOUND error +{{}} // <- References /about/credits.md + +{{}} // <- References /products/index.md +{{}} // <- References /products/index.md +``` + +To generate a hyperlink using `ref` or `relref` in markdown: + +```text +[About]({{}} "About Us") +``` + +Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below. + +### Link to another language version + +To link to another language version of a document, use this syntax: + +```go-html-template +{{}} +``` + - ### Get another Output Format ++### Get another output format + +To link to another Output Format of a document, use this syntax: + +```go-html-template +{{}} +``` + +### Heading IDs + +When using Markdown document types, Hugo generates element IDs for every heading on a page. For example: + +```md +## Reference +``` + +produces this HTML: + +```html +

Reference

+``` + +Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes: + +```go-html-template +{{}} +{{}} +``` + +Generate a custom heading ID by including an attribute. For example: + +```md +## Reference A {#foo} +## Reference B {id="bar"} +``` + +produces this HTML: + +```html +

Reference A

Reference B

+``` + +Hugo will generate unique element IDs if the same heading appears more than once on a page. For example: + +```md +## Reference +## Reference +## Reference +``` + +produces this HTML: + +```html +

Reference

+``` + +## Ref and RelRef Configuration + +The behavior can, since Hugo 0.45, 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`). + +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 --cc docs/content/en/content-management/diagrams.md index e664dd501,000000000..c0b2349b0 mode 100644,000000..100644 --- a/docs/content/en/content-management/diagrams.md +++ b/docs/content/en/content-management/diagrams.md @@@ -1,266 -1,0 +1,266 @@@ +--- +title: Diagrams +description: Use fenced code blocks and markdown render hooks to display diagrams. +categories: [content management] +keywords: [diagrams,drawing] +menu: + docs: + parent: content-management + weight: 50 +toc: true +weight: 50 +--- +{{< new-in "0.93.0" >}} + - ## GoAT Diagrams (Ascii) ++## GoAT diagrams (Ascii) + +Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block: + +````txt +```goat + . . . .--- 1 .-- 1 / 1 + / \ | | .---+ .-+ + + / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2 + + + | | | | ---+ ---+ + + / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3 + / \ / \ | | | | | | | | '---+ '-+ + + 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4 + +``` +```` + +Will be rendered as: + +```goat + + . . . .--- 1 .-- 1 / 1 + / \ | | .---+ .-+ + + / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2 + + + | | | | ---+ ---+ + + / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3 + / \ / \ | | | | | | | | '---+ '-+ + + 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4 +``` + - ## Mermaid Diagrams ++## Mermaid diagrams + +Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create `layouts/_default/_markup/render-codeblock-mermaid.html`: + +```go-html-template -

 +  {{- .Inner | safeHTML }}
-

++ +{{ .Page.Store.Set "hasMermaid" true }} +``` + +And then include this snippet at the bottom of the content template (**Note**: below `.Content` as the render hook is not processed until `.Content` is executed): + +```go-html-template +{{ if .Page.Store.Get "hasMermaid" }} + +{{ end }} +``` + +With that you can use the `mermaid` language in Markdown code blocks: + - ```` ++````text +```mermaid +sequenceDiagram + participant Alice + participant Bob + Alice->>John: Hello John, how are you? + loop Healthcheck + John->>John: Fight against hypochondria + end + Note right of John: Rational thoughts
prevail! + John-->>Alice: Great! + John->>Bob: How about you? + Bob-->>John: Jolly good! +``` +```` + - ## Goat Ascii Diagram Examples ++## Goat ASCII diagram examples + +### Graphics + +```goat + . + 0 3 P * Eye / ^ / + *-------* +y \ +) \ / Reflection + 1 /| 2 /| ^ \ \ \ v + *-------* | | v0 \ v3 --------*-------- + | |4 | |7 | *----\-----* + | *-----|-* +-----> +x / v X \ .-.<-------- o + |/ |/ / / o \ | / | Refraction / \ + *-------* v / \ +-' / \ + 5 6 +z v1 *------------------* v2 | o-----o + v + +``` + +### Complex + +```goat ++-------------------+ ^ .---. +| A Box |__.--.__ __.--> | .-. | | +| | '--' v | * |<--- | | ++-------------------+ '-' | | + Round *---(-. | + .-----------------. .-------. .----------. .-------. | | | + | Mixed Rounded | | | / Diagonals \ | | | | | | + | & Square Corners | '--. .--' / \ |---+---| '-)-' .--------. + '--+------------+-' .--. | '-------+--------' | | | | / Search / + | | | | '---. | '-------' | '-+------' + |<---------->| | | | v Interior | ^ + ' <---' '----' .-----------. ---. .--- v | + .------------------. Diag line | .-------. +---. \ / . | + | if (a > b) +---. .--->| | | | | Curved line \ / / \ | + | obj->fcn() | \ / | '-------' |<--' + / \ | + '------------------' '--' '--+--------' .--. .--. | .-. +Done?+-' + .---+-----. | ^ |\ | | /| .--+ | | \ / + | | | Join \|/ | | Curved | \| |/ | | \ | \ / + | | +----> o --o-- '-' Vertical '--' '--' '-- '--' + .---. + <--+---+-----' | /|\ | | 3 | + v not:line 'quotes' .-' '---' + .-. .---+--------. / A || B *bold* | ^ + | | | Not a dot | <---+---<-- A dash--is not a line v | + '-' '---------+--' / Nor/is this. --- + +``` + +### Process + +```goat + . + .---------. / \ + | START | / \ .-+-------+-. ___________ + '----+----' .-------. A / \ B | |COMPLEX| | / \ .-. + | | END |<-----+CHOICE +----->| | | +--->+ PREPARATION +--->| X | + v '-------' \ / | |PROCESS| | \___________/ '-' + .---------. \ / '-+---+---+-' + / INPUT / \ / + '-----+---' ' + | ^ + v | + .-----------. .-----+-----. .-. + | PROCESS +---------------->| PROCESS |<------+ X | + '-----------' '-----------' '-' +``` + +### File tree + +Created from + +```goat { width=300 color="orange" } +âââLinuxââ¬âAndroid + ââDebianââ¬âUbuntuââ¬âLubuntu + â â ââKubuntu + â â ââXubuntu + â â ââXubuntu + â ââMint + ââCentos + ââFedora +``` + + - ### Sequence Diagram ++### Sequence diagram + + + +```goat { class="w-40" } +âââââââ âââââ +âAliceâ âBobâ +ââââ¬âââ âââ¬ââ + â â + â Hello Bob! â + ââââââââââââ>â + â â + âHello Alice!â + â<ââââââââââââ +ââââ´âââ âââ´ââ +âAliceâ âBobâ +âââââââ âââââ + +``` + + +### Flowchart + + + +```goat + _________________ + â± â² âââââââ + â± DO YOU UNDERSTAND â²____________________________________________________âGOOD!â + â² FLOW CHARTS? â±yes ââââ¬âââ + â²_________________â± â + âno â + _________â½_________ ______________________ â + â± â² â± â² ââââââ â +â± OKAY, YOU SEE THE â²________________â± ... AND YOU CAN SEE â²___âGOODâ â +â² LINE LABELED 'YES'? â±yes â² THE ONES LABELED 'NO'? â±yesââââ¬ââ â + â²___________________â± â²______________________â± â â + âno âno â â + ________â½_________ _________â½__________ â â + â± â² âââââââââââââ â± â² â â + â± BUT YOU SEE THE â²___âWAIT, WHAT?â â± BUT YOU JUST â²___ â â + â² ONES LABELED 'NO'? â±yesâââââââââââââ â² FOLLOWED THEM TWICE? â±yesâ â â + â²__________________â± â²____________________â± â â â + âno âno â â â + âââââ½ââââ â â â â + âLISTEN.â âââââââââ¬ââââââââ â â + âââââ¬ââââ ââââââââ½ââââââ â â + âââââââ½âââââ â(THAT WASN'Tâ â â + âI HATE YOUâ âA QUESTION) â â â + ââââââââââââ ââââââââ¬ââââââ â â + ââââââ½ââââ â â + âSCREW ITâ â â + ââââââ¬ââââ â â + âââââââ¬ââââââ â + â â + âââââââ¬ââââââ + âââââââââ½âââââââ + âLET'S GO DRINGâ + âââââââââ¬âââââââ + âââââââââââ½ââââââââââ + âHEY, I SHOULD TRY â + âINSTALLING FREEBSD!â + âââââââââââââââââââââ + +``` + + +### Table + + + +```goat { class="w-80 dark-blue" } +ââââââââââââââââââââââââââââââââââââââââââââââââââ +â â +ââââââââââââââââââââââââââââââââââââââââââââââââââ¤ +âSYNTAX = { PRODUCTION } . â +ââââââââââââââââââââââââââââââââââââââââââââââââââ¤ +âPRODUCTION = IDENTIFIER "=" EXPRESSION "." . â +ââââââââââââââââââââââââââââââââââââââââââââââââââ¤ +âEXPRESSION = TERM { "|" TERM } . â +ââââââââââââââââââââââââââââââââââââââââââââââââââ¤ +âTERM = FACTOR { FACTOR } . â +ââââââââââââââââââââââââââââââââââââââââââââââââââ¤ +âFACTOR = IDENTIFIER â +ââââââââââââââââââââââââââââââââââââââââââââââââââ¤ +â | LITERAL â +ââââââââââââââââââââââââââââââââââââââââââââââââââ¤ +â | "[" EXPRESSION "]" â +ââââââââââââââââââââââââââââââââââââââââââââââââââ¤ +â | "(" EXPRESSION ")" â +ââââââââââââââââââââââââââââââââââââââââââââââââââ¤ +â | "{" EXPRESSION "}" . â +ââââââââââââââââââââââââââââââââââââââââââââââââââ¤ +âIDENTIFIER = letter { letter } . â +ââââââââââââââââââââââââââââââââââââââââââââââââââ¤ +âLITERAL = """" character { character } """" .â +ââââââââââââââââââââââââââââââââââââââââââââââââââ +``` diff --cc docs/content/en/content-management/formats.md index ba988c29b,000000000..a974d41d3 mode 100644,000000..100644 --- a/docs/content/en/content-management/formats.md +++ b/docs/content/en/content-management/formats.md @@@ -1,145 -1,0 +1,138 @@@ +--- - title: Content Formats - linkTitle: Content Formats ++title: Content formats +description: Both HTML and Markdown are supported content formats. +categories: [content management] +keywords: [markdown,asciidoc,pandoc,content format] +menu: + docs: + parent: content-management + weight: 40 +toc: true +weight: 40 +aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/] +--- + +You can put any file type into your `/content` directories, but Hugo uses the `markup` front matter value if set or the file extension (see `Markup identifiers` in the table below) to determine if the markup needs to be processed, e.g.: + +* Markdown converted to HTML +* [Shortcodes](/content-management/shortcodes/) processed +* Layout applied + +## List of content formats + +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.| + +The `markup identifier` is fetched from either the `markup` variable in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/). + - ## External Helpers ++## External helpers + +Some of the formats in the table above need external helpers installed on your PC. For example, for AsciiDoc files, +Hugo will try to call the `asciidoctor` command. This means that you will have to install the associated +tool on your machine to be able to use these formats. + +Hugo passes reasonable default arguments to these external helpers by default: + +- `asciidoctor`: `--no-header-footer -` +- `rst2html`: `--leave-comments --initial-header-level=2` +- `pandoc`: `--mathjax` + +{{% note %}} +Because additional formats are external commands, generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome. +{{% /note %}} + - ### External Helper AsciiDoc - - [AsciiDoc](https://github.com/asciidoc/asciidoc) implementation EOLs in Jan 2020 and is no longer supported. - AsciiDoc development is being continued under [Asciidoctor](https://github.com/asciidoctor). The format AsciiDoc - remains of course. Please continue with the implementation Asciidoctor. - - ### External Helper Asciidoctor ++### External helper Asciidoctor + +The Asciidoctor community offers a wide set of tools for the AsciiDoc format that can be installed additionally to Hugo. +[See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/). Make sure that also all +optional extensions like `asciidoctor-diagram` or `asciidoctor-html5s` are installed if required. + +{{% note %}} +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](https://asciidoctor.org/man/asciidoctor/) parameters can be customized in Hugo: + +Parameter | Comment +--- | --- +backend | Don't change this unless you know what you are doing. +doctype | Currently, the only document type supported in Hugo is `article`. +extensions | Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, `asciidoctor-question`, `asciidoctor-rouge`. +attributes | Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See [Asciidoctor's attributes](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions). +noHeaderOrFooter | Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Don't change this unless you know what you are doing. +safeMode | Safe mode level `unsafe`, `safe`, `server` or `secure`. Don't change this unless you know what you are doing. +sectionNumbers | Auto-number section titles. +verbose | Verbosely print processing information and configuration file checks to stderr. +trace | Include backtrace information on errors. +failureLevel | The minimum logging level that triggers a non-zero exit code (failure). + +Hugo provides additional settings that don't map directly to Asciidoctor's CLI options: + +workingFolderCurrent +: Sets the working directory to be the same as that of the AsciiDoc file being processed, so that [include](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files) will work with relative paths. This setting uses the `asciidoctor` cli parameter `--base-dir` and attribute `outdir=`. For rendering diagrams with [asciidoctor-diagram](https://asciidoctor.org/docs/asciidoctor-diagram/), `workingFolderCurrent` must be set to `true`. + +preserveTOC +: By default, Hugo removes the table of contents generated by Asciidoctor and provides it through the built-in variable [`.TableOfContents`](/content-management/toc/) to enable further customization and better integration with the various Hugo themes. This option can be set to `true` to preserve Asciidoctor's TOC in the generated page. + +Below are all the AsciiDoc related settings in Hugo with their default values: + +{{< code-toggle config="markup.asciidocExt" />}} + +Notice that for security concerns only extensions that do not have path separators (either `\`, `/` or `.`) are allowed. That means that extensions can only be invoked if they are in one's ruby's `$LOAD_PATH` (ie. most likely, the extension has been installed by the user). Any extension declared relative to the website's path will not be accepted. + +Example of how to set extensions and attributes: + +```yml +[markup.asciidocExt] + extensions = ["asciidoctor-html5s", "asciidoctor-diagram"] + workingFolderCurrent = true + [markup.asciidocExt.attributes] + my-base-url = "https://example.com/" + my-attribute-name = "my value" +``` + +In a complex Asciidoctor environment it is sometimes helpful to debug the exact call to your external helper with all +parameters. Run Hugo with `-v`. You will get an output like + +```txt +INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ... +``` + - ## Learn Markdown ++## Learn markdown + +Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running: + +* [Daring Fireball: Markdown, John Gruber (Creator of Markdown)][fireball] +* [Markdown Cheatsheet, Adam Pritchard][mdcheatsheet] +* [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial] +* [The Markdown Guide, Matt Cone][mdguide] + +[`emojify` function]: /functions/emojify/ +[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 +[hl]: /content-management/syntax-highlighting/ +[hlsc]: /content-management/shortcodes/#highlight +[hugocss]: /css/style.css +[ietf]: https://tools.ietf.org/html/ +[mathjaxdocs]: https://docs.mathjax.org/en/latest/ +[mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet +[mdguide]: https://www.markdownguide.org/ +[mdtutorial]: https://www.markdowntutorial.com/ +[org]: https://orgmode.org/ +[pandoc]: https://www.pandoc.org/ +[rest]: https://docutils.sourceforge.io/rst.html +[sc]: /content-management/shortcodes/ +[sct]: /templates/shortcode-templates/ diff --cc docs/content/en/content-management/front-matter.md index fb02f99f5,000000000..10317e805 mode 100644,000000..100644 --- a/docs/content/en/content-management/front-matter.md +++ b/docs/content/en/content-management/front-matter.md @@@ -1,239 -1,0 +1,239 @@@ +--- - title: Front Matter ++title: Front matter +description: Hugo allows you to add front matter in yaml, toml, or json to your content files. +categories: [content management] +keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"] +menu: + docs: + parent: content-management + weight: 60 +toc: true +weight: 60 +aliases: [/content/front-matter/] +--- + +**Front matter** allows you to keep metadata attached to an instance of a [content type]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength. + +{{< youtube Yh2xKRJGff4 >}} + - ## Front Matter Formats ++## Front matter formats + +Hugo supports four formats for front matter, each with their own identifying tokens. + +TOML +: identified by opening and closing `+++`. + +YAML +: identified by opening and closing `---`. + +JSON +: a single JSON object surrounded by '`{`' and '`}`', followed by a new line. + +ORG +: a group of Org mode keywords in the format '`#+KEY: VALUE`'. Any line that does not start with `#+` ends the front matter section. + Keyword values can be either strings (`#+KEY: VALUE`) or a whitespace separated list of strings (`#+KEY[]: VALUE_1 VALUE_2`). + +### Example + +{{< code-toggle >}} +title = "spf13-vim 3.0 release and new website" +description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." +tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] +date = "2012-04-06" +categories = [ + "Development", + "VIM" +] +slug = "spf13-vim-3-0-release-and-new-website" +{{< /code-toggle >}} + - ## Front Matter Variables ++## Front matter variables + +### Predefined + +There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates. + +aliases +: An array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details. + +audio +: An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`. + +cascade +: A map of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details. + +date +: The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable. + +description +: The description for the content. + +draft +: If `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command. + +expiryDate +: The datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command. + +headless +: If `true`, sets a leaf bundle to be [headless][headless-bundle]. + +images +: An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`. + +isCJKLanguage +: If `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages. + +keywords +: The meta keywords for the content. + +layout +: The layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type]. + +lastmod +: The datetime at which the content was last modified. + +linkTitle - : Used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle]. ++: Used for creating links to content; if set, Hugo defaults to using the `linkTitle` before the `title`. Hugo can also [order lists of content by `linkTitle`][bylinktitle]. + +markup +: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown. + +outputs +: Allows you to specify output formats specific to the content. See [output formats][outputs]. + +publishDate +: If in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`. + +resources +: Used for configuring page bundle resources. See [Page Resources][page-resources]. + +series +: An array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`. + +slug +: Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details. + +summary +: Text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section. + +title +: The title for the content. + +type +: The type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter. + +url +: Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details. + +videos +: An array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`. + +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. + +\ +: Field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.* + +{{% note %}} - If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site configuration file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors. ++If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site configuration file](/content-management/urls/#permalinks), Hugo will use the file name of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors. +{{% /note %}} + - ### User-Defined ++### User-defined + +You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates. + +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 >}} +include_toc: true +show_comments: false +{{}} + - ## Front Matter Cascade ++## Front matter cascade + - Any node or section can pass down to descendants a set of Front Matter values as long as defined underneath the reserved `cascade` Front Matter key. ++Any node or section can pass down to descendants a set of front matter values as long as defined underneath the reserved `cascade` front matter key. + - ### Target Specific Pages ++### Target specific pages + +The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets. + +{{< code-toggle copy=false >}} +title ="Blog" +[[cascade]] +background = "yosemite.jpg" +[cascade._target] +path="/blog/**" +lang="en" +kind="page" +[[cascade]] +background = "goldenbridge.jpg" +[cascade._target] +kind="section" +{{}} + +Keywords available for `_target`: + +path +: A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down. + +kind +: A Glob pattern matching the Page's Kind(s), e.g. "{home,section}". + +lang +: A Glob pattern matching the Page's language, e.g. "{en,sv}". + +environment +: A Glob pattern matching the build environment, e.g. "{production,development}" + +Any of the above can be omitted. + +### Example + +In `content/blog/_index.md` + +{{< code-toggle copy=false >}} +title: Blog +cascade: + banner: images/typewriter.jpg +{{}} + +With the above example the Blog section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless: + +- Said descendant has its own `banner` value set +- Or a closer ancestor node has its own `cascade.banner` value set. + - ## Order Content Through Front Matter ++## Order content through front matter + +You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views. + - ## Override Global Markdown Configuration ++## Override global markdown configuration + - It's possible to set some options for Markdown rendering in a content's front matter as an override to the [Rendering options set in your project configuration][config]. ++It's possible to set some options for Markdown rendering in a content's front matter as an override to the [rendering options set in your project configuration][config]. + - ## Front Matter Format Specs ++## Front matter format specs + +- [TOML Spec][toml] +- [YAML Spec][yaml] +- [JSON Spec][json] + +[variables]: /variables/ +[aliases]: /content-management/urls/#aliases +[archetype]: /content-management/archetypes/ +[bylinktitle]: /templates/lists/#by-link-title - [config]: /getting-started/configuration/ "Hugo documentation for site configuration" ++[config]: /getting-started/configuration/ +[content type]: /content-management/types/ +[contentorg]: /content-management/organization/ +[headless-bundle]: /content-management/page-bundles/#headless-bundle - [json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" - [lists]: /templates/lists/#order-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter." - [lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating." - [ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates" - [outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating" ++[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf ++[lists]: /templates/lists/#order-content ++[lookup]: /templates/lookup-order/ ++[ordering]: /templates/lists/ ++[outputs]: /templates/output-formats/ +[page-resources]: /content-management/page-resources/ +[pagevars]: /variables/page/ +[section]: /content-management/sections/ +[taxweight]: /content-management/taxonomies/ +[toml]: https://toml.io/ +[urls]: /content-management/urls/ +[variables]: /variables/ - [yaml]: https://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language" ++[yaml]: https://yaml.org/spec/ diff --cc docs/content/en/content-management/image-processing/index.md index 3d70951b3,000000000..273b68ab8 mode 100644,000000..100644 --- a/docs/content/en/content-management/image-processing/index.md +++ b/docs/content/en/content-management/image-processing/index.md @@@ -1,476 -1,0 +1,476 @@@ +--- - title: Image Processing ++title: Image processing +description: Resize, crop, rotate, filter, and convert images. - categories: [content management] ++categories: [fundamentals,content management] +keywords: [resources, images] +menu: + docs: + parent: content-management + weight: 90 +toc: true +weight: 90 +--- - ## Image Resources ++## Image resources + +To process an image, you must access the image as either a page resource or a global resource. + - ### Page Resources ++### Page resources + +A page resource is a file within a [page bundle]. A page bundle is a directory with an `index.md` or `_index.md` file at its root. + +```text +content/ +âââ posts/ + âââ post-1/ <-- page bundle + âââ index.md + âââ sunset.jpg <-- page resource +``` + - ### Global Resources ++### Global resources + +A global resource is a file: + +- Within the `assets` directory, or +- Within any directory [mounted] to the `assets` directory, or +- Located on a remote server accessible via `http` or `https` + +```text +assets/ +âââ images/ + âââ sunset.jpg <-- global resource +``` + +To access a local image as a global resource: + +```go-html-template +{{ $image := resources.Get "images/sunset.jpg" }} +``` + +To access a remote image as a global resource: + +```go-html-template +{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }} +``` + - ## Image Rendering ++## Image rendering + +Once you have accessed an image as either a page resource or a global resource, render it in your templates using the `Permalink`, `RelPermalink`, `Width`, and `Height` properties. + +Example 1: Throws an error if the resource is not found. + +```go-html-template +{{ $image := .Resources.GetMatch "sunset.jpg" }} +

+``` + +Example 2: Skips image rendering if the resource is not found. + +```go-html-template +{{ $image := .Resources.GetMatch "sunset.jpg" }} +{{ with $image }} +

+{{ end }} +``` + +Example 3: A more concise way to skip image rendering if the resource is not found. + +```go-html-template +{{ with .Resources.GetMatch "sunset.jpg" }} +

+{{ end }} +``` + - ## Image Processing Methods ++## Image processing methods + +The `image` resource implements the [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods. + +{{% note %}} - Metadata (Exif, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`] method with the _original_ image to extract Exif metadata from JPEG or TIFF images. ++Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`] method with the _original_ image to extract EXIF metadata from JPEG or TIFF images. +{{% /note %}} + +### Resize + +Resize an image to the specified 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 +{{/* Resize to a width of 600px and preserve aspect ratio */}} +{{ $image := $image.Resize "600x" }} + +{{/* Resize to a height of 400px and preserve aspect ratio */}} +{{ $image := $image.Resize "x400" }} + +{{/* Resize to a width of 600px and a height of 400px */}} +{{ $image := $image.Resize "600x400" }} +``` + +### Fit + +Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height. + +```go-html-template +{{ $image := $image.Fit "600x400" }} +``` + +### Fill + +Crop and resize an image to match the given dimensions. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point. + +```go-html-template +{{ $image := $image.Fill "600x400" }} +``` + +### Crop + +Crop an image to match the given dimensions without resizing. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point. + +```go-html-template +{{ $image := $image.Crop "600x400" }} +``` + +### Filter + +Apply one or more [filters] to an image. + +```go-html-template +{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +Write this in a more functional style using pipes. Hugo applies the filters in the order given. + +```go-html-template +{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +Sometimes it can be useful to create the filter chain once and then reuse it. + +```go-html-template +{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }} +{{ $image1 := $image1.Filter $filters }} +{{ $image2 := $image2.Filter $filters }} +``` + +### Colors + +{{< new-in "0.104.0" >}} + +`.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method. + +```go-html-template +{{ $colors := $image.Colors }} +``` + +This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled down image. + + - ### Exif ++### EXIF + - Provides an [Exif] object containing image metadata. ++Provides an [EXIF] object containing image metadata. + - You may access Exif data in JPEG and TIFF images. To prevent errors when processing images without Exif data, wrap the access in a [`with`] statement. ++You may access EXIF data in JPEG and TIFF images. To prevent errors when processing images without EXIF data, wrap the access in a [`with`] statement. + +```go-html-template +{{ with $image.Exif }} + Date: {{ .Date }} + Lat/Long: {{ .Lat }}/{{ .Long }} + Tags: + {{ range $k, $v := .Tags }} + TAG: {{ $k }}: {{ $v }} + {{ end }} +{{ end }} +``` + - You may also access Exif fields individually, using the [`lang.FormatNumber`] function to format the fields as needed. ++You may also access EXIF fields individually, using the [`lang.FormatNumber`] function to format the fields as needed. + +```go-html-template +{{ with $image.Exif }} +

Date: {{ .Format "January 02, 2006" }}
Aperture: {{ lang.FormatNumber 2 . }}
Brightness: {{ lang.FormatNumber 2 . }}
Exposure Time: {{ . }}
F Number: {{ . }}
Focal Length: {{ . }}
ISO Speed Ratings: {{ . }}
Lens Model: {{ . }}

+{{ end }} +``` + - #### Exif Variables ++#### EXIF variables + +.Date +: Image creation date/time. Format with the [time.Format] function. + +.Lat +: GPS latitude in degrees. + +.Long +: GPS longitude in degrees. + +.Tags - : A collection of the available Exif tags for this image. You may include or exclude specific tags from this collection in the [site configuration](#exif-data). ++: A collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration](#exif-data). + - ## Image Processing Options ++## Image processing options + +The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-separated, case-insensitive list of options. The order of the options within the list is irrelevant. + +### Dimensions + +With the [`Resize`] method you must specify width, height, or both. The [`Fit`], [`Fill`], and [`Crop`] methods require both width and height. All dimensions are in pixels. + +```go-html-template +{{ $image := $image.Resize "600x" }} +{{ $image := $image.Resize "x400" }} +{{ $image := $image.Resize "600x400" }} +{{ $image := $image.Fit "600x400" }} +{{ $image := $image.Fill "600x400" }} +{{ $image := $image.Crop "600x400" }} +``` + +### Rotation + +Rotates an image counter-clockwise by the given angle. Hugo performs rotation _before_ scaling. For example, if the original image is 600x400 and you wish to rotate the image 90 degrees counter-clockwise while scaling it by 50%: + +```go-html-template +{{ $image = $image.Resize "200x r90" }} +``` + +In the example above, the width represents the desired width _after_ rotation. + +To rotate an image without scaling, use the dimensions of the original image: + +```go-html-template +{{ with .Resources.GetMatch "sunset.jpg" }} + {{ with .Resize (printf "%dx%d r90" .Height .Width) }} +

+ {{ end }} +{{ end }} +``` + +In the example above, on the second line, we have reversed width and height to reflect the desired dimensions _after_ rotation. + +### Anchor + +When using the [`Crop`] or [`Fill`] method, the _anchor_ determines the placement of the crop box. You may specify `TopLeft`, `Top`, `TopRight`, `Left`, `Center`,`Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. + +The default value is `Smart`, which uses [Smartcrop] image analysis to determine the optimal placement of the crop box. You may override the default value in the [site configuration]. + +For example, if you have a 400x200 image with a bird in the upper left quadrant, you can create a 200x100 thumbnail containing the bird: + +```go-html-template +{{ $image.Crop "200x100 TopLeft" }} +``` + +If you apply [rotation](#rotation) when using the [`Crop`] or [`Fill`] method, specify the anchor relative to the rotated image. + - ### Target Format ++### Target format + +By default, Hugo encodes the image in the source format. You may convert the image to another format by specifying `bmp`, `gif`, `jpeg`, `jpg`, `png`, `tif`, `tiff`, or `webp`. + +```go-html-template +{{ $image.Resize "600x webp" }} +``` + +To convert an image without scaling, use the dimensions of the original image: + +```go-html-template +{{ with .Resources.GetMatch "sunset.jpg" }} + {{ with .Resize (printf "%dx%d webp" .Width .Height) }} +

+ {{ end }} +{{ end }} +``` + +### Quality + +Applicable to JPEG and WebP images, the `q` value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between 1 and 100, inclusive. + +The default value is 75. You may override the default value in the [site configuration]. + +```go-html-template +{{ $image.Resize "600x webp q50" }} +``` + +### Hint + + + +Applicable to WebP images, this option corresponds to a set of predefined encoding parameters. + +Value|Example +:--|:-- +`drawing`|Hand or line drawing with high-contrast details +`icon`|Small colorful image +`photo`|Outdoor photograph with natural lighting +`picture`|Indoor photograph such as a portrait +`text`|Image that is primarily text + +The default value is `photo`. You may override the default value in the [site configuration]. + +```go-html-template +{{ $image.Resize "600x webp picture" }} +``` + - ### Background Color ++### Background color + +When converting an image from a format that supports transparency (e.g., PNG) to a format that does _not_ support transparency (e.g., JPEG), you may specify the background color of the resulting image. + +Use either a 3-digit or a 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]. + +```go-html-template +{{ $image.Resize "600x jpg #b31280" }} +``` + - ### Resampling Filter ++### Resampling filter + +You may specify the resampling filter used when resizing an image. Commonly used resampling filters include: + +Filter|Description +:--|:-- +`Box`|Simple and fast averaging filter appropriate for downscaling +`Lanczos`|High-quality resampling filter for photographic images yielding sharp results +`CatmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results +`MitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom +`Linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters +`NearestNeighbor`|Fastest resampling filter, no antialiasing + +The default value is `Box`. You may override the default value in the [site configuration]. + +```go-html-template +{{ $image.Resize "600x400 Lanczos" }} +``` + +See [github.com/disintegration/imaging] for the complete list of resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters. + - ## Image Processing Examples ++## Image processing examples + +_The photo of the sunset used in the examples below is Copyright [BjÃ¸rn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ + +{{< imgproc sunset Resize "300x" />}} + +{{< imgproc sunset Fill "90x120 left" />}} + +{{< imgproc sunset Fill "90x120 right" />}} + +{{< imgproc sunset Fit "90x90" />}} + +{{< imgproc sunset Crop "250x250 center" />}} + +{{< imgproc sunset 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 >}} + +Call the shortcode from your Markdown like this: + +```go-html-template +{{}} +``` + +{{% note %}} +Note the self-closing shortcode syntax above. You may call the `imgproc` shortcode with or without **inner content**. +{{% /note %}} + - ## Imaging Configuration ++## Imaging configuration + - ### Processing Options ++### Processing options + +Define an `imaging` section in your site configuration to set the default [image processing options](#image-processing-options). + +{{< code-toggle file="hugo" copy=true >}} +[imaging] +resampleFilter = "Box" +quality = 75 +hint = "photo" +anchor = "Smart" +bgColor = "#ffffff" +{{< /code-toggle >}} + +anchor +: See image processing options: [anchor](#anchor). + +bgColor +: See image processing options: [background color](#background-color). + +hint +: See image processing options: [hint](#hint). + +quality +: See image processing options: [quality](#quality). + +resampleFilter +: See image processing options: [resampling filter](#resampling-filter). + - ### Exif Data ++### EXIF data + - Define an `imaging.exif` section in your site configuration to control the availability of Exif data. ++Define an `imaging.exif` section in your site configuration to control the availability of EXIF data. + +{{< code-toggle file="hugo" copy=true >}} +[imaging.exif] +includeFields = "" +excludeFields = "" +disableDate = false +disableLatLong = false +{{< /code-toggle >}} + +disableDate +: Hugo extracts the image creation date/time into `.Date`. Set this to `true` to disable. Default is `false`. + +disableLatLong +: Hugo extracts the GPS latitude and longitude into `.Lat` and `.Long`. Set this to `true` to disable. Default is `false`. + +excludeFields - : Regular expression matching the Exif tags to exclude from the `.Tags` collection. Default is `""`. ++: Regular expression matching the EXIF tags to exclude from the `.Tags` collection. Default is `""`. + +includeFields - : Regular expression matching the Exif tags to include in the `.Tags` collection. Default is `""`. To include all available tags, set this value to `".*"`. ++: 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`. +{{% /note %}} + - ## Smart Cropping of Images ++## Smart cropping of images + +By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or`Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice. + +Examples using the sunset image from above: + +{{< imgproc sunset Fill "200x200 smart" />}} + +{{< imgproc sunset Crop "200x200 smart" />}} + - ## Image Processing Performance Consideration ++## Image processing performance consideration + +Hugo caches processed images in the `resources` directory. If you include this directory in source control, Hugo will not have to regenerate the images in a CI/CD workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds. + +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 +hugo --gc +``` + +[time.Format]: /functions/dateformat +[`anchor`]: /content-management/image-processing#anchor - [mounted]: /hugo-modules/configuration#module-config-mounts ++[mounted]: /hugo-modules/configuration#module-configuration-mounts +[page bundle]: /content-management/page-bundles +[`lang.FormatNumber`]: /functions/lang +[filters]: /functions/images +[github.com/disintegration/imaging]: +[Smartcrop]: +[Exif]: +[`Colors`]: #colors +[`Crop`]: #crop +[`Exif`]: #exif +[`Fill`]: #fill +[`Filter`]: #filter +[`Fit`]: #fit +[`Resize`]: #resize +[site configuration]: #processing-options +[`with`]: /functions/with/ diff --cc docs/content/en/content-management/multilingual.md index 71adc214d,000000000..4c1f6446e mode 100644,000000..100644 --- a/docs/content/en/content-management/multilingual.md +++ b/docs/content/en/content-management/multilingual.md @@@ -1,652 -1,0 +1,674 @@@ +--- - title: Multilingual Mode ++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] +menu: + docs: + parent: content-management + weight: 230 +toc: true +weight: 230 +aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/] +--- + +You should define the available languages in a `languages` section in your site configuration. + +Also See [Hugo Multilingual Part 1: Content translation]. + - ## Configure Languages ++## Configure languages + - The following is an example of a site configuration for a multilingual Hugo project: ++This is an example of a site configuration for a multilingual project. Any key not defined in a `languages` object will fall back to the global value in the root of your site configuration. + +{{< code-toggle file="hugo" >}} - defaultContentLanguage = "en" - copyright = "Everything is mine" ++defaultContentLanguage = 'de' ++defaultContentLanguageInSubdir = true + - [params] - [params.navigation] - help = "Help" - - [languages] - [languages.en] - title = "My blog" ++[languages.de] ++contentDir = 'content/de' ++disabled = false ++languageCode = 'de-DE' ++languageDirection = 'ltr' ++languageName = 'Deutsch' ++title = 'Projekt Dokumentation' +weight = 1 - [languages.en.params] - linkedin = "https://linkedin.com/whoever" + - [languages.fr] - title = "Mon blogue" - weight = 2 - [languages.fr.params] - linkedin = "https://linkedin.com/fr/whoever" - [languages.fr.params.navigation] - help = "Aide" ++[languages.de.params] ++subtitle = 'Referenz, Tutorials und ErklÃ¤rungen' + - [languages.ar] - title = "ÙØ¯ÙÙØªÙ" ++[languages.en] ++contentDir = 'content/en' ++disabled = false ++languageCode = 'en-US' ++languageDirection = 'ltr' ++languageName = 'English' ++title = 'Project Documentation' +weight = 2 - languagedirection = "rtl" + - [languages.pt-pt] - title = "O meu blog" - weight = 3 ++[languages.en.params] ++subtitle = 'Reference, Tutorials, and Explanations' +{{< /code-toggle >}} + - Anything not defined in a `languages` block will fall back to the global value for that key (e.g., `copyright` for the English `en` language). This also works for `params`, as demonstrated with `help` above: You will get the value `Aide` in French and `Help` in all the languages without this parameter set. ++`defaultContentLanguage` ++: (`string`) The project's default language tag as defined by [RFC 5646]. Must be lower case, and must match one of the defined language keys. Default is `en`. Examples: ++ ++- `en` ++- `en-gb` ++- `pt-br` + - With the configuration above, all content, sitemap, RSS feeds, pagination, - and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French. ++`defaultContentLanguageInSubdir` ++: (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`. + - When working with front matter `Params` in [single page templates], omit the `params` in the key for the translation. ++`contentDir` ++: (`string`) The content directory for this language. Omit if [translating by file name]. + - `defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`. ++`disabled` ++: (`bool`) If `true`, Hugo will not render content for this language. Default is `false`. + - If the default language needs to be rendered below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`. ++`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: + - Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc. ++- `en` ++- `en-GB` ++- `pt-BR` + - **Please note:** use lowercase language codes, even when using regional languages (ie. use pt-pt instead of pt-PT). Currently Hugo language internals lowercase language codes, which can cause conflicts with settings like `defaultContentLanguage` which are not lowercased. Please track the evolution of this issue in [Hugo repository issue tracker](https://github.com/gohugoio/hugo/issues/7344) ++`languageDirection` ++: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`] HTML attribute. ++ ++`languageName` ++: (`string`) The language name, typically used when rendering a language switcher. ++ ++`title` ++: (`string`) The language title. When set, this overrides the site title for this language. ++ ++`weight` ++: (`int`) The language weight. When set to a non-zero value, this is the primary sort criteria for this language. ++ ++[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir ++[built-in RSS template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml ++[built-in alias template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html ++[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 ++[translating by file name]: #translation-by-file-name + +### Changes in Hugo 0.112.0 + +{{< 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 params to the top level language config is deprecated, add all of these below `[params]`, see `color` in the example below. ++1. Adding custom parameters to the top level language configuration is deprecated, add all of these below `[params]`, see `color` in the example below. + +```toml +title = "My blog" +languageCode = "en-us" + +[languages] +[languages.sv] +title = "Min blogg" +languageCode = "sv" +[languages.en.params] +color = "blue" +``` + +In the example above, all settings except `color` below `params` map to predefined configuration options in Hugo for the site and its language, and should be accessed via the documented accessors: + - ``` ++```go-html-template +{{ site.Title }} +{{ site.LanguageCode }} +{{ site.Params.color }} +``` + - ### Disable a Language ++### Disable a language + - You can disable one or more languages. This can be useful when working on a new translation. ++To disable a language within a `languages` object in your site configuration: + - {{< code-toggle file="hugo" >}} - disableLanguages = ["fr", "ja"] ++{{< code-toggle file="hugo" copy=false >}} ++[languages.es] ++disabled = true +{{< /code-toggle >}} + - Note that you cannot disable the default content language. ++To disable one or more languages in the root of your site configuration: + - We kept this as a standalone setting to make it easier to set via [OS environment]: - - ```bash - HUGO_DISABLELANGUAGES="fr ja" hugo - ``` ++{{< code-toggle file="hugo" copy=false >}} ++disableLanguages = ["es", "fr"] ++{{< /code-toggle >}} + - If you have already a list of disabled languages in `hugo.toml`, you can enable them in development like this: ++To disable one or more languages using an environment variable: + +```bash - HUGO_DISABLELANGUAGES=" " hugo server ++HUGO_DISABLELANGUAGES="es fr" hugo +``` + - ### Configure Multilingual Multihost ++Note that you cannot disable the default content language. ++ ++### Configure multilingual multihost + +From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details. + +This means that you can now configure a `baseURL` per `language`: + +{{% note %}} +If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. +{{% /note %}} + +Example: + +{{< code-toggle file="hugo" >}} +[languages] +[languages.fr] +baseURL = "https://example.fr" +languageName = "FranÃ§ais" +weight = 1 +title = "En FranÃ§ais" + +[languages.en] +baseURL = "https://example.com" +languageName = "English" +weight = 2 +title = "In English" +{{}} + +With the above, the two sites will be generated into `public` with their own root: + +```text +public +âââ en +âââ 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/`.** + +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) +Press Ctrl+C to stop +``` + +Live reload and `--navigateToChanged` between the servers work as expected. + - - ## Translate Your Content ++## Translate your content + +There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations. + - ### Translation by filename ++### Translation by file name + +Considering the following example: + +1. `/content/about.en.md` +2. `/content/about.fr.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + - Their language is __assigned__ according to the language code added as a __suffix to the filename__. ++Their language is __assigned__ according to the language code added as a __suffix to the file name__. + - By having the same **path and base filename**, the content pieces are __linked__ together as translated pages. ++By having the same **path and base file name**, the content pieces are __linked__ together as translated pages. + +{{% note %}} +If a file has no language code, it will be assigned the default language. +{{% /note %}} + +### Translation by content directory + - This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` param. ++This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` parameter. + +{{< code-toggle file="hugo" >}} +languages: + en: + weight: 10 + languageName: "English" + contentDir: "content/english" + fr: + weight: 20 + languageName: "FranÃ§ais" + contentDir: "content/french" +{{< /code-toggle >}} + +The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap. + +Considering the following example in conjunction with the configuration above: + +1. `/content/english/about.md` +2. `/content/french/about.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + +Their language is __assigned__ according to the content directory they are __placed__ in. + +By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages. + +### Bypassing default linking + +Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location. + +Considering the following example: + +1. `/content/about-us.en.md` +2. `/content/om.nn.md` +3. `/content/presentation/a-propos.fr.md` + +{{< code-toggle >}} +translationKey: "about" +{{< /code-toggle >}} + - By setting the `translationKey` front matter param to `about` in all three pages, they will be __linked__ as translated pages. ++By setting the `translationKey` front matter parameter to `about` in all three pages, they will be __linked__ as translated pages. + +### Localizing permalinks + - Because paths and filenames are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory). ++Because paths and file names are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory). + +To localize URLs: + +- For a regular page, set either [`slug`] or [`url`] in front matter +- For a section page, set [`url`] in front matter + +[`slug`]: /content-management/urls/#slug +[`url`]: /content-management/urls/#url + +For example, a French translation can have its own localized slug. + +{{< code-toggle file="content/about.fr.md" fm=true copy=false >}} +title: A Propos +slug: "a-propos" +{{< /code-toggle >}} + +At render, Hugo will build both `/about/` and `/fr/a-propos/` without affecting the translation link. + - ### Page Bundles ++### Page bundles + +To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (Markdown files, HTML files etc...). + +Therefore, from within a template, the page will have access to the files from all linked pages' bundles. + +If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows: + +* File from current language bundle, if present. +* First file found across bundles by order of language `Weight`. + +{{% note %}} - Page Bundle resources follow the same language assignment logic as content files, both by filename (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`). ++Page Bundle resources follow the same language assignment logic as content files, both by file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`). +{{%/ note %}} + - ## Reference the Translated Content ++## Reference translated content + +To create a list of links to translated content, use a template similar to the following: + +{{< code file="layouts/partials/i18nlist.html" >}} +{{ if .IsTranslated }} +

+ {{ .Lang }}: {{ .Title }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }} +

+{{ end }} +{{< /code >}} + +The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, whether a [single content page][contenttemplate] or the [homepage]. It will not print anything if there are no translations for a given page. + +The above also uses the [`i18n` function][i18func] described in the next section. + - ### List All Available Languages ++### List all available languages + +`.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator: + +{{< code file="layouts/partials/allLanguages.html" >}} +

{{ .Language.LanguageName }}

+{{< /code >}} + - ## Translation of Strings ++## Translation of strings + +Hugo uses [go-i18n] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows. + +Translations are collected from the `themes//i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646] with names such as `en-US.toml`, `fr.toml`, etc. + +Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7](https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7) are also supported. You may omit the `art-x-` prefix for brevity. For example: + +```text +art-x-hugolang +hugolang +``` + +Private use subtags must not exceed 8 alphanumeric characters. + +### Query basic translation + +From within your templates, use the `i18n` function like this: + +```go-html-template +{{ i18n "home" }} +``` + +The function will search for the `"home"` id: + +{{< code-toggle file="i18n/en-US" >}} +[home] +other = "Home" +{{< /code-toggle >}} + +The result will be + +```text +Home +``` + +### Query a flexible translation with variables + +Often you will want to use the page variables in the translation strings. To do so, pass the `.` context when calling `i18n`: + +```go-html-template +{{ i18n "wordCount" . }} +``` + +The function will pass the `.` context to the `"wordCount"` id: + +{{< code-toggle file="i18n/en-US" >}} +[wordCount] +other = "This article has {{ .WordCount }} words." +{{< /code-toggle >}} + +Assume `.WordCount` in the context has value is 101. The result will be: + +```text +This article has 101 words. +``` + +### Query a singular/plural translation + +In other to meet singular/plural requirement, you must pass a dictionary (map) with a numeric `.Count` property to the `i18n` function. The below example uses `.ReadingTime` variable which has a built-in `.Count` property. + +```go-html-template +{{ i18n "readingTime" .ReadingTime }} +``` + +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" >}} +[readingTime] +one = "One minute to read" +other = "{{ .Count }} minutes to read" +{{< /code-toggle >}} + +Assuming `.ReadingTime.Count` in the context has value is 525600. The result will be: + +```text +525600 minutes to read +``` + +If `.ReadingTime.Count` in the context has value is 1. The result is: + +```text +One minute to read +``` + +In case you need to pass a custom data: (`(dict "Count" numeric_value_only)` is minimum requirement) + +```go-html-template +{{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }} +``` + +## Localization + +The following localization examples assume your site's primary language is English, with translations to French and German. + +{{< code-toggle file="hugo" >}} +defaultContentLanguage = 'en' + +[languages] +[languages.en] +contentDir = 'content/en' +languageName = 'English' +weight = 1 +[languages.fr] +contentDir = 'content/fr' +languageName = 'FranÃ§ais' +weight = 2 +[languages.de] +contentDir = 'content/de' +languageName = 'Deutsch' +weight = 3 + +{{< /code-toggle >}} + +### Dates + +With this front matter: + +{{< code-toggle >}} +date = 2021-11-03T12:34:56+01:00 +{{< /code-toggle >}} + +And this template code: + +```go-html-template +{{ .Date | time.Format ":date_full" }} +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|Wednesday, November 3, 2021 +FranÃ§ais|mercredi 3 novembre 2021 +Deutsch|Mittwoch, 3. November 2021 + +See [time.Format] for details. + +### Currency + +With this template code: + +```go-html-template +{{ 512.5032 | lang.FormatCurrency 2 "USD" }} +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|$512.50 +FranÃ§ais|512,50 $US +Deutsch|512,50 $ + +See [lang.FormatCurrency] and [lang.FormatAccounting] for details. + +### Numbers + +With this template code: + +```go-html-template +{{ 512.5032 | lang.FormatNumber 2 }} +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|512.50 +FranÃ§ais|512,50 +Deutsch|512,50 + +See [lang.FormatNumber] and [lang.FormatNumberCustom] for details. + +### Percentages + +With this template code: + +```go-html-template +{{ 512.5032 | lang.FormatPercent 2 }} ---> 512.50% +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|512.50% +FranÃ§ais|512,50 % +Deutsch|512,50 % + +See [lang.FormatPercent] for details. + +## Menus + +Localization of menu entries depends on the 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 can (a) use translation tables, or (b) create language-specific menu entries under each language key. + +### Use translation tables + +When rendering the text that appears in menu each entry, the [example menu template] does this: + +```go-html-template +{{ or (T .Identifier) .Name | safeHTML }} +``` + +It queries the translation table for the current language using the menu entry's `identifier` and returns the translated string. If the translation table does not exist, or if the `identifier` key is not present in the translation table, it falls back to `name`. + +The `identifier` depends on how you define menu entries: + +- If you define the menu entry [automatically] using the section pages menu, the `identifier` is the page's `.Section`. +- If you define the menu entry [in site configuration] or [in front matter], set the `identifier` property to the desired value. + +For example, if you define menu entries in site configuration: + +{{< code-toggle file="hugo" copy=false >}} +[[menu.main]] + identifier = 'products' + name = 'Products' + pageRef = '/products' + weight = 10 +[[menu.main]] + identifier = 'services' + name = 'Services' + pageRef = '/services' + weight = 20 +{{< / code-toggle >}} + +Create corresponding entries in the translation tables: + +{{< code-toggle file="i18n/de" copy=false >}} +products = 'Produkte' +services = 'Leistungen' +{{< / code-toggle >}} + +[example menu template]: /templates/menu-templates/#example +[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 + +### Create language-specific menu entries + +For example: + +{{< code-toggle file="hugo" copy=false >}} +[languages.de] +languageCode = 'de-DE' +languageName = 'Deutsch' +weight = 1 + +[[languages.de.menu.main]] +name = 'Produkte' +pageRef = '/products' +weight = 10 + +[[languages.de.menu.main]] +name = 'Leistungen' +pageRef = '/services' +weight = 20 + +[languages.en] +languageCode = 'en-US' +languageName = 'English' +weight = 2 + +[[languages.en.menu.main]] +name = 'Products' +pageRef = '/products' +weight = 10 + +[[languages.en.menu.main]] +name = 'Services' +pageRef = '/services' +weight = 20 +{{< /code-toggle >}} + +For a simple menu with two languages, these menu entries are easy to create and maintain. For a larger menu, or with more than two languages, using translation tables as described above is preferable. + - ## Missing Translations ++## Missing translations + +If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. + +While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. + +{{% note %}} +Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments. +{{% /note %}} + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge]. + +To track down missing translation strings, run Hugo with the `--printI18nWarnings` flag: + +```bash +hugo --printI18nWarnings | grep i18n +i18n|MISSING_TRANSLATION|en|wordCount +``` + - ## Multilingual Themes support ++## Multilingual themes support + +To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria: + +* Come from the built-in `.Permalink` or `.RelPermalink` +* Be constructed with the [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR** be prefixed with `{{ .LanguagePrefix }}` + +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` + +If you organize content with translations in the same directory: + +```text +hugo new post/test.en.md +hugo new post/test.de.md +``` + +If you organize content with translations in different directories: + +```text +hugo new content/en/post/test.md +hugo new content/de/post/test.md +``` + +[abslangurl]: /functions/abslangurl +[config]: /getting-started/configuration/ +[contenttemplate]: /templates/single-page-templates/ +[go-i18n-source]: https://github.com/nicksnyder/go-i18n +[go-i18n]: https://github.com/nicksnyder/go-i18n +[homepage]: /templates/homepage/ +[Hugo Multilingual Part 1: Content translation]: https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/ +[i18func]: /functions/i18n/ +[lang.FormatAccounting]: /functions/lang +[lang.FormatCurrency]: /functions/lang +[lang.FormatNumber]: /functions/lang +[lang.FormatNumberCustom]: /functions/lang +[lang.FormatPercent]: /functions/lang +[lang.Merge]: /functions/lang.merge/ +[menus]: /content-management/menus/ +[OS environment]: /getting-started/configuration/#configure-with-environment-variables +[rellangurl]: /functions/rellangurl +[RFC 5646]: https://tools.ietf.org/html/rfc5646 +[single page templates]: /templates/single-page-templates/ +[time.Format]: /functions/dateformat diff --cc docs/content/en/content-management/organization/index.md index efa355ddc,000000000..2c0d2e604 mode 100644,000000..100644 --- a/docs/content/en/content-management/organization/index.md +++ b/docs/content/en/content-management/organization/index.md @@@ -1,161 -1,0 +1,161 @@@ +--- - title: Content Organization ++title: Content organization +linkTitle: Organization +description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site. - categories: [content management,fundamentals] ++categories: [fundamentals,content management] +keywords: [sections,content,organization,bundle,resources] +menu: + docs: + parent: content-management + weight: 20 +toc: true +weight: 20 +aliases: [/content/sections/] +--- + - ## Page Bundles ++## Page bundles + +Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`. + +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" >}} +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 ++## Organization of content source + +In Hugo, your content should be organized in a manner that reflects the rendered website. + +While Hugo supports content nested at any level, the top levels (i.e. `content/`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections]. + +Without any additional configuration, the following will automatically work: + +```txt +. +âââ content + âââ about + | âââ index.md // <- https://example.com/about/ + âââ posts + | âââ firstpost.md // <- https://example.com/posts/firstpost/ + | âââ happy + | | âââ ness.md // <- https://example.com/posts/happy/ness/ + | âââ secondpost.md // <- https://example.com/posts/secondpost/ + âââ quote + âââ first.md // <- https://example.com/quote/first/ + âââ second.md // <- https://example.com/quote/second/ +``` + - ## Path Breakdown in Hugo ++## Path breakdown in Hugo + + +The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.com"` in your [site's configuration file][config]. + - ### Index Pages: `_index.md` ++### Index pages: `_index.md` + +`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates], [taxonomy templates], [taxonomy terms templates], and your [homepage template]. + +{{% note %}} +**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/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 +. â¢--^-â£ +. path slug +. â¢--^-â£â¢---^---â£ +. filepath +. â¢------^------â£ +content/posts/_index.md +``` + +At build, this will output to the following destination with the associated values: + +```txt + + url ("/posts/") + â¢-^-â£ + baseurl section ("posts") +â¢--------^---------â£â¢-^-â£ + permalink +â¢----------^-------------â£ +https://example.com/posts/index.html +``` + +The [sections] can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. `_index.md`). + + - ### Single Pages in Sections ++### Single pages in sections + +Single content files in each of your sections will be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`: + + +```txt + path ("posts/my-first-hugo-post.md") +. â¢-----------^------------â£ +. section slug +. â¢-^-â£â¢--------^----------â£ +content/posts/my-first-hugo-post.md +``` + +When Hugo builds your site, the content will be output to the following destination: + +```txt + + url ("/posts/my-first-hugo-post/") + â¢------------^----------â£ + baseurl section slug +â¢--------^--------â£â¢-^--â£â¢-------^---------â£ + permalink +â¢--------------------^---------------------â£ +https://example.com/posts/my-first-hugo-post/index.html +``` + + - ## Paths Explained ++## Paths explained + +The following concepts provide more insight into the relationship between your project's organization and the default Hugo behavior when building output for the website. + +### `section` + +A default content type is determined by the section in which a content item is stored. `section` is determined by the location within the project's `content` directory. `section` *cannot* be specified or overridden in front matter. + +### `slug` + +The `slug` is the last segment of the URL path, defined by the file name and optionally overridden by a `slug` value in front matter. See [URL Management](/content-management/urls/#slug) for details. + +### `path` + +A content's `path` is determined by the section's path to the file. The file `path` + +* is based on the path to the content's location AND +* does not include the slug + +### `url` + +The `url` is the entire URL path, defined by the file path and optionally overridden by a `url` value in front matter. See [URL Management](/content-management/urls/#slug) for details. + +[config]: /getting-started/configuration/ +[formats]: /content-management/formats/ +[front matter]: /content-management/front-matter/ +[getpage]: /functions/getpage/ +[homepage template]: /templates/homepage/ +[homepage]: /templates/homepage/ +[lists]: /templates/lists/ +[pretty]: /content-management/urls/#appearance +[section templates]: /templates/section-templates/ +[sections]: /content-management/sections/ +[singles]: /templates/single-page-templates/ +[taxonomy templates]: /templates/taxonomy-templates/ +[taxonomy terms templates]: /templates/taxonomy-templates/ +[types]: /content-management/types/ +[urls]: /content-management/urls/ diff --cc docs/content/en/content-management/page-bundles.md index 2a5147c21,000000000..c4ce69f5f mode 100644,000000..100644 --- a/docs/content/en/content-management/page-bundles.md +++ b/docs/content/en/content-management/page-bundles.md @@@ -1,186 -1,0 +1,185 @@@ +--- - title: Page Bundles ++title: Page bundles +description: Content organization using Page Bundles +keywords: [page, bundle, leaf, branch] +categories: [content management] +menu : + docs: + parent: content-management + weight: 30 +toc: true +weight: 30 +--- + +Page Bundles are a way to group [Page Resources](/content-management/page-resources/). + +A Page Bundle can be one of: + +- Leaf Bundle (leaf means it has no children) +- Branch Bundle (home page, section, taxonomy terms, taxonomy list) + +| | Leaf Bundle | Branch Bundle | - |-------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ++|-------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Usage | Collection of content and attachments for single pages | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list) | - | Index filename | `index.md` [^fn:1] | `_index.md` [^fn:1] | ++| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] | +| Allowed Resources | Page and non-page (like images, PDF, etc.) types | Only non-page (like images, PDF, etc.) types | +| Where can the Resources live? | At any directory level within the leaf bundle directory. | Only in the directory level **of** the branch bundle directory i.e. the directory containing the `_index.md` ([ref](https://discourse.gohugo.io/t/question-about-content-folder-structure/11822/4?u=kaushalmodi)). | - | Layout type | `single` | `list` | ++| Layout type | [`single`](/templates/single-page-templates/) | [`list`](/templates/lists) | +| Nesting | Does not allow nesting of more bundles under it | Allows nesting of leaf or branch bundles under it | +| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` | - | Content from non-index page files... | Accessed only as page resources | Accessed only as regular pages | ++| Content from non-index page files...| Accessed only as page resources | Accessed only as regular pages | + - - ## Leaf Bundles {#leaf-bundles} ++## Leaf bundles + +A _Leaf Bundle_ is a directory at any hierarchy within the `content/` +directory, that contains an **`index.md`** file. + - ### Examples of Leaf Bundle organization {#examples-of-leaf-bundle-organization} ++### Examples of leaf bundle organization {#examples-of-leaf-bundle-organization} + +```text +content/ +âââ about +â âââ index.md +âââ posts +â âââ my-post +â â âââ content1.md +â â âââ content2.md +â â âââ image1.jpg +â â âââ image2.png +â â âââ index.md +â âââ my-other-post +â Â Â âââ index.md +â +âââ another-section + âââ .. + Â Â âââ not-a-leaf-bundle + âââ .. + Â Â âââ another-leaf-bundle + Â Â âââ index.md +``` + +In the above example `content/` directory, there are four leaf +bundles: + +`about` +: This leaf bundle is at the root level (directly under + `content` directory) and has only the `index.md`. + +`my-post` +: This leaf bundle has the `index.md`, two other content + Markdown files and two image files. + +- image1, image2: +These images are page resources of `my-post` + and only available in `my-post/index.md` resources. + +- content1, content2: +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` +: This leaf bundle has only the `index.md`. + +`another-leaf-bundle` +: This leaf bundle is nested under couple of + directories. This bundle also has only the `index.md`. + +{{% note %}} +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 {#headless-bundle} ++### Headless bundle + +A headless bundle is a bundle that is configured to not get published +anywhere: + +- It will have no `Permalink` and no rendered HTML in `public/`. +- It will not be part of `.Site.RegularPages`, etc. + +But you can get it by `.Site.GetPage`. Here is an example: + +```go-html-template +{{ $headless := .Site.GetPage "/some-headless-bundle" }} +{{ $reusablePages := $headless.Resources.Match "author*" }} +

Authors

+{{ range $reusablePages }} +

+ {{ .Content }} +{{ end }} +``` + +_In this example, we are assuming the `some-headless-bundle` to be a headless + bundle containing one or more **page** resources whose `.Name` matches + `"author*"`._ + +Explanation of the above example: + +1. Get the `some-headless-bundle` Page "object". +2. Collect a _slice_ of resources in this _Page Bundle_ that matches + `"author*"` using `.Resources.Match`. +3. Loop through that _slice_ of nested pages, and output their `.Title` and + `.Content`. + +--- + - A leaf bundle can be made headless by adding below in the Front Matter ++A leaf bundle can be made headless by adding below in the front matter +(in the `index.md`): + +{{< code-toggle file="content/headless/index.md" fm=true copy=false >}} +headless = true +{{< /code-toggle >}} + +There are many use cases of such headless page bundles: + +- Shared media galleries +- Reusable page content "snippets" + - ## Branch Bundles {#branch-bundles} ++## Branch bundles + +A _Branch Bundle_ is any directory at any hierarchy within the +`content/` directory, that contains at least an **`_index.md`** file. + +This `_index.md` can also be directly under the `content/` directory. + +{{% note %}} +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 {#examples-of-branch-bundle-organization} ++### Examples of branch bundle organization + +```text +content/ +âââ branch-bundle-1 +âÂ Â âââ branch-content1.md +âÂ Â âââ branch-content2.md +âÂ Â âââ image1.jpg +âÂ Â âââ image2.png +âÂ Â âââ _index.md +âââ branch-bundle-2 + âââ _index.md + âââ a-leaf-bundle + âââ index.md +``` + +In the above example `content/` directory, there are two branch +bundles (and a leaf bundle): + +`branch-bundle-1` +: This branch bundle has the `_index.md`, two + other content Markdown files and two image files. + +`branch-bundle-2` +: This branch bundle has the `_index.md` and a + nested leaf bundle. + +{{% note %}} +The hierarchy depth at which a branch bundle is created does not +matter. +{{% /note %}} + +[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any valid MIME type. diff --cc docs/content/en/content-management/page-resources.md index 54494c2e1,000000000..bbf288459 mode 100644,000000..100644 --- a/docs/content/en/content-management/page-resources.md +++ b/docs/content/en/content-management/page-resources.md @@@ -1,203 -1,0 +1,203 @@@ +--- - title: Page Resources ++title: Page resources +description: Page resources -- images, other pages, documents, etc. -- have page-relative URLs and their own metadata. +categories: [content management] +keywords: [bundle,content,resources] +menu: + docs: + parent: content-management + weight: 80 +toc: true +weight: 80 +--- +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 +page with which they are bundled. + +In this example, `first-post` is a page bundle with access to 10 page resources including audio, data, documents, images, and video. Although `second-post` is also a page bundle, it has no page resources and is unable to directly access the page resources associated with `first-post`. + +```text +content +âââ post + âââ first-post + â âââ images + â â âââ a.jpg + â â âââ b.jpg + â â âââ c.jpg + â âââ index.md (root of page bundle) + â âââ latest.html + â âââ manual.json + â âââ notice.md + â âââ office.mp3 + â âââ pocket.mp4 + â âââ rating.pdf + â âââ safety.txt + âââ second-post + âââ index.md (root of page bundle) +``` + +## Properties + +ResourceType +: The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`. + +Name - : Default value is the filename (relative to the owning page). Can be set in front matter. ++: Default value is the file name (relative to the owning page). Can be set in front matter. + +Title +: Default value is the same as `.Name`. Can be set in front matter. + +Permalink +: The absolute URL to the resource. Resources of type `page` will have no value. + +RelPermalink +: The relative URL to the resource. Resources of type `page` will have no value. + +Content +: The content of the resource itself. For most resources, this returns a string +with the contents of the file. Use this to create inline resources. + +```go-html-template +{{ with .Resources.GetMatch "script.js" }} + +{{ end }} + +{{ with .Resources.GetMatch "style.css" }} + +{{ end }} + +{{ with .Resources.GetMatch "img.png" }} -

+{{ end }} +``` + - MediaType - : The MIME type of the resource, such as `image/jpeg`. ++MediaType.Type ++: The media type (formerly known as a MIME type) of the resource (e.g., `image/jpeg`). + +MediaType.MainType - : The main type of the resource's MIME type. For example, a file of MIME type `application/pdf` has for MainType `application`. ++: The main type of the resource's media type (e.g., `image`). + +MediaType.SubType - : The subtype of the resource's MIME type. For example, a file of MIME type `application/pdf` has for SubType `pdf`. Note that this is not the same as the file extension. For example, Microsoft PowerPoint files (`.ppt`) have a subtype of `vnd.ms-powerpoint`. ++: The subtype of the resource's type (e.g., `jpeg`). This may or may not correspond to the file suffix. + +MediaType.Suffixes - : A slice of possible suffixes for the resource's MIME type. ++: A slice of possible file suffixes for the resource's media type (e.g., `[jpg jpeg jpe jif jfif]`). + +## Methods + +ByType +: Returns the page resources of the given type. + +```go-html-template +{{ .Resources.ByType "image" }} +``` +Match +: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive. + +```go-html-template +{{ .Resources.Match "images/*" }} +``` + +GetMatch +: Same as `Match` but will return the first match. + - ### Pattern Matching ++### Pattern matching + +```go +// Using Match/GetMatch to find this images/sunset.jpg ? +.Resources.Match "images/sun*" â +.Resources.Match "**/sunset.jpg" â +.Resources.Match "images/*.jpg" â +.Resources.Match "**.jpg" â +.Resources.Match "*" ð« +.Resources.Match "sunset.jpg" ð« +.Resources.Match "*sunset.jpg" ð« + +``` + - ## Page Resources Metadata ++## Page resources metadata + +The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). + +{{% note %}} +Resources of type `page` get `Title` etc. from their own front matter. +{{% /note %}} + +name +: Sets the value returned in `Name`. + +{{% note %}} +The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources. +{{% /note %}} + +title +: Sets the value returned in `Title` + +params +: A map of custom key/values. + +### Resources metadata example + +{{< code-toggle copy=false >}} +title: Application +date : 2018-01-25 +resources : +- src : "images/sunset.jpg" + name : "header" +- src : "documents/photo_specs.pdf" + title : "Photo Specifications" + params: + icon : "photo" +- src : "documents/guide.pdf" + title : "Instruction Guide" +- src : "documents/checklist.pdf" + title : "Document Checklist" +- src : "documents/payment.docx" + title : "Proof of Payment" +- src : "**.pdf" + name : "pdf-file-:counter" + params : + icon : "pdf" +- src : "**.docx" + params : + icon : "word" +{{}} + +From the example above: + +- `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`. +- `documents/photo_specs.pdf` will get the `photo` icon. +- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`. +- Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon. +- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`. +- Every docx in the bundle will receive the `word` icon. + +{{% note %}} +The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule. +{{% /note %}} + +### The `:counter` placeholder in `name` and `title` + +The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`. + +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 >}} +[[resources]] + src = "*specs.pdf" + title = "Specification #:counter" +[[resources]] + src = "**.pdf" + name = "pdf-file-:counter" +{{}} + +the `Name` and `Title` will be assigned to the resource files as follows: + +| Resource file | `Name` | `Title` | +|-------------------|-------------------|-----------------------| +| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` | +| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` | +| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` | +| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` | diff --cc docs/content/en/content-management/related.md index e80c0f06b,000000000..d897bf47f mode 100644,000000..100644 --- a/docs/content/en/content-management/related.md +++ b/docs/content/en/content-management/related.md @@@ -1,188 -1,0 +1,188 @@@ +--- - title: Related Content ++title: Related content +description: List related content in "See Also" sections. +categories: [content management] +keywords: [content] +menu: + docs: + parent: content-management + weight: 110 +toc: true +weight: 110 +aliases: [/content/related/,/related/] +--- + - Hugo uses a set of factors to identify a page's related content based on Front Matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content). ++Hugo uses a set of factors to identify a page's related content based on front matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content). + - ## List Related Content ++## List related content + +To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template: + +{{< code file="layouts/partials/related.html" >}} +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +

- {{ .Content }} -

- ++ +{{ end }} +{{< /code >}} + +To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes]. + +[archetypes]: /content-management/archetypes/ +[base templates]: /templates/base/ - [config]: /getting-started/configuration/ +[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/ +[front matter]: /content-management/front-matter/ - [pagetaxonomy]: /templates/taxonomy-templates/#display-a-single-piece-of-contents-taxonomies ++[pagetaxonomy]: /templates/taxonomy-templates/#list-terms-assigned-to-a-page +[pagevars]: /variables/page/ +[partials]: /templates/partials/ +[section]: /content-management/sections/ +[site variables]: /variables/site/ +[spf13]: https://spf13.com/ +[`with`]: /functions/with/ diff --cc docs/content/en/templates/sitemap-template.md index 37462a086,000000000..32299bf52 mode 100644,000000..100644 --- a/docs/content/en/templates/sitemap-template.md +++ b/docs/content/en/templates/sitemap-template.md @@@ -1,84 -1,0 +1,84 @@@ +--- - title: Sitemap Templates ++title: Sitemap templates +description: Hugo provides built-in sitemap templates. +categories: [templates] +keywords: [sitemap, xml, templates] +menu: + docs: + parent: templates - weight: 160 - weight: 160 ++ weight: 170 ++weight: 170 +aliases: [/layout/sitemap/,/templates/sitemap/] +toc: true +--- + +## Overview + +Hugo's built-in sitemap templates conform to v0.9 of the [sitemap protocol]. + +With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemap.xml] template. + +With a multilingual project, Hugo generates: + +- A sitemap.xml file in the root of each site (language) using the built-in [sitemap.xml] template +- A sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemapindex.xml] template + +## Configuration + +Set the default values for [change frequency] and [priority], and the name of the generated file, in your site configuration. + +{{< code-toggle file="hugo" >}} +[sitemap] + changefreq = 'monthly' + filename = 'sitemap.xml' + priority = 0.5 +{{}} + +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). + +filename +: The name of the generated file. Default is `sitemap.xml`. + +priority +: 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). + - ## Override Default Values ++## Override default values + +Override the default values for a given page in front matter. + +{{< code-toggle file="news.md" fm=true >}} +title = 'News' +[sitemap] + changefreq = 'weekly' + priority = 0.8 +{{}} + - ## Override Built-in Templates ++## Override built-in templates + +To override the built-in sitemap.xml template, create a new file in either of these locations: + +- layouts/sitemap.xml +- layouts/_default/sitemap.xml + +When ranging through the page collection, access the _change frequency_ and _priority_ with `.Sitemap.ChangeFreq` and `.Sitemap.Priority` respectively. + +To override the built-in sitemapindex.xml template, create a new file in either of these locations: + +- layouts/sitemapindex.xml +- layouts/_default/sitemapindex.xml + - ## Disable Sitemap Generation ++## Disable sitemap generation + +You may disable sitemap generation in your site configuration: + +{{< code-toggle file="hugo" >}} +disableKinds = ['sitemap'] +{{}} + +[`publishDir`]: /getting-started/configuration#publishdir +[change frequency]: +[priority]: +[sitemap protocol]: +[sitemap.xml]: +[sitemapindex.xml]: diff --cc docs/content/en/templates/taxonomy-templates.md index e343df471,000000000..9b4117e66 mode 100644,000000..100644 --- a/docs/content/en/templates/taxonomy-templates.md +++ b/docs/content/en/templates/taxonomy-templates.md @@@ -1,333 -1,0 +1,327 @@@ +--- - title: Taxonomy Templates ++title: Taxonomy templates +description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates. +categories: [templates] +keywords: [taxonomies,metadata,front matter,terms,templates] +menu: + docs: + parent: templates - weight: 50 - weight: 50 ++ weight: 90 ++weight: 90 +aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/] +toc: true +--- + + + +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: + +* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-templates) +* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-templates) +* List a single content's taxonomy terms within a [single page template] + - ## Taxonomy List Templates ++## Taxonomy list templates + +Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists]. + - ### Taxonomy List Template Lookup Order ++### Taxonomy list template lookup order + +See [Template Lookup](/templates/lookup-order/). + - ## Taxonomy Terms Templates ++## Taxonomy terms templates + - ### Taxonomy Terms Templates Lookup Order ++### Taxonomy terms templates lookup order + +See [Template Lookup](/templates/lookup-order/). + - ### Taxonomy Methods ++### Taxonomy methods + +A Taxonomy is a `map[string]WeightedPages`. + +.Get(term) +: Returns the WeightedPages for a term. + +.Count(term) +: The number of pieces of content assigned to this term. + +.Alphabetical +: Returns an OrderedTaxonomy (slice) ordered by Term. + +.ByCount +: Returns an OrderedTaxonomy (slice) ordered by number of entries. + +.Reverse +: Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy. + +### OrderedTaxonomy + +Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order. + +```go +[]struct { + Name string + WeightedPages WeightedPages +} +``` + +Each element of the slice has: + +.Term +: The Term used. + +.WeightedPages +: A slice of Weighted Pages. + +.Count +: The number of pieces of content assigned to this term. + +.Pages +: All Pages assigned to this term. All [list methods][renderlists] are available to this. + +## WeightedPages + +WeightedPages is simply a slice of WeightedPage. + +```go +type WeightedPages []WeightedPage +``` + +.Count(term) +: The number of pieces of content assigned to this term. + +.Pages +: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists]. + - ## Displaying custom metadata in Taxonomy Terms Templates ++## Displaying custom metadata in taxonomy terms templates + +If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content///_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such: + +```go-html-template +

- {{ .Title }} - {{ .Params.wikipedia }} -
++ {{ .Title }} ++ {{ .Params.wikipedia }} ++

+``` + + + - ## Order Taxonomies ++## Order taxonomies + +Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key. + - ### Order Alphabetically Example ++### Order alphabetically example + +```go-html-template +

{{ .Page.Title }} {{ .Count }}
{{ .Page.Title }} {{ .Count }}

+``` + + + - ## Order Content within Taxonomies ++## Order content within taxonomies + +Hugo uses both `date` and `weight` to order content within taxonomies. + +Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to. + +When iterating over content within taxonomies, the default sort is the same as that used for section and list pages: first by weight, then by date. This means that if the weights for two pieces of content are the same, then the more recent content will be displayed first. + +The default weight for any piece of content is 0. Zero means "does not have a weight", not "has a weight of numerical value zero". + +Weights of zero are thus treated specially: if two pages have unequal weights, and one of them is zero, then the zero-weighted page will always appear after the other one, regardless of the other's weight. Zero weights should thus be used with care: for example, if both positive and negative weights are used to extend a sequence in both directions, a zero-weighted page will appear not in the middle of the list, but at the end. + - ### Assign Weight ++### Assign weight + +Content can be assigned weight for each taxonomy that it's assigned to. + - +{{< code-toggle file="content/example.md" fm=true copy=false >}} +tags = [ "a", "b", "c" ] +tags_weight = 22 +categories = ["d"] +title = "Example" +categories_weight = 44 +{{< /code-toggle >}} + +The convention is `taxonomyname_weight`. + +In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy. + +It has also been assigned the weight of 44 when rendering the 'd' category. + +With this the same piece of content can appear in different positions in different taxonomies. + +Currently taxonomies only support the default ordering of content which is weight -> date. + + + +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. + +A [list template](/templates/lists/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages. + +A [taxonomy template](/templates/taxonomy-templates/) is a template used to +generate the list of terms for a given template. + + + +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/): + +1. For a given piece of content, you can list the terms attached +2. For a given piece of content, you can list other content with the same + term +3. You can list all terms for a taxonomy +4. You can list all taxonomies (with their terms) + - ## Display a Single Piece of Content's Taxonomies - - Within your content templates, you may wish to display the taxonomies that piece of content is assigned to. ++## List terms assigned to a page + - Because we are leveraging the front matter system to define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (i.e., `.Params.`). ++List the terms assigned to a page using the `.Page.GetTerms` method. + - ### Example: List Tags in a Single Page Template ++To render an unordered list: + +```go-html-template -

{{ .LinkTitle }}

{{ (site.GetPage $taxonomy).LinkTitle }}:

{{ .LinkTitle }}

++{{ end }} +``` + - If you want to list taxonomies inline, you will have to take care of optional plural endings in the title (if multiple taxonomies), as well as commas. Let's say we have a taxonomy "directors" such as `directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter. - - To list such taxonomies, use the following: - - ### Example: Comma-delimit Tags in a Single Page Template ++To render a comma-delimited list: + +```go-html-template - {{ $taxo := "directors" }} - {{ with .Param $taxo }} - Director{{ if gt (len .) 1 }}s{{ end }}: - {{ range $index, $director := . }} - {{- if gt $index 0 }}, {{ end -}} - {{ with $.Site.GetPage (printf "/%s/%s" $taxo $director) -}} - {{ $director }} - {{- end -}} - {{- end -}} ++{{ $taxonomy := "tags" }} ++{{ with .GetTerms $taxonomy }} ++

++ {{ (site.GetPage $taxonomy).LinkTitle }}: ++ {{ range $k, $_ := . -}} ++ {{ if $k }}, {{ end }} ++ {{ .LinkTitle }} ++ {{- end }} ++

+{{ end }} +``` + - Alternatively, you may use the [delimit template function][delimit] as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion. - - ## List Content with the Same Taxonomy Term ++## List content with the same taxonomy term + +If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content: + - ### Example: Showing Content in Same Series ++### Example: showing content in same series + +```go-html-template +

{{ .Page.Title }}
{{ .Page.Title }}

+``` + - ## List All content in a Given taxonomy ++## List all content in a given taxonomy + +This would be very useful in a sidebar as âfeatured contentâ. You could even have different sections of âfeatured contentâ by assigning different terms to the content. + - ### Example: Grouping "Featured" Content ++### Example: grouping "featured" content + +```go-html-template + +``` + - ## Render a Site's Taxonomies ++## Render a site's taxonomies + +If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page. + +This may take the form of a tag cloud, a menu, or simply a list. + +The following example displays all terms in a site's tags taxonomy: + - ### Example: List All Site Tags {#example-list-all-site-tags} ++### Example: list all site tags + +```go-html-template +

{{ .Page.Title }} {{ .Count }}
{{ .Page.Title }} {{ .Count }}

+``` + - ### Example: List All Taxonomies, Terms, and Assigned Content ++### Example: list all taxonomies, terms, and assigned content + +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" >}} -

{{ $taxonomy_term }} -
- {{ $key }}
-

++ {{ with site.GetPage $taxonomy }} ++ {{ .LinkTitle }} ++ {{ end }} ++
- ++ {{ .Page.LinkTitle }} ++
  - {{ .LinkTitle }}
  ++
-

++ ++ ++ {{ end }} ++ +{{< /code >}} + - ## `.Site.GetPage` for Taxonomies ++## `.Site.GetPage` for taxonomies + +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" >}} +{{ $taxo := "tags" }} +

{{ .Title }}
{{ .Title }}

+{{< /code >}} + + + + + + +[delimit]: /functions/delimit/ +[getpage]: /functions/getpage/ +[lists]: /templates/lists/ +[renderlists]: /templates/lists/ +[single page template]: /templates/single-page-templates/ +[sitevars]: /variables/site/ diff --cc docs/content/en/templates/template-debugging.md index 0f32fa732,000000000..fd400018b mode 100644,000000..100644 --- a/docs/content/en/templates/template-debugging.md +++ b/docs/content/en/templates/template-debugging.md @@@ -1,64 -1,0 +1,72 @@@ +--- - title: Template Debugging ++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: 180 - weight: 180 ++ 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? ++## 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 }} +``` + - ## Why Am I Showing No Defined Variables? ++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 ++

{{ . | jsonify (dict "indent" " ") }}

++``` ++ ++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 --cc docs/content/en/templates/views.md index 24ff61150,000000000..3d00a4ed6 mode 100644,000000..100644 --- a/docs/content/en/templates/views.md +++ b/docs/content/en/templates/views.md @@@ -1,114 -1,0 +1,114 @@@ +--- - title: Content View Templates - description: Hugo can render alternative views of your content, which is especially useful in list and summary views. ++title: Content view templates ++description: Hugo can render alternative views of your content, useful in list and summary views. +categories: [templates] +keywords: [views] +menu: + docs: + parent: templates - weight: 70 - weight: 70 ++ weight: 110 ++weight: 110 +toc: true +--- + +These alternative **content views** are especially useful in [list templates][lists]. + +The following are common use cases for content views: + +* You want content of every type to be shown on the homepage but only with limited [summary views][summaries]. +* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself. + - ## Create a Content View ++## Create a content view + +To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view. + +```txt + â¾ layouts/ + â¾ posts/ + li.html + single.html + summary.html + â¾ project/ + li.html + single.html + summary.html +``` + +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/ + li.html + single.html + summary.html +``` + - ## Which Template Will be Rendered? ++## Which template will be rendered? + +The following is the [lookup order][lookup] for content views: + +1. `/layouts//.html` +2. `/layouts/_default/.html` +3. `/themes//layouts//.html` +4. `/themes//layouts/_default/.html` + - ## Example: Content View Inside a List ++## Example: content view inside a list + +The following example demonstrates how to use content views inside your [list templates][lists]. + +### `list.html` + +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" >}} +

+ {{ range .Pages }} + {{ .Render "summary" }} + {{ end }} +

+{{< /code >}} + +### `summary.html` + +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" >}} +

{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words

+ {{ .Summary }} + +

+{{< /code >}} + +### `li.html` + +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" >}} +

+ {{ .Title }} +

+{{< /code >}} + +[lists]: /templates/lists/ +[lookup]: /templates/lookup-order/ +[pagevars]: /variables/page/ +[render]: /functions/render/ +[single]: /templates/single-page-templates/ +[spf]: https://spf13.com +[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html +[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html +[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html +[summaries]: /content-management/summaries/ +[taxonomylists]: /templates/taxonomy-templates/ diff --cc docs/content/en/tools/_index.md index b553dac9c,000000000..6cc8c44d7 mode 100644,000000..100644 --- a/docs/content/en/tools/_index.md +++ b/docs/content/en/tools/_index.md @@@ -1,19 -1,0 +1,20 @@@ +--- - title: Developer Tools - linktitle: Developer Tools Overview ++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] +keywords: [] +menu: + docs: - parent: tools - weight: 01 - weight: 01 ++ identifier: developer-tools-overview ++ parent: developer-tools ++ weight: 10 ++weight: 10 +--- + +One of Hugo's greatest strengths is its passionate---and always evolving---developer community. With the exception of the `highlight` shortcode mentioned in [Syntax Highlighting][syntax], the tools and other projects featured in this section are offerings from both commercial services and open-source projects, many of which are developed by Hugo developers just like you. + +[See the popularity of Hugo compared with other static site generators.][staticgen] + +[staticgen]: https://staticgen.com +[syntax]: /content-management/syntax-highlighting/ diff --cc docs/content/en/tools/editors.md index 5efeba336,000000000..92720ab42 mode 100644,000000..100644 --- a/docs/content/en/tools/editors.md +++ b/docs/content/en/tools/editors.md @@@ -1,45 -1,0 +1,40 @@@ +--- - title: Editor Plug-ins for Hugo - linktitle: Editor Plug-ins ++title: Editor plugins for Hugo ++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. +categories: [developer tools] +keywords: [editor, plug-ins] +menu: + docs: - parent: tools - weight: 50 - weight: 50 ++ parent: developer-tools ++ weight: 20 ++weight: 20 +--- + +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. + +## Sublime Text + +* [Hugofy](https://github.com/akmittal/Hugofy). Hugofy is a plugin for Sublime Text 3 to make life easier to use Hugo static site generator. +* [Hugo Snippets](https://packagecontrol.io/packages/Hugo%20Snippets). Hugo Snippets is a useful plugin for adding automatic snippets to Sublime Text 3. + +## Visual Studio Code + +* [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). +* [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. +* [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... +* [Syntax Highlighting for Hugo Shortcodes](https://marketplace.visualstudio.com/items?itemName=kaellarkin.hugo-shortcode-syntax). This extension add 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. + +## Vim + +* [Vim Hugo Helper](https://github.com/robertbasic/vim-hugo-helper). A small Vim plugin to help me with writing posts with Hugo. +* [vim-hugo](https://github.com/phelipetls/vim-hugo). A Vim plugin with syntax highlighting for templates and a few other features. + - ## Atom - - * [Hugofy](https://atom.io/packages/hugofy). A Hugo Static Website Generator package for Atom. - * [language-hugo](https://atom.io/packages/language-hugo). Adds syntax highlighting to Hugo files. - +[formats]: /content-management/formats/ diff --cc docs/content/en/tools/frontends.md index 1bfaf0995,000000000..bc4df22b5 mode 100644,000000..100644 --- a/docs/content/en/tools/frontends.md +++ b/docs/content/en/tools/frontends.md @@@ -1,22 -1,0 +1,22 @@@ +--- - title: Frontend Interfaces with Hugo - linktitle: Frontends ++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: tools - weight: 40 - weight: 40 ++ 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. - - [Netlify CMS](https://netlifycms.org). Netlify 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/Netlify CMS starter](https://github.com/netlify-templates/one-click-hugo-cms) is available to get new projects running quickly. ++- [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 ++## 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 --cc docs/content/en/tools/migrations.md index 0156c46db,000000000..6ef605ec6 mode 100644,000000..100644 --- a/docs/content/en/tools/migrations.md +++ b/docs/content/en/tools/migrations.md @@@ -1,80 -1,0 +1,80 @@@ +--- +title: Migrate to Hugo - linktitle: Migrations ++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] +menu: + docs: - parent: tools - weight: 10 - weight: 10 ++ parent: developer-tools ++ weight: 50 ++weight: 50 +aliases: [/developer-tools/migrations/, /developer-tools/migrated/] +toc: true +--- + +This section highlights some projects around Hugo that are independently developed. These tools try to extend the functionality of our static site generator or help you to get started. + +{{% note %}} +Do you know or maintain a similar project around Hugo? Feel free to open a [pull request](https://github.com/gohugoio/hugoDocs/pulls) on GitHub if you think it should be added. +{{% /note %}} + +Take a look at this list of migration tools if you currently use other blogging tools like Jekyll or WordPress but intend to switch to Hugo instead. They'll take care to export your content into Hugo-friendly formats. + +## Jekyll + +Alternatively, you can use the new [Jekyll import command](/commands/hugo_import_jekyll/). + +- [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. + +## Ghost + +- [ghostToHugo](https://github.com/jbarone/ghostToHugo) - Convert Ghost blog posts and export them to Hugo. + +## Octopress + +- [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. + +## 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. + +## 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. ++- [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. + +## Drupal + +- [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. + +## 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. + +## 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/). + +## 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. diff --cc docs/content/en/tools/other.md index 3f8aeebbb,000000000..272827911 mode 100644,000000..100644 --- a/docs/content/en/tools/other.md +++ b/docs/content/en/tools/other.md @@@ -1,23 -1,0 +1,23 @@@ +--- - title: Other Hugo Community Projects - linktitle: Other Projects ++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] +menu: + docs: - parent: tools - weight: 70 - weight: 70 ++ parent: developer-tools ++ weight: 60 ++weight: 60 +--- + +And for all the other small things around Hugo: + +- [hugo-gallery](https://github.com/icecreammatt/hugo-gallery) lets you create an image gallery for Hugo sites. +- [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. +- [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 --cc docs/content/en/tools/search.md index 030e9f2c7,000000000..620ba4862 mode 100644,000000..100644 --- a/docs/content/en/tools/search.md +++ b/docs/content/en/tools/search.md @@@ -1,30 -1,0 +1,30 @@@ +--- - title: Search for your Hugo Website - linktitle: Search ++title: Search for your Hugo website ++linkTitle: Search +description: See some of the open-source and commercial search options for your newly created Hugo website. +menu: + docs: - parent: tools - weight: 60 - weight: 60 ++ parent: developer-tools ++ weight: 40 ++weight: 40 +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. + +* [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. + - ## Commercial Search Services ++## Commercial search services + +* [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. diff --cc docs/content/en/troubleshooting/_index.md index 51f1791a3,000000000..01b38ecdb mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/_index.md +++ b/docs/content/en/troubleshooting/_index.md @@@ -1,14 -1,0 +1,16 @@@ +--- +title: Troubleshoot ++linkTitle: Overview +description: Frequently asked questions and known issues pulled from the Hugo Discuss forum. +menu: + docs: ++ identifier: troubleshooting-overview + parent: troubleshooting - weight: 1 - weight: 1 ++ weight: 10 ++weight: 10 +aliases: [/troubleshooting/faqs/,/faqs/] +--- + +The Troubleshooting section includes known issues, recent workarounds, and FAQs pulled from the [Hugo Discussion Forum][forum]. + +[forum]: https://discourse.gohugo.io diff --cc docs/content/en/troubleshooting/build-performance.md index b58cdc11f,000000000..b4bbe28da mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/build-performance.md +++ b/docs/content/en/troubleshooting/build-performance.md @@@ -1,87 -1,0 +1,88 @@@ +--- - title: Build Performance ++title: Build performance +description: An overview of features used for diagnosing and improving performance issues in site builds. +menu: + docs: + parent: troubleshooting - weight: 3 ++ weight: 30 ++weight: 30 +toc: true +--- + - ## Template Metrics ++## 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** ++**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 ++## 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/partialcached diff --cc docs/content/en/troubleshooting/faq.md index 04e857acb,000000000..c854b273d mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/faq.md +++ b/docs/content/en/troubleshooting/faq.md @@@ -1,61 -1,0 +1,62 @@@ +--- - title: Frequently Asked Questions - linktitle: FAQ ++title: Frequently asked questions ++linkTitle: Frequently asked questions +description: Solutions to some common Hugo problems. +categories: [troubleshooting] +menu: + docs: + parent: troubleshooting ++ weight: 20 ++weight: 20 +keywords: [faqs] - weight: 2 +toc: true +aliases: [/faq/] +--- + +{{% 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 %}} + +## I can't see my content! + - Is your Markdown file [in draft mode](https://gohugo.io/content-management/front-matter/#front-matter-variables)? When testing, run `hugo server` with the `-D` or `--buildDrafts` [switch](https://gohugo.io/getting-started/usage/#draft-future-and-expired-content). ++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). + +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. + +## Can I set configuration variables via OS environment? + +Yes you can! See [Configure with Environment Variables](/getting-started/configuration/#configure-with-environment-variables). + +## How do I schedule posts? + - 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]. ++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. + +How to automate the "publish at intervals" part depends on your situation: + +* 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 + * 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) + +Also see this Twitter thread: + +{{< tweet user="ChrisShort" id="962380712027590657" >}} + - [^date-hierarchy]: See [Configure Dates](https://gohugo.io/getting-started/configuration/#configure-dates) for the order in which the different date variables are complemented by each other when not explicitly set. ++[^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. + +## Can I use the latest Hugo version on Netlify? + +Yes you can! Read [this](/hosting-and-deployment/hosting-on-netlify/#configure-hugo-version-in-netlify). + +## I get "... this feature is not available in your current Hugo version" + +If you process `SCSS` or `Sass` to `CSS` in your Hugo project with `libsass` as the transpiler or if you convert images to the `webp` format, you need the Hugo `extended` version, or else you may see an error message similar to the below: + +```bash +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 +``` + +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` + +To confirm, run `hugo version` and look for the word `extended`. diff --cc docs/content/en/variables/_index.md index 9b5289573,000000000..1ad42a9b3 mode 100644,000000..100644 --- a/docs/content/en/variables/_index.md +++ b/docs/content/en/variables/_index.md @@@ -1,17 -1,0 +1,18 @@@ +--- - title: Variables and Params - linktitle: Variables Overview ++title: Variables and parameters ++linkTitle: Overview +description: Page-, file-, taxonomy-, and site-level variables and parameters available in templates. - categories: [variables and params] ++categories: [variables and parameters] +keywords: [variables,params,values,globals] +menu: + docs: ++ identifier: variables-overview + parent: variables + weight: 1 - weight: 01 ++weight: 1 +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/ "Understand context in Go templates by learning the language's fundamental templating functions." diff --cc docs/content/en/variables/files.md index 784ab7c64,000000000..fa2a63a9c mode 100644,000000..100644 --- a/docs/content/en/variables/files.md +++ b/docs/content/en/variables/files.md @@@ -1,102 -1,0 +1,102 @@@ +--- - title: File Variables ++title: File variables +description: "Use File variables to access file-related values for each page that is backed by a file." - categories: [variables and params] ++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 --cc docs/content/en/variables/git.md index dfd6e5407,000000000..0804f6a32 mode 100644,000000..100644 --- a/docs/content/en/variables/git.md +++ b/docs/content/en/variables/git.md @@@ -1,51 -1,0 +1,51 @@@ +--- - title: Git Info Variables - linktitle: Git Variables ++title: Git variables ++linkTitle: Git variables +description: Get the last Git revision information for every content file. - categories: [variables and params] ++categories: [variables and parameters] +keywords: [git] +menu: + docs: + parent: variables + weight: 70 +weight: 70 +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 %}} + - ## `.GitInfo` Prerequisites ++## `.GitInfo` prerequisites + +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 + +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/ diff --cc docs/content/en/variables/menus.md index b88514803,000000000..0fe727cd8 mode 100644,000000..100644 --- a/docs/content/en/variables/menus.md +++ b/docs/content/en/variables/menus.md @@@ -1,92 -1,0 +1,92 @@@ +--- - title: Menu Variables ++title: Menu variables +description: Use these variables and methods in your menu templates. - categories: [variables and params] ++categories: [variables and parameters] +keywords: [menus] +menu: + docs: + parent: variables + weight: 50 +weight: 50 +aliases: [/variables/menu/] +--- + +## Variables + +After [defining menu entries], access their properties in [menu templates] with these variables. + +.Children +: (`menu`) A collection of child menu entries, if any, under the current menu entry. + +.Identifier +: (`string`) The `identifier` property of the menu entry. If you define the menu entry [automatically], the page's `.Section`. + +.KeyName +: (`string`) The `identifier` property of the menu entry, else the `name` property. + +.Menu +: (`string`) The identifier of the menu that contains the menu entry. + +.Name +: (`string`) The `name` property of the menu entry. + +- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`. +- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`. + +.Page +: (`page`) A reference to the page associated with the menu entry. + + + +.Params +: (`map`) The `params` property of the menu entry. + +.Parent +: (`string`) The `parent` property of the menu entry. + +.Post +: (`template.HTML`) The `post` property of the menu entry. + +.Pre +: (`template.HTML`) The `pre` property of the menu entry. + +.Title +: (`string`) The `title` property of the menu entry. + +- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`. +- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`. + +.URL +: (`string`) The `.RelPermalink` of the page associated with the menu entry. For menu entries pointing to external resources, the `url` property of the menu entry. + +.Weight +: (`int`) The `weight` property of the menu entry. + +- If you define the menu entry [automatically], the page's `.Weight`. +- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.Weight`. + +## Methods + +.HasChildren +: (`bool`) Returns `true` if `.Children` is non-nil. + +.IsEqual +: (`bool`) Returns `true` if the compared menu entries represent the same menu entry. + +.IsSameResource +: (`bool`) Returns `true` if the compared menu entries point to the same resource. + +.Page.HasMenuCurrent +: (`bool`) Use this method to determine ancestors of the active menu entry. See [details](/functions/hasmenucurrent/). + +.Page.IsMenuCurrent +: (`bool`) Use this method to determine the active menu entry. See [details](/functions/ismenucurrent/). + +[automatically]: /content-management/menus/#define-automatically +[defining menu entries]: /content-management/menus/#overview +[in front matter]: /content-management/menus/#define-in-front-matter +[in site configuration]: /content-management/menus/#define-in-site-configuration +[menu templates]: /templates/menu-templates/ diff --cc docs/content/en/variables/page.md index edad543ad,000000000..fc6e2f567 mode 100644,000000..100644 --- a/docs/content/en/variables/page.md +++ b/docs/content/en/variables/page.md @@@ -1,325 -1,0 +1,325 @@@ +--- - title: Page Variables ++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 params] ++categories: [variables and parameters] +keywords: [pages] +menu: + docs: + parent: variables + weight: 20 +weight: 20 +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. + - ## Page Variables ++## Page variables + +.AlternativeOutputFormats +: contains all alternative formats for a given page; this variable is especially useful `link rel` list in your site's ``. (See [Output Formats](/templates/output-formats/).) + +.Aliases +: aliases of this page + +.Ancestors +: get the ancestors of each page, simplify [breadcrumb navigation](/content-management/sections#example-breadcrumb-navigation) implementation complexity + +.BundleType +: the [bundle] type: `leaf`, `branch`, or an empty string if the page is not a bundle. + +.Content +: the content itself, defined below the front matter. + +.Data +: the data specific to this type of page. + +.Date +: the date associated with the page; `.Date` pulls from the `date` field in a content's front matter. See also `.ExpiryDate`, `.PublishDate`, and `.Lastmod`. + +.Description +: the description for the page. + +.Draft +: a boolean, `true` if the content is marked as a draft in the front matter. + +.ExpiryDate +: the date on which the content is scheduled to expire; `.ExpiryDate` pulls from the `expirydate` field in a content's front matter. See also `.PublishDate`, `.Date`, and `.Lastmod`. + +.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 the content was last modified. `.Lastmod` pulls from the `lastmod` field in a content's front matter. + + - If `lastmod` is not set, and `.GitInfo` feature is disabled, the front matter `date` field will be used. + - If `lastmod` is not set, and `.GitInfo` feature is enabled, `.GitInfo.AuthorDate` will be used instead. + +See also `.ExpiryDate`, `.Date`, `.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](/variables/site/#site-pages) (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](/variables/site/#site-pages) 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/).) + +.Pages +: a collection of associated pages. This value will be `nil` within + the context of regular content pages. See [`.Pages`](#pages). + +.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/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](/variables/site/#site-pages) (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](/variables/site/#site-pages) 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; `.Publishdate` pulls from the `publishdate` field in a content's front matter. See also `.ExpiryDate`, `.Date`, and `.Lastmod`. + +.RawContent +: raw markdown content without the front matter. Useful with [remarkjs.com]( +https://remarkjs.com) + +.ReadingTime +: the estimated time, in minutes, it takes to read the content. + +.Resources +: resources such as images and CSS that are associated with this page + +.Ref +: returns the permalink for a given reference (e.g., `.Ref "sample.md"`). `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). + +.RelPermalink +: the relative permanent link for this page. + +.RelRef +: returns the relative permalink for a given reference (e.g., `RelRef +"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). + +.Site +: see [Site Variables](/variables/site/). + +.Sites +: returns all sites (languages). A typical use case would be to link back to the main language: `...`. + +.Sites.First +: returns the site for the first language. If this is not a multilingual setup, it will return itself. + +.Summary +: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting  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. + - ## Writable Page-scoped Variables ++## 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 ++## Section variables and methods + +Also see [Sections](/content-management/sections/). + +{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}} + - ## The `.Pages` Variable {#pages} ++## The `.Pages` variable {#pages} + +`.Pages` is an alias to `.Data.Pages`. It is conventional to use the +aliased form `.Pages`. + +### `.Pages` compared to `.Site.Pages` + +{{< getcontent path="readfiles/pages-vs-site-pages.md" >}} + - ## Page Fragments ++## Page fragments + +{{< new-in "0.111.0" >}} + +The `.Fragments` method returns a list of fragments for the current page. + +.Headings +: A recursive list of headings for the current page. Can be used to generate a table of contents. + +{{< todo >}}add .Headings toc example{{< /todo >}} + +.Identifiers +: A sorted list of identifiers for the current page. Can be used to check if a page contains a specific identifier or if a page contains duplicate identifiers: + +```go-html-template +{{ if .Fragments.Identifiers.Contains "my-identifier" }} +

Page contains identifier "my-identifier"

+{{ end }} + +{{ if gt (.Fragments.Identifiers.Count "my-identifier") 1 }} +

Page contains duplicate "my-identifier" fragments

+{{ end }} +``` + +.HeadingsMap +: Holds a map of headings for the current page. Can be used to start the table of contents from a specific heading. + +Also see the [Go Doc](https://pkg.go.dev/github.com/gohugoio/hugo@v0.111.0/markup/tableofcontents#Fragments) for the return type. + +### Fragments in hooks and shortcodes + +`.Fragments` are safe to call from render hooks, even on the page you're on (`.Page.Fragments`). For shortcodes we recommend that all `.Fragments` usage is nested inside the `{{}}` shortcode delimiter (`{{%/**/%}}` takes part in the ToC creation so it's easy to end up in a situation where you bite yourself in the tail). + + +## The global page function + +{{< new-in "0.111.1" >}} + +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're deeply nested inside `.Render`, partial etc., accessing that `Page` object isn't always practical or possible. + +For this reason, Hugo provides a global `page` function that you can use to access the current page from anywhere in any template. + +```go-html-template +{{ page.Title }} +``` + +There are one caveat with this, and this isn't new, but it's worth mentioning here: There are situations in Hugo where you may see a cached value, e.g. when using `partialCached` or in a shortcode. + - ## Page-level Params ++## Page-level params + +Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable. + +{{< code-toggle file="content/example.md" fm=true copy=false >}} +title: Example +categories: [one] +tags: [two,three,four] +{{< /code-toggle >}} + +With the above front matter, the `tags` and `categories` taxonomies are accessible via the following: + +* `.Params.tags` +* `.Params.categories` + +The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter: + +{{< code-toggle file="content/example.md" fm=true copy=false >}} +title: Example +affiliatelink: "http://www.my-book-link.here" +recommendedby: "My Mother" +{{< /code-toggle >}} + +These fields would then be accessible to via `.Params.affiliatelink` and `.Params.recommendedby`. + +```go-html-template +

Buy this book

It was recommended by {{ .Params.recommendedby }}.

+``` + +This template would render as follows: + +```html +

Buy this book

It was recommended by my Mother.

+``` + +{{% note %}} +See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content. +{{% /note %}} + - ### The `.Param` Method ++### The `.Param` method + - In Hugo, you can declare params in individual pages and globally for your entire website. A common use case is to have a general value for the site param and a more specific value for some of the pages (i.e., a header image): ++In Hugo, you can declare parameters in individual pages and globally for your entire website. A common use case is to have a general value for the site parameter and a more specific value for some of the pages (i.e., a header image): + +```go-html-template +{{ $.Param "header_image" }} +``` + +The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your site configuration). + - ### Access Nested Fields in Front Matter ++### Access nested fields in front matter + +When front matter contains nested fields like the following: + +{{< code-toggle file="content/example.md" fm=true copy=false >}} +title: Example +author: + given_name: John + family_name: Feminella + display_name: John Feminella +{{< /code-toggle >}} + +`.Param` can access these fields by concatenating the field names together with a dot: + +```go-html-template +{{ $.Param "author.display_name" }} +``` + +[gitinfo]: /variables/git/ +[File Variables]: /variables/files/ +[bundle]: /content-management/page-bundles +[scratch]: /functions/scratch +[store]: /functions/store diff --cc docs/content/en/variables/pages.md index 15904de95,000000000..3917a6558 mode 100644,000000..100644 --- a/docs/content/en/variables/pages.md +++ b/docs/content/en/variables/pages.md @@@ -1,25 -1,0 +1,25 @@@ +--- - title: Pages Methods ++title: Pages methods +description: Pages is the core page collection in Hugo and has many useful methods. - categories: [variables and params] ++categories: [variables and parameters] +keywords: [pages] +menu: + docs: + parent: variables + weight: 21 +weight: 21 +aliases: [/pages] +toc: true +--- + +Also see [List templates](/templates/lists) for an overview of sort methods. + +## .Next PAGE + +`.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. + +`.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`. + +## .Prev PAGE + +`.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`. diff --cc docs/content/en/variables/shortcodes.md index 3d4185b45,000000000..a03485d6f mode 100644,000000..100644 --- a/docs/content/en/variables/shortcodes.md +++ b/docs/content/en/variables/shortcodes.md @@@ -1,45 -1,0 +1,45 @@@ +--- - title: Shortcode Variables ++title: Shortcode variables +description: Shortcodes can access page variables and also have their own specific built-in variables. - categories: [variables and params] ++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 [filename 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). ++: Contains [file name and position](https://godoc.org/github.com/gohugoio/hugo/common/text#Position) for the shortcode in a page. Note that this can be relatively expensive to calculate, and is meant for error reporting. See [Error Handling in Shortcodes](/templates/shortcode-templates/#error-handling-in-shortcodes). + +.IsNamedParams +: boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes] + +.Inner +: represents the content between the opening and closing shortcode tags when a [closing shortcode][markdownshortcode] is used + +.Scratch +: returns a writable [`Scratch`][scratch] to store and manipulate data which will be attached to the shortcode context. This scratch is reset on server rebuilds. + +.InnerDeindent {{< new-in "0.100.0" >}} +: Gets the `.Inner` with any indentation removed. This is what's used in the built-in `{{}}` shortcode. + +[getfunction]: /functions/get/ +[markdownshortcode]: /content-management/shortcodes/#shortcodes-with-markdown +[shortcodes]: /templates/shortcode-templates/ +[scratch]: /functions/scratch diff --cc docs/content/en/variables/site.md index 7e587cc79,000000000..151e7a12d mode 100644,000000..100644 --- a/docs/content/en/variables/site.md +++ b/docs/content/en/variables/site.md @@@ -1,123 -1,0 +1,123 @@@ +--- - title: Site Variables ++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 params] ++categories: [variables and parameters] +keywords: [global,site] +menu: + docs: + parent: variables + weight: 10 +weight: 10 +aliases: [/variables/site-variables/] +toc: true +--- + +The following is a list of site-level (aka "global") variables. Many of these variables are defined in your site's [configuration file][config], whereas others are built into Hugo's core for convenient usage in your templates. + - ## Get the Site object from a partial ++## 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 List ++## Site variables list + +.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](https://gohugo.io/variables/page/) ++: 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 only one defined language. See also the functions [absLangURL](/functions/abslangurl/) and [relLangURL](/functions/rellangurl). + +.Site.Languages +: an ordered list (ordered by defined weight) of languages. + +.Site.LastChange +: a string representing the date/time of the most recent change to your site. This string is based on the [`date` variable in the front matter](/content-management/front-matter) of your content pages. + +.Site.Menus +: all the menus in the site. + +.Site.Pages +: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. See [`.Site.Pages`](#site-pages). + +.Site.RegularPages +: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. See [`.Site.Pages`](#site-pages). + +.Site.Sections +: top-level directories of the site. + +.Site.Taxonomies +: the [taxonomies](/content-management/taxonomies/) for the entire site. Also see section [Access taxonomy data from any template](/variables/taxonomy/#access-taxonomy-data-from-any-template). + +.Site.Title +: a string representing the title of the site. + - ## The `.Site.Params` Variable ++## The `.Site.Params` variable + +`.Site.Params` is a container holding the values from the `params` section of your site configuration. + +### Example: `.Site.Params` + - The following `config.[yaml|toml|json]` defines a site-wide param for `description`: ++The following `config.[yaml|toml|json]` defines a site-wide parameter for `description`: + +{{< code-toggle file="hugo" >}} +baseURL = "https://yoursite.example.com/" + +[params] + description = "Tesla's Awesome Hugo Site" + author = "Nikola Tesla" +{{}} + +You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description: + +{{< code file="layouts/partials/head.html" >}} + +{{< /code >}} + - ## The `.Site.Pages` Variable {#site-pages} ++## The `.Site.Pages` variable {#site-pages} + +### `.Site.Pages` compared to `.Pages` + +{{< getcontent path="readfiles/pages-vs-site-pages.md" >}} + +[config]: /getting-started/configuration/ diff --cc docs/content/en/variables/sitemap.md index b0b080d00,000000000..80fb11076 mode 100644,000000..100644 --- a/docs/content/en/variables/sitemap.md +++ b/docs/content/en/variables/sitemap.md @@@ -1,25 -1,0 +1,24 @@@ +--- - title: Sitemap Variables - linktitle: Sitemap Variables ++title: Sitemap variables +description: - categories: [variables and params] ++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 filename ++: the sitemap file name + +[pagevars]: /variables/page/ diff --cc docs/content/en/variables/taxonomy.md index 63b552328,000000000..3f0b799c8 mode 100644,000000..100644 --- a/docs/content/en/variables/taxonomy.md +++ b/docs/content/en/variables/taxonomy.md @@@ -1,138 -1,0 +1,138 @@@ +--- - title: Taxonomy Variables ++title: Taxonomy variables +description: Hugo's taxonomy system exposes variables to taxonomy and term templates. - categories: [variables and params] ++categories: [variables and parameters] +keywords: [taxonomy,term] +menu: + docs: + parent: variables + weight: 30 +toc: true +weight: 30 +--- + +## Taxonomy templates + +Pages rendered by taxonomy templates have `.Kind` set to `taxonomy` and `.Type` set to the taxonomy name. + +In taxonomy templates you may access `.Site`, `.Page`. `.Section`, and `.File` variables, as well as the following _taxonomy_ 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 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/index-function/ + +```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 +

+ {{ with site.GetPage $taxonomy }} + {{ .LinkTitle }} + {{ end }} +
- + {{ with site.GetPage (path.Join $taxonomy $term) }} + {{ .LinkTitle }} + {{ end }} +
+

+``` + +See [Taxonomy Templates] for more examples. + +[Taxonomy Templates]: /templates/taxonomy-templates/ diff --cc docs/go.mod index 3c5460fd5,000000000..3d585e7b5 mode 100644,000000..100644 --- a/docs/go.mod +++ b/docs/go.mod @@@ -1,5 -1,0 +1,5 @@@ +module github.com/gohugoio/hugoDocs + +go 1.16 + - require github.com/gohugoio/gohugoioTheme v0.0.0-20230527124826-78bc315d7b8a // indirect ++require github.com/gohugoio/gohugoioTheme v0.0.0-20230630055807-9874cd863bc5 // indirect diff --cc docs/go.sum index 9db956ea8,000000000..5d52b96bf mode 100644,000000..100644 --- a/docs/go.sum +++ b/docs/go.sum @@@ -1,67 -1,0 +1,75 @@@ +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= diff --cc docs/layouts/shortcodes/module-mounts-note.html index 654aafef4,000000000..e8b2a7a7e mode 100644,000000..100644 --- a/docs/layouts/shortcodes/module-mounts-note.html +++ b/docs/layouts/shortcodes/module-mounts-note.html @@@ -1,1 -1,0 +1,1 @@@ - Also see [Module Mounts Config](/hugo-modules/configuration/#module-config-mounts) for an alternative way to configure this directory (from Hugo 0.56). ++Also see [Module Mounts Config](/hugo-modules/configuration/#module-configuration-mounts) for an alternative way to configure this directory (from Hugo 0.56). diff --cc docs/netlify.toml index 135cdef64,000000000..3df9a72c9 mode 100644,000000..100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@@ -1,35 -1,0 +1,35 @@@ +[build] +publish = "public" +command = "hugo --gc --minify" + +[context.production.environment] - HUGO_VERSION = "0.113.0" ++HUGO_VERSION = "0.115.4" +HUGO_ENV = "production" +HUGO_ENABLEGITINFO = "true" + +[context.split1] +command = "hugo --gc --minify --enableGitInfo" + +[context.split1.environment] - HUGO_VERSION = "0.113.0" ++HUGO_VERSION = "0.115.4" +HUGO_ENV = "production" + +[context.deploy-preview] +command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL" + +[context.deploy-preview.environment] - HUGO_VERSION = "0.113.0" ++HUGO_VERSION = "0.115.4" + +[context.branch-deploy] +command = "hugo --gc --minify -b $DEPLOY_PRIME_URL" + +[context.branch-deploy.environment] - HUGO_VERSION = "0.113.0" ++HUGO_VERSION = "0.115.4" + +[context.next.environment] +HUGO_ENABLEGITINFO = "true" + +[[redirects]] +from = "/npmjs/*" +to = "/npmjs/" +status = 200

Hugo Sponsors

Reference

Reference A

Reference B

Reference

Reference

Reference

{{ i18n "translations" }}

Authors

{{ .Title }}

See Also

See Also

{{ .Get "title" }}

Steve Francia

{{ .Title }}

{{ .Title }}

{{ .Title }}

Buy this book

Buy this book