mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-24 15:28:54 +00:00
Bjørn Erik Pedersen
@@ -1,49 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
title: About Hugo
|
||||
linkTitle: Overview
|
||||
description: Hugo's features, roadmap, license, and motivation.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: about-hugo-overview
|
||||
parent: about
|
||||
weight: 10
|
||||
weight: 10
|
||||
aliases: [/about-hugo/,/docs/]
|
||||
---
|
||||
|
||||
Hugo is not your average static site generator.
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
title: Benefits of static site generators
|
||||
linkTitle: Static site generators
|
||||
description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing.
|
||||
categories: [about]
|
||||
keywords: [ssg,static,performance,security]
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
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
|
||||
|
||||
* ["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
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
title: Hugo features
|
||||
description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites.
|
||||
categories: [about]
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
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
|
||||
|
||||
* 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/
|
||||
@@ -1,134 +0,0 @@
|
||||
---
|
||||
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.
|
||||
categories: [about]
|
||||
keywords: ["GDPR", "Privacy", "Data Protection"]
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 60
|
||||
weight: 60
|
||||
toc: true
|
||||
aliases: [/privacy/,/gdpr/]
|
||||
---
|
||||
|
||||
General Data Protection Regulation ([GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation)) is a regulation in EU law on data protection and privacy for all individuals within the European Union and the European Economic Area. It became enforceable on 25 May 2018.
|
||||
|
||||
**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 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
|
||||
|
||||
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
|
||||
|
||||
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 >}}
|
||||
[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
|
||||
|
||||
### 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 overlaid with a play button. If the user clicks to play the video, it will open in a new tab directly on Vimeo's website.
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
title: License
|
||||
description: Hugo is released under the Apache 2.0 license.
|
||||
categories: [about]
|
||||
keywords: [license,apache]
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 70
|
||||
weight: 70
|
||||
---
|
||||
|
||||
## Apache License
|
||||
|
||||
|
||||
_Version 2.0, January 2004_
|
||||
_<http://www.apache.org/licenses/>_
|
||||
|
||||
### Terms and Conditions for use, reproduction, and distribution
|
||||
|
||||
#### 1. Definitions
|
||||
|
||||
“License” shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
“Licensor” shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
|
||||
|
||||
“Legal Entity” shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, “control” means **(i)** the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the outstanding shares, or **(iii)** beneficial ownership of such entity.
|
||||
|
||||
“You” (or “Your”) shall mean an individual or Legal Entity exercising permissions granted by this License.
|
||||
|
||||
“Source” form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
|
||||
|
||||
“Object” form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
|
||||
|
||||
“Work” shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
|
||||
|
||||
“Derivative Works” shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
|
||||
|
||||
“Contribution” shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, “submitted” means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as “Not a Contribution.”
|
||||
|
||||
“Contributor” shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
|
||||
|
||||
#### 2. Grant of Copyright License
|
||||
|
||||
Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
|
||||
|
||||
#### 3. Grant of Patent License
|
||||
|
||||
Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
|
||||
|
||||
#### 4. Redistribution
|
||||
|
||||
You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
|
||||
|
||||
* **(a)** You must give any other recipients of the Work or Derivative Works a copy of this License; and
|
||||
* **(b)** You must cause any modified files to carry prominent notices stating that You changed the files; and
|
||||
* **(c)** You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
|
||||
* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
|
||||
|
||||
#### 5. Submission of Contributions
|
||||
|
||||
Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
|
||||
|
||||
#### 6. Trademarks
|
||||
|
||||
This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
#### 7. Disclaimer of Warranty
|
||||
|
||||
Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
|
||||
|
||||
#### 8. Limitation of Liability
|
||||
|
||||
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
|
||||
|
||||
#### 9. Accepting Warranty or Additional Liability
|
||||
|
||||
While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
title: Hugo's security model
|
||||
description: A summary of Hugo's security model.
|
||||
categories: [about]
|
||||
keywords: [security,privacy]
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 50
|
||||
weight: 50
|
||||
toc: true
|
||||
aliases: [/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
|
||||
|
||||
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 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
|
||||
|
||||
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
|
||||
|
||||
These are the security threats as defined by [OWASP](https://en.wikipedia.org/wiki/OWASP).
|
||||
|
||||
For HTML output, this is the core security model:
|
||||
|
||||
<https://pkg.go.dev/html/template#hdr-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.
|
||||
@@ -1,57 +0,0 @@
|
||||
---
|
||||
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.
|
||||
categories: [about]
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 20
|
||||
weight: 20
|
||||
toc: true
|
||||
aliases: [/overview/introduction/,/about/why-i-built-hugo/]
|
||||
---
|
||||
|
||||
Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors.
|
||||
|
||||
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?
|
||||
|
||||
{{< youtube "CdiDYZ51a2o" >}}
|
||||
|
||||
## 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?
|
||||
|
||||
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/
|
||||
[DreamHost]: https://www.dreamhost.com/
|
||||
[Firebase]: https://firebase.google.com/docs/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/
|
||||
[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/
|
||||
@@ -1,84 +0,0 @@
|
||||
---
|
||||
title: "hugo"
|
||||
slug: hugo
|
||||
url: /commands/hugo/
|
||||
---
|
||||
## hugo
|
||||
|
||||
hugo builds your site
|
||||
|
||||
### Synopsis
|
||||
|
||||
hugo is the main command, used to build your Hugo site.
|
||||
|
||||
Hugo is a Fast and Flexible Static Site Generator
|
||||
built with love by spf13 and friends in Go.
|
||||
|
||||
Complete documentation is available at https://gohugo.io/.
|
||||
|
||||
```
|
||||
hugo [flags]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
|
||||
-D, --buildDrafts include content marked as draft
|
||||
-E, --buildExpired include expired content
|
||||
-F, --buildFuture include content with publishdate in the future
|
||||
--cacheDir string filesystem path to cache directory
|
||||
--cleanDestinationDir remove files from destination not found in static directories
|
||||
--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")
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
--debug debug output
|
||||
-d, --destination string filesystem path to write files to
|
||||
--disableKinds strings disable different kind of pages (home, RSS etc.)
|
||||
--enableGitInfo add Git revision, date, author, and CODEOWNERS info to the pages
|
||||
-e, --environment string build environment
|
||||
--forceSyncStatic copy all files when static is changed.
|
||||
--gc enable to run some cleanup tasks (remove unused cache files) after the build
|
||||
-h, --help help for hugo
|
||||
--ignoreCache ignores the cache directory
|
||||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
-l, --layoutDir string filesystem path to layout directory
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--minify minify any supported output format (HTML, XML etc.)
|
||||
--noBuildLock don't create .hugo_build.lock file
|
||||
--noChmod don't sync permission mode of files
|
||||
--noTimes don't sync modification time of files
|
||||
--panicOnWarning panic on first WARNING log
|
||||
--poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes
|
||||
--printI18nWarnings print missing translations
|
||||
--printMemoryUsage print memory usage to screen at intervals
|
||||
--printPathWarnings print warnings on duplicate target paths etc.
|
||||
--printUnusedTemplates print warnings on unused templates.
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (only useful for benchmark testing)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--templateMetrics display metrics about template executions
|
||||
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
|
||||
-t, --theme strings themes to use (located in /themes/THEMENAME/)
|
||||
--themesDir string filesystem path to themes directory
|
||||
--trace file write trace to file (not useful in general)
|
||||
-v, --verbose verbose output
|
||||
-w, --watch watch filesystem for changes and recreate as needed
|
||||
```
|
||||
|
||||
### SEE ALSO
|
||||
|
||||
* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
|
||||
* [hugo config](/commands/hugo_config/) - Print the site configuration
|
||||
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
|
||||
* [hugo deploy](/commands/hugo_deploy/) - Deploy your site to a Cloud provider.
|
||||
* [hugo env](/commands/hugo_env/) - Print Hugo version and environment info
|
||||
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
|
||||
* [hugo import](/commands/hugo_import/) - Import your site from others.
|
||||
* [hugo list](/commands/hugo_list/) - Listing out various types of content
|
||||
* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
|
||||
* [hugo new](/commands/hugo_new/) - Create new content for your site
|
||||
* [hugo server](/commands/hugo_server/) - A high performance webserver
|
||||
* [hugo version](/commands/hugo_version/) - Print Hugo version and environment info
|
||||
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
title: "hugo completion"
|
||||
slug: hugo_completion
|
||||
url: /commands/hugo_completion/
|
||||
---
|
||||
## hugo completion
|
||||
|
||||
Generate the autocompletion script for the specified shell
|
||||
|
||||
### Synopsis
|
||||
|
||||
Generate the autocompletion script for hugo for the specified shell.
|
||||
See each sub-command's help for details on how to use the generated script.
|
||||
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for completion
|
||||
```
|
||||
|
||||
### 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 completion bash](/commands/hugo_completion_bash/) - Generate the autocompletion script for bash
|
||||
* [hugo completion fish](/commands/hugo_completion_fish/) - Generate the autocompletion script for fish
|
||||
* [hugo completion powershell](/commands/hugo_completion_powershell/) - Generate the autocompletion script for powershell
|
||||
* [hugo completion zsh](/commands/hugo_completion_zsh/) - Generate the autocompletion script for zsh
|
||||
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
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
|
||||
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
title: "hugo completion fish"
|
||||
slug: hugo_completion_fish
|
||||
url: /commands/hugo_completion_fish/
|
||||
---
|
||||
## hugo completion fish
|
||||
|
||||
Generate the autocompletion script for fish
|
||||
|
||||
### Synopsis
|
||||
|
||||
Generate the autocompletion script for the fish shell.
|
||||
|
||||
To load completions in your current shell session:
|
||||
|
||||
hugo completion fish | source
|
||||
|
||||
To load completions for every new session, execute once:
|
||||
|
||||
hugo completion fish > ~/.config/fish/completions/hugo.fish
|
||||
|
||||
You will need to start a new shell for this setup to take effect.
|
||||
|
||||
|
||||
```
|
||||
hugo completion fish [flags]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for fish
|
||||
--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
|
||||
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
title: "hugo completion powershell"
|
||||
slug: hugo_completion_powershell
|
||||
url: /commands/hugo_completion_powershell/
|
||||
---
|
||||
## hugo completion powershell
|
||||
|
||||
Generate the autocompletion script for powershell
|
||||
|
||||
### Synopsis
|
||||
|
||||
Generate the autocompletion script for powershell.
|
||||
|
||||
To load completions in your current shell session:
|
||||
|
||||
hugo completion powershell | Out-String | Invoke-Expression
|
||||
|
||||
To load completions for every new session, add the output of the above command
|
||||
to your powershell profile.
|
||||
|
||||
|
||||
```
|
||||
hugo completion powershell [flags]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for powershell
|
||||
--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
|
||||
|
||||
@@ -1,67 +0,0 @@
|
||||
---
|
||||
title: "hugo completion zsh"
|
||||
slug: hugo_completion_zsh
|
||||
url: /commands/hugo_completion_zsh/
|
||||
---
|
||||
## hugo completion zsh
|
||||
|
||||
Generate the autocompletion script for zsh
|
||||
|
||||
### Synopsis
|
||||
|
||||
Generate the autocompletion script for the zsh shell.
|
||||
|
||||
If shell completion is not already enabled in your environment you will need
|
||||
to enable it. You can execute the following once:
|
||||
|
||||
echo "autoload -U compinit; compinit" >> ~/.zshrc
|
||||
|
||||
To load completions in your current shell session:
|
||||
|
||||
source <(hugo completion zsh)
|
||||
|
||||
To load completions for every new session, execute once:
|
||||
|
||||
#### Linux:
|
||||
|
||||
hugo completion zsh > "${fpath[1]}/_hugo"
|
||||
|
||||
#### macOS:
|
||||
|
||||
hugo completion zsh > $(brew --prefix)/share/zsh/site-functions/_hugo
|
||||
|
||||
You will need to start a new shell for this setup to take effect.
|
||||
|
||||
|
||||
```
|
||||
hugo completion zsh [flags]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for zsh
|
||||
--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
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
title: "hugo config"
|
||||
slug: hugo_config
|
||||
url: /commands/hugo_config/
|
||||
---
|
||||
## hugo config
|
||||
|
||||
Print the site configuration
|
||||
|
||||
### Synopsis
|
||||
|
||||
Print the site configuration, both default and custom settings.
|
||||
|
||||
```
|
||||
hugo config [command] [flags]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
|
||||
--cacheDir string filesystem path to cache directory
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
--format string preferred file format (toml, yaml or json) (default "toml")
|
||||
-h, --help help for config
|
||||
--lang string the language to display config for. Defaults to the first language defined.
|
||||
-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](/commands/hugo/) - hugo builds your site
|
||||
* [hugo config mounts](/commands/hugo_config_mounts/) - Print the configured file mounts
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: "hugo config mounts"
|
||||
slug: hugo_config_mounts
|
||||
url: /commands/hugo_config_mounts/
|
||||
---
|
||||
## hugo config mounts
|
||||
|
||||
Print the configured file mounts
|
||||
|
||||
```
|
||||
hugo config mounts [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
|
||||
--cacheDir string filesystem path to cache directory
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
-h, --help help for mounts
|
||||
-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 config](/commands/hugo_config/) - Print the site configuration
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
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.
|
||||
|
||||
### 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
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: "hugo convert toJSON"
|
||||
slug: hugo_convert_toJSON
|
||||
url: /commands/hugo_convert_tojson/
|
||||
---
|
||||
## hugo convert toJSON
|
||||
|
||||
Convert front matter to JSON
|
||||
|
||||
### Synopsis
|
||||
|
||||
toJSON converts all front matter in the content directory
|
||||
to use JSON for the front matter.
|
||||
|
||||
```
|
||||
hugo convert toJSON [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for toJSON
|
||||
```
|
||||
|
||||
### 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)
|
||||
-o, --output string filesystem path to write files to
|
||||
--quiet build in quiet mode
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
--unsafe enable less safe operations, please backup first
|
||||
-v, --verbose verbose output
|
||||
```
|
||||
|
||||
### SEE ALSO
|
||||
|
||||
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: "hugo convert toTOML"
|
||||
slug: hugo_convert_toTOML
|
||||
url: /commands/hugo_convert_totoml/
|
||||
---
|
||||
## hugo convert toTOML
|
||||
|
||||
Convert front matter to TOML
|
||||
|
||||
### Synopsis
|
||||
|
||||
toTOML converts all front matter in the content directory
|
||||
to use TOML for the front matter.
|
||||
|
||||
```
|
||||
hugo convert toTOML [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for toTOML
|
||||
```
|
||||
|
||||
### 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)
|
||||
-o, --output string filesystem path to write files to
|
||||
--quiet build in quiet mode
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
--unsafe enable less safe operations, please backup first
|
||||
-v, --verbose verbose output
|
||||
```
|
||||
|
||||
### SEE ALSO
|
||||
|
||||
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: "hugo convert toYAML"
|
||||
slug: hugo_convert_toYAML
|
||||
url: /commands/hugo_convert_toyaml/
|
||||
---
|
||||
## hugo convert toYAML
|
||||
|
||||
Convert front matter to YAML
|
||||
|
||||
### Synopsis
|
||||
|
||||
toYAML converts all front matter in the content directory
|
||||
to use YAML for the front matter.
|
||||
|
||||
```
|
||||
hugo convert toYAML [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for toYAML
|
||||
```
|
||||
|
||||
### 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)
|
||||
-o, --output string filesystem path to write files to
|
||||
--quiet build in quiet mode
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
--unsafe enable less safe operations, please backup first
|
||||
-v, --verbose verbose output
|
||||
```
|
||||
|
||||
### SEE ALSO
|
||||
|
||||
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
|
||||
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
title: "hugo deploy"
|
||||
slug: hugo_deploy
|
||||
url: /commands/hugo_deploy/
|
||||
---
|
||||
## hugo deploy
|
||||
|
||||
Deploy your site to a Cloud provider.
|
||||
|
||||
### Synopsis
|
||||
|
||||
Deploy your site to a Cloud provider.
|
||||
|
||||
See https://gohugo.io/hosting-and-deployment/hugo-deploy/ for detailed
|
||||
documentation.
|
||||
|
||||
|
||||
```
|
||||
hugo deploy [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
--confirm ask for confirmation before making changes to the target
|
||||
--dryRun dry run
|
||||
--force force upload of all files
|
||||
-h, --help help for deploy
|
||||
--invalidateCDN invalidate the CDN cache listed in the deployment target (default true)
|
||||
--maxDeletes int maximum # of files to delete, or -1 to disable (default 256)
|
||||
--target string target deployment from deployments section in config file; defaults to the first one
|
||||
--workers int number of workers to transfer files. defaults to 10 (default 10)
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: "hugo env"
|
||||
slug: hugo_env
|
||||
url: /commands/hugo_env/
|
||||
---
|
||||
## hugo env
|
||||
|
||||
Print Hugo version and environment info
|
||||
|
||||
### Synopsis
|
||||
|
||||
Print Hugo version and environment info. This is useful in Hugo bug reports
|
||||
|
||||
```
|
||||
hugo env [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for env
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: "hugo gen"
|
||||
slug: hugo_gen
|
||||
url: /commands/hugo_gen/
|
||||
---
|
||||
## hugo gen
|
||||
|
||||
A collection of several useful generators.
|
||||
|
||||
### 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
|
||||
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: "hugo gen chromastyles"
|
||||
slug: hugo_gen_chromastyles
|
||||
url: /commands/hugo_gen_chromastyles/
|
||||
---
|
||||
## hugo gen chromastyles
|
||||
|
||||
Generate CSS stylesheet for the Chroma code highlighter
|
||||
|
||||
### Synopsis
|
||||
|
||||
Generate CSS stylesheet for the Chroma code highlighter for a given style. This stylesheet is needed if markup.highlight.noClasses is disabled in config.
|
||||
|
||||
See https://xyproto.github.io/splash/docs/all.html for a preview of the available styles
|
||||
|
||||
```
|
||||
hugo gen chromastyles [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for chromastyles
|
||||
--highlightStyle string style used for highlighting lines (see https://github.com/alecthomas/chroma)
|
||||
--linesStyle string style used for line numbers (see https://github.com/alecthomas/chroma)
|
||||
--style string highlighter style (see https://xyproto.github.io/splash/docs/) (default "friendly")
|
||||
```
|
||||
|
||||
### 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 gen](/commands/hugo_gen/) - A collection of several useful generators.
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
title: "hugo gen doc"
|
||||
slug: hugo_gen_doc
|
||||
url: /commands/hugo_gen_doc/
|
||||
---
|
||||
## hugo gen doc
|
||||
|
||||
Generate Markdown documentation for the Hugo CLI.
|
||||
|
||||
### Synopsis
|
||||
|
||||
Generate Markdown documentation for the Hugo CLI.
|
||||
This command is, mostly, used to create up-to-date documentation
|
||||
of Hugo's command-line interface for https://gohugo.io/.
|
||||
|
||||
It creates one Markdown file per command with front matter suitable
|
||||
for rendering in Hugo.
|
||||
|
||||
```
|
||||
hugo gen doc [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
--dir string the directory to write the doc. (default "/tmp/hugodoc/")
|
||||
-h, --help help for doc
|
||||
```
|
||||
|
||||
### 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 gen](/commands/hugo_gen/) - A collection of several useful generators.
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: "hugo gen man"
|
||||
slug: hugo_gen_man
|
||||
url: /commands/hugo_gen_man/
|
||||
---
|
||||
## hugo gen man
|
||||
|
||||
Generate man pages for the Hugo CLI
|
||||
|
||||
### Synopsis
|
||||
|
||||
This command automatically generates up-to-date man pages of Hugo's
|
||||
command-line interface. By default, it creates the man page files
|
||||
in the "man" directory under the current directory.
|
||||
|
||||
```
|
||||
hugo gen man [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
--dir string the directory to write the man pages. (default "man/")
|
||||
-h, --help help for man
|
||||
```
|
||||
|
||||
### 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 gen](/commands/hugo_gen/) - A collection of several useful generators.
|
||||
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
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`.
|
||||
|
||||
### 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
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: "hugo import jekyll"
|
||||
slug: hugo_import_jekyll
|
||||
url: /commands/hugo_import_jekyll/
|
||||
---
|
||||
## hugo import jekyll
|
||||
|
||||
hugo import from Jekyll
|
||||
|
||||
### Synopsis
|
||||
|
||||
hugo import from Jekyll.
|
||||
|
||||
Import from Jekyll requires two paths, e.g. `hugo import jekyll jekyll_root_path target_path`.
|
||||
|
||||
```
|
||||
hugo import jekyll [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
--force allow import into non-empty target directory
|
||||
-h, --help help for jekyll
|
||||
```
|
||||
|
||||
### 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 import](/commands/hugo_import/) - Import your site from others.
|
||||
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
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
|
||||
|
||||
### 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
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: "hugo list all"
|
||||
slug: hugo_list_all
|
||||
url: /commands/hugo_list_all/
|
||||
---
|
||||
## hugo list all
|
||||
|
||||
List all posts
|
||||
|
||||
### Synopsis
|
||||
|
||||
List all of the posts in your content directory, include drafts, future and expired pages.
|
||||
|
||||
```
|
||||
hugo list all [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for all
|
||||
```
|
||||
|
||||
### 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 list](/commands/hugo_list/) - Listing out various types of content
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: "hugo list drafts"
|
||||
slug: hugo_list_drafts
|
||||
url: /commands/hugo_list_drafts/
|
||||
---
|
||||
## hugo list drafts
|
||||
|
||||
List all drafts
|
||||
|
||||
### Synopsis
|
||||
|
||||
List all of the drafts in your content directory.
|
||||
|
||||
```
|
||||
hugo list drafts [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for drafts
|
||||
```
|
||||
|
||||
### 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 list](/commands/hugo_list/) - Listing out various types of content
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: "hugo list expired"
|
||||
slug: hugo_list_expired
|
||||
url: /commands/hugo_list_expired/
|
||||
---
|
||||
## hugo list expired
|
||||
|
||||
List all posts already expired
|
||||
|
||||
### Synopsis
|
||||
|
||||
List all of the posts in your content directory which has already expired.
|
||||
|
||||
```
|
||||
hugo list expired [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for expired
|
||||
```
|
||||
|
||||
### 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 list](/commands/hugo_list/) - Listing out various types of content
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: "hugo list future"
|
||||
slug: hugo_list_future
|
||||
url: /commands/hugo_list_future/
|
||||
---
|
||||
## hugo list future
|
||||
|
||||
List all posts dated in the future
|
||||
|
||||
### Synopsis
|
||||
|
||||
List all of the posts in your content directory which will be posted in the future.
|
||||
|
||||
```
|
||||
hugo list future [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for future
|
||||
```
|
||||
|
||||
### 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 list](/commands/hugo_list/) - Listing out various types of content
|
||||
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
title: "hugo mod"
|
||||
slug: hugo_mod
|
||||
url: /commands/hugo_mod/
|
||||
---
|
||||
## hugo mod
|
||||
|
||||
Various Hugo Modules helpers.
|
||||
|
||||
### Synopsis
|
||||
|
||||
Various helpers to help manage the modules in your project's dependency graph.
|
||||
Most operations here requires a Go version installed on your system (>= Go 1.12) and the relevant VCS client (typically Git).
|
||||
This is not needed if you only operate on modules inside /themes or if you have vendored them via "hugo mod vendor".
|
||||
|
||||
|
||||
Note that Hugo will always start out by resolving the components defined in the site
|
||||
configuration, provided by a _vendor directory (if no --ignoreVendorPaths flag provided),
|
||||
Go Modules, or a folder inside the themes directory, in that order.
|
||||
|
||||
See https://gohugo.io/hugo-modules/ for more information.
|
||||
|
||||
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for mod
|
||||
```
|
||||
|
||||
### 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 mod clean](/commands/hugo_mod_clean/) - Delete the Hugo Module cache for the current project.
|
||||
* [hugo mod get](/commands/hugo_mod_get/) - Resolves dependencies in your current Hugo Project.
|
||||
* [hugo mod graph](/commands/hugo_mod_graph/) - Print a module dependency graph.
|
||||
* [hugo mod init](/commands/hugo_mod_init/) - Initialize this project as a Hugo Module.
|
||||
* [hugo mod npm](/commands/hugo_mod_npm/) - Various npm helpers.
|
||||
* [hugo mod tidy](/commands/hugo_mod_tidy/) - Remove unused entries in go.mod and go.sum.
|
||||
* [hugo mod vendor](/commands/hugo_mod_vendor/) - Vendor all module dependencies into the _vendor directory.
|
||||
* [hugo mod verify](/commands/hugo_mod_verify/) - Verify dependencies.
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
title: "hugo mod clean"
|
||||
slug: hugo_mod_clean
|
||||
url: /commands/hugo_mod_clean/
|
||||
---
|
||||
## hugo mod clean
|
||||
|
||||
Delete the Hugo Module cache for the current project.
|
||||
|
||||
### Synopsis
|
||||
|
||||
Delete the Hugo Module cache for the current project.
|
||||
|
||||
```
|
||||
hugo mod clean [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
--all clean entire module cache
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
|
||||
--cacheDir string filesystem path to cache directory
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
-h, --help help for clean
|
||||
--pattern string pattern matching module paths to clean (all if not set), e.g. "**hugo*"
|
||||
-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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
|
||||
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
title: "hugo mod get"
|
||||
slug: hugo_mod_get
|
||||
url: /commands/hugo_mod_get/
|
||||
---
|
||||
## hugo mod get
|
||||
|
||||
Resolves dependencies in your current Hugo Project.
|
||||
|
||||
### Synopsis
|
||||
|
||||
|
||||
Resolves dependencies in your current Hugo Project.
|
||||
|
||||
Some examples:
|
||||
|
||||
Install the latest version possible for a given module:
|
||||
|
||||
hugo mod get github.com/gohugoio/testshortcodes
|
||||
|
||||
Install a specific version:
|
||||
|
||||
hugo mod get github.com/gohugoio/testshortcodes@v0.3.0
|
||||
|
||||
Install the latest versions of all direct module dependencies:
|
||||
|
||||
hugo mod get
|
||||
hugo mod get ./... (recursive)
|
||||
|
||||
Install the latest versions of all module dependencies (direct and indirect):
|
||||
|
||||
hugo mod get -u
|
||||
hugo mod get -u ./... (recursive)
|
||||
|
||||
Run "go help get" for more information. All flags available for "go get" is also relevant here.
|
||||
|
||||
Note that Hugo will always start out by resolving the components defined in the site
|
||||
configuration, provided by a _vendor directory (if no --ignoreVendorPaths flag provided),
|
||||
Go Modules, or a folder inside the themes directory, in that order.
|
||||
|
||||
See https://gohugo.io/hugo-modules/ for more information.
|
||||
|
||||
|
||||
|
||||
```
|
||||
hugo mod get [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for get
|
||||
```
|
||||
|
||||
### 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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
title: "hugo mod graph"
|
||||
slug: hugo_mod_graph
|
||||
url: /commands/hugo_mod_graph/
|
||||
---
|
||||
## hugo mod graph
|
||||
|
||||
Print a module dependency graph.
|
||||
|
||||
### Synopsis
|
||||
|
||||
Print a module dependency graph with information about module status (disabled, vendored).
|
||||
Note that for vendored modules, that is the version listed and not the one from go.mod.
|
||||
|
||||
|
||||
```
|
||||
hugo mod graph [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
|
||||
--cacheDir string filesystem path to cache directory
|
||||
--clean delete module cache for dependencies that fail verification
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
-h, --help help for graph
|
||||
-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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
|
||||
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
title: "hugo mod init"
|
||||
slug: hugo_mod_init
|
||||
url: /commands/hugo_mod_init/
|
||||
---
|
||||
## hugo mod init
|
||||
|
||||
Initialize this project as a Hugo Module.
|
||||
|
||||
### Synopsis
|
||||
|
||||
Initialize this project as a Hugo Module.
|
||||
It will try to guess the module path, but you may help by passing it as an argument, e.g:
|
||||
|
||||
hugo mod init github.com/gohugoio/testshortcodes
|
||||
|
||||
Note that Hugo Modules supports multi-module projects, so you can initialize a Hugo Module
|
||||
inside a subfolder on GitHub, as one example.
|
||||
|
||||
|
||||
```
|
||||
hugo mod init [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
|
||||
--cacheDir string filesystem path to cache directory
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
-h, --help help for init
|
||||
-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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
---
|
||||
title: "hugo mod npm"
|
||||
slug: hugo_mod_npm
|
||||
url: /commands/hugo_mod_npm/
|
||||
---
|
||||
## hugo mod npm
|
||||
|
||||
Various npm helpers.
|
||||
|
||||
### Synopsis
|
||||
|
||||
Various npm (Node package manager) helpers.
|
||||
|
||||
```
|
||||
hugo mod npm [command] [flags]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for npm
|
||||
```
|
||||
|
||||
### 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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
|
||||
* [hugo mod npm pack](/commands/hugo_mod_npm_pack/) - Experimental: Prepares and writes a composite package.json file for your project.
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
title: "hugo mod npm pack"
|
||||
slug: hugo_mod_npm_pack
|
||||
url: /commands/hugo_mod_npm_pack/
|
||||
---
|
||||
## hugo mod npm pack
|
||||
|
||||
Experimental: Prepares and writes a composite package.json file for your project.
|
||||
|
||||
### Synopsis
|
||||
|
||||
Prepares and writes a composite package.json file for your project.
|
||||
|
||||
On first run it creates a "package.hugo.json" in the project root if not already there. This file will be used as a template file
|
||||
with the base dependency set.
|
||||
|
||||
This set will be merged with all "package.hugo.json" files found in the dependency tree, picking the version closest to the project.
|
||||
|
||||
This command is marked as 'Experimental'. We think it's a great idea, so it's not likely to be
|
||||
removed from Hugo, but we need to test this out in "real life" to get a feel of it,
|
||||
so this may/will change in future versions of Hugo.
|
||||
|
||||
|
||||
```
|
||||
hugo mod npm pack [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
|
||||
--cacheDir string filesystem path to cache directory
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
-h, --help help for pack
|
||||
-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 mod npm](/commands/hugo_mod_npm/) - Various npm helpers.
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: "hugo mod tidy"
|
||||
slug: hugo_mod_tidy
|
||||
url: /commands/hugo_mod_tidy/
|
||||
---
|
||||
## hugo mod tidy
|
||||
|
||||
Remove unused entries in go.mod and go.sum.
|
||||
|
||||
```
|
||||
hugo mod tidy [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
|
||||
--cacheDir string filesystem path to cache directory
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
-h, --help help for tidy
|
||||
-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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
title: "hugo mod vendor"
|
||||
slug: hugo_mod_vendor
|
||||
url: /commands/hugo_mod_vendor/
|
||||
---
|
||||
## hugo mod vendor
|
||||
|
||||
Vendor all module dependencies into the _vendor directory.
|
||||
|
||||
### Synopsis
|
||||
|
||||
Vendor all module dependencies into the _vendor directory.
|
||||
If a module is vendored, that is where Hugo will look for it's dependencies.
|
||||
|
||||
|
||||
```
|
||||
hugo mod vendor [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
|
||||
--cacheDir string filesystem path to cache directory
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
-h, --help help for vendor
|
||||
-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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
|
||||
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: "hugo mod verify"
|
||||
slug: hugo_mod_verify
|
||||
url: /commands/hugo_mod_verify/
|
||||
---
|
||||
## hugo mod verify
|
||||
|
||||
Verify dependencies.
|
||||
|
||||
### Synopsis
|
||||
|
||||
Verify checks that the dependencies of the current module, which are stored in a local downloaded source cache, have not been modified since being downloaded.
|
||||
|
||||
```
|
||||
hugo mod verify [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
|
||||
--cacheDir string filesystem path to cache directory
|
||||
--clean delete module cache for dependencies that fail verification
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
-h, --help help for verify
|
||||
-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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
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.
|
||||
|
||||
### 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 theme (skeleton)
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
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.
|
||||
|
||||
```
|
||||
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
|
||||
-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
|
||||
-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
|
||||
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
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
|
||||
--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
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: "hugo new theme"
|
||||
slug: hugo_new_theme
|
||||
url: /commands/hugo_new_theme/
|
||||
---
|
||||
## hugo new theme
|
||||
|
||||
Create a new theme (skeleton)
|
||||
|
||||
### Synopsis
|
||||
|
||||
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 [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
|
||||
|
||||
@@ -1,98 +0,0 @@
|
||||
---
|
||||
title: "hugo server"
|
||||
slug: hugo_server
|
||||
url: /commands/hugo_server/
|
||||
---
|
||||
## hugo server
|
||||
|
||||
A high performance webserver
|
||||
|
||||
### Synopsis
|
||||
|
||||
Hugo provides its own webserver which builds and serves the site.
|
||||
While hugo server is high performance, it is a webserver with limited options.
|
||||
|
||||
'hugo server' will avoid writing the rendered and served content to disk,
|
||||
preferring to store it in memory.
|
||||
|
||||
By default hugo will also watch your files for any changes you make and
|
||||
automatically rebuild the site. It will then live reload any open browser pages
|
||||
and push the latest content to them. As most Hugo sites are built in a fraction
|
||||
of a second, you will be able to save and see your changes nearly instantly.
|
||||
|
||||
```
|
||||
hugo server [command] [flags]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
--appendPort append port to baseURL (default true)
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
|
||||
--bind string interface to which the server will bind (default "127.0.0.1")
|
||||
-D, --buildDrafts include content marked as draft
|
||||
-E, --buildExpired include expired content
|
||||
-F, --buildFuture include content with publishdate in the future
|
||||
--cacheDir string filesystem path to cache directory
|
||||
--cleanDestinationDir remove files from destination not found in static directories
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
--disableBrowserError do not show build errors in the browser
|
||||
--disableFastRender enables full re-renders on changes
|
||||
--disableKinds strings disable different kind of pages (home, RSS etc.)
|
||||
--disableLiveReload watch without enabling live browser reload on rebuild
|
||||
--enableGitInfo add Git revision, date, author, and CODEOWNERS info to the pages
|
||||
--forceSyncStatic copy all files when static is changed.
|
||||
--gc enable to run some cleanup tasks (remove unused cache files) after the build
|
||||
-h, --help help for server
|
||||
--ignoreCache ignores the cache directory
|
||||
-l, --layoutDir string filesystem path to layout directory
|
||||
--liveReloadPort int port for live reloading (i.e. 443 in HTTPS proxy situations) (default -1)
|
||||
--meminterval string interval to poll memory usage (requires --memstats), valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". (default "100ms")
|
||||
--memstats string log memory usage to this file
|
||||
--minify minify any supported output format (HTML, XML etc.)
|
||||
--navigateToChanged navigate to changed content file on live browser reload
|
||||
--noBuildLock don't create .hugo_build.lock file
|
||||
--noChmod don't sync permission mode of files
|
||||
--noHTTPCache prevent HTTP caching
|
||||
--noTimes don't sync modification time of files
|
||||
--panicOnWarning panic on first WARNING log
|
||||
--poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes
|
||||
-p, --port int port on which the server will listen (default 1313)
|
||||
--printI18nWarnings print missing translations
|
||||
--printMemoryUsage print memory usage to screen at intervals
|
||||
--printPathWarnings print warnings on duplicate target paths etc.
|
||||
--printUnusedTemplates print warnings on unused templates.
|
||||
--renderStaticToDisk serve static files from disk and dynamic files from memory
|
||||
--renderToDisk serve all files from disk (default is from memory)
|
||||
--templateMetrics display metrics about template executions
|
||||
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
|
||||
-t, --theme strings themes to use (located in /themes/THEMENAME/)
|
||||
--tlsAuto generate and use locally-trusted certificates.
|
||||
--tlsCertFile string path to TLS certificate file
|
||||
--tlsKeyFile string path to TLS key file
|
||||
--trace file write trace to file (not useful in general)
|
||||
-w, --watch watch filesystem for changes and recreate as needed (default true)
|
||||
```
|
||||
|
||||
### 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 server trust](/commands/hugo_server_trust/) - Install the local CA in the system trust store.
|
||||
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
title: "hugo server trust"
|
||||
slug: hugo_server_trust
|
||||
url: /commands/hugo_server_trust/
|
||||
---
|
||||
## hugo server trust
|
||||
|
||||
Install the local CA in the system trust store.
|
||||
|
||||
```
|
||||
hugo server trust [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for trust
|
||||
--uninstall Uninstall the local CA (but do not delete it).
|
||||
```
|
||||
|
||||
### 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 server](/commands/hugo_server/) - A high performance webserver
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: "hugo version"
|
||||
slug: hugo_version
|
||||
url: /commands/hugo_version/
|
||||
---
|
||||
## hugo version
|
||||
|
||||
Print Hugo version and environment info
|
||||
|
||||
### Synopsis
|
||||
|
||||
Print Hugo version and environment info. This is useful in Hugo bug reports.
|
||||
|
||||
```
|
||||
hugo version [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for version
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
@@ -1,13 +0,0 @@
|
||||
---
|
||||
cascade:
|
||||
_build:
|
||||
list: never
|
||||
publishResources: false
|
||||
render: never
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
| Kind | Description | Example |
|
||||
|----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------|
|
||||
| `home` | The landing page for the home page | `/index.html` |
|
||||
| `page` | The landing page for a given page | `my-post` page (`/posts/my-post/index.html`) |
|
||||
| `section` | The landing page of a given section | `posts` section (`/posts/index.html`) |
|
||||
| `taxonomy` | The landing page for a taxonomy | `tags` taxonomy (`/tags/index.html`) |
|
||||
| `term` | The landing page for one taxonomy's term | term `awesome` in `tags` taxonomy (`/tags/awesome/index.html`) |
|
||||
|
||||
Four other page kinds unrelated to content are `robotsTXT`, `RSS`, `sitemap`, and `404`. Although primarily for internal use, you can specify the name when disabling one or more page kinds on your site. For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
disableKinds = ['robotsTXT','404']
|
||||
{{< /code-toggle >}}
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
title: Content management
|
||||
linkTitle: Overview
|
||||
description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: content-management-overview
|
||||
parent: content-management
|
||||
weight: 10
|
||||
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.
|
||||
@@ -1,184 +0,0 @@
|
||||
---
|
||||
title: Archetypes
|
||||
description: An archetype is a template for new content.
|
||||
categories: [content management]
|
||||
keywords: [archetypes,generators,metadata,front matter]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 140
|
||||
quicklinks:
|
||||
weight: 140
|
||||
toc: true
|
||||
aliases: [/content/archetypes/]
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
A content file consists of [front matter] and markup. The markup is typically markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON.
|
||||
|
||||
The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype:
|
||||
|
||||
{{< code-toggle file=archetypes/default.md fm=true >}}
|
||||
title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
|
||||
date = '{{ .Date }}'
|
||||
draft = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
When you create new content, Hugo evaluates the [template actions] within the archetype. For example:
|
||||
|
||||
```sh
|
||||
hugo new content posts/my-first-post.md
|
||||
```
|
||||
|
||||
With the default archetype shown above, Hugo creates this content file:
|
||||
|
||||
{{< code-toggle file=content/posts/my-first-post.md fm=true >}}
|
||||
title = 'My First Post'
|
||||
date = '2023-08-24T11:49:46-07:00'
|
||||
draft = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
You can create an archetype for one or more [content types]. For example, use one archetype for posts, and use the default archetype for everything else:
|
||||
|
||||
```text
|
||||
archetypes/
|
||||
├── default.md
|
||||
└── posts.md
|
||||
```
|
||||
|
||||
## Lookup order
|
||||
|
||||
Hugo looks for archetypes in the `archetypes` directory in the root of your project, falling back to the `archetypes` directory in themes or installed modules. An archetype for a specific content type takes precedence over the default archetype.
|
||||
|
||||
For example, with this command:
|
||||
|
||||
```sh
|
||||
hugo new content posts/my-first-post.md
|
||||
```
|
||||
|
||||
The archetype lookup order is:
|
||||
|
||||
1. archetypes/posts.md
|
||||
1. archetypes/default.md
|
||||
1. themes/my-theme/archetypes/posts.md
|
||||
1. themes/my-theme/archetypes/default.md
|
||||
|
||||
If none of these exists, Hugo uses a built-in default archetype.
|
||||
|
||||
## Functions and context
|
||||
|
||||
You can use any [template function] within an archetype. As shown above, the default archetype uses the [`replace`](/functions/strings/replace) function to replace hyphens with spaces when populating the title in front matter.
|
||||
|
||||
Archetypes receive the following objects and values in [context]:
|
||||
|
||||
- `.Date`
|
||||
- `.Type`
|
||||
- `.Site` (see [details](/variables/site/))
|
||||
- `.File` (see [details](/variables/file/))
|
||||
|
||||
As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter.
|
||||
|
||||
## Include content
|
||||
|
||||
Although typically used as a front matter template, you can also use an archetype to populate content.
|
||||
|
||||
For example, in a documentation site you might have a section (content type) for functions. Every page within this section should follow the same format: a brief description, the function signature, examples, and notes. We can pre-populate the page to remind content authors of the standard format.
|
||||
|
||||
{{< code file=archetypes/functions.md >}}
|
||||
---
|
||||
date: '{{ .Date }}'
|
||||
draft: true
|
||||
title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
|
||||
---
|
||||
|
||||
A brief description of what the function does, using simple present tense in the third person singular form. For example:
|
||||
|
||||
`someFunction` returns the string `s` repeated `n` times.
|
||||
|
||||
## Signature
|
||||
|
||||
```text
|
||||
func someFunction(s string, n int) string
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
One or more practical examples, each within a fenced code block.
|
||||
|
||||
## Notes
|
||||
|
||||
Additional information to clarify as needed.
|
||||
{{< /code >}}
|
||||
|
||||
Although you can include [template actions] within the content body, remember that Hugo evaluates these once---at the time of content creation. In most cases, place template actions in a [template] where Hugo evaluates the actions every time you [build](/getting-started/glossary/#build) the site.
|
||||
|
||||
## Leaf bundles
|
||||
|
||||
You can also create archetypes for [leaf bundles](/getting-started/glossary/#leaf-bundle).
|
||||
|
||||
For example, in a photography site you might have a section (content type) for galleries. Each gallery is leaf bundle with content and images.
|
||||
|
||||
Create an archetype for galleries:
|
||||
|
||||
```text
|
||||
archetypes/
|
||||
├── galleries/
|
||||
│ ├── images/
|
||||
│ │ └── .gitkeep
|
||||
│ └── index.md <-- same format as default.md
|
||||
└── default.md
|
||||
```
|
||||
|
||||
Subdirectories within an archetype must contain at least one file. Without a file, Hugo will not create the subdirectory when you create new content. The name and size of the file are irrelevant. The example above includes a `.gitkeep` file, an empty file commonly used to preserve otherwise empty directories in a Git repository.
|
||||
|
||||
To create a new gallery:
|
||||
|
||||
```sh
|
||||
hugo new galleries/bryce-canyon
|
||||
```
|
||||
|
||||
This produces:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── galleries/
|
||||
│ └── bryce-canyon/
|
||||
│ ├── images/
|
||||
│ │ └── .gitkeep
|
||||
│ └── index.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
## Use alternate archetype
|
||||
|
||||
Use the `--kind` command line flag to specify an alternate archetype when creating content.
|
||||
|
||||
For example, let's say your site has two sections: articles and tutorials. Create an archetype for each content type:
|
||||
|
||||
```text
|
||||
archetypes/
|
||||
├── articles.md
|
||||
├── default.md
|
||||
└── tutorials.md
|
||||
```
|
||||
|
||||
To create an article using the articles archetype:
|
||||
|
||||
```sh
|
||||
hugo new content articles/something.md
|
||||
```
|
||||
|
||||
To create an article using the tutorials archetype:
|
||||
|
||||
```sh
|
||||
hugo new content --kind tutorials articles/something.md
|
||||
```
|
||||
|
||||
[content formats]: /getting-started/glossary/#content-format
|
||||
[content types]: /getting-started/glossary/#content-type
|
||||
[context]: /getting-started/glossary/#context
|
||||
[front matter]: /getting-started/glossary/#front-matter
|
||||
[template actions]: /getting-started/glossary/#template-action
|
||||
[template]: /getting-started/glossary/#template
|
||||
[template function]: /getting-started/glossary/#function
|
||||
@@ -1,321 +0,0 @@
|
||||
---
|
||||
title: Build options
|
||||
description: Build options help define how Hugo must treat a given page when building the site.
|
||||
categories: [content management,fundamentals]
|
||||
keywords: [build,content,front matter, page resources]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 70
|
||||
weight: 70
|
||||
toc: true
|
||||
aliases: [/content/build-options/]
|
||||
---
|
||||
|
||||
Build options are stored in a reserved front matter object named `_build` with these defaults:
|
||||
|
||||
{{< code-toggle file=content/example/index.md fm=true >}}
|
||||
[_build]
|
||||
list = 'always'
|
||||
publishResources = true
|
||||
render = 'always'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
|
||||
list
|
||||
: When to include the page within page collections. Specify one of:
|
||||
|
||||
- `always`
|
||||
: Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value.
|
||||
|
||||
- `local`
|
||||
: Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections.
|
||||
|
||||
- `never`
|
||||
: Do not include the page in _any_ page collection.
|
||||
|
||||
publishResources
|
||||
: Applicable to [page bundles], determines whether to publish the associated [page resources]. Specify one of:
|
||||
|
||||
- `true`
|
||||
: Always publish resources. This is the default value.
|
||||
|
||||
- `false`
|
||||
: Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template.
|
||||
|
||||
render
|
||||
: When to render the page. Specify one of:
|
||||
|
||||
- `always`
|
||||
: Always render the page to disk. This is the default value.
|
||||
|
||||
- `link`
|
||||
: Do not render the page to disk, but include it in all page collections.
|
||||
|
||||
- `never`
|
||||
: Never render the page to disk, and exclude it from all page collections.
|
||||
|
||||
[page bundles]: content-management/page-bundles
|
||||
[page resources]: /content-management/page-resources
|
||||
[`Permalink`]: /methods/resource/permalink
|
||||
[`RelPermalink`]: /methods/resource/relpermalink
|
||||
[`Publish`]: /methods/resource/publish
|
||||
|
||||
{{% note %}}
|
||||
Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method.
|
||||
|
||||
[`.Page.GetPage`]: /methods/page/getpage
|
||||
[`.Site.GetPage`]: /methods/site/getpage
|
||||
{{% /note %}}
|
||||
|
||||
## Example -- headless page
|
||||
|
||||
Create a unpublished page whose content and resources can be included in other pages.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── headless/
|
||||
│ ├── a.jpg
|
||||
│ ├── b.jpg
|
||||
│ └── index.md <-- leaf bundle
|
||||
└── _index.md <-- home page
|
||||
```
|
||||
|
||||
Set the build options in front matter:
|
||||
|
||||
{{< code-toggle file=content/headless/index.md fm=true >}}
|
||||
title = 'Headless page'
|
||||
[_build]
|
||||
list = 'never'
|
||||
publishResources = false
|
||||
render = 'never'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To include the content and images on the home page:
|
||||
|
||||
{{< code file=layouts/_default/home.html >}}
|
||||
{{ with .Site.GetPage "/headless" }}
|
||||
{{ .Content }}
|
||||
{{ range .Resources.ByType "image" }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
The published site will have this structure:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── headless/
|
||||
│ ├── a.jpg
|
||||
│ └── b.jpg
|
||||
└── index.html
|
||||
```
|
||||
|
||||
In the example above, note that:
|
||||
|
||||
1. Hugo did not publish an HTML file for the page.
|
||||
2. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
|
||||
|
||||
## Example -- headless section
|
||||
|
||||
Create a unpublished section whose content and resources can be included in other pages.
|
||||
|
||||
[branch bundle]: /content-management/page-bundles
|
||||
|
||||
```text
|
||||
content/
|
||||
├── headless/
|
||||
│ ├── note-1/
|
||||
│ │ ├── a.jpg
|
||||
│ │ ├── b.jpg
|
||||
│ │ └── index.md <-- leaf bundle
|
||||
│ ├── note-2/
|
||||
│ │ ├── c.jpg
|
||||
│ │ ├── d.jpg
|
||||
│ │ └── index.md <-- leaf bundle
|
||||
│ └── _index.md <-- branch bundle
|
||||
└── _index.md <-- home page
|
||||
```
|
||||
|
||||
Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
|
||||
|
||||
{{< code-toggle file=content/headless/_index.md fm=true >}}
|
||||
title = 'Headless section'
|
||||
[[cascade]]
|
||||
[cascade._build]
|
||||
list = 'local'
|
||||
publishResources = false
|
||||
render = 'never'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
In the front matter above, note that we have set `list` to `local` to include the descendant pages in local page collections.
|
||||
|
||||
To include the content and images on the home page:
|
||||
|
||||
{{< code file=layouts/_default/home.html >}}
|
||||
{{ with .Site.GetPage "/headless" }}
|
||||
{{ range .Pages }}
|
||||
{{ .Content }}
|
||||
{{ range .Resources.ByType "image" }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
The published site will have this structure:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── headless/
|
||||
│ ├── note-1/
|
||||
│ │ ├── a.jpg
|
||||
│ │ └── b.jpg
|
||||
│ └── note-2/
|
||||
│ ├── c.jpg
|
||||
│ └── d.jpg
|
||||
└── index.html
|
||||
```
|
||||
|
||||
In the example above, note that:
|
||||
|
||||
1. Hugo did not publish an HTML file for the page.
|
||||
2. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
|
||||
|
||||
## Example -- list without publishing
|
||||
|
||||
Publish a section page without publishing the descendant pages. For example, to create a glossary:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── glossary/
|
||||
│ ├── _index.md
|
||||
│ ├── bar.md
|
||||
│ ├── baz.md
|
||||
│ └── foo.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
|
||||
|
||||
{{< code-toggle file=content/glossary/_index.md fm=true >}}
|
||||
title = 'Glossary'
|
||||
[_build]
|
||||
render = 'always'
|
||||
[[cascade]]
|
||||
[cascade._build]
|
||||
list = 'local'
|
||||
publishResources = false
|
||||
render = 'never'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To render the glossary:
|
||||
|
||||
{{< code file=layouts/glossary/list.html >}}
|
||||
<dl>
|
||||
{{ range .Pages }}
|
||||
<dt>{{ .Title }}</dt>
|
||||
<dd>{{ .Content }}</dd>
|
||||
{{ end }}
|
||||
</dl>
|
||||
{{< /code >}}
|
||||
|
||||
The published site will have this structure:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── glossary/
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
## Example -- publish without listing
|
||||
|
||||
Publish a section's descendant pages without publishing the section page itself.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── books/
|
||||
│ ├── _index.md
|
||||
│ ├── book-1.md
|
||||
│ └── book-2.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
Set the build options in front matter:
|
||||
|
||||
{{< code-toggle file=content/books/_index.md >}}
|
||||
title = 'Books'
|
||||
[_build]
|
||||
render = 'never'
|
||||
list = 'never'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The published site will have this structure:
|
||||
|
||||
```html
|
||||
public/
|
||||
├── books/
|
||||
│ ├── book-1/
|
||||
│ │ └── index.html
|
||||
│ └── book-2/
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
## Example -- conditionally hide section
|
||||
|
||||
Consider this example. A documentation site has a team of contributors with access to 20 custom shortcodes. Each shortcode takes several arguments, and requires documentation for the contributors to reference when using them.
|
||||
|
||||
Instead of external documentation for the shortcodes, include an "internal" section that is hidden when building the production site.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── internal/
|
||||
│ ├── shortcodes/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── shortcode-1.md
|
||||
│ │ └── shortcode-2.md
|
||||
│ └── _index.md
|
||||
├── reference/
|
||||
│ ├── _index.md
|
||||
│ ├── reference-1.md
|
||||
│ └── reference-2.md
|
||||
├── tutorials/
|
||||
│ ├── _index.md
|
||||
│ ├── tutorial-1.md
|
||||
│ └── tutorial-2.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages, and use the `target` keyword to target the production environment.
|
||||
|
||||
{{< code-toggle file=content/internal/_index.md >}}
|
||||
title = 'Internal'
|
||||
[[cascade]]
|
||||
[cascade._build]
|
||||
render = 'never'
|
||||
list = 'never'
|
||||
[cascade._target]
|
||||
environment = 'production'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The production site will have this structure:
|
||||
|
||||
```html
|
||||
public/
|
||||
├── reference/
|
||||
│ ├── reference-1/
|
||||
│ │ └── index.html
|
||||
│ ├── reference-2/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
├── tutorials/
|
||||
│ ├── tutorial-1/
|
||||
│ │ └── index.html
|
||||
│ ├── tutorial-2/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
@@ -1,74 +0,0 @@
|
||||
---
|
||||
title: Comments
|
||||
description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
|
||||
categories: [content management]
|
||||
keywords: [sections,content,organization]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 220
|
||||
weight: 220
|
||||
toc: true
|
||||
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 file=hugo >}}
|
||||
[services.disqus]
|
||||
shortname = 'your-disqus-shortname'
|
||||
{{</ code-toggle >}}
|
||||
|
||||
For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter] of a single content file:
|
||||
|
||||
* `disqus_identifier`
|
||||
* `disqus_title`
|
||||
* `disqus_url`
|
||||
|
||||
### Render Hugo's built-in Disqus partial template
|
||||
|
||||
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)
|
||||
* [Comentario](https://gitlab.com/comentario/comentario) (Open Source, self-hosted, Go/Angular, run locally, in Docker or Kubernetes)
|
||||
* [Commento](https://commento.io/) (Open Source, available as a service, local install, or docker image)
|
||||
* [Giscus](https://giscus.app/) (Open source, comments system powered by GitHub Discussions)
|
||||
* [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
|
||||
@@ -1,150 +0,0 @@
|
||||
---
|
||||
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
|
||||
weight: 170
|
||||
toc: true
|
||||
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
|
||||
{{</* ref "document2" */>}} // <- From pages/document1.md, relative path
|
||||
{{</* ref "document2#anchor" */>}}
|
||||
{{</* ref "document2.md" */>}}
|
||||
{{</* ref "document2.md#anchor" */>}}
|
||||
{{</* ref "#anchor" */>}} // <- From pages/document2.md
|
||||
{{</* ref "/blog/my-post" */>}} // <- From anywhere, absolute path
|
||||
{{</* ref "/blog/my-post.md" */>}}
|
||||
{{</* relref "document" */>}}
|
||||
{{</* relref "document.md" */>}}
|
||||
{{</* relref "#anchor" */>}}
|
||||
{{</* relref "/blog/my-post.md" */>}}
|
||||
```
|
||||
|
||||
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
|
||||
{{</* ref "/about" */>}} // <- References /about/_index.md
|
||||
{{</* ref "/about/_index" */>}} // Raises REF_NOT_FOUND error
|
||||
{{</* ref "/about/credits.md" */>}} // <- References /about/credits.md
|
||||
|
||||
{{</* ref "/products" */>}} // <- References /products/index.md
|
||||
{{</* ref "/products/index" */>}} // <- References /products/index.md
|
||||
```
|
||||
|
||||
To generate a hyperlink using `ref` or `relref` in markdown:
|
||||
|
||||
```text
|
||||
[About]({{</* ref "/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
|
||||
{{</* relref path="document.md" lang="ja" */>}}
|
||||
```
|
||||
|
||||
### Get another output format
|
||||
|
||||
To link to another Output Format of a document, use this syntax:
|
||||
|
||||
```go-html-template
|
||||
{{</* relref path="document.md" outputFormat="rss" */>}}
|
||||
```
|
||||
|
||||
### 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
|
||||
<h2 id="reference">Reference</h2>
|
||||
```
|
||||
|
||||
Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes:
|
||||
|
||||
```go-html-template
|
||||
{{</* ref "document.md#reference" */>}}
|
||||
{{</* relref "document.md#reference" */>}}
|
||||
```
|
||||
|
||||
Generate a custom heading ID by including an attribute. For example:
|
||||
|
||||
```md
|
||||
## Reference A {#foo}
|
||||
## Reference B {id="bar"}
|
||||
```
|
||||
|
||||
produces this HTML:
|
||||
|
||||
```html
|
||||
<h2 id="foo">Reference A</h2>
|
||||
<h2 id="bar">Reference B</h2>
|
||||
```
|
||||
|
||||
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
|
||||
<h2 id="reference">Reference</h2>
|
||||
<h2 id="reference-1">Reference</h2>
|
||||
<h2 id="reference-2">Reference</h2>
|
||||
```
|
||||
|
||||
## Ref and RelRef Configuration
|
||||
|
||||
The behavior can be configured in `hugo.toml`:
|
||||
|
||||
refLinksErrorLevel ("ERROR")
|
||||
: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
|
||||
|
||||
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/
|
||||
@@ -1,263 +0,0 @@
|
||||
---
|
||||
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
|
||||
weight: 50
|
||||
toc: true
|
||||
---
|
||||
{{< new-in 0.93.0 >}}
|
||||
|
||||
## 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
|
||||
|
||||
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
|
||||
<pre class="mermaid">
|
||||
{{- .Inner | safeHTML }}
|
||||
</pre>
|
||||
{{ .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" }}
|
||||
<script type="module">
|
||||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
|
||||
mermaid.initialize({ startOnLoad: true });
|
||||
</script>
|
||||
{{ 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 <br/>prevail!
|
||||
John-->>Alice: Great!
|
||||
John->>Bob: How about you?
|
||||
Bob-->>John: Jolly good!
|
||||
```
|
||||
````
|
||||
|
||||
## 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 <https://arthursonzogni.com/Diagon/#Tree>
|
||||
|
||||
```goat { width=300 color="orange" }
|
||||
───Linux─┬─Android
|
||||
├─Debian─┬─Ubuntu─┬─Lubuntu
|
||||
│ │ ├─Kubuntu
|
||||
│ │ ├─Xubuntu
|
||||
│ │ └─Xubuntu
|
||||
│ └─Mint
|
||||
├─Centos
|
||||
└─Fedora
|
||||
```
|
||||
|
||||
### Sequence diagram
|
||||
|
||||
<https://arthursonzogni.com/Diagon/#Sequence>
|
||||
|
||||
```goat { class="w-40" }
|
||||
┌─────┐ ┌───┐
|
||||
│Alice│ │Bob│
|
||||
└──┬──┘ └─┬─┘
|
||||
│ │
|
||||
│ Hello Bob! │
|
||||
│───────────>│
|
||||
│ │
|
||||
│Hello Alice!│
|
||||
│<───────────│
|
||||
┌──┴──┐ ┌─┴─┐
|
||||
│Alice│ │Bob│
|
||||
└─────┘ └───┘
|
||||
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
|
||||
<https://arthursonzogni.com/Diagon/#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
|
||||
|
||||
<https://arthursonzogni.com/Diagon/#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 } """" .│
|
||||
└────────────────────────────────────────────────┘
|
||||
```
|
||||
@@ -1,93 +0,0 @@
|
||||
---
|
||||
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
|
||||
weight: 40
|
||||
toc: true
|
||||
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 | `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
|
||||
|
||||
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 %}}
|
||||
|
||||
### 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 parameters can be customized in Hugo. See [details].
|
||||
|
||||
[details]: /getting-started/configuration-markup/#asciidoc
|
||||
|
||||
## 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]
|
||||
|
||||
[ascii]: https://asciidoctor.org/
|
||||
[config]: /getting-started/configuration/
|
||||
[developer tools]: /tools/
|
||||
[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/
|
||||
@@ -1,244 +0,0 @@
|
||||
---
|
||||
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
|
||||
weight: 60
|
||||
toc: true
|
||||
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
|
||||
|
||||
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.
|
||||
Array values can either be separated into multiple lines (`#+KEY: VALUE_1` and `#+KEY: VALUE_2`) 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
|
||||
|
||||
### 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`.
|
||||
|
||||
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.
|
||||
|
||||
taxonomies
|
||||
: Field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.*
|
||||
|
||||
{{% note %}}
|
||||
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
|
||||
|
||||
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 >}}
|
||||
include_toc: true
|
||||
show_comments: false
|
||||
{{</ code-toggle >}}
|
||||
|
||||
## 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.
|
||||
|
||||
### 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 >}}
|
||||
title ="Blog"
|
||||
[[cascade]]
|
||||
background = "yosemite.jpg"
|
||||
[cascade._target]
|
||||
path="/blog/**"
|
||||
lang="en"
|
||||
kind="page"
|
||||
[[cascade]]
|
||||
background = "goldenbridge.jpg"
|
||||
[cascade._target]
|
||||
kind="section"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
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.
|
||||
|
||||
{{% note %}}
|
||||
When making a site that supports multiple languages, defining a `[[cascade]]` is recommended to be done in [Site Config](../../getting-started/configuration/#cascade) to prevent duplication.
|
||||
|
||||
If you instea define a `[[cascade]]` in front matter for multiple languages, an `content/XX/foo/_index.md` file needs to be made on a per-language basis, with `XX` the glob pattern matching the Page's language. In this case, the **lang** keyword is ignored.
|
||||
{{% /note %}}
|
||||
|
||||
### Example
|
||||
|
||||
In `content/blog/_index.md`
|
||||
|
||||
{{< code-toggle >}}
|
||||
title: Blog
|
||||
cascade:
|
||||
banner: images/typewriter.jpg
|
||||
{{</ code-toggle >}}
|
||||
|
||||
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
|
||||
|
||||
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 [`<TAXONOMY>_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
|
||||
|
||||
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
|
||||
|
||||
- [TOML Spec][toml]
|
||||
- [YAML Spec][yaml]
|
||||
- [JSON Spec][json]
|
||||
|
||||
[variables]: /variables/
|
||||
[aliases]: /content-management/urls/#aliases
|
||||
[archetype]: /content-management/archetypes/
|
||||
[config]: /getting-started/configuration/
|
||||
[content type]: /content-management/types/
|
||||
[contentorg]: /content-management/organization/
|
||||
[headless-bundle]: /content-management/page-bundles/#headless-bundle
|
||||
[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
|
||||
[lists]: /templates/lists/#sort-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/
|
||||
@@ -1,521 +0,0 @@
|
||||
---
|
||||
title: Image processing
|
||||
description: Resize, crop, rotate, filter, and convert images.
|
||||
categories: [content management,fundamentals]
|
||||
keywords: [resources,images]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 90
|
||||
toc: true
|
||||
weight: 90
|
||||
---
|
||||
|
||||
## Image resources
|
||||
|
||||
To process an image you must access the file as a page resource, global resource, or remote resource.
|
||||
|
||||
### Page resource
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
To access an image as a page resource:
|
||||
|
||||
```go-html-template
|
||||
{{ $image := .Resources.Get "sunset.jpg" }}
|
||||
```
|
||||
|
||||
### Global resource
|
||||
|
||||
A global resource is a file within the `assets` directory, or within any directory [mounted] to the `assets` directory.
|
||||
|
||||
```text
|
||||
assets/
|
||||
└── images/
|
||||
└── sunset.jpg <-- global resource
|
||||
```
|
||||
|
||||
To access an image as a global resource:
|
||||
|
||||
```go-html-template
|
||||
{{ $image := resources.Get "images/sunset.jpg" }}
|
||||
```
|
||||
|
||||
### Remote resource
|
||||
|
||||
A remote resource is a file on a remote server, accessible via HTTP or HTTPS. To access an image as a remote resource:
|
||||
|
||||
```go-html-template
|
||||
{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}
|
||||
```
|
||||
|
||||
## 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" }}
|
||||
<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">
|
||||
```
|
||||
|
||||
Example 2: Skips image rendering if the resource is not found.
|
||||
|
||||
```go-html-template
|
||||
{{ $image := .Resources.GetMatch "sunset.jpg" }}
|
||||
{{ with $image }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
|
||||
{{ 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" }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Example 4: Skips rendering if there's problem accessing a remote resource.
|
||||
|
||||
```go-html-template
|
||||
{{ $u := "https://gohugo.io/img/hugo-logo.png" }}
|
||||
{{ with resources.GetRemote $u }}
|
||||
{{ with .Err }}
|
||||
{{ errorf "%s" . }}
|
||||
{{ else }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %q" $u }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Image processing methods
|
||||
|
||||
The `image` resource implements the [`Process`], [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods.
|
||||
|
||||
{{% note %}}
|
||||
Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the `Exif` method with the _original_ image to extract EXIF metadata from JPEG or TIFF images.
|
||||
{{% /note %}}
|
||||
|
||||
### Process
|
||||
|
||||
{{< new-in 0.119.0 >}}
|
||||
|
||||
{{% note %}}
|
||||
The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process).
|
||||
{{% /note %}}
|
||||
|
||||
Process processes the image with the given specification. The specification can contain an optional action, one of `resize`, `crop`, `fit` or `fill`. This means that you can use this method instead of [`Resize`], [`Fit`], [`Fill`], or [`Crop`].
|
||||
|
||||
See [Options](#image-processing-options) for available options.
|
||||
|
||||
You can also use this method apply image processing that does not need any scaling, e.g. format conversions:
|
||||
|
||||
```go-html-template
|
||||
{{/* Convert the image from JPG to PNG. */}}
|
||||
{{ $png := $jpg.Process "png" }}
|
||||
```
|
||||
|
||||
Some more examples:
|
||||
|
||||
```go-html-template
|
||||
{{/* Rotate the image 90 degrees counter-clockwise. */}}
|
||||
{{ $image := $image.Process "r90" }}
|
||||
|
||||
{{/* Scaling actions. */}}
|
||||
{{ $image := $image.Process "resize 600x" }}
|
||||
{{ $image := $image.Process "crop 600x400" }}
|
||||
{{ $image := $image.Process "fit 600x400" }}
|
||||
{{ $image := $image.Process "fill 600x400" }}
|
||||
```
|
||||
|
||||
### Resize
|
||||
|
||||
Resize an image to the given width and/or height.
|
||||
|
||||
If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio.
|
||||
|
||||
```go-html-template
|
||||
{{/* 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
|
||||
|
||||
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.
|
||||
|
||||
```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.
|
||||
|
||||
```go-html-template
|
||||
{{ with $image.Exif }}
|
||||
<ul>
|
||||
{{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
|
||||
{{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
|
||||
{{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
|
||||
{{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
|
||||
{{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
|
||||
{{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
|
||||
{{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
|
||||
{{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
#### 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).
|
||||
|
||||
## Image processing options
|
||||
|
||||
The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-delimited, case-insensitive list of options. The order of the options within the list is irrelevant.
|
||||
|
||||
### Dimensions
|
||||
|
||||
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) }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
|
||||
{{ 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
|
||||
|
||||
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) }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .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, and is equivalent to the `-preset` flag for the [`cwebp`] encoder.
|
||||
|
||||
[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
|
||||
|
||||
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
|
||||
|
||||
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 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
|
||||
|
||||
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
|
||||
|
||||
_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.jpg" "resize 300x" />}}
|
||||
|
||||
{{< imgproc "sunset.jpg" "fill 90x120 left" />}}
|
||||
|
||||
{{< imgproc "sunset.jpg" "fill 90x120 right" />}}
|
||||
|
||||
{{< imgproc "sunset.jpg" "fit 90x90" />}}
|
||||
|
||||
{{< imgproc "sunset.jpg" "crop 250x250 center" />}}
|
||||
|
||||
{{< imgproc "sunset.jpg" "resize 300x q10" />}}
|
||||
|
||||
This is the shortcode used to generate the examples above:
|
||||
|
||||
{{< readfile file=layouts/shortcodes/imgproc.html highlight=go-html-template >}}
|
||||
|
||||
Call the shortcode from your Markdown like this:
|
||||
|
||||
```go-html-template
|
||||
{{</* imgproc "sunset.jpg" "resize 300x" /*/>}}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Note the self-closing shortcode syntax above. You may call the `imgproc` shortcode with or without **inner content**.
|
||||
{{% /note %}}
|
||||
|
||||
## Imaging configuration
|
||||
|
||||
### Processing options
|
||||
|
||||
Define an `imaging` section in your site configuration to set the default [image processing options](#image-processing-options).
|
||||
|
||||
{{< code-toggle config=imaging />}}
|
||||
|
||||
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
|
||||
|
||||
Define an `imaging.exif` section in your site configuration to control the availability of EXIF data.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[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 `""`.
|
||||
|
||||
includeFields
|
||||
: Regular expression matching the EXIF tags to include in the `.Tags` collection. Default is `""`. To include all available tags, set this value to `".*"`.
|
||||
|
||||
{{% note %}}
|
||||
To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
|
||||
|
||||
To control tag availability, change the `excludeFields` or `includeFields` settings as described above.
|
||||
{{% /note %}}
|
||||
|
||||
## Smart cropping of images
|
||||
|
||||
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.jpg" "fill 200x200 smart" />}}
|
||||
|
||||
{{< imgproc "sunset.jpg" "crop 200x200 smart" />}}
|
||||
|
||||
## 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:
|
||||
|
||||
```sh
|
||||
hugo --gc
|
||||
```
|
||||
|
||||
[time.Format]: /functions/time/format
|
||||
[`anchor`]: /content-management/image-processing#anchor
|
||||
[mounted]: /hugo-modules/configuration#module-configuration-mounts
|
||||
[page bundle]: /content-management/page-bundles
|
||||
[`lang.FormatNumber`]: /functions/lang/formatnumber
|
||||
[filters]: /functions/images/filter/#image-filters
|
||||
[github.com/disintegration/imaging]: <https://github.com/disintegration/imaging#image-resizing>
|
||||
[Smartcrop]: <https://github.com/muesli/smartcrop#smartcrop>
|
||||
[Exif]: <https://en.wikipedia.org/wiki/Exif>
|
||||
[`Process`]: #process
|
||||
[`Colors`]: #colors
|
||||
[`Crop`]: #crop
|
||||
[`Exif`]: #exif
|
||||
[`Fill`]: #fill
|
||||
[`Filter`]: #filter
|
||||
[`Fit`]: #fit
|
||||
[`Resize`]: #resize
|
||||
[site configuration]: #processing-options
|
||||
[`with`]: /functions/go-template/with/
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 34 KiB |
@@ -1,232 +0,0 @@
|
||||
---
|
||||
title: Menus
|
||||
description: Create menus by defining entries, localizing each entry, and rendering the resulting data structure.
|
||||
categories: [content management]
|
||||
keywords: [menus]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 190
|
||||
weight: 190
|
||||
toc: true
|
||||
aliases: [/extras/menus/]
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
To create a menu for your site:
|
||||
|
||||
1. Define the menu entries
|
||||
2. [Localize] each entry
|
||||
3. Render the menu with a [template]
|
||||
|
||||
Create multiple menus, either flat or nested. For example, create a main menu for the header, and a separate menu for the footer.
|
||||
|
||||
There are three ways to define menu entries:
|
||||
|
||||
1. Automatically
|
||||
1. In front matter
|
||||
1. In site configuration
|
||||
|
||||
{{% note %}}
|
||||
Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site.
|
||||
{{% /note %}}
|
||||
|
||||
## Define automatically
|
||||
|
||||
To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
sectionPagesMenu = "main"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
## Define in front matter
|
||||
|
||||
To add a page to the "main" menu:
|
||||
|
||||
{{< code-toggle file=content/about.md fm=true >}}
|
||||
title = 'About'
|
||||
menus = 'main'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
To add a page to the "main" and "footer" menus:
|
||||
|
||||
{{< code-toggle file=content/contact.md fm=true >}}
|
||||
title = 'Contact'
|
||||
menus = ['main','footer']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details.
|
||||
|
||||
{{% note %}}
|
||||
The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`.
|
||||
{{% /note %}}
|
||||
|
||||
### Properties {#properties-front-matter}
|
||||
|
||||
Use these properties when defining menu entries in front matter:
|
||||
|
||||
identifier
|
||||
: (`string`) Required when two or more menu entries have the same `name`, or when localizing the `name` using translation tables. Must start with a letter, followed by letters, digits, or underscores.
|
||||
|
||||
name
|
||||
: (`string`) The text to display when rendering the menu entry.
|
||||
|
||||
params
|
||||
: (`map`) User-defined properties for the menu entry.
|
||||
|
||||
parent
|
||||
: (`string`) The `identifier` of the parent menu entry. If `identifier` is not defined, use `name`. Required for child entries in a nested menu.
|
||||
|
||||
post
|
||||
: (`string`) The HTML to append when rendering the menu entry.
|
||||
|
||||
pre
|
||||
: (`string`) The HTML to prepend when rendering the menu entry.
|
||||
|
||||
title
|
||||
: (`string`) The HTML `title` attribute of the rendered menu entry.
|
||||
|
||||
weight
|
||||
: (`int`) A non-zero integer indicating the entry's position relative the root of the menu, or to its parent for a child entry. Lighter entries float to the top, while heavier entries sink to the bottom.
|
||||
|
||||
### Example {#example-front-matter}
|
||||
|
||||
This front matter menu entry demonstrates some of the available properties:
|
||||
|
||||
{{< code-toggle file=content/products/software.md fm=true >}}
|
||||
title = 'Software'
|
||||
[[menus.main]]
|
||||
parent = 'Products'
|
||||
weight = 20
|
||||
pre = '<i class="fa-solid fa-code"></i>'
|
||||
[menus.main.params]
|
||||
class = 'center'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
## Define in site configuration
|
||||
|
||||
To define entries for the "main" menu:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
name = 'Home'
|
||||
pageRef = '/'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 20
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 30
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
To define entries for the "footer" menu:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.footer]]
|
||||
name = 'Terms'
|
||||
pageRef = '/terms'
|
||||
weight = 10
|
||||
|
||||
[[menus.footer]]
|
||||
name = 'Privacy'
|
||||
pageRef = '/privacy'
|
||||
weight = 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This creates a menu structure that you can access with `site.Menus.footer` in your templates. See [menu templates] for details.
|
||||
|
||||
{{% note %}}
|
||||
The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`.
|
||||
{{% /note %}}
|
||||
|
||||
### Properties {#properties-site-configuration}
|
||||
|
||||
{{% note %}}
|
||||
The [properties available to entries defined in front matter] are also available to entries defined in site configuration.
|
||||
|
||||
[properties available to entries defined in front matter]: /content-management/menus/#properties-front-matter
|
||||
{{% /note %}}
|
||||
|
||||
Each menu entry defined in site configuration requires two or more properties:
|
||||
|
||||
- Specify `name` and `pageRef` for internal links
|
||||
- Specify `name` and `url` for external links
|
||||
|
||||
pageRef
|
||||
: (`string`) The file path of the target page, relative to the `content` directory. Omit language code and file extension. Required for *internal* links.
|
||||
|
||||
Kind|pageRef
|
||||
:--|:--
|
||||
home|`/`
|
||||
page|`/books/book-1`
|
||||
section|`/books`
|
||||
taxonomy|`/tags`
|
||||
term|`/tags/foo`
|
||||
|
||||
url
|
||||
: (`string`) Required for *external* links.
|
||||
|
||||
### Example {#example-site-configuration}
|
||||
|
||||
This nested menu demonstrates some of the available properties:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Hardware'
|
||||
pageRef = '/products/hardware'
|
||||
parent = 'Products'
|
||||
weight = 1
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Software'
|
||||
pageRef = '/products/software'
|
||||
parent = 'Products'
|
||||
weight = 2
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Hugo'
|
||||
pre = '<i class="fa fa-heart"></i>'
|
||||
url = 'https://gohugo.io/'
|
||||
weight = 30
|
||||
[menus.main.params]
|
||||
rel = 'external'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
## Localize
|
||||
|
||||
Hugo provides two methods to localize your menu entries. See [multilingual].
|
||||
|
||||
## Render
|
||||
|
||||
See [menu templates].
|
||||
|
||||
[localize]: /content-management/multilingual/#menus
|
||||
[menu templates]: /templates/menu-templates/
|
||||
[multilingual]: /content-management/multilingual/#menus
|
||||
[template]: /templates/menu-templates/
|
||||
@@ -1,716 +0,0 @@
|
||||
---
|
||||
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
|
||||
weight: 230
|
||||
toc: true
|
||||
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
|
||||
|
||||
This is the default language configuration:
|
||||
|
||||
{{< code-toggle config=languages />}}
|
||||
|
||||
This is an example of a site configuration for a multilingual project. Any key not defined in a `languages` object will fall back to the global value in the root of your site configuration.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
defaultContentLanguage = 'de'
|
||||
defaultContentLanguageInSubdir = true
|
||||
|
||||
[languages.de]
|
||||
contentDir = 'content/de'
|
||||
disabled = false
|
||||
languageCode = 'de-DE'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'Deutsch'
|
||||
title = 'Projekt Dokumentation'
|
||||
weight = 1
|
||||
|
||||
[languages.de.params]
|
||||
subtitle = 'Referenz, Tutorials und Erklärungen'
|
||||
|
||||
[languages.en]
|
||||
contentDir = 'content/en'
|
||||
disabled = false
|
||||
languageCode = 'en-US'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'English'
|
||||
title = 'Project Documentation'
|
||||
weight = 2
|
||||
|
||||
[languages.en.params]
|
||||
subtitle = 'Reference, Tutorials, and Explanations'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
defaultContentLanguage
|
||||
: (`string`) The project's default language tag as defined by [RFC 5646]. Must be lower case, and must match one of the defined language keys. Default is `en`. Examples:
|
||||
|
||||
- `en`
|
||||
- `en-gb`
|
||||
- `pt-br`
|
||||
|
||||
defaultContentLanguageInSubdir
|
||||
: (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`.
|
||||
|
||||
contentDir
|
||||
: (`string`) The content directory for this language. Omit if [translating by file name].
|
||||
|
||||
disabled
|
||||
: (`bool`) If `true`, Hugo will not render content for this language. Default is `false`.
|
||||
|
||||
languageCode
|
||||
: (`string`) The language tag as defined by [RFC 5646]. This value may include upper and lower case characters, hyphens, or underscores, and does not affect localization or URLs. Hugo uses this value to populate the `language` element in the [built-in RSS template], and the `lang` attribute of the `html` element in the [built-in alias template]. Examples:
|
||||
|
||||
- `en`
|
||||
- `en-GB`
|
||||
- `pt-BR`
|
||||
|
||||
languageDirection
|
||||
: (`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 parameters to the top level language configuration is deprecated. Define custom parameters within `languages.xx.params`. See `color` in the example below.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
|
||||
title = "My blog"
|
||||
languageCode = "en-us"
|
||||
|
||||
[languages]
|
||||
[languages.sv]
|
||||
title = "Min blogg"
|
||||
languageCode = "sv"
|
||||
[languages.en.params]
|
||||
color = "blue"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
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
|
||||
|
||||
To disable a language within a `languages` object in your site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[languages.es]
|
||||
disabled = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To disable one or more languages in the root of your site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
disableLanguages = ["es", "fr"]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To disable one or more languages using an environment variable:
|
||||
|
||||
```sh
|
||||
HUGO_DISABLELANGUAGES="es fr" hugo
|
||||
```
|
||||
|
||||
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.org/"
|
||||
languageName = "English"
|
||||
weight = 2
|
||||
title = "In English"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
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.org/`.**
|
||||
|
||||
When you run `hugo server` we will start multiple HTTP servers. You will typically see something like this in the console:
|
||||
|
||||
```text
|
||||
Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) fr
|
||||
Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) en
|
||||
Press Ctrl+C to stop
|
||||
```
|
||||
|
||||
Live reload and `--navigateToChanged` between the servers work as expected.
|
||||
|
||||
## 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 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 file name__.
|
||||
|
||||
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` 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 parameter to `about` in all three pages, they will be __linked__ as translated pages.
|
||||
|
||||
### Localizing permalinks
|
||||
|
||||
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 >}}
|
||||
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
|
||||
|
||||
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 file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`).
|
||||
{{%/ note %}}
|
||||
|
||||
## 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 }}
|
||||
<h4>{{ i18n "translations" }}</h4>
|
||||
<ul>
|
||||
{{ range .Translations }}
|
||||
<li>
|
||||
<a href="{{ .RelPermalink }}">{{ .Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ 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
|
||||
|
||||
`.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 >}}
|
||||
<ul>
|
||||
{{ range $.Site.Home.AllTranslations }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .Language.LanguageName }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{< /code >}}
|
||||
|
||||
## 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/<THEME>/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:
|
||||
|
||||
[`i18n`]: /functions/lang/translate
|
||||
|
||||
```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
|
||||
|
||||
To enable pluralization when translating, pass a map with a numeric `.Count` property to the `i18n` function. The example below 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 }}
|
||||
```
|
||||
|
||||
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 how you define them:
|
||||
|
||||
- When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry.
|
||||
- When you define menu entries [in front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry.
|
||||
- When you define menu entries [in site configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry.
|
||||
|
||||
### Create language-specific menu entries
|
||||
|
||||
#### Method 1 -- Use a single configuration file
|
||||
|
||||
For a simple menu with a small number of entries, use a single configuration file. For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[languages.de]
|
||||
languageCode = 'de-DE'
|
||||
languageName = 'Deutsch'
|
||||
weight = 1
|
||||
|
||||
[[languages.de.menus.main]]
|
||||
name = 'Produkte'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
|
||||
[[languages.de.menus.main]]
|
||||
name = 'Leistungen'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
|
||||
[languages.en]
|
||||
languageCode = 'en-US'
|
||||
languageName = 'English'
|
||||
weight = 2
|
||||
|
||||
[[languages.en.menus.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
|
||||
[[languages.en.menus.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Method 2 -- Use a configuration directory
|
||||
|
||||
With a more complex menu structure, create a [configuration directory] and split the menu entries into multiple files, one file per language. For example:
|
||||
|
||||
```text
|
||||
config/
|
||||
└── _default/
|
||||
├── menus.de.toml
|
||||
├── menus.en.toml
|
||||
└── hugo.toml
|
||||
```
|
||||
|
||||
{{< code-toggle file=config/_default/menus.de >}}
|
||||
[[main]]
|
||||
name = 'Produkte'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
[[main]]
|
||||
name = 'Leistungen'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{< code-toggle file=config/_default/menus.en >}}
|
||||
[[main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
[[main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[configuration directory]: /getting-started/configuration/#configuration-directory
|
||||
|
||||
### 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 >}}
|
||||
[[menus.main]]
|
||||
identifier = 'products'
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
[[menus.main]]
|
||||
identifier = 'services'
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
{{< / code-toggle >}}
|
||||
|
||||
Create corresponding entries in the translation tables:
|
||||
|
||||
{{< code-toggle file=i18n/de >}}
|
||||
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
|
||||
|
||||
## 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:
|
||||
|
||||
```sh
|
||||
hugo --printI18nWarnings | grep i18n
|
||||
i18n|MISSING_TRANSLATION|en|wordCount
|
||||
```
|
||||
|
||||
## 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`] or [`absLangURL`] template function, 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 content`
|
||||
|
||||
If you organize content with translations in the same directory:
|
||||
|
||||
```sh
|
||||
hugo new content post/test.en.md
|
||||
hugo new content post/test.de.md
|
||||
```
|
||||
|
||||
If you organize content with translations in different directories:
|
||||
|
||||
```sh
|
||||
hugo new content content/en/post/test.md
|
||||
hugo new content content/de/post/test.md
|
||||
```
|
||||
|
||||
[`abslangurl`]: /functions/urls/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/lang/translate
|
||||
[lang.FormatAccounting]: /functions/lang/formataccounting
|
||||
[lang.FormatCurrency]: /functions/lang/formatcurrency
|
||||
[lang.FormatNumber]: /functions/lang/formatnumber
|
||||
[lang.FormatNumberCustom]: /functions/lang/formatnumbercustom
|
||||
[lang.FormatPercent]: /functions/lang/formatpercent
|
||||
[lang.Merge]: /functions/lang/merge/
|
||||
[menus]: /content-management/menus/
|
||||
[OS environment]: /getting-started/configuration/#configure-with-environment-variables
|
||||
[`rellangurl`]: /functions/urls/rellangurl
|
||||
[RFC 5646]: https://tools.ietf.org/html/rfc5646
|
||||
[single page templates]: /templates/single-page-templates/
|
||||
[`time.Format`]: /functions/time/format
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 34 KiB |
@@ -1,154 +0,0 @@
|
||||
---
|
||||
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]
|
||||
keywords: [sections,content,organization,bundle,resources]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 20
|
||||
weight: 20
|
||||
toc: true
|
||||
aliases: [/content/sections/]
|
||||
---
|
||||
|
||||
## 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-content-bundles.png" "resize 300x" >}}
|
||||
The illustration shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed.
|
||||
{{< /imgproc >}}
|
||||
|
||||
{{% note %}}
|
||||
The bundle documentation is a **work in progress**. We will publish more comprehensive docs about this soon.
|
||||
{{% /note %}}
|
||||
|
||||
## Organization of content source
|
||||
|
||||
In Hugo, your content should be organized in a manner that reflects the rendered website.
|
||||
|
||||
While Hugo supports content nested at any level, the top levels (i.e. `content/<DIRECTORIES>`) 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.org/about/
|
||||
├── posts
|
||||
| ├── firstpost.md // <- https://example.org/posts/firstpost/
|
||||
| ├── happy
|
||||
| | └── ness.md // <- https://example.org/posts/happy/ness/
|
||||
| └── secondpost.md // <- https://example.org/posts/secondpost/
|
||||
└── quote
|
||||
├── first.md // <- https://example.org/quote/first/
|
||||
└── second.md // <- https://example.org/quote/second/
|
||||
```
|
||||
|
||||
## Path breakdown in Hugo
|
||||
|
||||
The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org"` in your [site's configuration file][config].
|
||||
|
||||
### Index pages: `_index.md`
|
||||
|
||||
`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates], [taxonomy templates], [taxonomy terms templates], and your [homepage template].
|
||||
|
||||
{{% note %}}
|
||||
**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/methods/page/getpage).
|
||||
{{% /note %}}
|
||||
|
||||
You can create one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website:
|
||||
|
||||
```txt
|
||||
. url
|
||||
. ⊢--^-⊣
|
||||
. 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.org/posts/index.html
|
||||
```
|
||||
|
||||
The [sections] can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. `_index.md`).
|
||||
|
||||
### Single pages in sections
|
||||
|
||||
Single content files in each of your sections will be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`:
|
||||
|
||||
```txt
|
||||
path ("posts/my-first-hugo-post.md")
|
||||
. ⊢-----------^------------⊣
|
||||
. 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.org/posts/my-first-hugo-post/index.html
|
||||
```
|
||||
|
||||
## Paths explained
|
||||
|
||||
The following concepts provide more insight into the relationship between your project's organization and the default Hugo behavior when building output for the website.
|
||||
|
||||
### `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]: /methods/page/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/
|
||||
@@ -1,183 +0,0 @@
|
||||
---
|
||||
title: Page bundles
|
||||
description: Content organization using Page Bundles
|
||||
categories: [content management]
|
||||
keywords: [page,bundle,leaf,branch]
|
||||
menu :
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 30
|
||||
weight: 30
|
||||
toc: true
|
||||
---
|
||||
|
||||
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 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`](/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 |
|
||||
|
||||
## 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}
|
||||
|
||||
```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
|
||||
|
||||
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*" }}
|
||||
<h2>Authors</h2>
|
||||
{{ range $reusablePages }}
|
||||
<h3>{{ .Title }}</h3>
|
||||
{{ .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
|
||||
(in the `index.md`):
|
||||
|
||||
{{< code-toggle file=content/headless/index.md fm=true >}}
|
||||
headless = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
There are many use cases of such headless page bundles:
|
||||
|
||||
- Shared media galleries
|
||||
- Reusable page content "snippets"
|
||||
|
||||
## 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
|
||||
|
||||
```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.
|
||||
@@ -1,203 +0,0 @@
|
||||
---
|
||||
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
|
||||
weight: 80
|
||||
toc: true
|
||||
---
|
||||
Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or
|
||||
`_index.md` files at their root. Page resources are only available to the
|
||||
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 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" }}
|
||||
<script>{{ .Content | safeJS }}</script>
|
||||
{{ end }}
|
||||
|
||||
{{ with .Resources.GetMatch "style.css" }}
|
||||
<style>{{ .Content | safeCSS }}</style>
|
||||
{{ end }}
|
||||
|
||||
{{ with .Resources.GetMatch "img.png" }}
|
||||
<img src="data:{{ .MediaType.Type }};base64,{{ .Content | base64Encode }}">
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
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 media type (e.g., `image`).
|
||||
|
||||
MediaType.SubType
|
||||
: 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 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
|
||||
|
||||
```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
|
||||
|
||||
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 >}}
|
||||
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"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
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 file=content/inspections/engine/index.md fm=true >}}
|
||||
title = 'Engine inspections'
|
||||
[[resources]]
|
||||
src = "*specs.pdf"
|
||||
title = "Specification #:counter"
|
||||
[[resources]]
|
||||
src = "**.pdf"
|
||||
name = "pdf-file-:counter"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
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"` |
|
||||
@@ -1,178 +0,0 @@
|
||||
---
|
||||
title: Related content
|
||||
description: List related content in "See Also" sections.
|
||||
categories: [content management]
|
||||
keywords: [content]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 110
|
||||
weight: 110
|
||||
toc: true
|
||||
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).
|
||||
|
||||
## 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 }}
|
||||
<h3>See Also</h3>
|
||||
<ul>
|
||||
{{ range . }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
The `Related` method takes one argument which may be a `Page` or a options map. The options map have these options:
|
||||
|
||||
indices
|
||||
: (`slice`) The indices to search within.
|
||||
|
||||
document
|
||||
: (`page`) The page for which to find related content. Required when specifying an options map.
|
||||
|
||||
namedSlices
|
||||
: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function.
|
||||
|
||||
fragments
|
||||
: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment] identifiers of the documents.
|
||||
|
||||
[fragment]: /getting-started/glossary/#fragment
|
||||
[`keyVals`]: /functions/collections/keyvals/
|
||||
|
||||
A fictional example using all of the above options:
|
||||
|
||||
```go-html-template
|
||||
{{ $page := . }}
|
||||
{{ $opts := dict
|
||||
"indices" (slice "tags" "keywords")
|
||||
"document" $page
|
||||
"namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date))
|
||||
"fragments" (slice "heading-1" "heading-2")
|
||||
}}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndices`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
|
||||
{{% /note %}}
|
||||
|
||||
## Index content headings in related content
|
||||
|
||||
{{< new-in 0.111.0 >}}
|
||||
|
||||
Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[related]
|
||||
threshold = 20
|
||||
includeNewer = true
|
||||
toLower = false
|
||||
[[related.indices]]
|
||||
name = "fragmentrefs"
|
||||
type = "fragments"
|
||||
applyFilter = true
|
||||
weight = 80
|
||||
{{< /code-toggle >}}
|
||||
|
||||
* The `name` maps to a optional front matter slice attribute that can be used to link from the page level down to the fragment/heading level.
|
||||
* If `applyFilter`is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing:
|
||||
|
||||
```go-html-template
|
||||
{{ $related := .Site.RegularPages.Related . | first 5 }}
|
||||
{{ with $related }}
|
||||
<h2>See Also</h2>
|
||||
<ul>
|
||||
{{ range $i, $p := . }}
|
||||
<li>
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
{{ with .HeadingsFiltered }}
|
||||
<ul>
|
||||
{{ range . }}
|
||||
{{ $link := printf "%s#%s" $p.RelPermalink .ID | safeURL }}
|
||||
<li>
|
||||
<a href="{{ $link }}">{{ .Title }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Configure related content
|
||||
|
||||
Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed.
|
||||
|
||||
### Default configuration
|
||||
|
||||
Without any `related` configuration set on the project, Hugo's Related Content methods will use the following.
|
||||
|
||||
{{< code-toggle config=related />}}
|
||||
|
||||
Custom configuration should be set using the same syntax.
|
||||
|
||||
{{% note %}}
|
||||
If you add a `related` configuration section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults.
|
||||
{{% /note %}}
|
||||
|
||||
### Top level configuration options
|
||||
|
||||
threshold
|
||||
: (`int`) A value between 0-100. Lower value will give more, but maybe not so relevant, matches.
|
||||
|
||||
includeNewer
|
||||
: (`bool`) Set to `true` to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added.
|
||||
|
||||
toLower
|
||||
: (`bool`) Set to `true` to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index.
|
||||
|
||||
### Configuration options per index
|
||||
|
||||
name
|
||||
: (`string`) The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
|
||||
|
||||
type {{< new-in 0.111.0 >}}
|
||||
: (`string`) One of `basic`(default) or `fragments`.
|
||||
|
||||
applyFilter {{< new-in 0.111.0 >}}
|
||||
: (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type.
|
||||
|
||||
weight
|
||||
: (`int`) An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best.
|
||||
|
||||
cardinalityThreshold {{< new-in 0.111.0 >}}
|
||||
: (`int`) A percentage (0-100) used to remove common keywords from the index. As an example, setting this to `50` will remove all keywords that are used in more than 50% of the documents in the index. Default is `0`.
|
||||
|
||||
pattern
|
||||
: (`string`) This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default.
|
||||
|
||||
toLower
|
||||
: (`bool`) See above.
|
||||
|
||||
## Performance considerations
|
||||
|
||||
**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast.
|
||||
|
||||
This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread:
|
||||
|
||||
{{< tweet user="scott_lowe" id="898398437527363585" >}}
|
||||
|
||||
Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog.
|
||||
|
||||
He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that:
|
||||
|
||||
* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before.
|
||||
* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites.
|
||||
|
||||
{{% note %}}
|
||||
We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock).
|
||||
{{% /note %}}
|
||||
@@ -1,161 +0,0 @@
|
||||
---
|
||||
title: Sections
|
||||
description: Organize content into sections.
|
||||
|
||||
categories: [content management]
|
||||
keywords: [lists,sections,content types,organization]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 120
|
||||
weight: 120
|
||||
toc: true
|
||||
aliases: [/content/sections/]
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
A section is a top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](/getting-started/glossary/#collection) in [context](/getting-started/glossary/#context).
|
||||
|
||||
{{% note %}}
|
||||
Although top-level directories without _index.md files are sections, we recommend creating _index.md files in _all_ sections.
|
||||
{{% /note %}}
|
||||
|
||||
A typical site consists of one or more sections. For example:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── articles/ <-- section (top-level directory)
|
||||
│ ├── 2022/
|
||||
│ │ ├── article-1/
|
||||
│ │ │ ├── cover.jpg
|
||||
│ │ │ └── index.md
|
||||
│ │ └── article-2.md
|
||||
│ └── 2023/
|
||||
│ ├── article-3.md
|
||||
│ └── article-4.md
|
||||
├── products/ <-- section (top-level directory)
|
||||
│ ├── product-1/ <-- section (has _index.md file)
|
||||
│ │ ├── benefits/ <-- section (has _index.md file)
|
||||
│ │ │ ├── _index.md
|
||||
│ │ │ ├── benefit-1.md
|
||||
│ │ │ └── benefit-2.md
|
||||
│ │ ├── features/ <-- section (has _index.md file)
|
||||
│ │ │ ├── _index.md
|
||||
│ │ │ ├── feature-1.md
|
||||
│ │ │ └── feature-2.md
|
||||
│ │ └── _index.md
|
||||
│ └── product-2/ <-- section (has _index.md file)
|
||||
│ ├── benefits/ <-- section (has _index.md file)
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── benefit-1.md
|
||||
│ │ └── benefit-2.md
|
||||
│ ├── features/ <-- section (has _index.md file)
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── feature-1.md
|
||||
│ │ └── feature-2.md
|
||||
│ └── _index.md
|
||||
├── _index.md
|
||||
└── about.md
|
||||
```
|
||||
|
||||
The example above has two top-level sections: articles and products. None of the directories under articles are sections, while all of the directories under products are sections. A section within a section is a known as a nested section or subsection.
|
||||
|
||||
## Explanation
|
||||
|
||||
Sections and non-sections behave differently.
|
||||
|
||||
||Sections|Non-sections
|
||||
:--|:-:|:-:
|
||||
Directory names become URL segments|:heavy_check_mark:|:heavy_check_mark:
|
||||
Have logical ancestors and descendants|:heavy_check_mark:|:x:
|
||||
Have list pages|:heavy_check_mark:|:x:
|
||||
|
||||
With the file structure from the [example above](#overview):
|
||||
|
||||
1. The list page for the articles section includes all articles, regardless of directory structure; none of the subdirectories are sections.
|
||||
|
||||
1. The articles/2022 and articles/2023 directories do not have list pages; they are not sections.
|
||||
|
||||
1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `.RegularPagesRecursive` collection instead of the `.Pages` collection in the list template. See [details](/variables/page/#page-collections).
|
||||
|
||||
1. All directories in the products section have list pages; each directory is a section.
|
||||
|
||||
## Template selection
|
||||
|
||||
Hugo has a defined [lookup order] to determine which template to use when rendering a page. The [lookup rules] consider the top-level section name; subsection names are not considered when selecting a template.
|
||||
|
||||
With the file structure from the [example above](#overview):
|
||||
|
||||
Content directory|List page template
|
||||
:--|:--
|
||||
content/products|layouts/products/list.html
|
||||
content/products/product-1|layouts/products/list.html
|
||||
content/products/product-1/benefits|layouts/products/list.html
|
||||
|
||||
Content directory|Single page template
|
||||
:--|:--
|
||||
content/products|layouts/products/single.html
|
||||
content/products/product-1|layouts/products/single.html
|
||||
content/products/product-1/benefits|layouts/products/single.html
|
||||
|
||||
If you need to use a different template for a subsection, specify `type` and/or `layout` in front matter.
|
||||
|
||||
[lookup rules]: /templates/lookup-order/#lookup-rules
|
||||
[lookup order]: /templates/lookup-order/
|
||||
|
||||
## Ancestors and descendants
|
||||
|
||||
A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview):
|
||||
|
||||
```text
|
||||
content/products/product-1/benefits/benefit-1.md
|
||||
```
|
||||
|
||||
The content file (benefit-1.md) has four ancestors: benefits, product-1, products, and the home page. This logical relationship allows us to use the `.Parent` and `.Ancestors` methods to traverse the site structure.
|
||||
|
||||
For example, use the `.Ancestors` method to render breadcrumb navigation.
|
||||
|
||||
{{< code file=layouts/partials/breadcrumb.html >}}
|
||||
<nav aria-label="breadcrumb" class="breadcrumb">
|
||||
<ol>
|
||||
{{ range .Ancestors.Reverse }}
|
||||
<li>
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
<li class="active">
|
||||
<a aria-current="page" href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
</li>
|
||||
</ol>
|
||||
</nav>
|
||||
{{< /code >}}
|
||||
|
||||
With this CSS:
|
||||
|
||||
```css
|
||||
.breadcrumb ol {
|
||||
padding-left: 0;
|
||||
}
|
||||
|
||||
.breadcrumb li {
|
||||
display: inline;
|
||||
}
|
||||
|
||||
.breadcrumb li:not(:last-child)::after {
|
||||
content: "»";
|
||||
}
|
||||
```
|
||||
|
||||
Hugo renders this, where each breadcrumb is a link to the corresponding page:
|
||||
|
||||
```text
|
||||
Home » Products » Product 1 » Benefits » Benefit 1
|
||||
```
|
||||
|
||||
[archetype]: /content-management/archetypes/
|
||||
[content type]: /content-management/types/
|
||||
[directory structure]: /getting-started/directory-structure/
|
||||
[section templates]: /templates/section-templates/
|
||||
[leaf bundles]: /content-management/page-bundles/#leaf-bundles
|
||||
[branch bundles]: /content-management/page-bundles/#branch-bundles
|
||||
@@ -1,404 +0,0 @@
|
||||
---
|
||||
title: Shortcodes
|
||||
description: Shortcodes are simple snippets inside your content files calling built-in or custom templates.
|
||||
categories: [content management]
|
||||
keywords: [markdown,content,shortcodes]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 100
|
||||
weight: 100
|
||||
toc: true
|
||||
aliases: [/extras/shortcodes/]
|
||||
testparam: "Hugo Rocks!"
|
||||
---
|
||||
|
||||
## What a shortcode is
|
||||
|
||||
Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframe>`'s) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax.
|
||||
|
||||
Hugo created **shortcodes** to circumvent these limitations.
|
||||
|
||||
A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead.
|
||||
|
||||
In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.
|
||||
|
||||
## Use shortcodes
|
||||
|
||||
{{< youtube 2xkNJL4gJ9E >}}
|
||||
|
||||
In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
|
||||
|
||||
The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`.
|
||||
|
||||
Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
|
||||
|
||||
Here are two examples of paired shortcodes:
|
||||
|
||||
```go-html-template
|
||||
{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
|
||||
```
|
||||
|
||||
The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
|
||||
|
||||
### Shortcodes with raw string parameters
|
||||
|
||||
You can pass multiple lines as parameters to a shortcode by using raw string literals:
|
||||
|
||||
```go-html-template
|
||||
{{</* myshortcode `This is some <b>HTML</b>,
|
||||
and a new line with a "quoted string".` */>}}
|
||||
```
|
||||
|
||||
### Shortcodes with markdown
|
||||
|
||||
Shortcodes using the `%` as the outer-most delimiter will be fully rendered when sent to the content renderer. This means that the rendered output from a shortcode can be part of the page's table of contents, footnotes, etc.
|
||||
|
||||
### Shortcodes without markdown
|
||||
|
||||
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML:
|
||||
|
||||
```go-html-template
|
||||
{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
|
||||
```
|
||||
|
||||
### Nested shortcodes
|
||||
|
||||
You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
|
||||
|
||||
## Use Hugo's built-in shortcodes
|
||||
|
||||
Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your Markdown content clean.
|
||||
|
||||
### `figure`
|
||||
|
||||
`figure` is an extension of the image syntax in Markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement].
|
||||
|
||||
The `figure` shortcode can use the following named parameters:
|
||||
|
||||
src
|
||||
: URL of the image to be displayed.
|
||||
|
||||
link
|
||||
: If the image needs to be hyperlinked, URL of the destination.
|
||||
|
||||
target
|
||||
: Optional `target` attribute for the URL if `link` parameter is set.
|
||||
|
||||
rel
|
||||
: Optional `rel` attribute for the URL if `link` parameter is set.
|
||||
|
||||
alt
|
||||
: Alternate text for the image if the image cannot be displayed.
|
||||
|
||||
title
|
||||
: Image title.
|
||||
|
||||
caption
|
||||
: Image caption. Markdown within the value of `caption` will be rendered.
|
||||
|
||||
class
|
||||
: `class` attribute of the HTML `figure` tag.
|
||||
|
||||
height
|
||||
: `height` attribute of the image.
|
||||
|
||||
width
|
||||
: `width` attribute of the image.
|
||||
|
||||
loading
|
||||
: `loading` attribute of the image.
|
||||
|
||||
attr
|
||||
: Image attribution text. Markdown within the value of `attr` will be rendered.
|
||||
|
||||
attrlink
|
||||
: If the attribution text needs to be hyperlinked, URL of the destination.
|
||||
|
||||
#### Example `figure` input
|
||||
|
||||
{{< code file=figure-input-example.md >}}
|
||||
{{</* figure src="elephant.jpg" title="An elephant at sunset" */>}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `figure` output
|
||||
|
||||
```html
|
||||
<figure>
|
||||
<img src="elephant.jpg">
|
||||
<figcaption><h4>An elephant at sunset</h4></figcaption>
|
||||
</figure>
|
||||
```
|
||||
|
||||
### `gist`
|
||||
|
||||
To display a GitHub [gist] with this URL:
|
||||
|
||||
[gist]: https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists
|
||||
|
||||
```text
|
||||
https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
|
||||
```text
|
||||
{{</* gist user 50a7482715eac222e230d1e64dd9a89b */>}}
|
||||
```
|
||||
|
||||
This will display all files in the gist alphabetically by file name.
|
||||
|
||||
{{< gist jmooring 23932424365401ffa5e9d9810102a477 >}}
|
||||
|
||||
To display a specific file within the gist:
|
||||
|
||||
```text
|
||||
{{</* gist user 23932424365401ffa5e9d9810102a477 list.html */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}}
|
||||
|
||||
### `highlight`
|
||||
|
||||
To display a highlighted code sample:
|
||||
|
||||
```text
|
||||
{{</* highlight go-html-template */>}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{</* /highlight */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< highlight go-html-template >}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{< /highlight >}}
|
||||
|
||||
To specify one or more [highlighting options], include a quotation-encapsulated, comma-separated list:
|
||||
|
||||
[highlighting options]: /functions/transform/highlight/
|
||||
|
||||
```text
|
||||
{{</* highlight go-html-template "lineNos=inline, lineNoStart=42" */>}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{</* /highlight */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{< /highlight >}}
|
||||
|
||||
### `instagram`
|
||||
|
||||
The `instagram` shortcode uses Facebook's **oEmbed Read** feature. The Facebook [developer documentation] states:
|
||||
|
||||
- This permission or feature requires successful completion of the App Review process before your app can access live data. [Learn More]
|
||||
- This permission or feature is only available with business verification. You may also need to sign additional contracts before your app can access data. [Learn More Here]
|
||||
|
||||
[developer documentation]: https://developers.facebook.com/docs/features-reference/oembed-read
|
||||
[Learn More]: https://developers.facebook.com/docs/app-review
|
||||
[Learn More Here]: https://developers.facebook.com/docs/development/release/business-verification
|
||||
|
||||
You must obtain an Access Token to use the `instagram` shortcode.
|
||||
|
||||
If your site configuration is private:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[services.instagram]
|
||||
accessToken = 'xxx'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
If your site configuration is _not_ private, set the Access Token with an environment variable:
|
||||
|
||||
```sh
|
||||
HUGO_SERVICES_INSTAGRAM_ACCESSTOKEN=xxx hugo --gc --minify
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
If you are using a Client Access Token, you must combine the Access Token with your App ID using a pipe symbol (`APPID|ACCESSTOKEN`).
|
||||
{{% /note %}}
|
||||
|
||||
To display an Instagram post with this URL:
|
||||
|
||||
```text
|
||||
https://www.instagram.com/p/BWNjjyYFxVx/
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
|
||||
```text
|
||||
{{</* instagram BWNjjyYFxVx */>}}
|
||||
```
|
||||
|
||||
### `param`
|
||||
|
||||
Gets a value from the current `Page's` parameters set in front matter, with a fallback to the site parameter value. It will log an `ERROR` if the parameter with the given key could not be found in either.
|
||||
|
||||
```sh
|
||||
{{</* param testparam */>}}
|
||||
```
|
||||
|
||||
Since `testparam` is a parameter defined in front matter of this page with the value `Hugo Rocks!`, the above will print:
|
||||
|
||||
{{< param testparam >}}
|
||||
|
||||
To access deeply nested parameters, use "dot syntax", e.g:
|
||||
|
||||
```sh
|
||||
{{</* param "my.nested.param" */>}}
|
||||
```
|
||||
|
||||
### `ref` and `relref`
|
||||
|
||||
These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page.
|
||||
|
||||
`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
|
||||
|
||||
{{% note %}}
|
||||
Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
|
||||
{{% /note %}}
|
||||
|
||||
`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
|
||||
|
||||
#### Example `ref` and `relref` input
|
||||
|
||||
```go-html-template
|
||||
[Neat]({{</* ref "blog/neat.md" */>}})
|
||||
[Who]({{</* relref "about.md#who" */>}})
|
||||
```
|
||||
|
||||
#### Example `ref` and `relref` output
|
||||
|
||||
Assuming that standard Hugo pretty URLs are turned on.
|
||||
|
||||
```html
|
||||
<a href="https://example.org/blog/neat">Neat</a>
|
||||
<a href="/about/#who">Who</a>
|
||||
```
|
||||
|
||||
### `tweet`
|
||||
|
||||
To display a Twitter post with this URL:
|
||||
|
||||
```txt
|
||||
https://twitter.com/SanDiegoZoo/status/1453110110599868418
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
|
||||
```text
|
||||
{{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}
|
||||
|
||||
### `vimeo`
|
||||
|
||||
To display a Vimeo video with this URL:
|
||||
|
||||
```text
|
||||
https://vimeo.com/channels/staffpicks/55073825
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
|
||||
```text
|
||||
{{</* vimeo 55073825 */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< vimeo 55073825 >}}
|
||||
|
||||
{{% note %}}
|
||||
If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
|
||||
|
||||
```go
|
||||
{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
|
||||
```
|
||||
{{% /note %}}
|
||||
|
||||
### `youtube`
|
||||
|
||||
The `youtube` shortcode embeds a responsive video player for [YouTube videos]. Only the ID of the video is required, e.g.:
|
||||
|
||||
```txt
|
||||
https://www.youtube.com/watch?v=w7Ft2ymGmfc
|
||||
```
|
||||
|
||||
#### Example `youtube` input
|
||||
|
||||
Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
|
||||
|
||||
{{< code file=example-youtube-input.md >}}
|
||||
{{</* youtube w7Ft2ymGmfc */>}}
|
||||
{{< /code >}}
|
||||
|
||||
Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named and unnamed parameters, so you'll need to assign the yet unnamed video ID to the parameter `id`:
|
||||
|
||||
{{< code file=example-youtube-input-with-autoplay.md >}}
|
||||
{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
|
||||
{{< /code >}}
|
||||
|
||||
For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video. You can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used.
|
||||
|
||||
{{< code file=example-youtube-input-with-title.md >}}
|
||||
{{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `youtube` output
|
||||
|
||||
Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
|
||||
|
||||
{{< code file=example-youtube-output.html >}}
|
||||
{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `youtube` display
|
||||
|
||||
Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your style sheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
|
||||
|
||||
{{< youtube w7Ft2ymGmfc >}}
|
||||
|
||||
## Privacy configuration
|
||||
|
||||
To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR].
|
||||
|
||||
## Create custom shortcodes
|
||||
|
||||
To learn more about creating custom shortcodes, see the [shortcode template documentation].
|
||||
|
||||
[`figure` shortcode]: #figure
|
||||
[contentmanagementsection]: /content-management/formats/
|
||||
[examplegist]: https://gist.github.com/spf13/7896402
|
||||
[figureelement]: https://html5doctor.com/the-figure-figcaption-elements/
|
||||
[Hugo and the GDPR]: /about/hugo-and-gdpr/
|
||||
[Instagram]: https://www.instagram.com/
|
||||
[pagevariables]: /variables/page/
|
||||
[partials]: /templates/partials/
|
||||
[quickstart]: /getting-started/quick-start/
|
||||
[sctemps]: /templates/shortcode-templates/
|
||||
[scvars]: /variables/shortcode/
|
||||
[shortcode template documentation]: /templates/shortcode-templates/
|
||||
[templatessection]: /templates/
|
||||
[Vimeo]: https://vimeo.com/
|
||||
[YouTube Videos]: https://www.youtube.com/
|
||||
[YouTube Input shortcode]: #youtube
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
title: Static files
|
||||
description: Files that get served **statically** (as-is, no modification) on the site root.
|
||||
categories: [content management]
|
||||
keywords: [source, directories]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 200
|
||||
weight: 200
|
||||
toc: true
|
||||
aliases: [/static-files]
|
||||
---
|
||||
|
||||
By default, the `static/` directory in the site project is used for
|
||||
all **static files** (e.g. stylesheets, JavaScript, images). The static files are served on the site root path (eg. if you have the file `static/image.png` you can access it using `http://{server-url}/image.png`, to include it in a document you can use ` )`.
|
||||
|
||||
Hugo can be configured to look into a different directory, or even
|
||||
**multiple directories** for such static files by configuring the
|
||||
`staticDir` parameter in the [site configuration]. All the files in all the
|
||||
static directories will form a union filesystem.
|
||||
|
||||
This union filesystem will be served from your site root. So a file
|
||||
`<SITE PROJECT>/static/me.png` will be accessible as
|
||||
`<MY_BASEURL>/me.png`.
|
||||
|
||||
Here's an example of setting `staticDir` and `staticDir2` for a
|
||||
multi-language site:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
staticDir = ["static1", "static2"]
|
||||
|
||||
[languages]
|
||||
[languages.en]
|
||||
staticDir2 = "static_en"
|
||||
baseURL = "https://example.org/"
|
||||
languageName = "English"
|
||||
weight = 2
|
||||
title = "In English"
|
||||
[languages.no]
|
||||
staticDir = ["staticDir_override", "static_no"]
|
||||
baseURL = "https://example.no"
|
||||
languageName = "Norsk"
|
||||
weight = 1
|
||||
title = "På norsk"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
In the above, with no theme used:
|
||||
|
||||
- The English site will get its static files as a union of "static1",
|
||||
"static2" and "static_en". On file duplicates, the right-most
|
||||
version will win.
|
||||
- The Norwegian site will get its static files as a union of
|
||||
"staticDir_override" and "static_no".
|
||||
|
||||
Note 1
|
||||
: The **2** (can be a number between 0 and 10) in `staticDir2` is
|
||||
added to tell Hugo that you want to **add** this directory to the
|
||||
global set of static directories defined using `staticDir`. Using
|
||||
`staticDir` on the language level would replace the global value (as
|
||||
can be seen in the Norwegian site case).
|
||||
|
||||
Note 2
|
||||
: The example above is a [multihost setup]. In a regular setup, all
|
||||
the static directories will be available to all sites.
|
||||
|
||||
[site configuration]: /getting-started/configuration/#all-configuration-settings
|
||||
[multihost setup]: /content-management/multilingual/#configure-multilingual-multihost
|
||||
@@ -1,110 +0,0 @@
|
||||
---
|
||||
title: Content summaries
|
||||
linkTitle: Summaries
|
||||
description: Hugo generates summaries of your content.
|
||||
categories: [content management]
|
||||
keywords: [summaries,abstracts,read more]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 160
|
||||
weight: 160
|
||||
toc: true
|
||||
aliases: [/content/summaries/,/content-management/content-summaries/]
|
||||
---
|
||||
|
||||
<!--more-->
|
||||
|
||||
With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views.
|
||||
|
||||
## Summary splitting options
|
||||
|
||||
* Automatic Summary Split
|
||||
* Manual Summary Split
|
||||
* Front Matter Summary
|
||||
|
||||
It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables].
|
||||
|
||||
### Automatic summary splitting
|
||||
|
||||
By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/).
|
||||
|
||||
{{% note %}}
|
||||
You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`.
|
||||
{{% /note %}}
|
||||
|
||||
{{% note %}}
|
||||
The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](/getting-started/configuration/).
|
||||
{{% /note %}}
|
||||
|
||||
### Manual summary splitting
|
||||
|
||||
Alternatively, you may add the `<!--more-->` summary divider where you want to split the article.
|
||||
|
||||
For [Org mode content][org], use `# more` where you want to split the article.
|
||||
|
||||
Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact.
|
||||
|
||||
{{% note %}}
|
||||
The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature.
|
||||
{{% /note %}}
|
||||
|
||||
Pros
|
||||
: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved.
|
||||
|
||||
Cons
|
||||
: Extra work for content authors, since they need to remember to type `<!--more-->` (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/).
|
||||
|
||||
{{% note %}}
|
||||
Be careful to enter `<!--more-->` exactly; i.e., all lowercase and with no whitespace.
|
||||
{{% /note %}}
|
||||
|
||||
### Front matter summary
|
||||
|
||||
You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter.
|
||||
|
||||
Pros
|
||||
: Complete freedom of text independent of the content of the article. Markup can be used within the summary.
|
||||
|
||||
Cons
|
||||
: Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article.
|
||||
|
||||
## Summary selection order
|
||||
|
||||
Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`. It is as follows:
|
||||
|
||||
1. If there is a `<!--more-->` summary divider present in the article, the text up to the divider will be provided as per the manual summary split method
|
||||
2. If there is a `summary` variable in the article front matter the value of the variable will be provided as per the front matter summary method
|
||||
3. The text at the start of the article will be provided as per the automatic summary split method
|
||||
|
||||
{{% note %}}
|
||||
Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a `<!--more-->` summary divider Hugo will use the manual summary split method.
|
||||
{{% /note %}}
|
||||
|
||||
## Example: first 10 articles with summaries
|
||||
|
||||
You can show content summaries with the following code. You could use the following snippet, for example, in a [section template].
|
||||
|
||||
{{< code file=page-list-with-summaries.html >}}
|
||||
{{ range first 10 .Pages }}
|
||||
<article>
|
||||
<!-- this <div> includes the title summary -->
|
||||
<div>
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
|
||||
{{ .Summary }}
|
||||
</div>
|
||||
{{ if .Truncated }}
|
||||
<!-- This <div> includes a read more link, but only if the summary is truncated... -->
|
||||
<div>
|
||||
<a href="{{ .RelPermalink }}">Read More…</a>
|
||||
</div>
|
||||
{{ end }}
|
||||
</article>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
Note how the `.Truncated` boolean variable value may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
|
||||
|
||||
[org]: /content-management/formats/
|
||||
[pagevariables]: /variables/page/
|
||||
[section template]: /templates/section-templates/
|
||||
@@ -1,138 +0,0 @@
|
||||
---
|
||||
title: Syntax highlighting
|
||||
description: Hugo comes with really fast syntax highlighting from Chroma.
|
||||
categories: [content management]
|
||||
keywords: [highlighting,chroma,code blocks,syntax]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 240
|
||||
weight: 240
|
||||
toc: true
|
||||
aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
|
||||
---
|
||||
|
||||
Hugo uses [Chroma](https://github.com/alecthomas/chroma) as its code highlighter; it is built in Go and is really, really fast.
|
||||
|
||||
## Configure syntax highlighter
|
||||
|
||||
See [Configure Highlight](/getting-started/configuration-markup#highlight).
|
||||
|
||||
## Generate syntax highlighter CSS
|
||||
|
||||
If you run with `markup.highlight.noClasses=false` in your site configuration, you need a style sheet.
|
||||
|
||||
You can generate one with Hugo:
|
||||
|
||||
```sh
|
||||
hugo gen chromastyles --style=monokai > syntax.css
|
||||
```
|
||||
|
||||
Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles.
|
||||
|
||||
## Highlight shortcode
|
||||
|
||||
Highlighting is carried out via the built-in [`highlight` shortcode](/content-management/shortcodes/#highlight). It takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode.
|
||||
|
||||
Options:
|
||||
|
||||
* `linenos`: configure line numbers. Valid values are `true`, `false`, `table`, or `inline`. `false` will turn off line numbers if it's configured to be on in site configuration. `table` will give copy-and-paste friendly code blocks.
|
||||
* `hl_lines`: lists a set of line numbers or line number ranges to be highlighted.
|
||||
* `linenostart=199`: starts the line number count from 199.
|
||||
* `anchorlinenos`: Configure anchors on line numbers. Valid values are `true` or `false`;
|
||||
* `lineanchors`: Configure a prefix for the anchors on line numbers. Will be suffixed with `-`, so linking to the line number 1 with the option `lineanchors=prefix` adds the anchor `prefix-1` to the page.
|
||||
* `hl_inline` Highlight inside a `<code>` (inline HTML element) tag. Valid values are `true` or `false`. The `code` tag will get a class with name `code-inline`. {{< new-in 0.101.0 >}}
|
||||
|
||||
### Example: highlight shortcode
|
||||
|
||||
```go-html-template
|
||||
{{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}}
|
||||
// ... code
|
||||
{{</* / highlight */>}}
|
||||
```
|
||||
|
||||
Gives this:
|
||||
|
||||
{{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}}
|
||||
// GetTitleFunc returns a func that can be used to transform a string to
|
||||
// title case.
|
||||
//
|
||||
// The supported styles are
|
||||
//
|
||||
// - "Go" (strings.Title)
|
||||
// - "AP" (see https://www.apstylebook.com/)
|
||||
// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
|
||||
//
|
||||
// If an unknown or empty style is provided, AP style is what you get.
|
||||
func GetTitleFunc(style string) func(s string) string {
|
||||
switch strings.ToLower(style) {
|
||||
case "go":
|
||||
return strings.Title
|
||||
case "chicago":
|
||||
return transform.NewTitleConverter(transform.ChicagoStyle)
|
||||
default:
|
||||
return transform.NewTitleConverter(transform.APStyle)
|
||||
}
|
||||
}
|
||||
{{< / highlight >}}
|
||||
|
||||
## Highlight Hugo/Go template code
|
||||
|
||||
For highlighting Hugo/Go template code on your page, add `/*` after the opening double curly braces and `*/` before closing curly braces.
|
||||
|
||||
``` go
|
||||
{{</*/* myshortcode */*/>}}
|
||||
```
|
||||
|
||||
Gives this:
|
||||
|
||||
``` go
|
||||
{{</* myshortcode */>}}
|
||||
```
|
||||
|
||||
## Highlight template function
|
||||
|
||||
See [Highlight](/functions/transform/highlight/).
|
||||
|
||||
## Highlighting in code fences
|
||||
|
||||
Highlighting in code fences is enabled by default.
|
||||
|
||||
````txt
|
||||
```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
|
||||
// ... code
|
||||
```
|
||||
````
|
||||
|
||||
Gives this:
|
||||
|
||||
```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
|
||||
// GetTitleFunc returns a func that can be used to transform a string to
|
||||
// title case.
|
||||
//
|
||||
// The supported styles are
|
||||
//
|
||||
// - "Go" (strings.Title)
|
||||
// - "AP" (see https://www.apstylebook.com/)
|
||||
// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
|
||||
//
|
||||
// If an unknown or empty style is provided, AP style is what you get.
|
||||
func GetTitleFunc(style string) func(s string) string {
|
||||
switch strings.ToLower(style) {
|
||||
case "go":
|
||||
return strings.Title
|
||||
case "chicago":
|
||||
return transform.NewTitleConverter(transform.ChicagoStyle)
|
||||
default:
|
||||
return transform.NewTitleConverter(transform.APStyle)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The options are the same as in the [highlighting shortcode](/content-management/syntax-highlighting/#highlight-shortcode), including `linenos=false`, but note the slightly different Markdown attribute syntax.
|
||||
|
||||
## List of Chroma highlighting languages
|
||||
|
||||
The full list of Chroma lexers and their aliases (which is the identifier used in the `highlight` template func or when doing highlighting in code fences):
|
||||
|
||||
{{< chroma-lexers >}}
|
||||
@@ -1,188 +0,0 @@
|
||||
---
|
||||
title: Taxonomies
|
||||
description: Hugo includes support for user-defined taxonomies.
|
||||
categories: [content management]
|
||||
keywords: [taxonomies,metadata,front matter,terms]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 150
|
||||
weight: 150
|
||||
toc: true
|
||||
aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes]
|
||||
---
|
||||
|
||||
## What is a taxonomy?
|
||||
|
||||
Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications of logical relationships between content.
|
||||
|
||||
### Definitions
|
||||
|
||||
Taxonomy
|
||||
: a categorization that can be used to classify content
|
||||
|
||||
Term
|
||||
: a key within the taxonomy
|
||||
|
||||
Value
|
||||
: a piece of content assigned to a term
|
||||
|
||||
## Example taxonomy: movie website
|
||||
|
||||
Let's assume you are making a website about movies. You may want to include the following taxonomies:
|
||||
|
||||
* Actors
|
||||
* Directors
|
||||
* Studios
|
||||
* Genre
|
||||
* Year
|
||||
* Awards
|
||||
|
||||
Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
|
||||
|
||||
### Movie taxonomy organization
|
||||
|
||||
To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:
|
||||
|
||||
```txt
|
||||
Actor <- Taxonomy
|
||||
Bruce Willis <- Term
|
||||
The Sixth Sense <- Value
|
||||
Unbreakable <- Value
|
||||
Moonrise Kingdom <- Value
|
||||
Samuel L. Jackson <- Term
|
||||
Unbreakable <- Value
|
||||
The Avengers <- Value
|
||||
xXx <- Value
|
||||
```
|
||||
|
||||
From the perspective of the content, the relationships would appear differently, although the data and labels used are the same:
|
||||
|
||||
```txt
|
||||
Unbreakable <- Value
|
||||
Actors <- Taxonomy
|
||||
Bruce Willis <- Term
|
||||
Samuel L. Jackson <- Term
|
||||
Director <- Taxonomy
|
||||
M. Night Shyamalan <- Term
|
||||
...
|
||||
Moonrise Kingdom <- Value
|
||||
Actors <- Taxonomy
|
||||
Bruce Willis <- Term
|
||||
Bill Murray <- Term
|
||||
Director <- Taxonomy
|
||||
Wes Anderson <- Term
|
||||
...
|
||||
```
|
||||
|
||||
## Default taxonomies
|
||||
|
||||
Hugo natively supports taxonomies.
|
||||
|
||||
Without adding a single line to your [site configuration] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be the same as manually [configuring your taxonomies](#configure-taxonomies) as below:
|
||||
|
||||
{{< code-toggle config=taxonomies />}}
|
||||
|
||||
If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site configuration] to the following:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
disableKinds = ["taxonomy","term"]
|
||||
{{</ code-toggle >}}
|
||||
|
||||
{{% include "content-management/_common/page-kinds.md" %}}
|
||||
|
||||
### Default destinations
|
||||
|
||||
When taxonomies are used---and [taxonomy templates] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
|
||||
|
||||
* A single page at `example.com/categories/` that lists all the [terms within the taxonomy]
|
||||
* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter]
|
||||
|
||||
## Configure taxonomies
|
||||
|
||||
Custom taxonomies other than the [defaults](#default-taxonomies) must be defined in your [site configuration] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
|
||||
|
||||
### Example: adding a custom taxonomy named "series"
|
||||
|
||||
{{% note %}}
|
||||
While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_.
|
||||
{{% /note %}}
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[taxonomies]
|
||||
tag = "tags"
|
||||
category = "categories"
|
||||
series = "series"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
### Example: removing default taxonomies
|
||||
|
||||
If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so by modifying the `taxonomies` value in your [site configuration].
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[taxonomies]
|
||||
tag = "tags"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies).
|
||||
|
||||
{{% note %}}
|
||||
You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
|
||||
{{% /note %}}
|
||||
|
||||
## Add taxonomies to content
|
||||
|
||||
Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type] or [content section].
|
||||
|
||||
Assigning content to a taxonomy is done in the [front matter]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type.
|
||||
|
||||
{{% note %}}
|
||||
If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
|
||||
{{% /note %}}
|
||||
|
||||
### Example: front matter with taxonomies
|
||||
|
||||
{{< code-toggle file=content/example.md fm=true >}}
|
||||
title = "Hugo: A fast and flexible static site generator"
|
||||
tags = [ "Development", "Go", "fast", "Blogging" ]
|
||||
categories = [ "Development" ]
|
||||
series = [ "Go Web Dev" ]
|
||||
slug = "hugo"
|
||||
project_url = "https://github.com/gohugoio/hugo"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
## Order taxonomies
|
||||
|
||||
A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy list templates] and is declared in a content file's [front matter]. The convention for declaring taxonomic weight is `taxonomyname_weight`.
|
||||
|
||||
The following show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page.
|
||||
|
||||
### Example: taxonomic `weight`
|
||||
|
||||
{{< code-toggle >}}
|
||||
title = "foo"
|
||||
tags = [ "a", "b", "c" ]
|
||||
tags_weight = 22
|
||||
categories = ["d"]
|
||||
categories_weight = 44
|
||||
{{</ code-toggle >}}
|
||||
|
||||
By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies.
|
||||
|
||||
## Add custom metadata to a taxonomy or term
|
||||
|
||||
If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter. Continuing with our 'Actors' example, let's say you want to add a Wikipedia page link to each actor. Your terms pages would be something like this:
|
||||
|
||||
{{< code-toggle file=content/actors/bruce-willis/_index.md fm=true >}}
|
||||
title: "Bruce Willis"
|
||||
wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[content section]: /content-management/sections/
|
||||
[content type]: /content-management/types/
|
||||
[documentation on archetypes]: /content-management/archetypes/
|
||||
[front matter]: /content-management/front-matter/
|
||||
[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-list-templates
|
||||
[taxonomy templates]: /templates/taxonomy-templates/
|
||||
[terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates
|
||||
[site configuration]: /getting-started/configuration/
|
||||
@@ -1,117 +0,0 @@
|
||||
---
|
||||
title: Table of contents
|
||||
description: Hugo can automatically parse Markdown content and create a Table of Contents you can use in your templates.
|
||||
categories: [content management]
|
||||
keywords: [table of contents, toc]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 210
|
||||
weight: 210
|
||||
toc: true
|
||||
aliases: [/extras/toc/]
|
||||
---
|
||||
|
||||
{{% note %}}
|
||||
|
||||
Previously, there was no out-of-the-box way to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `<nav id="TableOfContents"><ul></ul></nav>` was going to start at `<h1>` when pulling from `{{ .Content }}`.
|
||||
|
||||
Hugo [v0.60.0](https://github.com/gohugoio/hugo/releases/tag/v0.60.0) made a switch to [Goldmark](https://github.com/yuin/goldmark/) as the default library for Markdown which has improved and configurable implementation of TOC. Take a look at [how to configure TOC](/getting-started/configuration-markup/#table-of-contents) for Goldmark renderer.
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
## Usage
|
||||
|
||||
Create your Markdown the way you normally would with the appropriate headings. Here is some example content:
|
||||
|
||||
```md
|
||||
<!-- Your front matter up here -->
|
||||
|
||||
## Introduction
|
||||
|
||||
One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
|
||||
|
||||
## My Heading
|
||||
|
||||
He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
|
||||
|
||||
### My Subheading
|
||||
|
||||
A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
|
||||
```
|
||||
|
||||
Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`.
|
||||
|
||||
The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with appropriate HTML headings. See [the available settings](/getting-started/configuration-markup/#table-of-contents) to configure what heading levels you want to include in TOC.
|
||||
|
||||
## Template example: basic TOC
|
||||
|
||||
The following is an example of a very basic [single page template]:
|
||||
|
||||
{{< code file=layout/_default/single.html >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
<article>
|
||||
<header>
|
||||
<h1>{{ .Title }}</h1>
|
||||
</header>
|
||||
{{ .Content }}
|
||||
</article>
|
||||
<aside>
|
||||
{{ .TableOfContents }}
|
||||
</aside>
|
||||
</main>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
## Template example: TOC partial
|
||||
|
||||
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals] in your templating:
|
||||
|
||||
{{< code file=layouts/partials/toc.html >}}
|
||||
{{ if and (gt .WordCount 400 ) (.Params.toc) }}
|
||||
<aside>
|
||||
<header>
|
||||
<h2>{{ .Title }}</h2>
|
||||
</header>
|
||||
{{ .TableOfContents }}
|
||||
</aside>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{ .TableOfContents }}` variable to pull from.
|
||||
{{% /note %}}
|
||||
|
||||
## Usage with AsciiDoc
|
||||
|
||||
Hugo supports table of contents with AsciiDoc content format.
|
||||
|
||||
In the header of your content file, specify the AsciiDoc TOC directives necessary to ensure that the table of contents is generated. Hugo will use the generated TOC to populate the page variable `.TableOfContents` in the same way as described for Markdown. See example below:
|
||||
|
||||
```asciidoc
|
||||
// <!-- Your front matter up here -->
|
||||
:toc:
|
||||
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] configuration key
|
||||
:toclevels: 4
|
||||
|
||||
== Introduction
|
||||
|
||||
One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
|
||||
|
||||
== My Heading
|
||||
|
||||
He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
|
||||
|
||||
=== My Subheading
|
||||
|
||||
A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
|
||||
```
|
||||
|
||||
Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown.
|
||||
|
||||
[conditionals]: /templates/introduction/#conditionals
|
||||
[front matter]: /content-management/front-matter/
|
||||
[pagevars]: /variables/page/
|
||||
[partials]: /templates/partials/
|
||||
[single page template]: /templates/single-page-templates/
|
||||
@@ -1,20 +0,0 @@
|
||||
---
|
||||
title: Content types
|
||||
description: Hugo is built around content organized in sections.
|
||||
categories: [content management]
|
||||
keywords: [lists,sections,content types,types,organization]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 130
|
||||
weight: 130
|
||||
toc: true
|
||||
aliases: [/content/types]
|
||||
---
|
||||
|
||||
A **content type** is a way to organize your content. Hugo resolves the content type from either the `type` in front matter or, if not set, the first directory in the file path. E.g. `content/blog/my-first-event.md` will be of type `blog` if no `type` is set.
|
||||
|
||||
A content type is used to
|
||||
|
||||
- Determine how the content is rendered. See [Template Lookup Order](/templates/lookup-order/) and [Content Views](/templates/views) for more.
|
||||
- Determine which [archetype](/content-management/archetypes/) template to use for new content.
|
||||
@@ -1,432 +0,0 @@
|
||||
---
|
||||
title: URL management
|
||||
description: Control the structure and appearance of URLs through front matter entries and settings in your site configuration.
|
||||
categories: [content management]
|
||||
keywords: [aliases,redirects,permalinks,urls]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 180
|
||||
weight: 180
|
||||
toc: true
|
||||
aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
By default, when Hugo renders a page, the resulting URL matches the file path within the `content` directory. For example:
|
||||
|
||||
```text
|
||||
content/posts/post-1.md → https://example.org/posts/post-1/
|
||||
```
|
||||
|
||||
You can change the structure and appearance of URLs with front matter values and site configuration options.
|
||||
|
||||
## Front matter
|
||||
|
||||
### `slug`
|
||||
|
||||
Set the `slug` in front matter to override the last segment of the path. The `slug` value does not affect section pages.
|
||||
|
||||
{{< code-toggle file=content/posts/post-1.md fm=true >}}
|
||||
title = 'My First Post'
|
||||
slug = 'my-first-post'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The resulting URL will be:
|
||||
|
||||
```text
|
||||
https://example.org/posts/my-first-post/
|
||||
```
|
||||
|
||||
### `url`
|
||||
|
||||
Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages.
|
||||
|
||||
With this front matter:
|
||||
|
||||
{{< code-toggle file=content/posts/post-1.md fm=true >}}
|
||||
title = 'My First Article'
|
||||
url = '/articles/my-first-article'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The resulting URL will be:
|
||||
|
||||
```text
|
||||
https://example.org/articles/my-first-article/
|
||||
```
|
||||
|
||||
If you include a file extension:
|
||||
|
||||
{{< code-toggle file=content/posts/post-1.md fm=true >}}
|
||||
title = 'My First Article'
|
||||
url = '/articles/my-first-article.html'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The resulting URL will be:
|
||||
|
||||
```text
|
||||
https://example.org/articles/my-first-article.html
|
||||
```
|
||||
|
||||
In a monolingual site, a `url` value with or without a leading slash is relative to the `baseURL`.
|
||||
|
||||
In a multilingual site:
|
||||
|
||||
- A `url` value with a leading slash is relative to the `baseURL`.
|
||||
- A `url` value without a leading slash is relative to the `baseURL` plus the language prefix.
|
||||
|
||||
Site type|Front matter `url`|Resulting URL
|
||||
:--|:--|:--
|
||||
monolingual|`/about`|`https://example.org/about/`
|
||||
monolingual|`about`|`https://example.org/about/`
|
||||
multilingual|`/about`|`https://example.org/about/`
|
||||
multilingual|`about`|`https://example.org/de/about/`
|
||||
|
||||
If you set both `slug` and `url` in front matter, the `url` value takes precedence.
|
||||
|
||||
## Site configuration
|
||||
|
||||
### Permalinks
|
||||
|
||||
In your site configuration, define a URL pattern for each top-level section. Each URL pattern can target a given language and/or [page kind].
|
||||
|
||||
Front matter `url` values override the URL patterns defined in the `permalinks` section of your site configuration.
|
||||
|
||||
[page kind]: /templates/section-templates/#page-kinds
|
||||
|
||||
#### Monolingual examples {#permalinks-monolingual-examples}
|
||||
|
||||
With this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── posts/
|
||||
│ ├── bash-in-slow-motion.md
|
||||
│ └── tls-in-a-nutshell.md
|
||||
├── tutorials/
|
||||
│ ├── git-for-beginners.md
|
||||
│ └── javascript-bundling-with-hugo.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
Render tutorials under "training", and render the posts under "articles" with a date-base hierarchy:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[permalinks.page]
|
||||
posts = '/articles/:year/:month/:slug/'
|
||||
tutorials = '/training/:slug/'
|
||||
[permalinks.section]
|
||||
posts = '/articles/'
|
||||
tutorials = '/training/'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The structure of the published site will be:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── articles/
|
||||
│ ├── 2023/
|
||||
│ │ ├── 04/
|
||||
│ │ │ └── bash-in-slow-motion/
|
||||
│ │ │ └── index.html
|
||||
│ │ └── 06/
|
||||
│ │ └── tls-in-a-nutshell/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
├── training/
|
||||
│ ├── git-for-beginners/
|
||||
│ │ └── index.html
|
||||
│ ├── javascript-bundling-with-hugo/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
To create a date-based hierarchy for regular pages in the content root:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[permalinks.page]
|
||||
"/" = "/:year/:month/:slug/"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Use the same approach with taxonomy terms. For example, to omit the taxonomy segment of the URL:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[permalinks.term]
|
||||
'tags' = '/:slug/'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Multilingual example {#permalinks-multilingual-example}
|
||||
|
||||
Use the `permalinks` configuration as a component of your localization strategy.
|
||||
|
||||
With this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── en/
|
||||
│ ├── books/
|
||||
│ │ ├── les-miserables.md
|
||||
│ │ └── the-hunchback-of-notre-dame.md
|
||||
│ └── _index.md
|
||||
└── es/
|
||||
├── books/
|
||||
│ ├── les-miserables.md
|
||||
│ └── the-hunchback-of-notre-dame.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
And this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
defaultContentLanguage = 'en'
|
||||
defaultContentLanguageInSubdir = true
|
||||
|
||||
[languages.en]
|
||||
contentDir = 'content/en'
|
||||
languageCode = 'en-US'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'English'
|
||||
weight = 1
|
||||
|
||||
[languages.en.permalinks.page]
|
||||
books = "/books/:slug/"
|
||||
|
||||
[languages.en.permalinks.section]
|
||||
books = "/books/"
|
||||
|
||||
[languages.es]
|
||||
contentDir = 'content/es'
|
||||
languageCode = 'es-ES'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'Español'
|
||||
weight = 2
|
||||
|
||||
[languages.es.permalinks.page]
|
||||
books = "/libros/:slug/"
|
||||
|
||||
[languages.es.permalinks.section]
|
||||
books = "/libros/"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The structure of the published site will be:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── en/
|
||||
│ ├── books/
|
||||
│ │ ├── les-miserables/
|
||||
│ │ │ └── index.html
|
||||
│ │ ├── the-hunchback-of-notre-dame/
|
||||
│ │ │ └── index.html
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
├── es/
|
||||
│ ├── libros/
|
||||
│ │ ├── les-miserables/
|
||||
│ │ │ └── index.html
|
||||
│ │ ├── the-hunchback-of-notre-dame/
|
||||
│ │ │ └── index.html
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
````
|
||||
|
||||
#### Tokens
|
||||
|
||||
Use these tokens when defining the URL pattern. The `date` field in front matter determines the value of time-related tokens.
|
||||
|
||||
`:year`
|
||||
: the 4-digit year
|
||||
|
||||
`:month`
|
||||
: the 2-digit month
|
||||
|
||||
`:monthname`
|
||||
: the name of the month
|
||||
|
||||
`:day`
|
||||
: the 2-digit day
|
||||
|
||||
`:weekday`
|
||||
: the 1-digit day of the week (Sunday = 0)
|
||||
|
||||
`:weekdayname`
|
||||
: the name of the day of the week
|
||||
|
||||
`:yearday`
|
||||
: the 1- to 3-digit day of the year
|
||||
|
||||
`:section`
|
||||
: the content's section
|
||||
|
||||
`:sections`
|
||||
: the content's sections hierarchy. You can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
|
||||
|
||||
`:title`
|
||||
: the content's title
|
||||
|
||||
`:slug`
|
||||
: the content's slug (or title if no slug is provided in the front matter)
|
||||
|
||||
`:slugorfilename`
|
||||
: the content's slug (or file name if no slug is provided in the front matter)
|
||||
|
||||
`:filename`
|
||||
: the content's file name (without extension)
|
||||
|
||||
For time-related values, you can also use the layout string components defined in Go's [time package]. For example:
|
||||
|
||||
[time package]: https://pkg.go.dev/time#pkg-constants
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
permalinks:
|
||||
posts: /:06/:1/:2/:title/
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Appearance
|
||||
|
||||
The appearance of a URL is either ugly or pretty.
|
||||
|
||||
Type|Path|URL
|
||||
:--|:--|:--
|
||||
ugly|content/about.md|`https://example.org/about.html`
|
||||
pretty|content/about.md|`https://example.org/about/`
|
||||
|
||||
By default, Hugo produces pretty URLs. To generate ugly URLs, change your site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
uglyURLs = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Post-processing
|
||||
|
||||
Hugo provides two mutually exclusive configuration options to alter URLs _after_ it renders a page.
|
||||
|
||||
#### Canonical URLs
|
||||
|
||||
{{% note %}}
|
||||
This is a legacy configuration option, superseded by template functions and markdown render hooks, and will likely be [removed in a future release].
|
||||
|
||||
[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733
|
||||
{{% /note %}}
|
||||
|
||||
If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then prepends the `baseURL` to create absolute URLs.
|
||||
|
||||
```html
|
||||
<a href="/about"> → <a href="https://example.org/about/">
|
||||
<img src="/a.gif"> → <img src="https://example.org/a.gif">
|
||||
```
|
||||
|
||||
This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, this is a legacy configuration option that will likely be removed in a future release.
|
||||
|
||||
To enable:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
canonifyURLs = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Relative URLs
|
||||
|
||||
{{% note %}}
|
||||
Do not enable this option unless you are creating a serverless site, navigable via the file system.
|
||||
{{% /note %}}
|
||||
|
||||
If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then transforms the URL to be relative to the current page.
|
||||
|
||||
For example, when rendering `content/posts/post-1`:
|
||||
|
||||
```html
|
||||
<a href="/about"> → <a href="../../about">
|
||||
<img src="/a.gif"> → <img src="../../a.gif">
|
||||
```
|
||||
|
||||
This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, do not enable this option unless you are creating a serverless site.
|
||||
|
||||
To enable:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
relativeURLs = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Aliases
|
||||
|
||||
Create redirects from old URLs to new URLs with aliases:
|
||||
|
||||
- An alias with a leading slash is relative to the `baseURL`
|
||||
- An alias without a leading slash is relative to the current directory
|
||||
|
||||
### Examples {#alias-examples}
|
||||
|
||||
Change the file name of an existing page, and create an alias from the previous URL to the new URL:
|
||||
|
||||
{{< code-toggle file=content/posts/new-file-name.md >}}
|
||||
aliases = ['/posts/previous-file-name']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Each of these directory-relative aliases is equivalent to the site-relative alias above:
|
||||
|
||||
- `previous-file-name`
|
||||
- `./previous-file-name`
|
||||
- `../posts/previous-file-name`
|
||||
|
||||
You can create more than one alias to the current page:
|
||||
|
||||
{{< code-toggle file=content/posts/new-file-name.md >}}
|
||||
aliases = ['previous-file-name','original-file-name']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias:
|
||||
|
||||
{{< code-toggle file=content/posts/new-file-name.de.md >}}
|
||||
aliases = ['/de/posts/previous-file-name']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### How aliases work
|
||||
|
||||
Using the first example above, Hugo generates the following site structure:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── posts/
|
||||
│ ├── new-file-name/
|
||||
│ │ └── index.html
|
||||
│ ├── previous-file-name/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
The alias from the previous URL to the new URL is a client-side redirect:
|
||||
|
||||
{{< code file=posts/previous-file-name/index.html >}}
|
||||
<!DOCTYPE html>
|
||||
<html lang="en-us">
|
||||
<head>
|
||||
<title>https://example.org/posts/new-file-name/</title>
|
||||
<link rel="canonical" href="https://example.org/posts/new-file-name/">
|
||||
<meta name="robots" content="noindex">
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="refresh" content="0; url=https://example.org/posts/new-file-name/">
|
||||
</head>
|
||||
</html>
|
||||
{{< /code >}}
|
||||
|
||||
Collectively, the elements in the `head` section:
|
||||
|
||||
- Tell search engines that the new URL is canonical
|
||||
- Tell search engines not to index the previous URL
|
||||
- Tell the browser to redirect to the new URL
|
||||
|
||||
Hugo renders alias files before rendering pages. A new page with the previous file name will overwrite the alias, as expected.
|
||||
|
||||
### Customize
|
||||
|
||||
Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context:
|
||||
|
||||
Permalink
|
||||
: the link to the page being aliased
|
||||
|
||||
Page
|
||||
: the Page data for the page being aliased
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
title: Contribute to the Hugo project
|
||||
linkTitle: Overview
|
||||
description: Contribute to Hugo development, documentation, and themes.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: contribute-overview
|
||||
parent: contribute
|
||||
weight: 10
|
||||
weight: 10
|
||||
aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/]
|
||||
---
|
||||
|
||||
Hugo relies heavily on the enthusiasm and participation of the open-source community. We need your support.
|
||||
@@ -1,430 +0,0 @@
|
||||
---
|
||||
title: Development
|
||||
description: Contribute to the development of Hugo.
|
||||
categories: [contribute]
|
||||
keywords: [development]
|
||||
menu:
|
||||
docs:
|
||||
parent: contribute
|
||||
weight: 20
|
||||
weight: 20
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
Hugo is an open-source project and lives by the work of its [contributors]. There are plenty of [open issues][issues], and we need your help to make Hugo even more awesome. You don't need to be a Go guru to contribute to the project's development.
|
||||
|
||||
## Assumptions
|
||||
|
||||
This contribution guide takes a step-by-step approach in hopes of helping newcomers. Therefore, we only assume the following:
|
||||
|
||||
* You are new to Git or open-source projects in general
|
||||
* You are a fan of Hugo and enthusiastic about contributing to the project
|
||||
|
||||
{{% note %}}
|
||||
If you're struggling at any point in this contribution guide, reach out to the Hugo community in [Hugo's Discussion forum](https://discourse.gohugo.io).
|
||||
{{% /note %}}
|
||||
|
||||
## Install Go
|
||||
|
||||
The installation of Go should take only a few minutes. You have more than one option to get Go up and running on your machine.
|
||||
|
||||
If you are having trouble following the installation guides for Go, check out [Go Bootcamp, which contains setups for every platform][gobootcamp] or reach out to the Hugo community in the [Hugo Discussion Forums][forums].
|
||||
|
||||
### Install Go from source
|
||||
|
||||
[Download the latest stable version of Go][godl] and follow the official [Go installation guide][goinstall].
|
||||
|
||||
Once you're finished installing Go, let's confirm everything is working correctly. Open a terminal---or command line under Windows--and type the following:
|
||||
|
||||
```txt
|
||||
go version
|
||||
```
|
||||
|
||||
You should see something similar to the following written to the console. Note that the version here reflects the most recent version of Go as of the last update for this page:
|
||||
|
||||
```txt
|
||||
go version go1.12 darwin/amd64
|
||||
```
|
||||
|
||||
Next, make sure that you set up your `GOPATH` [as described in the installation guide][setupgopath].
|
||||
|
||||
You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace; for example:
|
||||
|
||||
```txt
|
||||
/Users/<yourusername>/Code/go
|
||||
```
|
||||
|
||||
### Install Go with Homebrew
|
||||
|
||||
If you are a macOS user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command:
|
||||
|
||||
{{< code file=install-go.sh >}}
|
||||
brew install go
|
||||
{{< /code >}}
|
||||
|
||||
### Install Go via GVM
|
||||
|
||||
More experienced users can use the [Go Version Manager][gvm] (GVM). GVM allows you to switch between different Go versions *on the same machine*. If you're a beginner, you probably don't need this feature. However, GVM makes it easy to upgrade to a new released Go version with just a few commands.
|
||||
|
||||
GVM comes in especially handy if you follow the development of Hugo over a longer period of time. Future versions of Hugo will usually be compiled with the latest version of Go. Sooner or later, you will have to upgrade if you want to keep up.
|
||||
|
||||
## Create a GitHub account
|
||||
|
||||
If you're going to contribute code, you'll need to have an account on GitHub. Go to [www.github.com/join](https://github.com/join) and set up a personal account.
|
||||
|
||||
## Install Git on your system
|
||||
|
||||
You will need to have Git installed on your computer to contribute to Hugo development. Teaching Git is outside the scope of the Hugo docs, but if you're looking for an excellent reference to learn the basics of Git, we recommend the [Git book][gitbook] if you are not sure where to begin. We will include short explanations of the Git commands in this document.
|
||||
|
||||
Git is a [version control system](https://en.wikipedia.org/wiki/Version_control) to track the changes of source code. Hugo depends on smaller third-party packages that are used to extend the functionality. We use them because we don't want to reinvent the wheel.
|
||||
|
||||
Go ships with a sub-command called `get` that will download these packages for us when we set up our working environment. The source code of the packages is tracked with Git. `get` will interact with the Git servers of the package hosters in order to fetch all dependencies.
|
||||
|
||||
Move back to the terminal and check if Git is already installed. Type in `git version` and press enter. You can skip the rest of this section if the command returned a version number. Otherwise [download](https://git-scm.com/downloads) the latest version of Git and follow this [installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
|
||||
|
||||
Finally, check again with `git version` if Git was installed successfully.
|
||||
|
||||
### Git graphical front ends
|
||||
|
||||
There are several [GUI clients](https://git-scm.com/downloads/guis) that help you to operate Git. Not all are available for all operating systems and maybe differ in their usage. Because of this we will document how to use the command-line, since the commands are the same everywhere.
|
||||
|
||||
### Install Hub on your system (optional)
|
||||
|
||||
Hub is a great tool for working with GitHub. The main site for it is [hub.github.com](https://hub.github.com/). Feel free to install this little Git wrapper.
|
||||
|
||||
On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew](https://brew.sh):
|
||||
|
||||
```txt
|
||||
brew install hub
|
||||
```
|
||||
|
||||
Now we'll create an [alias in Bash](https://tldp.org/LDP/abs/html/aliases.html) so that typing `git` actually runs `Hub`:
|
||||
|
||||
```txt
|
||||
echo "alias git='hub'" >> ~/.bash_profile
|
||||
```
|
||||
|
||||
Confirm the installation:
|
||||
|
||||
```txt
|
||||
git version 2.21.0
|
||||
hub version 2.10.0
|
||||
```
|
||||
|
||||
## Set up your working copy
|
||||
|
||||
You set up the working copy of the repository locally on your computer. Your local copy of the files is what you'll edit, compile, and end up pushing back to GitHub. The main steps are cloning the repository and creating your fork as a remote.
|
||||
|
||||
### Clone the repository
|
||||
|
||||
We assume that you've set up your `GOPATH` (see the section above if you're unsure about this). You should now copy the Hugo repository down to your computer. You'll hear this called "clone the repo". GitHub's [help pages](https://help.github.com/articles/cloning-a-repository/) give us a short explanation:
|
||||
|
||||
{{% note %}}
|
||||
When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations.
|
||||
{{% /note %}}
|
||||
|
||||
We're going to clone the [master Hugo repository](https://github.com/gohugoio/hugo). That seems counter-intuitive, since you won't have commit rights on it. But it's required for the Go workflow. You'll work on a copy of the master and push your changes to your own repository on GitHub.
|
||||
|
||||
So, let's make a new directory and clone that master repository:
|
||||
|
||||
```txt
|
||||
mkdir $HOME/src
|
||||
cd $HOME/src
|
||||
git clone https://github.com/gohugoio/hugo.git
|
||||
```
|
||||
|
||||
Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. The easiest is to clone Hugo in a directory outside of GOPATH
|
||||
|
||||
And then, install dependencies of Hugo by running the following in the cloned directory:
|
||||
|
||||
```txt
|
||||
cd $HOME/src/hugo
|
||||
go install
|
||||
```
|
||||
|
||||
Hugo relies on [mage](https://github.com/magefile/mage) for some convenient build and test targets. If you don't already have it, get it:
|
||||
|
||||
```txt
|
||||
go install github.com/magefile/mage@latest
|
||||
```
|
||||
|
||||
### Fork the repository
|
||||
|
||||
If you're not familiar with this term, GitHub's [help pages](https://help.github.com/articles/fork-a-repo/) provide again a simple explanation:
|
||||
|
||||
{{% note %}}
|
||||
A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
|
||||
{{% /note %}}
|
||||
|
||||
#### Fork by hand
|
||||
|
||||
Open the [Hugo repository](https://github.com/gohugoio/hugo) on GitHub and click on the "Fork" button in the top right.
|
||||
|
||||
|
||||
|
||||
Now open your fork repository on GitHub and copy the remote URL of your fork. You can choose between HTTPS and SSH as protocol that Git should use for the following operations. HTTPS works always [if you're not sure](https://help.github.com/articles/which-remote-url-should-i-use/).
|
||||
|
||||
|
||||
|
||||
Switch back to the terminal and move into the directory of the cloned master repository from the last step.
|
||||
|
||||
```txt
|
||||
cd $HOME/src/hugo
|
||||
```
|
||||
|
||||
Now Git needs to know that our fork exists by adding the copied remote url:
|
||||
|
||||
```txt
|
||||
git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>
|
||||
```
|
||||
|
||||
#### Fork with Hub
|
||||
|
||||
Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy:
|
||||
|
||||
```txt
|
||||
git fork
|
||||
```
|
||||
|
||||
That command will log in to GitHub using your account, create a fork of the repository that you're currently working in, and add it as a remote to your working copy.
|
||||
|
||||
#### Trust, but verify
|
||||
|
||||
Let's check if everything went right by listing all known remotes:
|
||||
|
||||
```txt
|
||||
git remote -v
|
||||
```
|
||||
|
||||
The output should look similar:
|
||||
|
||||
```txt
|
||||
digitalcraftsman git@github.com:digitalcraftsman/hugo.git (fetch)
|
||||
digitalcraftsman git@github.com:digitalcraftsman/hugo.git (push)
|
||||
origin https://github.com/gohugoio/hugo (fetch)
|
||||
origin https://github.com/gohugoio/hugo (push)
|
||||
```
|
||||
|
||||
## The Hugo Git contribution workflow
|
||||
|
||||
### Create a new branch
|
||||
|
||||
You should never develop against the "master" branch. The development team will not accept a pull request against that branch. Instead, create a descriptive named branch and work on it.
|
||||
|
||||
First, you should always pull the latest changes from the master repository:
|
||||
|
||||
```txt
|
||||
git checkout master
|
||||
git pull
|
||||
```
|
||||
|
||||
Now we can create a new branch for your additions:
|
||||
|
||||
```txt
|
||||
git checkout -b <BRANCH-NAME>
|
||||
```
|
||||
|
||||
You can check on which branch you are with `git branch`. You should see a list of all local branches. The current branch is indicated with a little asterisk.
|
||||
|
||||
### Contribute to documentation
|
||||
|
||||
Perhaps you want to start contributing to the Hugo docs. If so, you can ignore most of the following steps and focus on the `/docs` directory within your newly cloned repository. You can change directories into the Hugo docs using `cd docs`.
|
||||
|
||||
You can start Hugo's built-in server via `hugo server`. Browse the documentation by entering [http://localhost:1313](http://localhost:1313) in the address bar of your browser. The server automatically updates the page whenever you change content.
|
||||
|
||||
We have developed a [separate Hugo documentation contribution guide][docscontrib] for more information on how the Hugo docs are built, organized, and improved by the generosity of people like you.
|
||||
|
||||
### Build Hugo
|
||||
|
||||
While making changes in the codebase it's a good idea to build the binary to test them:
|
||||
|
||||
```txt
|
||||
mage hugo
|
||||
```
|
||||
|
||||
This command generates the binary file at the root of the repository.
|
||||
|
||||
If you want to install the binary in `$GOPATH/bin`, run
|
||||
|
||||
```txt
|
||||
mage install
|
||||
```
|
||||
|
||||
### Test
|
||||
|
||||
Sometimes changes on the codebase can cause unintended side effects. Or they don't work as expected. Most functions have their own test cases. You can find them in files ending with `_test.go`.
|
||||
|
||||
Make sure the commands
|
||||
|
||||
```txt
|
||||
mage -v check
|
||||
```
|
||||
|
||||
passes.
|
||||
|
||||
### Formatting
|
||||
|
||||
The Go code style guide maybe is opinionated but it ensures that the codebase looks the same, regardless who wrote the code. Go comes with its own formatting tool. Let's apply the style guide to our additions:
|
||||
|
||||
```txt
|
||||
mage fmt
|
||||
```
|
||||
|
||||
Once you made your additions commit your changes. Make sure that you follow our [code contribution guidelines](https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md):
|
||||
|
||||
```txt
|
||||
# Add all changed files
|
||||
git add --all
|
||||
git commit --message "YOUR COMMIT MESSAGE"
|
||||
```
|
||||
|
||||
The commit message should describe what the commit does (e.g. add feature XYZ), not how it is done.
|
||||
|
||||
### Modify commits
|
||||
|
||||
You noticed some commit messages don't fulfill the code contribution guidelines or you just forget something to add some files? No problem. Git provides the necessary tools to fix such problems. The next two methods cover all common cases.
|
||||
|
||||
If you are unsure what a command does leave the commit as it is. We can fix your commits later in the pull request.
|
||||
|
||||
#### Modify the last commit
|
||||
|
||||
Let's say you want to modify the last commit message. Run the following command and replace the current message:
|
||||
|
||||
```txt
|
||||
git commit --amend -m"YOUR NEW COMMIT MESSAGE"
|
||||
```
|
||||
|
||||
Take a look at the commit log to see the change:
|
||||
|
||||
```txt
|
||||
git log
|
||||
# Exit with q
|
||||
```
|
||||
|
||||
After making the last commit you may have forgotten something. There is no need to create a new commit. Just add the latest changes and merge them into the intended commit:
|
||||
|
||||
```txt
|
||||
git add --all
|
||||
git commit --amend
|
||||
```
|
||||
|
||||
#### Modify multiple commits
|
||||
|
||||
{{% note %}}
|
||||
Modifications such as those described in this section can have serious unintended consequences. Skip this section if you're not sure!
|
||||
{{% /note %}}
|
||||
|
||||
This is a bit more advanced. Git allows you to [rebase](https://git-scm.com/docs/git-rebase) commits interactively. In other words: it allows you to rewrite the commit history.
|
||||
|
||||
```txt
|
||||
git rebase --interactive @~6
|
||||
```
|
||||
|
||||
The `6` at the end of the command represents the number of commits that should be modified. An editor should open and present a list of last six commit messages:
|
||||
|
||||
```txt
|
||||
pick 80d02a1 tpl: Add hasPrefix to template function smoke test"
|
||||
pick aaee038 tpl: Sort the smoke tests
|
||||
pick f0dbf2c tpl: Add the other test case for hasPrefix
|
||||
pick 911c35b Add "How to contribute to Hugo" tutorial
|
||||
pick 33c8973 Begin workflow
|
||||
pick 3502f2e Refactoring and typo fixes
|
||||
```
|
||||
|
||||
In the case above we should merge the last two commits in the commit of this tutorial (`Add "How to contribute to Hugo" tutorial`). You can "squash" commits, i.e. merge two or more commits into a single one.
|
||||
|
||||
All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short:
|
||||
|
||||
```txt
|
||||
pick 80d02a1 tpl: Add hasPrefix to template function smoke test"
|
||||
pick aaee038 tpl: Sort the smoke tests
|
||||
pick f0dbf2c tpl: Add the other test case for hasPrefix
|
||||
pick 911c35b Add "How to contribute to Hugo" tutorial
|
||||
squash 33c8973 Begin workflow
|
||||
squash 3502f2e Refactoring and typo fixes
|
||||
```
|
||||
|
||||
We also want to rewrite the commits message of the third last commit. We forgot "docs:" as prefix according to the code contribution guidelines. The operation to rewrite a commit is called `reword` (or `r` as shortcut).
|
||||
|
||||
You should end up with a similar setup:
|
||||
|
||||
```txt
|
||||
pick 80d02a1 tpl: Add hasPrefix to template function smoke test"
|
||||
pick aaee038 tpl: Sort the smoke tests
|
||||
pick f0dbf2c tpl: Add the other test case for hasPrefix
|
||||
reword 911c35b Add "How to contribute to Hugo" tutorial
|
||||
squash 33c8973 Begin workflow
|
||||
squash 3502f2e Refactoring and typo fixes
|
||||
```
|
||||
|
||||
Close the editor. It should open again with a new tab. A text is instructing you to define a new commit message for the last two commits that should be merged (aka "squashed"). Save the file with <kbd>CTRL</kbd>+<kbd>S</kbd> and close the editor again.
|
||||
|
||||
A last time a new tab opens. Enter a new commit message and save again. Your terminal should contain a status message. Hopefully this one:
|
||||
|
||||
```txt
|
||||
Successfully rebased and updated refs/heads/<BRANCHNAME>.
|
||||
```
|
||||
|
||||
Check the commit log if everything looks as expected. Should an error occur you can abort this rebase with `git rebase --abort`.
|
||||
|
||||
### Push commits
|
||||
|
||||
To push our commits to the fork on GitHub we need to specify a destination. A destination is defined by the remote and a branch name. Earlier, the defined that the remote URL of our fork is the same as our GitHub handle, in my case `digitalcraftsman`. The branch should have the same as our local one. This makes it easy to identify corresponding branches.
|
||||
|
||||
```txt
|
||||
git push --set-upstream <YOUR-GITHUB-USERNAME> <BRANCHNAME>
|
||||
```
|
||||
|
||||
Now Git knows the destination. Next time when you to push commits you just need to enter `git push`.
|
||||
|
||||
If you modified your commit history in the last step GitHub will reject your try to push. This is a safety-feature because the commit history isn't the same and new commits can't be appended as usual. You can enforce this push explicitly with `git push --force`.
|
||||
|
||||
## Open a pull request
|
||||
|
||||
We made a lot of progress. Good work. In this step we finally open a pull request to submit our additions. Open the [Hugo master repository](https://github.com/gohugoio/hugo/) on GitHub in your browser.
|
||||
|
||||
You should find a green button labeled with "New pull request". But GitHub is clever and probably suggests you a pull request like in the beige box below:
|
||||
|
||||
|
||||
|
||||
The new page summaries the most important information of your pull request. Scroll down and you find the additions of all your commits. Make sure everything looks as expected and click on "Create pull request".
|
||||
|
||||
### Accept the contributor license agreement
|
||||
|
||||
Last but not least you should accept the contributor license agreement (CLA). A new comment should be added automatically to your pull request. Click on the yellow badge, accept the agreement and authenticate yourself with your GitHub account. It just takes a few clicks and only needs to be done once.
|
||||
|
||||
|
||||
|
||||
### Automatic builds
|
||||
|
||||
We use a GitHub Actions workflow to build and test. This is a matrix build across combinations of operating system (macOS, Windows, and Ubuntu) and Go versions. The workflow is triggered by the submission of a pull request. If you are a first-time contributor, the workflow requires approval from a project maintainer.
|
||||
|
||||
## Where to start?
|
||||
|
||||
Thank you for reading through this contribution guide. Hopefully, we will see you again soon on GitHub. There are plenty of [open issues][issues] for you to help with.
|
||||
|
||||
Feel free to [open an issue][newissue] if you think you found a bug or you have a new idea to improve Hugo. We are happy to hear from you.
|
||||
|
||||
## Additional references for learning Git and Go
|
||||
|
||||
* [Codecademy's Free "Learn Git" Course][codecademy] (Free)
|
||||
* [Code School and GitHub's "Try Git" Tutorial][trygit] (Free)
|
||||
* [The Git Book][gitbook] (Free)
|
||||
* [Go Bootcamp][gobootcamp]
|
||||
|
||||
[codecademy]: https://www.codecademy.com/learn/learn-git
|
||||
[contributors]: https://github.com/gohugoio/hugo/graphs/contributors
|
||||
[docscontrib]: /contribute/documentation/
|
||||
[forums]: https://discourse.gohugo.io
|
||||
[gitbook]: https://git-scm.com/
|
||||
[gobootcamp]: https://www.golang-book.com/guides/machine_setup
|
||||
[godl]: https://go.dev/dl/
|
||||
[goinstall]: https://go.dev/doc/install
|
||||
[gvm]: https://github.com/moovweb/gvm
|
||||
[issues]: https://github.com/gohugoio/hugo/issues
|
||||
[newissue]: https://github.com/gohugoio/hugo/issues/new
|
||||
[releases]: /getting-started/
|
||||
[setupgopath]: https://go.dev/doc/code#Workspaces
|
||||
[trygit]: https://try.github.io/levels/1/challenges/1
|
||||
@@ -1,371 +0,0 @@
|
||||
---
|
||||
title: Documentation
|
||||
description: Help us to improve the documentation by identifying issues and suggesting changes.
|
||||
categories: [contribute]
|
||||
keywords: [documentation]
|
||||
menu:
|
||||
docs:
|
||||
parent: contribute
|
||||
weight: 30
|
||||
weight: 30
|
||||
toc: true
|
||||
aliases: [/contribute/docs/]
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
We welcome corrections and improvements to the documentation. Please note that the documentation resides in its own repository, separate from the project repository.
|
||||
|
||||
For corrections and improvements to the current documentation, please submit issues and pull requests to the [documentation repository].
|
||||
|
||||
For documentation related to a new feature, please include the documentation changes when you submit a pull request to the [project repository].
|
||||
|
||||
## Guidelines
|
||||
|
||||
### Markdown
|
||||
|
||||
Please follow these markdown guidelines:
|
||||
|
||||
- Use [ATX] headings, not [setext] headings, levels 2 through 4
|
||||
- Use [fenced code blocks], not [indented code blocks]
|
||||
- Use hyphens, not asterisks, with unordered [list items]
|
||||
- Use the [note shortcode] instead of blockquotes
|
||||
- Do not mix [raw HTML] within markdown
|
||||
- Do not use bold text instead of a heading or description term (`dt`)
|
||||
- Remove consecutive blank lines (maximum of two)
|
||||
- Remove trailing spaces
|
||||
|
||||
### Style
|
||||
|
||||
Although we do not strictly adhere to the [Microsoft Writing Style Guide], it is an excellent resource for questions related to style, grammar, and voice.
|
||||
|
||||
#### Terminology
|
||||
|
||||
Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note:
|
||||
|
||||
- The term "front matter" is two words unless you are referring to the configuration key
|
||||
- Use the word "map" instead of "dictionary"
|
||||
- Use the word "flag" instead of "option" when referring to a command line flag
|
||||
|
||||
#### Page titles and headings
|
||||
|
||||
Please follow these guidelines for page titles and headings:
|
||||
|
||||
- Use sentence-style capitalization
|
||||
- Avoid markdown in headings and page titles
|
||||
- Shorter is better
|
||||
|
||||
#### Use active voice with present tense
|
||||
|
||||
In software documentation, passive voice is unavoidable in some cases. Please use active voice when possible.
|
||||
|
||||
No → With Hugo you can build a static site.\
|
||||
Yes → Build a static site with Hugo.
|
||||
|
||||
No → This will cause Hugo to generate HTML files in the public directory.\
|
||||
Yes → Hugo generates HTML files in the public directory.
|
||||
|
||||
#### Use second person instead of third person
|
||||
|
||||
No → Users should exercise caution when deleting files.\
|
||||
Better → You must be cautious when deleting files.\
|
||||
Best → Be cautious when deleting files.
|
||||
|
||||
#### Avoid adverbs when possible
|
||||
|
||||
No → Hugo is extremely fast.\
|
||||
Yes → Hugo is fast.
|
||||
|
||||
{{% note %}}
|
||||
"It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995).
|
||||
{{% /note %}}
|
||||
|
||||
#### Miscellaneous
|
||||
|
||||
Other guidelines to consider:
|
||||
|
||||
- Do not place list items directly under a heading; include an introductory sentence or phrase before the list.
|
||||
- Avoid use of **bold** text. Use the [note shortcode] to draw attention to important content.
|
||||
- Do not place description terms (`dt`) within backticks unless required for syntactic clarity.
|
||||
- Do not use Hugo's `ref` or `relref` shortcodes. We use a link render hook to resolve and validate link destinations, including fragments.
|
||||
- Shorter is better. If there is more than one way to do something, describe the current best practice. For example, avoid phrases such as "you can also do..." and "in older versions you had to..."
|
||||
- When including code samples, use short snippets that demonstrate the concept.
|
||||
- The Hugo user community is global; use [basic english](https://simple.wikipedia.org/wiki/Basic_English) when possible.
|
||||
|
||||
#### Level 6 markdown headings
|
||||
|
||||
Level 6 markdown headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
|
||||
|
||||
[glossary]: /getting-started/glossary
|
||||
|
||||
## Code examples
|
||||
|
||||
Indent code by two spaces. With examples of template code, include a space after opening action delimiters, and include a space before closing action delimiters.
|
||||
|
||||
### Fenced code blocks
|
||||
|
||||
Always include the language code when using a fenced code block:
|
||||
|
||||
````text
|
||||
```go-html-template
|
||||
{{ if eq $foo "bar" }}
|
||||
{{ print "foo is bar" }}
|
||||
{{ end }}
|
||||
```
|
||||
````
|
||||
|
||||
Rendered:
|
||||
|
||||
```go-html-template
|
||||
{{ if eq $foo "bar" }}
|
||||
{{ print "foo is bar" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
### Shortcode calls
|
||||
|
||||
Use this syntax to include shortcodes calls within your code examples:
|
||||
|
||||
```text
|
||||
{{</*/* foo */*/>}}
|
||||
{{%/*/* foo */*/%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
```text
|
||||
{{</* foo */>}}
|
||||
{{%/* foo */%}}
|
||||
```
|
||||
|
||||
### Site configuration
|
||||
|
||||
Use the [code-toggle shortcode] to include site configuration examples:
|
||||
|
||||
```text
|
||||
{{</* code-toggle file=hugo */>}}
|
||||
baseURL = 'https://example.org/'
|
||||
languageCode = 'en-US'
|
||||
title = 'My Site'
|
||||
{{</* /code-toggle */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
baseURL = 'https://example.org/'
|
||||
languageCode = 'en-US'
|
||||
title = 'My Site'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Front matter
|
||||
|
||||
Use the [code-toggle shortcode] to include front matter examples:
|
||||
|
||||
```text
|
||||
{{</* code-toggle file=content/posts/my-first-post.md fm=true */>}}
|
||||
title = 'My first post'
|
||||
date = 2023-11-09T12:56:07-08:00
|
||||
draft = false
|
||||
{{</* /code-toggle */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< code-toggle file=content/posts/my-first-post.md fm=true >}}
|
||||
title = 'My first post'
|
||||
date = 2023-11-09T12:56:07-08:00
|
||||
draft = false
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Other code examples
|
||||
|
||||
Use the [code shortcode] for other code examples that require a file name:
|
||||
|
||||
```text
|
||||
{{</* code file=layouts/_default/single.html */>}}
|
||||
{{ range .Site.RegularPages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{</* /code */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
{{ range .Site.RegularPages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
## Shortcodes
|
||||
|
||||
These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.
|
||||
|
||||
### deprecated-in
|
||||
|
||||
Use the “deprecated-in” shortcode to indicate that a feature is deprecated:
|
||||
|
||||
```text
|
||||
{{%/* deprecated-in 0.120.0 */%}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver
|
||||
{{%/* /deprecated-in */%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{% deprecated-in 0.120.0 %}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver
|
||||
{{% /deprecated-in %}}
|
||||
|
||||
### code
|
||||
|
||||
Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments:
|
||||
|
||||
copy
|
||||
: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
|
||||
|
||||
file
|
||||
: (`string`) The file name to display.
|
||||
|
||||
lang
|
||||
: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is "html", sets the code language to `go-html-template`. Default is `text`.
|
||||
|
||||
### code-toggle
|
||||
|
||||
Use the "code-toggle" shortcode to display examples of site configuration, front matter, or data files. See the [code examples] above. This shortcode takes these arguments:
|
||||
|
||||
copy
|
||||
: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
|
||||
|
||||
file
|
||||
: (`string`) The file name to display. Omit the file extension for site configuration examples.
|
||||
|
||||
fm
|
||||
: (`bool`) Whether the example is front matter. Default is `false`.
|
||||
|
||||
### new-in
|
||||
|
||||
Use the "new-in" shortcode to indicate a new feature:
|
||||
|
||||
```text
|
||||
{{</* new-in 0.120.0 */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< new-in 0.120.0 >}}
|
||||
|
||||
### note
|
||||
|
||||
Use the "note" shortcode with `{{%/* */%}}` delimiters to call attention to important content:
|
||||
|
||||
```text
|
||||
{{%/* note */%}}
|
||||
Use the [`math.Mod`] function to control...
|
||||
|
||||
[`math.Mod`]: /functions/math/mod/
|
||||
{{%/* /note */%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{% note %}}
|
||||
Use the [`math.Mod`] function to control...
|
||||
|
||||
[`math.Mod`]: /functions/math/mod/
|
||||
{{% /note %}}
|
||||
|
||||
## New features
|
||||
|
||||
Use the "new-in" shortcode to indicate a new feature:
|
||||
|
||||
{{< code file=content/something/foo.md lang=text >}}
|
||||
{{</* new-in 0.120.0 */>}}
|
||||
{{< /code >}}
|
||||
|
||||
The "new in" label will be hidden if the specified version is older than a predefined threshold, based on differences in major and minor versions. See [details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/new-in.html).
|
||||
|
||||
## Deprecated features
|
||||
|
||||
Use the "deprecated-in" shortcode to indicate that a feature is deprecated:
|
||||
|
||||
{{< code file=content/something/foo.md >}}
|
||||
{{%/* deprecated-in 0.120.0 */%}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver
|
||||
{{%/* /deprecated-in */%}}
|
||||
{{< /code >}}
|
||||
|
||||
When deprecating a function or method, add this to front matter:
|
||||
|
||||
{{< code-toggle file=content/something/foo.md fm=true >}}
|
||||
expiryDate: 2024-10-30
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Set the `expiryDate` to one year from the date of deprecation, and add a brief front matter comment to explain the setting.
|
||||
|
||||
## GitHub workflow
|
||||
|
||||
{{% note %}}
|
||||
This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line.
|
||||
{{% /note %}}
|
||||
|
||||
Use this workflow to create and submit pull requests.
|
||||
|
||||
Step 1
|
||||
: Fork the [documentation repository].
|
||||
|
||||
Step 2
|
||||
: Clone your fork.
|
||||
|
||||
Step 3
|
||||
: Create a new branch with a descriptive name.
|
||||
|
||||
```sh
|
||||
git checkout -b fix/typos-shortcode-templates
|
||||
```
|
||||
|
||||
Step 4
|
||||
: Make changes.
|
||||
|
||||
Step 5
|
||||
: Commit your changes with a descriptive commit message, typically 50 characters or less. Add the "Closes" keyword if your change addresses one or more open [issues].
|
||||
|
||||
```sh
|
||||
git commit -m "Fix typos on the shortcode templates page
|
||||
|
||||
Closes #1234
|
||||
Closes #5678"
|
||||
```
|
||||
|
||||
Step 6
|
||||
: Push the new branch to your fork of the documentation repository.
|
||||
|
||||
Step 7
|
||||
: Visit the [documentation repository] and create a pull request (PR).
|
||||
|
||||
Step 8
|
||||
: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
|
||||
|
||||
[ATX]: https://spec.commonmark.org/0.30/#atx-headings
|
||||
[Microsoft Writing Style Guide]: https://learn.microsoft.com/en-us/style-guide/welcome/
|
||||
[basic english]: https://simple.wikipedia.org/wiki/Basic_English
|
||||
[code examples]: #code-examples
|
||||
[code shortcode]: #code
|
||||
[code-toggle shortcode]: #code-toggle
|
||||
[documentation repository]: https://github.com/gohugoio/hugoDocs/
|
||||
[fenced code blocks]: https://spec.commonmark.org/0.30/#fenced-code-blocks
|
||||
[glossary of terms]: /getting-started/glossary/
|
||||
[indented code blocks]: https://spec.commonmark.org/0.30/#indented-code-blocks
|
||||
[issues]: https://github.com/gohugoio/hugoDocs/issues
|
||||
[list items]: https://spec.commonmark.org/0.30/#list-items
|
||||
[note shortcode]: #note
|
||||
[project repository]: https://github.com/gohugoio/hugo
|
||||
[raw HTML]: https://spec.commonmark.org/0.30/#raw-html
|
||||
[setext]: https://spec.commonmark.org/0.30/#setext-heading
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: Themes
|
||||
description: If you've built a Hugo theme and want to contribute back to the Hugo Community, please share it with us.
|
||||
categories: [contribute]
|
||||
keywords: [themes]
|
||||
menu:
|
||||
docs:
|
||||
parent: contribute
|
||||
weight: 40
|
||||
weight: 40
|
||||
aliases: [/contribute/theme/]
|
||||
---
|
||||
|
||||
Visit [themes.gohugo.io] to browse a collection of themes created by the Hugo community.
|
||||
|
||||
To submit your theme:
|
||||
|
||||
1. Read the [submission guidelines]
|
||||
2. Open a pull request in the [themes repository]
|
||||
|
||||
Other useful theme directories:
|
||||
|
||||
- [jamstack.club]
|
||||
- [jamstackthemes.dev]
|
||||
|
||||
[jamstack.club]: https://jamstack.club/#ssg=hugo
|
||||
[jamstackthemes.dev]: https://jamstackthemes.dev/ssg/hugo
|
||||
[submission guidelines]: https://github.com/gohugoio/hugoThemesSiteBuilder/tree/main#readme
|
||||
[themes repository]: https://github.com/gohugoio/hugoThemesSiteBuilder
|
||||
[themes.gohugo.io]: https://themes.gohugo.io/
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
title: Hugo Documentation
|
||||
linkTitle: Hugo
|
||||
description: Hugo is the world's fastest static website engine. It's written in Go (aka Golang) and developed by bep, spf13 and friends.
|
||||
menu:
|
||||
main:
|
||||
weight: 1
|
||||
weight: 1
|
||||
layout: documentation-home
|
||||
---
|
||||
|
||||
A fast and flexible [static site generator] built with love by [bep], [spf13], and [friends] in [Go].
|
||||
|
||||
Hugo is optimized for speed and designed for flexibility. With its advanced templating system and fast asset pipelines, Hugo renders a complete site in seconds, often less.
|
||||
|
||||
[bep]: https://github.com/bep
|
||||
[spf13]: https://github.com/spf13
|
||||
[friends]: https://github.com/gohugoio/hugo/graphs/contributors
|
||||
[go]: https://go.dev/
|
||||
[static site generator]: https://en.wikipedia.org/wiki/Static_site_generator
|
||||
|
||||
Below you will find some of the most common and helpful pages from our documentation.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 72 KiB |
@@ -1,13 +0,0 @@
|
||||
---
|
||||
cascade:
|
||||
_build:
|
||||
list: never
|
||||
publishResources: false
|
||||
render: never
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
Path|Pattern|Match
|
||||
:--|:--|:--
|
||||
`images/foo/a.jpg`|`images/foo/*.jpg`|`true`
|
||||
`images/foo/a.jpg`|`images/foo/*.*`|`true`
|
||||
`images/foo/a.jpg`|`images/foo/*`|`true`
|
||||
`images/foo/a.jpg`|`images/*/*.jpg`|`true`
|
||||
`images/foo/a.jpg`|`images/*/*.*`|`true`
|
||||
`images/foo/a.jpg`|`images/*/*`|`true`
|
||||
`images/foo/a.jpg`|`*/*/*.jpg`|`true`
|
||||
`images/foo/a.jpg`|`*/*/*.*`|`true`
|
||||
`images/foo/a.jpg`|`*/*/*`|`true`
|
||||
`images/foo/a.jpg`|`**/*.jpg`|`true`
|
||||
`images/foo/a.jpg`|`**/*.*`|`true`
|
||||
`images/foo/a.jpg`|`**/*`|`true`
|
||||
`images/foo/a.jpg`|`**`|`true`
|
||||
`images/foo/a.jpg`|`*/*.jpg`|`false`
|
||||
`images/foo/a.jpg`|`*.jpg`|`false`
|
||||
`images/foo/a.jpg`|`*.*`|`false`
|
||||
`images/foo/a.jpg`|`*`|`false`
|
||||
@@ -1,10 +0,0 @@
|
||||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
{{% note %}}
|
||||
|
||||
Localization of dates, currencies, numbers, and percentages is performed by the [gohugoio/locales] package. The language tag of the current site must match one of the listed locales.
|
||||
|
||||
[gohugoio/locales]: https://github.com/gohugoio/locales
|
||||
{{% /note %}}
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes.
|
||||
|
||||
Go's regular expression package implements the [RE2 syntax]. The RE2 syntax is a subset of that accepted by [PCRE], roughly speaking, and with various [caveats]. Note that the RE2 `\C` escape sequence is not supported.
|
||||
|
||||
[caveats]: https://swtch.com/~rsc/regexp/regexp3.html#caveats
|
||||
[PCRE]: https://www.pcre.org/
|
||||
[RE2 syntax]: https://github.com/google/re2/wiki/Syntax/
|
||||
[string literal]: https://go.dev/ref/spec#String_literals
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
Format a `time.Time` value based on [Go's reference time]:
|
||||
|
||||
[Go's reference time]: https://pkg.go.dev/time#pkg-constants
|
||||
|
||||
```text
|
||||
Mon Jan 2 15:04:05 MST 2006
|
||||
```
|
||||
|
||||
Create a layout string using these components:
|
||||
|
||||
Description|Valid components
|
||||
:--|:--
|
||||
Year|`"2006" "06"`
|
||||
Month|`"Jan" "January" "01" "1"`
|
||||
Day of the week|`"Mon" "Monday"`
|
||||
Day of the month|`"2" "_2" "02"`
|
||||
Day of the year|`"__2" "002"`
|
||||
Hour|`"15" "3" "03"`
|
||||
Minute|`"4" "04"`
|
||||
Second|`"5" "05"`
|
||||
AM/PM mark|`"PM"`
|
||||
Time zone offsets|`"-0700" "-07:00" "-07" "-070000" "-07:00:00"`
|
||||
|
||||
Replace the sign in the layout string with a Z to print Z instead of an offset for the UTC zone.
|
||||
|
||||
Description|Valid components
|
||||
:--|:--
|
||||
Time zone offsets|`"Z0700" "Z07:00" "Z07" "Z070000" "Z07:00:00"`
|
||||
|
||||
```go-html-template
|
||||
{{ $t := "2023-01-27T23:44:58-08:00" }}
|
||||
{{ $t = time.AsTime $t }}
|
||||
{{ $t = $t.Format "Jan 02, 2006 3:04 PM Z07:00" }}
|
||||
|
||||
{{ $t }} → Jan 27, 2023 11:44 PM -08:00
|
||||
```
|
||||
|
||||
Strings such as `PST` and `CET` are not time zones. They are time zone _abbreviations_.
|
||||
|
||||
Strings such as `-07:00` and `+01:00` are not time zones. They are time zone _offsets_.
|
||||
|
||||
A time zone is a geographic area with the same local time. For example, the time zone abbreviated by `PST` and `PDT` (depending on Daylight Savings Time) is `America/Los_Angeles`.
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
title: Functions
|
||||
linkTitle: Overview
|
||||
description: A list of Hugo template functions including examples.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: functions-overview
|
||||
parent: functions
|
||||
weight: 10
|
||||
weight: 10
|
||||
showSectionMenu: true
|
||||
aliases: [/layout/functions/,/templates/functions]
|
||||
---
|
||||
|
||||
Use these functions within your templates and archetypes.
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
title: cast.ToFloat
|
||||
description: Converts a value to a decimal floating-point number (base 10).
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [float]
|
||||
related:
|
||||
- functions/cast/ToInt
|
||||
- functions/cast/ToString
|
||||
returnType: float64
|
||||
signatures: [cast.ToFloat INPUT]
|
||||
aliases: [/functions/float]
|
||||
---
|
||||
|
||||
With a decimal (base 10) input:
|
||||
|
||||
```go-html-template
|
||||
{{ float 11 }} → 11 (float64)
|
||||
{{ float "11" }} → 11 (float64)
|
||||
|
||||
{{ float 11.1 }} → 11.1 (float64)
|
||||
{{ float "11.1" }} → 11.1 (float64)
|
||||
|
||||
{{ float 11.9 }} → 11.9 (float64)
|
||||
{{ float "11.9" }} → 11.9 (float64)
|
||||
```
|
||||
|
||||
With a binary (base 2) input:
|
||||
|
||||
```go-html-template
|
||||
{{ float 0b11 }} → 3 (float64)
|
||||
```
|
||||
|
||||
With an octal (base 8) input (use either notation):
|
||||
|
||||
```go-html-template
|
||||
{{ float 011 }} → 9 (float64)
|
||||
{{ float "011" }} → 11 (float64)
|
||||
|
||||
{{ float 0o11 }} → 9 (float64)
|
||||
```
|
||||
|
||||
With a hexadecimal (base 16) input:
|
||||
|
||||
```go-html-template
|
||||
{{ float 0x11 }} → 17 (float64)
|
||||
```
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
title: cast.ToInt
|
||||
description: Converts a value to a decimal integer (base 10).
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [int]
|
||||
related:
|
||||
- functions/cast/ToFloat
|
||||
- functions/cast/ToString
|
||||
returnType: int
|
||||
signatures: [cast/ToInt INPUT]
|
||||
aliases: [/functions/int]
|
||||
---
|
||||
|
||||
With a decimal (base 10) input:
|
||||
|
||||
```go-html-template
|
||||
{{ int 11 }} → 11 (int)
|
||||
{{ int "11" }} → 11 (int)
|
||||
|
||||
{{ int 11.1 }} → 11 (int)
|
||||
{{ int 11.9 }} → 11 (int)
|
||||
```
|
||||
|
||||
With a binary (base 2) input:
|
||||
|
||||
```go-html-template
|
||||
{{ int 0b11 }} → 3 (int)
|
||||
{{ int "0b11" }} → 3 (int)
|
||||
```
|
||||
|
||||
With an octal (base 8) input (use either notation):
|
||||
|
||||
```go-html-template
|
||||
{{ int 011 }} → 9 (int)
|
||||
{{ int "011" }} → 9 (int)
|
||||
|
||||
{{ int 0o11 }} → 9 (int)
|
||||
{{ int "0o11" }} → 9 (int)
|
||||
```
|
||||
|
||||
With a hexadecimal (base 16) input:
|
||||
|
||||
```go-html-template
|
||||
{{ int 0x11 }} → 17 (int)
|
||||
{{ int "0x11" }} → 17 (int)
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros:
|
||||
|
||||
`{{ strings/TrimLeft "0" "0011" | int }} → 11`
|
||||
{{% /note %}}
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
title: cast.ToString
|
||||
description: Converts a value to a string.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [string]
|
||||
related:
|
||||
- functions/cast/ToFloat
|
||||
- functions/cast/ToInt
|
||||
returnType: string
|
||||
signatures: [cast.ToString INPUT]
|
||||
aliases: [/functions/string]
|
||||
---
|
||||
|
||||
With a decimal (base 10) input:
|
||||
|
||||
```go-html-template
|
||||
{{ string 11 }} → 11 (string)
|
||||
{{ string "11" }} → 11 (string)
|
||||
|
||||
{{ string 11.1 }} → 11.1 (string)
|
||||
{{ string "11.1" }} → 11.1 (string)
|
||||
|
||||
{{ string 11.9 }} → 11.9 (string)
|
||||
{{ string "11.9" }} → 11.9 (string)
|
||||
```
|
||||
|
||||
With a binary (base 2) input:
|
||||
|
||||
```go-html-template
|
||||
{{ string 0b11 }} → 3 (string)
|
||||
{{ string "0b11" }} → 0b11 (string)
|
||||
```
|
||||
|
||||
With an octal (base 8) input (use either notation):
|
||||
|
||||
```go-html-template
|
||||
{{ string 011 }} → 9 (string)
|
||||
{{ string "011" }} → 011 (string)
|
||||
|
||||
{{ string 0o11 }} → 9 (string)
|
||||
{{ string "0o11" }} → 0o11 (string)
|
||||
```
|
||||
|
||||
With a hexadecimal (base 16) input:
|
||||
|
||||
```go-html-template
|
||||
{{ string 0x11 }} → 17 (string)
|
||||
{{ string "0x11" }} → 0x11 (string)
|
||||
```
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
title: Cast functions
|
||||
linkTitle: cast
|
||||
description: Template functions to cast a value from one data type to another.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
---
|
||||
|
||||
Use these functions to cast a value from one data type to another.
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
title: collections.After
|
||||
description: Slices an array to the items after the Nth item.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [after]
|
||||
related:
|
||||
- functions/collections/First
|
||||
- functions/collections/Last
|
||||
returnType: any
|
||||
signatures: [collections.After INDEX COLLECTION]
|
||||
aliases: [/functions/after]
|
||||
---
|
||||
|
||||
The following shows `after` being used in conjunction with the [`slice`]function:
|
||||
|
||||
```go-html-template
|
||||
{{ $data := slice "one" "two" "three" "four" }}
|
||||
<ul>
|
||||
{{ range after 2 $data }}
|
||||
<li>{{ . }}</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
The template above is rendered to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li>three</li>
|
||||
<li>four</li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
## Example of `after` with `first`: 2nd–4th most recent articles
|
||||
|
||||
You can use `after` in combination with the [`first`] function and Hugo's [powerful sorting methods][lists]. Let's assume you have a list page at `example.com/articles`. You have 10 articles, but you want your templating for the [list/section page] to show only two rows:
|
||||
|
||||
1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
|
||||
2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
|
||||
|
||||
{{< code file=layouts/section/articles.html >}}
|
||||
{{ define "main" }}
|
||||
<section class="row featured-article">
|
||||
<h2>Featured Article</h2>
|
||||
{{ range first 1 .Pages.ByPublishDate.Reverse }}
|
||||
<header>
|
||||
<h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
|
||||
</header>
|
||||
<p>{{ .Description }}</p>
|
||||
{{ end }}
|
||||
</section>
|
||||
<div class="row recent-articles">
|
||||
<h2>Recent Articles</h2>
|
||||
{{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
|
||||
<section class="recent-article">
|
||||
<header>
|
||||
<h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
|
||||
</header>
|
||||
<p>{{ .Description }}</p>
|
||||
</section>
|
||||
{{ end }}
|
||||
</div>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
[`first`]: /functions/collections/first
|
||||
[list/section page]: /templates/section-templates
|
||||
[lists]: /templates/lists/#sort-content
|
||||
[`slice`]: /functions/collections/slice/
|
||||
@@ -1,101 +0,0 @@
|
||||
---
|
||||
title: collections.Append
|
||||
description: Appends one or more elements to a slice and returns the resulting slice.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [append]
|
||||
related:
|
||||
- functions/collections/Merge
|
||||
returnType: any
|
||||
signatures:
|
||||
- collections.Append ELEMENT [ELEMENT...] COLLECTION
|
||||
- collections.Append COLLECTION1 COLLECTION2
|
||||
aliases: [/functions/append]
|
||||
---
|
||||
|
||||
This function appends all elements, excluding the last, to the last element. This allows [pipe](/getting-started/glossary/#pipeline) constructs as shown below.
|
||||
|
||||
Append a single element to a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "a" "b" }}
|
||||
{{ $s }} → [a b]
|
||||
|
||||
{{ $s = $s | append "c" }}
|
||||
{{ $s }} → [a b c]
|
||||
```
|
||||
|
||||
Append two elements to a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "a" "b" }}
|
||||
{{ $s }} → [a b]
|
||||
|
||||
{{ $s = $s | append "c" "d" }}
|
||||
{{ $s }} → [a b c d]
|
||||
```
|
||||
|
||||
Append two elements, as a slice, to a slice. This produces the same result as the previous example:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "a" "b" }}
|
||||
{{ $s }} → [a b]
|
||||
|
||||
{{ $s = $s | append (slice "c" "d") }}
|
||||
{{ $s }} → [a b c d]
|
||||
```
|
||||
|
||||
Start with an empty slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice }}
|
||||
{{ $s }} → []
|
||||
|
||||
{{ $s = $s | append "a" }}
|
||||
{{ $s }} → [a]
|
||||
|
||||
{{ $s = $s | append "b" "c" }}
|
||||
{{ $s }} → [a b c]
|
||||
|
||||
{{ $s = $s | append (slice "d" "e") }}
|
||||
{{ $s }} → [a b c d e]
|
||||
```
|
||||
|
||||
If you start with a slice of a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice (slice "a" "b") }}
|
||||
{{ $s }} → [[a b]]
|
||||
|
||||
{{ $s = $s | append (slice "c" "d") }}
|
||||
{{ $s }} → [[a b] [c d]]
|
||||
```
|
||||
|
||||
To create a slice of slices, starting with an empty slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice }}
|
||||
{{ $s }} → []
|
||||
|
||||
{{ $s = $s | append (slice (slice "a" "b")) }}
|
||||
{{ $s }} → [[a b]]
|
||||
|
||||
{{ $s = $s | append (slice "c" "d") }}
|
||||
{{ $s }} → [[a b] [c d]]
|
||||
```
|
||||
|
||||
Although the elements in the examples above are strings, you can use the `append` function with any data type, including Pages. For example, on the home page of a corporate site, to display links to the two most recent press releases followed by links to the four most recent articles:
|
||||
|
||||
```go-html-template
|
||||
{{ $p := where site.RegularPages "Type" "press-releases" | first 2 }}
|
||||
{{ $p = $p | append (where site.RegularPages "Type" "articles" | first 4) }}
|
||||
|
||||
{{ with $p }}
|
||||
<ul>
|
||||
{{ range . }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
title: collections.Apply
|
||||
description: Returns a new collection with each element transformed by the given function.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [apply]
|
||||
related: []
|
||||
returnType: '[]any'
|
||||
signatures: [collections.Apply COLLECTION FUNCTION PARAM...]
|
||||
aliases: [/functions/apply]
|
||||
---
|
||||
|
||||
The `apply` function takes three or more arguments, depending on the function being applied to the collection elements.
|
||||
|
||||
The first argument is the collection itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the collection element.
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "hello" "world" }}
|
||||
|
||||
{{ $s = apply $s "strings.FirstUpper" "." }}
|
||||
{{ $s }} → [Hello World]
|
||||
|
||||
{{ $s = apply $s "strings.Replace" "." "l" "_" }}
|
||||
{{ $s }} → [He__o Wor_d]
|
||||
```
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
title: collections.Complement
|
||||
description: Returns the elements of the last collection that are not in any of the others.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [complement]
|
||||
related:
|
||||
- functions/collections/Intersect
|
||||
- functions/collections/SymDiff
|
||||
- functions/collections/Union
|
||||
returnType: any
|
||||
signatures: ['collections.Complement COLLECTION [COLLECTION...]']
|
||||
aliases: [/functions/complement]
|
||||
---
|
||||
|
||||
To find the elements within `$c3` that do not exist in `$c1` or `$c2`:
|
||||
|
||||
```go-html-template
|
||||
{{ $c1 := slice 3 }}
|
||||
{{ $c2 := slice 4 5 }}
|
||||
{{ $c3 := slice 1 2 3 4 5 }}
|
||||
|
||||
{{ complement $c1 $c2 $c3 }} → [1 2]
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Make your code simpler to understand by using a [chained pipeline]:
|
||||
|
||||
[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $c3 | complement $c1 $c2 }} → [1 2]
|
||||
```
|
||||
|
||||
You can also use the `complement` function with page collections. Let's say your site has five content types:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── blog/
|
||||
├── books/
|
||||
├── faqs/
|
||||
├── films/
|
||||
└── songs/
|
||||
```
|
||||
|
||||
To list everything except blog articles (`blog`) and frequently asked questions (`faqs`):
|
||||
|
||||
```go-html-template
|
||||
{{ $blog := where site.RegularPages "Type" "blog" }}
|
||||
{{ $faqs := where site.RegularPages "Type" "faqs" }}
|
||||
{{ range site.RegularPages | complement $blog $faqs }}
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
|
||||
|
||||
[`where`]: /functions/collections/where
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }}
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
In this example we use the `complement` function to remove [stop words] from a sentence:
|
||||
|
||||
```go-html-template
|
||||
{{ $text := "The quick brown fox jumps over the lazy dog" }}
|
||||
{{ $stopWords := slice "a" "an" "in" "over" "the" "under" }}
|
||||
{{ $filtered := split $text " " | complement $stopWords }}
|
||||
|
||||
{{ delimit $filtered " " }} → The quick brown fox jumps lazy dog
|
||||
```
|
||||
|
||||
[stop words]: https://en.wikipedia.org/wiki/Stop_word
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
title: collections.Delimit
|
||||
description: Loops through any array, slice, or map and returns a string of all the values separated by a delimiter.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [delimit]
|
||||
related:
|
||||
- functions/strings/Split
|
||||
returnType: string
|
||||
signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]']
|
||||
aliases: [/functions/delimit]
|
||||
---
|
||||
|
||||
Delimit a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "b" "a" "c" }}
|
||||
{{ delimit $s ", " }} → b, a, c
|
||||
{{ delimit $s ", " " and "}} → b, a and c
|
||||
```
|
||||
|
||||
Delimit a map:
|
||||
|
||||
{{% note %}}
|
||||
The `delimit` function sorts maps by key, returning the values.
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $m := dict "b" 2 "a" 1 "c" 3 }}
|
||||
{{ delimit $m ", " }} → 1, 2, 3
|
||||
{{ delimit $m ", " " and "}} → 1, 2 and 3
|
||||
```
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
title: collections.Dictionary
|
||||
description: Creates a map from a list of key and value pairs.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [dict]
|
||||
related:
|
||||
- functions/collections/Slice
|
||||
returnType: mapany
|
||||
signatures: ['collections.Dictionary KEY VALUE [VALUE...]']
|
||||
aliases: [/functions/dict]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $m := dict "a" 1 "b" 2 }}
|
||||
```
|
||||
|
||||
The above produces this data structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"a": 1,
|
||||
"b": 2
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.:
|
||||
|
||||
```go-html-template
|
||||
{{ $m := dict (slice "a" "b" "c") "value" }}
|
||||
```
|
||||
|
||||
The above produces this data structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"a": {
|
||||
"b": {
|
||||
"c": "value"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Pass values to a partial template
|
||||
|
||||
The partial below creates an SVG and expects `fill`, `height` and `width` from the caller:
|
||||
|
||||
### Partial definition
|
||||
|
||||
{{< code file=layouts/partials/svgs/external-links.svg >}}
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 32" aria-label="External Link">
|
||||
<path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path>
|
||||
</svg>
|
||||
{{< /code >}}
|
||||
|
||||
### Partial call
|
||||
|
||||
The `fill`, `height` and `width` values can be stored in one object with `dict` and passed to the partial:
|
||||
|
||||
{{< code file=layouts/_default/list.html >}}
|
||||
{{ partial "svgs/external-links.svg" (dict "fill" "#01589B" "width" 10 "height" 20 ) }}
|
||||
{{< /code >}}
|
||||
|
||||
[partials]: /templates/partials/
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user