diff --git a/content/en/about/privacy.md b/content/en/about/privacy.md index ef4faa793..828995c07 100644 --- a/content/en/about/privacy.md +++ b/content/en/about/privacy.md @@ -34,9 +34,9 @@ Some of these templates include settings to enhance privacy. ## Configuration -{{% note %}} +{{< note >}} These settings affect the behavior of some of Hugo's embedded templates. These settings may or may not affect the behavior of templates provided by third parties in their modules or themes. -{{% /note %}} +{{< /note >}} These are the default privacy settings for Hugo's embedded templates: diff --git a/content/en/content-management/build-options.md b/content/en/content-management/build-options.md index e78462455..b9762e563 100644 --- a/content/en/content-management/build-options.md +++ b/content/en/content-management/build-options.md @@ -60,12 +60,12 @@ render [`RelPermalink`]: /methods/resource/relpermalink/ [`Publish`]: /methods/resource/publish/ -{{% note %}} +{{< 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 %}} +{{< /note >}} ## Example -- headless page diff --git a/content/en/content-management/content-adapters.md b/content/en/content-management/content-adapters.md index 420d49d9d..7339b4c68 100644 --- a/content/en/content-management/content-adapters.md +++ b/content/en/content-management/content-adapters.md @@ -91,9 +91,9 @@ Returns the `Site` to which the pages will be added. {{ .Site.Title }} {{< /code >}} -{{% note %}} +{{< note >}} Note that the `Site` returned isn't fully built when invoked from the content adapters; if you try to call methods that depends on pages, e.g. `.Site.Pages`, you will get an error saying "this method cannot be called before the site is fully initialized". -{{% /note %}} +{{< /note >}} ###### Store @@ -141,11 +141,11 @@ Key|Description|Required `path`|The page's [logical path](g) relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark: `title`|The page title.|  -{{% note %}} +{{< note >}} While `path` is the only required field, we recommend setting `title` as well. When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`. -{{% /note %}} +{{< /note >}} ## Resource map @@ -160,11 +160,11 @@ Key|Description|Required `path`|The resources's [logical path](g) relative to the content adapter. Do not include a leading slash.|:heavy_check_mark: `title`|The resource title.|  -{{% note %}} +{{< note >}} If the `content.value` is a string Hugo creates a new resource. If the `content.value` is a resource, Hugo obtains the value from the existing resource. When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`. -{{% /note %}} +{{< /note >}} ## Example diff --git a/content/en/content-management/data-sources.md b/content/en/content-management/data-sources.md index 1237e4f4d..b6942aaa0 100644 --- a/content/en/content-management/data-sources.md +++ b/content/en/content-management/data-sources.md @@ -22,9 +22,9 @@ The `data` directory in the root of your project may contain one or more data fi Hugo also merges data directories from themes and modules into this single data structure, where the `data` directory in the root of your project takes precedence. -{{% note %}} +{{< note >}} Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead. -{{% /note %}} +{{< /note >}} Theme and module authors may wish to namespace their data files to prevent collisions. For example: @@ -35,9 +35,9 @@ project/ └── foo.json ``` -{{% note %}} +{{< note >}} Do not place CSV files in the `data` directory. Access CSV files as page, global, or remote resources. -{{% /note %}} +{{< /note >}} See the documentation for the [`Data`] method on a `Site` object for details and examples. diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md index 9f5fc9e11..0493c3308 100644 --- a/content/en/content-management/front-matter.md +++ b/content/en/content-management/front-matter.md @@ -45,11 +45,11 @@ Front matter fields may be [boolean](g), [integer](g), [float](g), [string](g), The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below. -{{% note %}} +{{< note >}} The field names below are reserved. For example, you cannot create a custom field named `type`. Create custom fields under the `params` key. See the [parameters] section for details. [parameters]: #parameters -{{% /note %}} +{{< /note >}} ###### aliases @@ -382,11 +382,11 @@ Use any combination of these keywords to target a set of pages: Any of the above can be omitted. -{{% note %}} +{{< note >}} With a multilingual site it may be more efficient to define the `cascade` values in your site configuration to avoid duplicating the `cascade` values on the section, taxonomy, or term page for each language. With a multilingual site, if you choose to define the `cascade` values in front matter, you must create a section, taxonomy, or term page for each language; the `lang` keyword is ignored. -{{% /note %}} +{{< /note >}} ### Example diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index fa97edca6..05f40cd73 100644 --- a/content/en/content-management/image-processing/index.md +++ b/content/en/content-management/image-processing/index.md @@ -104,17 +104,17 @@ Example 4: Skips rendering if there's problem accessing a remote resource. The `image` resource implements the [`Process`], [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods. -{{% note %}} +{{< 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, PNG, TIFF, and WebP images. -{{% /note %}} +{{< /note >}} ### Process {{< new-in 0.119.0 />}} -{{% note %}} +{{< 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 %}} +{{< /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`]. @@ -460,11 +460,11 @@ excludeFields 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 %}} + {{< 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 %}} + {{< /note >}} ## Smart cropping of images diff --git a/content/en/content-management/mathematics.md b/content/en/content-management/mathematics.md index 0006de29d..2172c0fa4 100644 --- a/content/en/content-management/mathematics.md +++ b/content/en/content-management/mathematics.md @@ -43,13 +43,13 @@ Equations and expressions can be displayed inline with other text, or as standal Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different. -{{% note %}} +{{< note >}} You can configure Hugo to render mathematical markup on the client side using the MathJax or KaTeX display engine, or you can render the markup with the [`transform.ToMath`] function while building your site. The first approach is described below. [`transform.ToMath`]: /functions/transform/tomath/ -{{% /note %}} +{{< /note >}} ## Setup @@ -73,11 +73,11 @@ math = true The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3]. -{{% note %}} +{{< note >}} The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. See the [inline delimiters](#inline-delimiters) section for details. -{{% /note %}} +{{< /note >}} To disable passthrough of inline snippets, omit the `inline` key from the configuration: @@ -178,19 +178,19 @@ If you add the `$...$` delimiter pair to your configuration and JavaScript, you A \\$5 bill _saved_ is a \\$5 bill _earned_. ``` -{{% note %}} +{{< note >}} If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437). -{{% /note %}} +{{< /note >}} ## Engines MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.11. -{{% note %}} +{{< note >}} If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437). See the [inline delimiters](#inline-delimiters) section for details. -{{% /note %}} +{{< /note >}} To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this: diff --git a/content/en/content-management/menus.md b/content/en/content-management/menus.md index 15cf505ea..1f7b339be 100644 --- a/content/en/content-management/menus.md +++ b/content/en/content-management/menus.md @@ -28,9 +28,9 @@ There are three ways to define menu entries: 1. In front matter 1. In site configuration -{{% note %}} +{{< 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 %}} +{{< /note >}} ## Define automatically @@ -62,9 +62,9 @@ menus = ['main','footer'] Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details. -{{% note %}} +{{< note >}} The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`. -{{% /note %}} +{{< /note >}} ### Properties {#properties-front-matter} @@ -149,17 +149,17 @@ weight = 20 This creates a menu structure that you can access with `site.Menus.footer` in your templates. See [menu templates] for details. -{{% note %}} +{{< note >}} The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`. -{{% /note %}} +{{< /note >}} ### Properties {#properties-site-configuration} -{{% note %}} +{{< 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 %}} +{{< /note >}} Each menu entry defined in site configuration requires two or more properties: diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md index 8233185d5..e532da5af 100644 --- a/content/en/content-management/multilingual.md +++ b/content/en/content-management/multilingual.md @@ -30,9 +30,9 @@ Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7] - `hugolang` -{{% note %}} +{{< note >}} Private use subtags must not exceed 8 alphanumeric characters. -{{% /note %}} +{{< /note >}} [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 [RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 @@ -174,9 +174,9 @@ Note that you cannot disable the default content language. Hugo supports multiple languages in a multihost configuration. This means you can configure a `baseURL` per `language`. -{{% note %}} +{{< note >}} If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. -{{% /note %}} +{{< /note >}} Example: @@ -232,9 +232,9 @@ Their language is __assigned__ according to the language code added as a __suffi By having the same **path and base file name**, the content pieces are __linked__ together as translated pages. -{{% note %}} +{{< note >}} If a file has no language code, it will be assigned the default language. -{{% /note %}} +{{< /note >}} ### Translation by content directory @@ -314,9 +314,9 @@ If, across the linked bundles, two or more files share the same basename, only o * File from current language bundle, if present. * First file found across bundles by order of language `Weight`. -{{% note %}} +{{< 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 %}} +{{< /note >}} ## Reference translated content @@ -588,9 +588,9 @@ If a string does not have a translation for the current language, Hugo will use 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 %}} +{{< note >}} Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments. -{{% /note %}} +{{< /note >}} For merging of content from other languages (i.e. missing content translations), see [lang.Merge]. diff --git a/content/en/content-management/organization/index.md b/content/en/content-management/organization/index.md index 99a3224bf..5d4f65a2d 100644 --- a/content/en/content-management/organization/index.md +++ b/content/en/content-management/organization/index.md @@ -73,9 +73,9 @@ The following demonstrates the relationships between your content organization a `_index.md` has a special role in Hugo. It allows you to add front matter and content to `home`, `section`, `taxonomy`, and `term` pages. -{{% note %}} +{{< note >}} **Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/methods/page/getpage). -{{% /note %}} +{{< /note >}} You can create one `_index.md` for your home page and one in each of your content sections, taxonomies, and 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: diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md index 3638f2fb5..d08db5cf4 100644 --- a/content/en/content-management/page-bundles.md +++ b/content/en/content-management/page-bundles.md @@ -35,9 +35,9 @@ leaf bundle branch bundle : A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page. -{{% note %}} +{{< note >}} In the definitions above and the examples below, the extension of the index file depends on the [content format](g). For example, use `index.md` for Markdown content, `index.html` for HTML content, `index.adoc` for AsciiDoc content, etc. -{{% /note %}} +{{< /note >}} ## Comparison @@ -108,9 +108,9 @@ my-other-post another-leaf-bundle : This leaf bundle does not contain any page resources. -{{% note %}} +{{< note >}} Create leaf bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants. -{{% /note %}} +{{< /note >}} ## Branch bundles @@ -142,9 +142,9 @@ branch-bundle-1 branch-bundle-2 : This branch bundle contains an index file and a leaf bundle. -{{% note %}} +{{< note >}} Create branch bundles at any depth within the `content` directory. Branch bundles may have descendants. -{{% /note %}} +{{< /note >}} ## Headless bundles diff --git a/content/en/content-management/page-resources.md b/content/en/content-management/page-resources.md index 84c3309cd..978edad30 100644 --- a/content/en/content-management/page-resources.md +++ b/content/en/content-management/page-resources.md @@ -120,16 +120,16 @@ List the titles in the data file, and throw an error if the file does not exist. 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 %}} +{{< note >}} Resources of type `page` get `Title` etc. from their own front matter. -{{% /note %}} +{{< /note >}} name : (`string`) Sets the value returned in `Name`. -{{% note %}} +{{< note >}} The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources. -{{% /note %}} +{{< /note >}} title : (`string`) Sets the value returned in `Title` @@ -173,9 +173,9 @@ From the example above: - 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 %}} +{{< 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 %}} +{{< /note >}} ### The `:counter` placeholder in `name` and `title` @@ -210,11 +210,11 @@ the `Name` and `Title` will be assigned to the resource files as follows: By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site. -{{% note %}} +{{< note >}} This behavior is limited to Markdown content. Shared page resources for other [content formats] are copied into each language bundle. [content formats]: /content-management/formats/ -{{% /note %}} +{{< /note >}} Consider this site configuration: @@ -289,7 +289,7 @@ public/ This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost. -{{% note %}} +{{< note >}} To resolve Markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method. By default, with multilingual single-host sites, Hugo enables its [embedded link render hook] and [embedded image render hook] to resolve Markdown link and image destinations. @@ -300,7 +300,7 @@ You may override the embedded render hooks as needed, provided they capture the [embedded image render hook]: /render-hooks/images/#default [`Resources.Get`]: /methods/page/resources/#get [`RelPermalink`]: /methods/resource/relpermalink/ -{{% /note %}} +{{< /note >}} Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired: diff --git a/content/en/content-management/related.md b/content/en/content-management/related.md index 6431d12a3..bd24635db 100644 --- a/content/en/content-management/related.md +++ b/content/en/content-management/related.md @@ -58,9 +58,9 @@ A fictional example using all of the above options: }} ``` -{{% note %}} +{{< 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 %}} +{{< /note >}} ## Index content headings in related content @@ -117,9 +117,9 @@ Without any `related` configuration set on the project, Hugo's Related Content m Custom configuration should be set using the same syntax. -{{% note %}} +{{< 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 %}} +{{< /note >}} ### Top level configuration options diff --git a/content/en/content-management/sections.md b/content/en/content-management/sections.md index ce6916fd3..3b8864339 100644 --- a/content/en/content-management/sections.md +++ b/content/en/content-management/sections.md @@ -17,9 +17,9 @@ aliases: [/content/sections/] 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](g). Section templates receive one or more page [collections](g) in [context](g). -{{% note %}} +{{< note >}} Although top-level directories without `_index.md` files are sections, we recommend creating `_index.md` files in _all_ sections. -{{% /note %}} +{{< /note >}} A typical site consists of one or more sections. For example: diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md index 55d1ffa66..f373f5a05 100644 --- a/content/en/content-management/shortcodes.md +++ b/content/en/content-management/shortcodes.md @@ -81,9 +81,9 @@ Inline shortcodes process their inner content within the same context as regular [shortcode method]: /templates/shortcode/#methods -{{% note %}} +{{< note >}} You cannot [nest](#nesting) inline shortcodes. -{{% /note %}} +{{< /note >}} Learn more about creating shortcodes in the [shortcode templates] section. diff --git a/content/en/content-management/taxonomies.md b/content/en/content-management/taxonomies.md index 6ba9e2a25..ae80fc8a5 100644 --- a/content/en/content-management/taxonomies.md +++ b/content/en/content-management/taxonomies.md @@ -104,9 +104,9 @@ Custom taxonomies other than the [defaults](#default-taxonomies) must be defined ### Example: adding a custom taxonomy named "series" -{{% note %}} +{{< note >}} While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_. -{{% /note %}} +{{< /note >}} {{< code-toggle file=hugo >}} [taxonomies] @@ -126,9 +126,9 @@ If you want to have just the default `tags` taxonomy, and remove the `categories If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies). -{{% note %}} +{{< 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 %}} +{{< /note >}} ## Assign terms to content diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md index ab0c7148a..9b0a81452 100644 --- a/content/en/content-management/urls.md +++ b/content/en/content-management/urls.md @@ -43,14 +43,14 @@ https://example.org/posts/my-first-post/ Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages. -{{% note %}} +{{< note >}} Hugo does not sanitize the `url` front matter field, allowing you to generate: - File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters]. Hugo throws an error if a file path includes a character reserved by the current operating system. - URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL. [reserved characters]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions -{{% /note %}} +{{< /note >}} If you set both `slug` and `url` in front matter, the `url` value takes precedence. @@ -355,11 +355,11 @@ Hugo provides two mutually exclusive configuration options to alter URLs _after_ #### Canonical URLs -{{% note %}} +{{< 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 %}} +{{< /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. @@ -378,9 +378,9 @@ canonifyURLs = true #### Relative URLs -{{% note %}} +{{< note >}} Do not enable this option unless you are creating a serverless site, navigable via the file system. -{{% /note %}} +{{< /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. diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md index ef6fd9d37..cde48a4c8 100644 --- a/content/en/contribute/development.md +++ b/content/en/contribute/development.md @@ -58,15 +58,15 @@ To build the extended or extended/deploy edition from source you must: [Go documentation]: https://go.dev/doc/code#Command [Go]: https://go.dev/doc/install -{{% note %}} +{{< note >}} See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows. -{{% /note %}} +{{< /note >}} ## GitHub workflow -{{% note %}} +{{< note >}} This section assumes that you have a working knowledge of Go, Git and GitHub, and are comfortable working on the command line. -{{% /note %}} +{{< /note >}} Use this workflow to create and submit pull requests. diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index 285985b3d..61643fcf0 100644 --- a/content/en/contribute/documentation.md +++ b/content/en/contribute/documentation.md @@ -111,9 +111,9 @@ Best → Be cautious when deleting files. No → Hugo is extremely fast.\ Yes → Hugo is fast. -{{% note %}} +{{< note >}} "It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995). -{{% /note %}} +{{< /note >}} ### Level 6 headings @@ -305,18 +305,18 @@ draft: false Use the `deprecated-in` shortcode to indicate that a feature is deprecated: ```text -{{%/* deprecated-in 0.127.0 */%}} +{{}} Use [`hugo.IsServer`] instead. [`hugo.IsServer`]: /functions/hugo/isserver/ -{{%/* /deprecated-in */%}} +{{}} ``` -{{% deprecated-in 0.127.0 %}} +{{< deprecated-in 0.144.0 >}} Use [`hugo.IsServer`] instead. [`hugo.IsServer`]: /functions/hugo/isserver/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} ### eturl @@ -362,21 +362,21 @@ Use the `new-in` shortcode to indicate a new feature: ### note -Use the `note` shortcode with `{{%/* */%}}` delimiters to call attention to important content: +Use the `note` shortcode to call attention to important content: ```text -{{%/* note */%}} +{{}} Use the [`math.Mod`] function to control... [`math.Mod`]: /functions/math/mod/ -{{%/* /note */%}} +{{}} ``` -{{% note %}} +{{< note >}} Use the [`math.Mod`] function to control... [`math.Mod`]: /functions/math/mod/ -{{% /note %}} +{{< /note >}} ## New features @@ -393,11 +393,11 @@ The "new in" label will be hidden if the specified version is older than a prede 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 something like this to front matter: @@ -410,9 +410,9 @@ Set the `expiryDate` to two years from the date of deprecation, and add a brief ## GitHub workflow -{{% note %}} +{{< note >}} This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line. -{{% /note %}} +{{< /note >}} Use this workflow to create and submit pull requests. diff --git a/content/en/functions/_common/highlighting-options.md b/content/en/functions/_common/highlighting-options.md index 2d07ccccc..d3f986502 100644 --- a/content/en/functions/_common/highlighting-options.md +++ b/content/en/functions/_common/highlighting-options.md @@ -11,9 +11,9 @@ codeFences guessSyntax : (`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer](g). Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`. -{{% note %}} +{{< note >}} The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection. -{{% /note %}} +{{< /note >}} hl_Lines : (`string`) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option. @@ -48,7 +48,7 @@ wrapperClass {{< new-in 0.140.2 />}} : (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`. -{{% note %}} +{{< note >}} Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation: lineNos=inline @@ -56,4 +56,4 @@ lineNos=inline lineNos=table : equivalent to `lineNos=true` and `lineNumbersInTable=true` -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/_common/locales.md b/content/en/functions/_common/locales.md index 42d008776..abcfb41c2 100644 --- a/content/en/functions/_common/locales.md +++ b/content/en/functions/_common/locales.md @@ -2,9 +2,9 @@ _comment: Do not remove front matter. --- -{{% note %}} +{{< 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 %}} +{{< /note >}} diff --git a/content/en/functions/cast/ToInt.md b/content/en/functions/cast/ToInt.md index c4bb10268..3e272cba4 100644 --- a/content/en/functions/cast/ToInt.md +++ b/content/en/functions/cast/ToInt.md @@ -46,8 +46,8 @@ With a hexadecimal (base 16) input: {{ int "0x11" }} → 17 (int) ``` -{{% note %}} +{{< 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 %}} +{{< /note >}} diff --git a/content/en/functions/collections/Complement.md b/content/en/functions/collections/Complement.md index 1c785de0b..b4c59822d 100644 --- a/content/en/functions/collections/Complement.md +++ b/content/en/functions/collections/Complement.md @@ -24,11 +24,11 @@ To find the elements within `$c3` that do not exist in `$c1` or `$c2`: {{ complement $c1 $c2 $c3 }} → [1 2] ``` -{{% note %}} +{{< note >}} Make your code simpler to understand by using a [chained pipeline]: [chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines -{{% /note %}} +{{< /note >}} ```go-html-template {{ $c3 | complement $c1 $c2 }} → [1 2] @@ -55,11 +55,11 @@ To list everything except blog articles (`blog`) and frequently asked questions {{ end }} ``` -{{% note %}} +{{< note >}} Although the example above demonstrates the `complement` function, you could use the [`where`] function as well: [`where`]: /functions/collections/where/ -{{% /note %}} +{{< /note >}} ```go-html-template {{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }} diff --git a/content/en/functions/collections/Delimit.md b/content/en/functions/collections/Delimit.md index b85059d4b..6370ca17d 100644 --- a/content/en/functions/collections/Delimit.md +++ b/content/en/functions/collections/Delimit.md @@ -22,9 +22,9 @@ Delimit a slice: Delimit a map: -{{% note %}} +{{< note >}} The `delimit` function sorts maps by key, returning the values. -{{% /note %}} +{{< /note >}} ```go-html-template {{ $m := dict "b" 2 "a" 1 "c" 3 }} diff --git a/content/en/functions/collections/IsSet.md b/content/en/functions/collections/IsSet.md index 62b81b712..431a2aae6 100644 --- a/content/en/functions/collections/IsSet.md +++ b/content/en/functions/collections/IsSet.md @@ -40,6 +40,6 @@ But if the value of `showHeroImage` is `false`, we can't use either `if` or `wit {{ end }} ``` -{{% note %}} +{{< note >}} When using the `isset` function you must reference the key using lower case. See the previous example. -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/collections/Merge.md b/content/en/functions/collections/Merge.md index 3f5208cfc..7cc788f85 100644 --- a/content/en/functions/collections/Merge.md +++ b/content/en/functions/collections/Merge.md @@ -64,6 +64,6 @@ Example 4 {{ $merged.z.a }} → huey ``` -{{% note %}} +{{< note >}} Regardless of depth, merging only applies to maps. For slices, use [append](/functions/collections/append). -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/collections/Seq.md b/content/en/functions/collections/Seq.md index b572bd7c0..b9f66e8d7 100644 --- a/content/en/functions/collections/Seq.md +++ b/content/en/functions/collections/Seq.md @@ -31,6 +31,6 @@ A contrived example of iterating over a sequence of integers: {{ $product }} → 24 ``` -{{% note %}} +{{< note >}} The slice created by the `seq` function is limited to 2000 elements. -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/collections/Sort.md b/content/en/functions/collections/Sort.md index 815260f20..ae8f30609 100644 --- a/content/en/functions/collections/Sort.md +++ b/content/en/functions/collections/Sort.md @@ -65,9 +65,9 @@ firstName = "Jean" lastName = "Valjean" {{< /code-toggle >}} -{{% note %}} +{{< note >}} When sorting maps, the `KEY` argument must be lowercase. -{{% /note %}} +{{< /note >}} ### Ascending order {#map-ascending-order} @@ -141,11 +141,11 @@ After sorting: ## Sort a page collection -{{% note %}} +{{< note >}} Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well. [sorting and grouping methods]: /methods/pages/ -{{% /note %}} +{{< /note >}} In this contrived example, sort the site's regular pages by `.Type` in descending order: diff --git a/content/en/functions/collections/Where.md b/content/en/functions/collections/Where.md index 014a063a1..ea02d3ef2 100644 --- a/content/en/functions/collections/Where.md +++ b/content/en/functions/collections/Where.md @@ -90,9 +90,9 @@ Use any of the following logical operators: `like` {{< new-in 0.116.0 />}} : (`bool`) Reports whether the given field value matches the regular expression specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression. -{{% note %}} +{{< note >}} The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps. -{{% /note %}} +{{< /note >}} ## String comparison @@ -178,9 +178,9 @@ To return a collection of pages where the "author" page parameter begins with ei {{% include "functions/_common/regular-expressions.md" %}} -{{% note %}} +{{< note >}} Use the `like` operator to compare string values. Comparing other data types will result in an empty collection. -{{% /note %}} +{{< /note >}} ## Date comparison @@ -205,9 +205,9 @@ For example, to return a collection of pages that were created before the curren With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON). -{{% note %}} +{{< note >}} Using TOML for pages with custom front matter dates enables precise date comparisons. -{{% /note %}} +{{< /note >}} With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons. diff --git a/content/en/functions/compare/Default.md b/content/en/functions/compare/Default.md index bf859d51c..ab52367ec 100644 --- a/content/en/functions/compare/Default.md +++ b/content/en/functions/compare/Default.md @@ -14,7 +14,7 @@ aliases: [/functions/default] The `default` function returns the second argument if set, else the first argument. -{{% note %}} +{{< note >}} When the second argument is the boolean `false` value, the `default` function returns `false`. All _other_ falsy values are considered unset. {{% include "functions/go-template/_common/truthy-falsy.md" %}} @@ -22,7 +22,7 @@ When the second argument is the boolean `false` value, the `default` function re To set a default value based on truthiness, use the [`or`] operator instead. [`or`]: /functions/go-template/or/ -{{% /note %}} +{{< /note >}} The `default` function returns the second argument if set: diff --git a/content/en/functions/crypto/FNV32a.md b/content/en/functions/crypto/FNV32a.md index 0255349a3..3c13346c5 100644 --- a/content/en/functions/crypto/FNV32a.md +++ b/content/en/functions/crypto/FNV32a.md @@ -11,8 +11,8 @@ action: expiryDate: 2026-07-31 # deprecated 2024-07-31 in v0.129.0 --- -{{% deprecated-in 0.129.0 %}} +{{< deprecated-in 0.129.0 >}} Use [`hash.FNV32a`] instead. [`hash.FNV32a`]: /functions/hash/FNV32a/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/functions/css/PostCSS.md b/content/en/functions/css/PostCSS.md index 1a1a792ec..9b806c2a9 100644 --- a/content/en/functions/css/PostCSS.md +++ b/content/en/functions/css/PostCSS.md @@ -50,9 +50,9 @@ module.exports = { }; {{< /code >}} -{{% note %}} +{{< note >}} {{% include "functions/resources/_common/postcss-windows-warning.md" %}} -{{% /note %}} +{{< /note >}} Step 4 : Place your CSS file within the `assets/css` directory. diff --git a/content/en/functions/data/GetCSV.md b/content/en/functions/data/GetCSV.md index be848bce5..40e6de7e1 100644 --- a/content/en/functions/data/GetCSV.md +++ b/content/en/functions/data/GetCSV.md @@ -12,14 +12,14 @@ toc: true expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0 --- -{{% deprecated-in 0.123.0 %}} +{{< deprecated-in 0.123.0 >}} Instead, use [`transform.Unmarshal`] with a [global resource](g), [page resource](g), or [remote resource](g). See the [remote data example]. [`transform.Unmarshal`]: /functions/transform/unmarshal/ [remote data example]: /functions/resources/getremote/#remote-data -{{% /deprecated-in %}} +{{< /deprecated-in >}} Given the following directory structure: @@ -36,11 +36,11 @@ Access the data with either of the following: {{ $data := getCSV "," "other-files/" "pets.csv" }} ``` -{{% note %}} +{{< note >}} When working with local data, the file path is relative to the working directory. You must not place CSV files in the project's `data` directory. -{{% /note %}} +{{< /note >}} Access remote data with either of the following: diff --git a/content/en/functions/data/GetJSON.md b/content/en/functions/data/GetJSON.md index 1b42cbf16..58334174b 100644 --- a/content/en/functions/data/GetJSON.md +++ b/content/en/functions/data/GetJSON.md @@ -12,14 +12,14 @@ toc: true expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0 --- -{{% deprecated-in 0.123.0 %}} +{{< deprecated-in 0.123.0 >}} Instead, use [`transform.Unmarshal`] with a [global resource](g), [page resource](g), or [remote resource](g). See the [remote data example]. [`transform.Unmarshal`]: /functions/transform/unmarshal/ [remote data example]: /functions/resources/getremote/#remote-data -{{% /deprecated-in %}} +{{< /deprecated-in >}} Given the following directory structure: @@ -36,9 +36,9 @@ Access the data with either of the following: {{ $data := getJSON "other-files/" "books.json" }} ``` -{{% note %}} +{{< note >}} When working with local data, the file path is relative to the working directory. -{{% /note %}} +{{< /note >}} Access remote data with either of the following: diff --git a/content/en/functions/debug/Dump.md b/content/en/functions/debug/Dump.md index 67b264bed..20c0ae8a2 100644 --- a/content/en/functions/debug/Dump.md +++ b/content/en/functions/debug/Dump.md @@ -29,6 +29,6 @@ action: ] ``` -{{% note %}} +{{< note >}} Output from this function may change from one release to the next. Use for debugging only. -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/global/page.md b/content/en/functions/global/page.md index 1dc8be515..0ebb3a7d8 100644 --- a/content/en/functions/global/page.md +++ b/content/en/functions/global/page.md @@ -27,9 +27,9 @@ When a `Page` object is not in context, you can use the global `page` function: {{ page.Params.foo }} ``` -{{% note %}} +{{< note >}} Do not use the global `page` function in shortcodes, partials called by shortcodes, or cached partials. See [warnings](#warnings) below. -{{% /note %}} +{{< /note >}} ## Explanation diff --git a/content/en/functions/global/site.md b/content/en/functions/global/site.md index a4879fee0..fd29bd6de 100644 --- a/content/en/functions/global/site.md +++ b/content/en/functions/global/site.md @@ -27,6 +27,6 @@ When the `Site` object is in context you can use the `Site` property: {{ $.Site.Params.foo }} ``` -{{% note %}} +{{< note >}} To simplify your templates, use the global `site` function regardless of whether the `Site` object is in context. -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/go-template/range.md b/content/en/functions/go-template/range.md index 96713c4b7..94f654a55 100644 --- a/content/en/functions/go-template/range.md +++ b/content/en/functions/go-template/range.md @@ -59,9 +59,9 @@ Hugo will throw an error: The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Within the `range` block, if we want to render the page title, we need to get the context passed into the template. -{{% note %}} +{{< note >}} Use the `$` to get the context passed into the template. -{{% /note %}} +{{< /note >}} This template will render the page title three times: @@ -71,9 +71,9 @@ This template will render the page title three times: {{ end }} ``` -{{% note %}} +{{< note >}} Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +{{< /note >}} [`seq`]: /functions/collections/seq/ diff --git a/content/en/functions/go-template/return.md b/content/en/functions/go-template/return.md index df5b2496e..9b40889e1 100644 --- a/content/en/functions/go-template/return.md +++ b/content/en/functions/go-template/return.md @@ -19,9 +19,9 @@ The returned value may be of any data type including, but not limited to, [`bool A `return` statement without a value returns an empty string of type `template.HTML`. -{{% note %}} +{{< note >}} Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below. -{{% /note %}} +{{< /note >}} ## Example @@ -70,9 +70,9 @@ See additional examples in the [partial templates] section. ## Usage -{{% note %}} +{{< note >}} Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. -{{% /note %}} +{{< /note >}} A partial that returns a value must contain only one `return` statement, placed at the end of the template. @@ -88,9 +88,9 @@ For example: {{ return $result }} {{< /code >}} -{{% note %}} +{{< note >}} The construct below is incorrect; it contains more than one `return` statement. -{{% /note %}} +{{< /note >}} {{< code file="layouts/partials/do-not-do-this.html" >}} {{ if math.ModBool . 2 }} diff --git a/content/en/functions/go-template/try.md b/content/en/functions/go-template/try.md index f3385a04c..979c90b61 100644 --- a/content/en/functions/go-template/try.md +++ b/content/en/functions/go-template/try.md @@ -108,6 +108,6 @@ In the above, note that the [context](g) within the last conditional block is th [template context]: /templates/introduction/#template-context -{{% note %}} +{{< note >}} Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil. -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/go-template/with.md b/content/en/functions/go-template/with.md index a730f4d2c..64f8859bf 100644 --- a/content/en/functions/go-template/with.md +++ b/content/en/functions/go-template/with.md @@ -78,9 +78,9 @@ Hugo will throw an error: The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Inside of the `with` block, if we want to render the page title, we need to get the context passed into the template. -{{% note %}} +{{< note >}} Use the `$` to get the context passed into the template. -{{% /note %}} +{{< /note >}} This template will render the page title as desired: @@ -90,9 +90,9 @@ This template will render the page title as desired: {{ end }} ``` -{{% note %}} +{{< note >}} Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +{{< /note >}} {{% include "functions/go-template/_common/text-template.md" %}} diff --git a/content/en/functions/images/AutoOrient.md b/content/en/functions/images/AutoOrient.md index 8e3708eea..fca9d392e 100644 --- a/content/en/functions/images/AutoOrient.md +++ b/content/en/functions/images/AutoOrient.md @@ -25,9 +25,9 @@ Create the filter: {{% include "functions/images/_common/apply-image-filter.md" %}} -{{% note %}} +{{< note >}} When using with other filters, specify `images.AutoOrient` first. -{{% /note %}} +{{< /note >}} ```go-html-template {{ $filters := slice diff --git a/content/en/functions/images/Config.md b/content/en/functions/images/Config.md index 8f79a65f8..4df088033 100644 --- a/content/en/functions/images/Config.md +++ b/content/en/functions/images/Config.md @@ -24,10 +24,10 @@ See [image processing] for an overview of Hugo's image pipeline. Supported image formats include GIF, JPEG, PNG, TIFF, and WebP. -{{% note %}} +{{< note >}} This is a legacy function, superseded by the [`Width`] and [`Height`] methods for [global resources](g), [page resources](g), and [remote resources](g). See the [image processing] section for details. [`Width`]: /methods/resource/width/ [`Height`]: /methods/resource/height/ [image processing]: /content-management/image-processing/ -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/images/Mask.md b/content/en/functions/images/Mask.md index 8116e8946..11fce93b0 100644 --- a/content/en/functions/images/Mask.md +++ b/content/en/functions/images/Mask.md @@ -17,9 +17,9 @@ toc: true The `images.Mask` filter applies a mask to an image. Black pixels in the mask make the corresponding areas of the base image transparent, while white pixels keep them opaque. Color images are converted to grayscale for masking purposes. The mask is automatically resized to match the dimensions of the base image. -{{% note %}} +{{< note >}} Of the formats supported by Hugo's imaging pipelie, only PNG and WebP have an alpha channel to support transparency. If your source image has a different format and you require transparent masked areas, convert it to either PNG or WebP as shown in the example below. -{{% /note %}} +{{< /note >}} When applying a mask to a non-transparent image format such as JPEG, the masked areas will be filled with the color specified by the `bgColor` parameter in your [site configuration]. You can override that color with a `Process` image filter: diff --git a/content/en/functions/images/QR.md b/content/en/functions/images/QR.md index e3f914fd1..cbefaefff 100644 --- a/content/en/functions/images/QR.md +++ b/content/en/functions/images/QR.md @@ -116,9 +116,9 @@ If the QR code will be printed, use the default `scale` value of `4` pixels per Avoid using Hugo's image processing methods to resize QR codes. Resizing can introduce blurring due to anti-aliasing when a QR code module occupies a fractional number of pixels. -{{% note %}} +{{< note >}} Always test the rendered QR code both on-screen and in print. -{{% /note %}} +{{< /note >}} ## Shortcode diff --git a/content/en/functions/js/Batch.md b/content/en/functions/js/Batch.md index 08913f61f..fe9ec979f 100644 --- a/content/en/functions/js/Batch.md +++ b/content/en/functions/js/Batch.md @@ -16,9 +16,9 @@ weight: 20 toc: true --- -{{% note %}} +{{< note >}} For a runnable example of this feature, see [this test and demo repo](https://github.com/bep/hugojsbatchdemo/). -{{% /note %}} +{{< /note >}} The Batch `ID` is used to create the base directory for this batch. Forward slashes are allowed. `js.Batch` returns an object with an API with this structure: @@ -250,13 +250,13 @@ Eeach [`Resource`] will be of media type `application/javascript` or `text/css`. In a template you would typically handle one group with a given `ID` (e.g. scripts for the current section). Because of the concurrent build, this needs to be done in a [`templates.Defer`] block: -{{% note %}} +{{< note >}} The [`templates.Defer`] acts as a synchronisation point to handle scripts added concurrently by different templates. If you have a setup with where the batch is created in one go (in one template), you don't need it. See [this discussion](https://discourse.gohugo.io/t/js-batch-with-simple-global-script/53002/5?u=bep) for more. [`templates.Defer`]: /functions/templates/defer/ -{{% /note %}} +{{< /note >}} ```go-html-template {{ $group := .group }} diff --git a/content/en/functions/js/Build.md b/content/en/functions/js/Build.md index 9bdc2454a..e1fb7d2e2 100644 --- a/content/en/functions/js/Build.md +++ b/content/en/functions/js/Build.md @@ -109,9 +109,9 @@ Any imports in a file outside `assets` or that does not resolve to a component i The start directory for resolving npm packages (aka. packages that live inside a `node_modules` directory) is always the main project directory. -{{% note %}} +{{< note >}} If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project. -{{% /note %}} +{{< /note >}} ## Examples diff --git a/content/en/functions/lang/Translate.md b/content/en/functions/lang/Translate.md index 48c1345e2..60f2b0337 100644 --- a/content/en/functions/lang/Translate.md +++ b/content/en/functions/lang/Translate.md @@ -20,14 +20,14 @@ If the key is not found in the translation table for the current language, the ` If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string. -{{% note %}} +{{< note >}} To list missing and fallback translations, use the `--printI18nWarnings` flag when building your site. To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`] to `true` in your site configuration. [`enableMissingTranslationPlaceholders`]: /getting-started/configuration/#enablemissingtranslationplaceholders -{{% /note %}} +{{< /note >}} ## Translation tables @@ -76,9 +76,9 @@ privacy = 'prywatność' security = 'bezpieczeństwo' {{< /code-toggle >}} -{{% note %}} +{{< note >}} The examples below use the `T` alias for brevity. -{{% /note %}} +{{< /note >}} When viewing the English language site: @@ -136,9 +136,9 @@ many = '{{ . }} miesięcy' other = '{{ . }} miesiąca' {{< /code-toggle >}} -{{% note %}} +{{< note >}} The examples below use the `T` alias for brevity. -{{% /note %}} +{{< /note >}} When viewing the English language site: @@ -185,9 +185,9 @@ Template code: {{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old. ``` -{{% note %}} +{{< note >}} Translation tables may contain both simple translations and translations with pluralization. -{{% /note %}} +{{< /note >}} ## Reserved keys diff --git a/content/en/functions/math/Counter.md b/content/en/functions/math/Counter.md index 457806b8e..5daf1ea19 100644 --- a/content/en/functions/math/Counter.md +++ b/content/en/functions/math/Counter.md @@ -30,6 +30,6 @@ Use this function to: [`warnf`]: /functions/fmt/warnf/ [`resources.FromString`]: /functions/resources/fromstring/ -{{% note %}} +{{< note >}} Due to concurrency, the value returned in a given template for a given page will vary from one build to the next. You cannot use this function to assign a static id to each page. -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/partials/IncludeCached.md b/content/en/functions/partials/IncludeCached.md index 8b57c3399..ebce49145 100644 --- a/content/en/functions/partials/IncludeCached.md +++ b/content/en/functions/partials/IncludeCached.md @@ -22,11 +22,11 @@ Without a [`return`] statement, the `partialCached` function returns a string of The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. -{{% note %}} +{{< note >}} Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once. Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result. -{{% /note %}} +{{< /note >}} Here is the simplest usage: diff --git a/content/en/functions/resources/Babel.md b/content/en/functions/resources/Babel.md index 757aff780..8fd0c58cc 100644 --- a/content/en/functions/resources/Babel.md +++ b/content/en/functions/resources/Babel.md @@ -10,8 +10,8 @@ action: expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`js.Babel`] instead. [`js.Babel`]: /functions/js/babel/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/functions/resources/ByType.md b/content/en/functions/resources/ByType.md index ba9dcde0c..273460d8c 100644 --- a/content/en/functions/resources/ByType.md +++ b/content/en/functions/resources/ByType.md @@ -23,12 +23,12 @@ The [media type] is typically one of `image`, `text`, `audio`, `video`, or `appl {{ end }} ``` -{{% note %}} +{{< note >}} This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. For page resources, use the [`Resources.ByType`] method on a `Page` object. [`Resources.ByType`]: /methods/page/resources/ -{{% /note %}} +{{< /note >}} [media type]: https://en.wikipedia.org/wiki/Media_type diff --git a/content/en/functions/resources/Copy.md b/content/en/functions/resources/Copy.md index 3be3dfd57..946c83c23 100644 --- a/content/en/functions/resources/Copy.md +++ b/content/en/functions/resources/Copy.md @@ -23,6 +23,6 @@ The relative URL of the new published resource will be: /img/new-image-name.jpg ``` -{{% note %}} +{{< note >}} Use the `resources.Copy` function with global, page, and remote resources. -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/resources/Get.md b/content/en/functions/resources/Get.md index c6450febf..1702b0415 100644 --- a/content/en/functions/resources/Get.md +++ b/content/en/functions/resources/Get.md @@ -21,10 +21,10 @@ action: {{ end }} ``` -{{% note %}} +{{< note >}} This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. For page resources, use the [`Resources.Get`] method on a `Page` object. [`Resources.Get`]: /methods/page/resources/ -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/resources/GetMatch.md b/content/en/functions/resources/GetMatch.md index 7af2e7be8..81f430706 100644 --- a/content/en/functions/resources/GetMatch.md +++ b/content/en/functions/resources/GetMatch.md @@ -21,13 +21,13 @@ action: {{ end }} ``` -{{% note %}} +{{< note >}} This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. For page resources, use the [`Resources.GetMatch`] method on a `Page` object. [`Resources.GetMatch`]: /methods/page/resources/ -{{% /note %}} +{{< /note >}} Hugo determines a match using a case-insensitive [glob pattern]. diff --git a/content/en/functions/resources/GetRemote.md b/content/en/functions/resources/GetRemote.md index 3b294e5a1..a617a0ccd 100644 --- a/content/en/functions/resources/GetRemote.md +++ b/content/en/functions/resources/GetRemote.md @@ -69,11 +69,11 @@ The `resources.GetRemote` function takes an optional map of options. ## Options examples -{{% note %}} +{{< note >}} For brevity, the examples below do not include [error handling]. [error handling]: #error-handling -{{% /note %}} +{{< /note >}} To include a header: @@ -148,7 +148,7 @@ When retrieving remote data, use the [`transform.Unmarshal`] function to [unmars {{ end }} ``` -{{% note %}} +{{< note >}} When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`. In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead: @@ -156,7 +156,7 @@ In these cases, pass the resource `Content` through the `transform.Unmarshal` fu `{{ $data = .Content | transform.Unmarshal }}` [Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type -{{% /note %}} +{{< /note >}} ## Error handling @@ -164,9 +164,9 @@ Use the [`try`] statement to capture HTTP request errors. If you do not handle t [`try`]: /functions/go-template/try -{{% note %}} +{{< note >}} Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil. -{{% /note %}} +{{< /note >}} ```go-html-template {{ $url := "https://broken-example.org/images/a.jpg" }} diff --git a/content/en/functions/resources/Match.md b/content/en/functions/resources/Match.md index 3e65555ba..dd163180c 100644 --- a/content/en/functions/resources/Match.md +++ b/content/en/functions/resources/Match.md @@ -21,13 +21,13 @@ action: {{ end }} ``` -{{% note %}} +{{< note >}} This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. For page resources, use the [`Resources.Match`] method on a `Page` object. [`Resources.Match`]: /methods/page/resources/ -{{% /note %}} +{{< /note >}} Hugo determines a match using a case-insensitive [glob pattern]. diff --git a/content/en/functions/resources/PostCSS.md b/content/en/functions/resources/PostCSS.md index 5d3f85a30..faa328dc2 100644 --- a/content/en/functions/resources/PostCSS.md +++ b/content/en/functions/resources/PostCSS.md @@ -10,8 +10,8 @@ action: expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`css.PostCSS`] instead. [`css.PostCSS`]: /functions/css/postcss/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/functions/resources/PostProcess.md b/content/en/functions/resources/PostProcess.md index b157d5fd9..7c4116995 100644 --- a/content/en/functions/resources/PostProcess.md +++ b/content/en/functions/resources/PostProcess.md @@ -85,9 +85,9 @@ module.exports = { }; {{< /code >}} -{{% note %}} +{{< note >}} {{% include "functions/resources/_common/postcss-windows-warning.md" %}} -{{% /note %}} +{{< /note >}} Step 5 : Place your CSS file within the `assets/css` directory. diff --git a/content/en/functions/resources/ToCSS.md b/content/en/functions/resources/ToCSS.md index 54c34a6b0..8cbb7faff 100644 --- a/content/en/functions/resources/ToCSS.md +++ b/content/en/functions/resources/ToCSS.md @@ -10,8 +10,8 @@ action: expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`css.Sass`] instead. [`css.Sass`]: /functions/css/sass/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/functions/safe/CSS.md b/content/en/functions/safe/CSS.md index 5d67789b6..2e7c0eac7 100644 --- a/content/en/functions/safe/CSS.md +++ b/content/en/functions/safe/CSS.md @@ -51,9 +51,9 @@ Hugo renders the above to:

foo

``` -{{% note %}} +{{< note >}} `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. -{{% /note %}} +{{< /note >}} To declare the string as safe: diff --git a/content/en/functions/safe/URL.md b/content/en/functions/safe/URL.md index e4b3224da..b38d67e59 100644 --- a/content/en/functions/safe/URL.md +++ b/content/en/functions/safe/URL.md @@ -50,9 +50,9 @@ Hugo renders the above to: IRC ``` -{{% note %}} +{{< note >}} `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. -{{% /note %}} +{{< /note >}} To declare the string as safe: diff --git a/content/en/functions/strings/FindRESubmatch.md b/content/en/functions/strings/FindRESubmatch.md index 3feb15bbd..a149f892a 100644 --- a/content/en/functions/strings/FindRESubmatch.md +++ b/content/en/functions/strings/FindRESubmatch.md @@ -85,6 +85,6 @@ https://example.org https://gohugo.io ``` -{{% note %}} +{{< note >}} You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/strings/FindRe.md b/content/en/functions/strings/FindRe.md index 861f38a12..fd2180539 100644 --- a/content/en/functions/strings/FindRe.md +++ b/content/en/functions/strings/FindRe.md @@ -31,6 +31,6 @@ To limit the number of matches to one: {{ findRE `(?s).*?` .Content 1 }} ``` -{{% note %}} +{{< note >}} You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/strings/ReplaceRE.md b/content/en/functions/strings/ReplaceRE.md index 1c32c34fb..d92e81ef4 100644 --- a/content/en/functions/strings/ReplaceRE.md +++ b/content/en/functions/strings/ReplaceRE.md @@ -35,9 +35,9 @@ Use `$1`, `$2`, etc. within the replacement string to insert the content of each {{ replaceRE "^https?://([^/]+).*" "$1" $s }} → gohugo.io ``` -{{% note %}} +{{< note >}} You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. -{{% /note %}} +{{< /note >}} [RE2]: https://github.com/google/re2/wiki/Syntax [string literal]: https://go.dev/ref/spec#String_literals diff --git a/content/en/functions/strings/Split.md b/content/en/functions/strings/Split.md index ccc5f53a2..8a99d780f 100644 --- a/content/en/functions/strings/Split.md +++ b/content/en/functions/strings/Split.md @@ -19,8 +19,8 @@ Examples: {{ split "abc" "" }} → ["a", "b", "c"] ``` -{{% note %}} +{{< note >}} The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice. [`collections.Delimit`]: /functions/collections/delimit/ -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/strings/Truncate.md b/content/en/functions/strings/Truncate.md index 2e7693eb5..d48303eaf 100644 --- a/content/en/functions/strings/Truncate.md +++ b/content/en/functions/strings/Truncate.md @@ -17,8 +17,8 @@ Since Go templates are HTML-aware, `truncate` will intelligently handle normal s {{ "Keep my HTML" | safeHTML | truncate 10 }} → Keep my … ``` -{{% note %}} +{{< note >}} If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. [`safeHTML`]: /functions/safe/html/ -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/templates/Defer.md b/content/en/functions/templates/Defer.md index c43ef43bf..35dc1c1a2 100644 --- a/content/en/functions/templates/Defer.md +++ b/content/en/functions/templates/Defer.md @@ -42,13 +42,13 @@ In some rare use cases, you may need to defer the execution of a template until {{ end }} ``` -{{% note %}} +{{< note >}} This function only works in combination with the `with` keyword. -{{% /note %}} +{{< /note >}} -{{% note %}} +{{< note >}} Variables defined on the outside are not visible on the inside and vice versa. To pass in data, use the `data` [option](#options). -{{% /note %}} +{{< /note >}} For the above to work well when running the server (or `hugo -w`), you want to have a configuration similar to this: diff --git a/content/en/functions/transform/Markdownify.md b/content/en/functions/transform/Markdownify.md index 7a84f43b7..151e63cbb 100644 --- a/content/en/functions/transform/Markdownify.md +++ b/content/en/functions/transform/Markdownify.md @@ -23,9 +23,9 @@ To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] m [`RenderString`]: /methods/page/renderstring/ -{{% note %}} +{{< note >}} Although the `markdownify` function honors [Markdown render hooks] when rendering Markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details. [Markdown render hooks]: /render-hooks/ [#9692]: https://github.com/gohugoio/hugo/issues/9692 -{{% /note %}} +{{< /note >}} diff --git a/content/en/functions/transform/Remarshal.md b/content/en/functions/transform/Remarshal.md index 24ef4381d..8d45d1fe6 100644 --- a/content/en/functions/transform/Remarshal.md +++ b/content/en/functions/transform/Remarshal.md @@ -15,11 +15,11 @@ aliases: [/functions/transform.remarshal] The format must be one of `json`, `toml`, `yaml`, or `xml`. If the input is a string of serialized data, it must be valid JSON, TOML, YAML, or XML. -{{% note %}} +{{< note >}} This function is primarily a helper for Hugo's documentation, used to convert configuration and front matter examples to JSON, TOML, and YAML. This is not a general purpose converter, and may change without notice if required for Hugo's documentation site. -{{% /note %}} +{{< /note >}} Example 1 : Convert a string of TOML to JSON. diff --git a/content/en/functions/transform/ToMath.md b/content/en/functions/transform/ToMath.md index 9b40e1498..d27cde103 100644 --- a/content/en/functions/transform/ToMath.md +++ b/content/en/functions/transform/ToMath.md @@ -23,14 +23,14 @@ Hugo uses an embedded instance of the [KaTeX] display engine to render mathemati {{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }} ``` -{{% note %}} +{{< note >}} By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result. [MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet. -{{% /note %}} +{{< /note >}} ```go-html-template {{ $opts := dict "output" "htmlAndMathml" }} @@ -109,9 +109,9 @@ block = [['\[', '\]'], ['$$', '$$']] inline = [['\(', '\)']] {{< /code-toggle >}} -{{% note %}} +{{< note >}} The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. -{{% /note %}} +{{< /note >}} ###### Step 2 diff --git a/content/en/functions/transform/Unmarshal.md b/content/en/functions/transform/Unmarshal.md index e50fc0ee0..22390fd72 100644 --- a/content/en/functions/transform/Unmarshal.md +++ b/content/en/functions/transform/Unmarshal.md @@ -112,7 +112,7 @@ A remote resource is a file on a remote server, accessible via HTTP or HTTPS. {{ end }} ``` -{{% note %}} +{{< note >}} When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`. In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead: @@ -120,7 +120,7 @@ In these cases, pass the resource `Content` through the `transform.Unmarshal` fu `{{ $data = .Content | transform.Unmarshal }}` [Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type -{{% /note %}} +{{< /note >}} ## Options diff --git a/content/en/getting-started/configuration-build.md b/content/en/getting-started/configuration-build.md index 791d4bb99..ad081e7d9 100644 --- a/content/en/getting-started/configuration-build.md +++ b/content/en/getting-started/configuration-build.md @@ -74,12 +74,12 @@ If `enable` is set to `true`, creates a `hugo_stats.json` file in the root of yo Exclude `class` attributes, `id` attributes, or tags from `hugo_stats.json` with the `disableClasses`, `disableIDs`, and `disableTags` keys. -{{% note %}} +{{< note >}} Given that CSS purging is typically limited to production builds, place the `buildStats` object below [`config/production`]. [`config/production`]: /getting-started/configuration/#configuration-directory Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential. -{{% /note %}} +{{< /note >}} Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build. diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md index ef885e44b..9205d0fd1 100644 --- a/content/en/getting-started/configuration-markup.md +++ b/content/en/getting-started/configuration-markup.md @@ -35,12 +35,12 @@ defaultMarkdownHandler|Description To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy]. -{{% note %}} +{{< note >}} Unless you need a unique capability provided by one of the alternative Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM). [commonmark]: https://spec.commonmark.org/0.30/ [github flavored markdown]: https://github.github.com/gfm/ -{{% /note %}} +{{< /note >}} [asciidoc]: https://asciidoc.org/ [content format]: /content-management/formats/#formats @@ -159,12 +159,12 @@ Most of the Goldmark settings above are self-explanatory, but some require expla [multilingual page resources]: /content-management/page-resources/#multilingual -{{% note %}} +{{< note >}} With multilingual single-host sites, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host sites. [embedded image render hook]: /render-hooks/images/#default [embedded link render hook]: /render-hooks/links/#default -{{% /note %}} +{{< /note >}} ###### parser.wrapStandAloneImageWithinParagraph @@ -200,11 +200,11 @@ This is also the strategy used by the [anchorize](/functions/urls/anchorize) tem [embedded image render hook]: /render-hooks/images/#default -{{% note %}} +{{< note >}} The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. [duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles -{{% /note %}} +{{< /note >}} ###### renderHooks.link.enableDefault @@ -214,11 +214,11 @@ The embedded image render hook is automatically enabled for multilingual single- [embedded link render hook]: /render-hooks/links/#default -{{% note %}} +{{< note >}} The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. [duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles -{{% /note %}} +{{< /note >}} ###### renderer.hardWraps @@ -250,9 +250,9 @@ This is the default configuration for the AsciiDoc renderer: (`string array`) An array of enabled extensions, one or more of `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, or `asciidoctor-question`. -{{% note %}} +{{< note >}} To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`. -{{% /note %}} +{{< /note >}} ###### failureLevel diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 23376f68f..79842f26f 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -22,9 +22,9 @@ my-project/ └── hugo.toml ``` -{{% note %}} +{{< note >}} With v0.109.0 and earlier the basename of the site configuration file was `config` instead of `hugo`. You can use either, but should transition to the new naming convention when practical. -{{% /note %}} +{{< /note >}} A simple example: @@ -51,13 +51,13 @@ Combine two or more configuration files, with left-to-right precedence: hugo --config a.toml,b.yaml,c.json ``` -{{% note %}} +{{< note >}} See the specifications for each file format: [TOML], [YAML], and [JSON]. [TOML]: https://toml.io/en/latest [YAML]: https://yaml.org/spec/ [JSON]: https://datatracker.ietf.org/doc/html/rfc7159 -{{% /note %}} +{{< /note >}} ## Configuration directory @@ -242,11 +242,11 @@ See [Configure File Caches](#configure-file-caches). Pass down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#cascade). -{{% note %}} +{{< note >}} For a website in a single language, define the `[[cascade]]` in [Front Matter](/content-management/front-matter#cascade). For a multilingual website, define the `[[cascade]]` in [Site Config](/getting-started/configuration/#cascade). To remain consistent and prevent unexpected behavior, do not mix these strategies. -{{% /note %}} +{{< /note >}} ###### cleanDestinationDir @@ -547,7 +547,7 @@ See [module configuration](/hugo-modules/configuration/#module-configuration-imp (`bool`) Watch filesystem for changes and recreate as needed. Default is `false`. -{{% note %}} +{{< note >}} If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line: ```txt cd ~/sites/yourhugosite @@ -559,7 +559,7 @@ which shows output like ```txt enableemoji: true ``` -{{% /note %}} +{{< /note >}} ## Configure page @@ -598,12 +598,12 @@ To sort all fields in ascending order: nextPrevSortOrder = 'asc' {{< /code-toggle >}} -{{% note %}} +{{< note >}} These settings do not apply to the [`Next`] or [`Prev`] methods on a `Pages` object. [`Next`]: /methods/pages/next [`Prev`]: /methods/pages/next -{{% /note %}} +{{< /note >}} ## Configure build @@ -754,19 +754,19 @@ $ env HUGO_TITLE="Some Title" hugo This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs [Netlify configuration file](https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml) for an example. -{{% note %}} +{{< note >}} Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables. To set configuration parameters, prefix the name with `HUGO_PARAMS_` -{{% /note %}} +{{< /note >}} If you are using snake_cased variable names, the above will not work. Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter. ## Ignore content and data files when rendering -{{% note %}} +{{< note >}} This works, but we recommend you use the newer and more powerful [includeFiles and excludeFiles](/hugo-modules/configuration/#module-configuration-mounts) mount options. -{{% /note %}} +{{< /note >}} To exclude specific files from the `content`, `data`, and `i18n` directories when rendering your site, set `ignoreFiles` to one or more regular expressions to match against the absolute file path. @@ -938,11 +938,11 @@ polling {{< new-in 0.124.0 />}} -{{% note %}} +{{< note >}} The `segments` configuration is currently only used to configure partitioned rendering. This feature is only about what gets rendered when, Hugo's entire object graph (sites and pages) is always available. -{{% /note %}} +{{< /note >}} * Each segment consists of zero or more `exclude` filters and zero or more `include` filters. * Each filter consists of one or more field Glob matchers. diff --git a/content/en/getting-started/directory-structure.md b/content/en/getting-started/directory-structure.md index ce1df600f..246c30e63 100644 --- a/content/en/getting-started/directory-structure.md +++ b/content/en/getting-started/directory-structure.md @@ -158,11 +158,11 @@ source = '/home/user/shared-content' target = 'content' {{< /code-toggle >}} -{{% note %}} +{{< note >}} When you overlay one directory on top of another, you must mount both directories. Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's union file system instead. -{{% /note %}} +{{< /note >}} After mounting, the union file system has this structure: @@ -185,9 +185,9 @@ home/ └── hugo.toml ``` -{{% note %}} +{{< note >}} When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's `content` directory was mounted first. -{{% /note %}} +{{< /note >}} You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/hugo-modules/configuration/#module-configuration-mounts). diff --git a/content/en/getting-started/quick-start.md b/content/en/getting-started/quick-start.md index cb22e0121..0ffcbabd0 100644 --- a/content/en/getting-started/quick-start.md +++ b/content/en/getting-started/quick-start.md @@ -33,7 +33,7 @@ You must also be comfortable working from the command line. ### Commands -{{% note %}} +{{< note >}} **If you are a Windows user:** - Do not use the Command Prompt @@ -44,7 +44,7 @@ PowerShell and Windows PowerShell [are different applications]. [PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows [are different applications]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3 -{{% /note %}} +{{< /note >}} Verify that you have installed Hugo {{% param "minVersion" %}} or later. @@ -153,12 +153,12 @@ View your site at the URL displayed in your terminal. Keep the development serve When satisfied with your new content, set the front matter `draft` parameter to `false`. -{{% note %}} +{{< note >}} Hugo's rendering engine conforms to the CommonMark [specification] for Markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation. [live testing tool]: https://spec.commonmark.org/dingus/ [specification]: https://spec.commonmark.org/ -{{% /note %}} +{{< /note >}} ## Configure the site @@ -183,7 +183,7 @@ Start Hugo's development server to see your changes, remembering to include draf hugo server -D ``` -{{% note %}} +{{< note >}} Most theme authors provide configuration guidelines and options. Make sure to visit your theme's repository or documentation site for details. [The New Dynamic], authors of the Ananke theme, provide [documentation] for configuration and usage. They also provide a [demonstration site]. @@ -191,7 +191,7 @@ Most theme authors provide configuration guidelines and options. Make sure to vi [demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/ [documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme [The New Dynamic]: https://www.thenewdynamic.com/ -{{% /note %}} +{{< /note >}} ## Publish the site diff --git a/content/en/getting-started/usage.md b/content/en/getting-started/usage.md index 3380b0ff2..9cf619ed5 100644 --- a/content/en/getting-started/usage.md +++ b/content/en/getting-started/usage.md @@ -50,11 +50,11 @@ hugo The [`hugo`] command builds your site, publishing the files to the `public` directory. To publish your site to a different directory, use the [`--destination`] flag or set [`publishDir`] in your site configuration. -{{% note %}} +{{< note >}} Hugo does not clear the `public` directory before building your site. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build. Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build. -{{% /note %}} +{{< /note >}} ## Draft, future, and expired content @@ -67,12 +67,12 @@ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [ {{< new-in 0.123.0 />}} -{{% note %}} +{{< note >}} Hugo publishes descendants of draft, future, and expired [node](g) pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages. [build options]: /content-management/build-options/ [`cascade`]: /content-management/front-matter/#cascade-field -{{% /note %}} +{{< /note >}} You can override the default behavior when running `hugo` or `hugo server` with command line flags: @@ -84,11 +84,11 @@ hugo --buildFuture # or -F Although you can also set these values in your site configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings. -{{% note %}} +{{< note >}} As noted above, Hugo does not clear the `public` directory before building your site. Depending on the _current_ evaluation of the four conditions above, after the build your `public` directory may contain extraneous files from a previous build. A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content. -{{% /note %}} +{{< /note >}} ## Develop and test your site @@ -122,9 +122,9 @@ hugo server --navigateToChanged ## Deploy your site -{{% note %}} +{{< note >}} As noted above, Hugo does not clear the `public` directory before building your site. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content. -{{% /note %}} +{{< /note >}} When you are ready to deploy your site, run: diff --git a/content/en/hosting-and-deployment/hosting-on-firebase.md b/content/en/hosting-and-deployment/hosting-on-firebase.md index 028964bcf..1612a248d 100644 --- a/content/en/hosting-and-deployment/hosting-on-firebase.md +++ b/content/en/hosting-and-deployment/hosting-on-firebase.md @@ -91,9 +91,9 @@ firebase login:ci You can also set up your CI and add the token to a private variable like `$FIREBASE_DEPLOY_TOKEN`. -{{% note %}} +{{< note >}} This is a private secret and it should not appear in a public repository. Make sure you understand your chosen CI and that it's not visible to others. -{{% /note %}} +{{< /note >}} You can then add a step in your build to do the deployment using the token: diff --git a/content/en/hosting-and-deployment/hosting-on-github/index.md b/content/en/hosting-and-deployment/hosting-on-github/index.md index 81d6a4c87..77c77d7f3 100644 --- a/content/en/hosting-and-deployment/hosting-on-github/index.md +++ b/content/en/hosting-and-deployment/hosting-on-github/index.md @@ -26,11 +26,11 @@ Please complete the following tasks before continuing: There are three types of GitHub Pages sites: project, user, and organization. Project sites are connected to a specific project hosted on GitHub. User and organization sites are connected to a specific account on GitHub.com. -{{% note %}} +{{< note >}} See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming. [GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites -{{% /note %}} +{{< /note >}} [GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites diff --git a/content/en/hosting-and-deployment/hugo-deploy.md b/content/en/hosting-and-deployment/hugo-deploy.md index f33dab50e..a7a92f7da 100644 --- a/content/en/hosting-and-deployment/hugo-deploy.md +++ b/content/en/hosting-and-deployment/hugo-deploy.md @@ -13,11 +13,11 @@ toc: true Use the `hugo deploy` command to deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or an Azure Storage container -{{% note %}} +{{< note >}} This feature requires the Hugo extended/deploy edition. See the [installation] section for details. [installation]: /installation/ -{{% /note %}} +{{< /note >}} ## Assumptions @@ -93,7 +93,7 @@ the [deployment target's configuration][config] -- * If the configuration specifies an `exclude` pattern, files matching the pattern are skipped. -{{% note %}} +{{< note >}} When creating the local file list, a few additional skips apply: first, Hugo always skips files named `.DS_Store`. @@ -102,7 +102,7 @@ Second, Hugo always skips local hidden directories traverse into them, except for the special [hidden directory named `.well-known`](https://en.wikipedia.org/wiki/Well-known_URI), which is traversed if it exists. -{{% /note %}} +{{< /note >}} ### How the local and remote file lists are compared @@ -117,11 +117,11 @@ if Hugo cannot detect any differences between local and remote. Files are deleted from the remote bucket if they are not present in the local file list. -{{% note %}} +{{< note >}} If a remote file is excluded from the file list generation using the exclude/include configs, then the comparison step will not know to delete the file -- so it will remain on the remote even if it isn't present locally. -{{% /note %}} +{{< /note >}} If the [`--confirm` or `--dryRun` flags][commandline] are given, Hugo displays what differences it has found and either pauses or stops here. @@ -133,11 +133,11 @@ changed files are uploaded, and files missing locally but present remotely are deleted. As files are uploaded, their headers are also configured on the remote according to the matchers configuration. -{{% note %}} +{{< note >}} As a safety measure to help prevent accidents, if there are more than 256 files to delete, Hugo won't delete any files from the remote. Use the `--maxDeletes` command line flag to override this. -{{% /note %}} +{{< /note >}} ## Advanced configuration diff --git a/content/en/hugo-modules/configuration.md b/content/en/hugo-modules/configuration.md index 0bc1b47d8..b99de0e9c 100644 --- a/content/en/hugo-modules/configuration.md +++ b/content/en/hugo-modules/configuration.md @@ -112,13 +112,13 @@ noVendor ## Module configuration: mounts -{{% note %}} +{{< note >}} When the `mounts` configuration was introduced in Hugo 0.56.0, we were careful to preserve the existing `contentDir`, `staticDir`, and similar configuration to make sure all existing sites just continued to work. But you should not have both: if you add a `mounts` section you should remove the old `contentDir`, `staticDir`, etc. settings. -{{% /note %}} +{{< /note >}} -{{% note %}} +{{< note >}} When you add a mount, the default mount for the concerned target root is ignored: be sure to explicitly add it. -{{% /note %}} +{{< /note >}} ### Default mounts diff --git a/content/en/hugo-modules/theme-components.md b/content/en/hugo-modules/theme-components.md index 9e52620ce..e167239e3 100644 --- a/content/en/hugo-modules/theme-components.md +++ b/content/en/hugo-modules/theme-components.md @@ -12,9 +12,9 @@ aliases: [/themes/customize/,/themes/customizing/] toc: true --- -{{% note %}} +{{< note >}} This section contain information that may be outdated and is in the process of being rewritten. -{{% /note %}} +{{< /note >}} Since Hugo `0.42` a project can configure a theme as a composite of as many theme components you need: {{< code-toggle file=hugo >}} diff --git a/content/en/installation/linux.md b/content/en/installation/linux.md index ba59d0f2a..e2c8dc5ea 100644 --- a/content/en/installation/linux.md +++ b/content/en/installation/linux.md @@ -59,13 +59,13 @@ sudo snap disconnect hugo:ssh-keys Most Linux distributions maintain a repository for commonly installed applications. -{{% note %}} +{{< note >}} The Hugo version available in package repositories varies based on Linux distribution and release, and in some cases will not be the [latest version]. Use one of the other installation methods if your package repository does not provide the desired version. [latest version]: https://github.com/gohugoio/hugo/releases/latest -{{% /note %}} +{{< /note >}} ### Alpine Linux diff --git a/content/en/installation/windows.md b/content/en/installation/windows.md index e66878d70..435afd955 100644 --- a/content/en/installation/windows.md +++ b/content/en/installation/windows.md @@ -11,9 +11,9 @@ weight: 40 toc: true --- -{{% note %}} +{{< note >}} Hugo v0.121.1 and later require at least Windows 10 or Windows Server 2016. -{{% /note %}} +{{< /note >}} ## Editions @@ -65,9 +65,9 @@ winget uninstall --name "Hugo (Extended)" {{% include "installation/_common/04-build-from-source.md" %}} -{{% note %}} +{{< note >}} See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows. -{{% /note %}} +{{< /note >}} ## Comparison diff --git a/content/en/methods/menu-entry/Identifier.md b/content/en/methods/menu-entry/Identifier.md index ba8b77ece..ec7007f56 100644 --- a/content/en/methods/menu-entry/Identifier.md +++ b/content/en/methods/menu-entry/Identifier.md @@ -37,8 +37,8 @@ This example uses the `Identifier` method when querying the translation table on ``` -{{% note %}} +{{< note >}} In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. [details]: /content-management/menus/#properties-front-matter -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/menu-entry/PageRef.md b/content/en/methods/menu-entry/PageRef.md index 368579796..9e53d2599 100644 --- a/content/en/methods/menu-entry/PageRef.md +++ b/content/en/methods/menu-entry/PageRef.md @@ -31,11 +31,11 @@ If a matching page is not found: - The [`Page`] method returns nil - The [`HasMenuCurrent`] and [`IsMenuCurrent`] methods on a `Page` object return `false` -{{% note %}} +{{< note >}} In almost also scenarios you should use the [`URL`] method instead. [`URL`]: /methods/menu-entry/url/ -{{% /note %}} +{{< /note >}} [defining a menu entry]: /content-management/menus/#define-in-site-configuration [`Page`]: /methods/menu-entry/page/ @@ -48,11 +48,11 @@ In almost also scenarios you should use the [`URL`] method instead. This example is contrived. -{{% note %}} +{{< note >}} In almost also scenarios you should use the [`URL`] method instead. [`URL`]: /methods/menu-entry/url/ -{{% /note %}} +{{< /note >}} Consider this content structure: diff --git a/content/en/methods/menu/ByWeight.md b/content/en/methods/menu/ByWeight.md index 7ba27031a..d55c8544f 100644 --- a/content/en/methods/menu/ByWeight.md +++ b/content/en/methods/menu/ByWeight.md @@ -53,11 +53,11 @@ Hugo renders this to: ``` -{{% note %}} +{{< note >}} In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. [details]: /content-management/menus/#properties-front-matter -{{% /note %}} +{{< /note >}} You can also sort menu entries using the [`sort`] function. For example, to sort by `weight` in descending order: diff --git a/content/en/methods/page/CurrentSection.md b/content/en/methods/page/CurrentSection.md index 1684ee483..980526905 100644 --- a/content/en/methods/page/CurrentSection.md +++ b/content/en/methods/page/CurrentSection.md @@ -18,9 +18,9 @@ action: {{% glossary-term section %}} -{{% note %}} +{{< note >}} The current section of a [section page](g), [taxonomy page](g), [term page](g), or the home page, is itself. -{{% /note %}} +{{< /note >}} Consider this content structure: diff --git a/content/en/methods/page/Data.md b/content/en/methods/page/Data.md index b3df243c5..1e3a262bd 100644 --- a/content/en/methods/page/Data.md +++ b/content/en/methods/page/Data.md @@ -12,7 +12,7 @@ toc: true The `Data` method on a `Page` object returns a unique data object for each [page kind](g). -{{% note %}} +{{< note >}} The `Data` method is only useful within [taxonomy](g) and [term](g) templates. Themes that are not actively maintained may still use `.Data.Pages` in list templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`] @@ -20,7 +20,7 @@ Themes that are not actively maintained may still use `.Data.Pages` in list temp [`Pages`]: /methods/page/pages/ [`RegularPages`]: /methods/page/regularpages/ [`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/ -{{% /note %}} +{{< /note >}} The examples that follow are based on this site configuration: @@ -67,11 +67,11 @@ Terms {{ $taxonomyObject := .Data.Terms }} ``` -{{% note %}} +{{< note >}} Once you have captured the `Taxonomy` object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages. [taxonomy methods]: /methods/taxonomy/ -{{% /note %}} +{{< /note >}} Learn more about [taxonomy templates]. diff --git a/content/en/methods/page/Date.md b/content/en/methods/page/Date.md index 113d6ca09..b16edaeb6 100644 --- a/content/en/methods/page/Date.md +++ b/content/en/methods/page/Date.md @@ -19,11 +19,11 @@ title = 'Article 1' date = 2023-10-19T00:40:04-07:00 {{< /code-toggle >}} -{{% note %}} +{{< note >}} The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your site, in the site configuration. See [details]. [details]: /getting-started/configuration/#configure-dates -{{% /note %}} +{{< /note >}} The date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods]. diff --git a/content/en/methods/page/File.md b/content/en/methods/page/File.md index 359c1ad2e..85fdf88a1 100644 --- a/content/en/methods/page/File.md +++ b/content/en/methods/page/File.md @@ -22,15 +22,15 @@ content/ └── book-2.md ``` -{{% note %}} +{{< note >}} Code defensively by verifying file existence as shown in the examples below. -{{% /note %}} +{{< /note >}} ## Methods -{{% note %}} +{{< note >}} The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system. -{{% /note %}} +{{< /note >}} ###### BaseFileName diff --git a/content/en/methods/page/FirstSection.md b/content/en/methods/page/FirstSection.md index 29fbdc841..abc286443 100644 --- a/content/en/methods/page/FirstSection.md +++ b/content/en/methods/page/FirstSection.md @@ -18,9 +18,9 @@ action: {{% glossary-term section %}} -{{% note %}} +{{< note >}} When called on the home page, the `FirstSection` method returns the `Page` object of the home page itself. -{{% /note %}} +{{< /note >}} Consider this content structure: diff --git a/content/en/methods/page/Fragments.md b/content/en/methods/page/Fragments.md index 581cbf7c3..e0c2a51da 100644 --- a/content/en/methods/page/Fragments.md +++ b/content/en/methods/page/Fragments.md @@ -88,11 +88,14 @@ Hugo renders this to: ``` -{{% note %}} +{{< note >}} It is safe to use the `Fragments` methods within a render hook, even for the current page. -When using the `Fragments` methods within a shortcode, call the shortcode using the `{{}}` notation. If you use the `{{%/* */%}}` notation, the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop. -{{% /note %}} +When using the `Fragments` methods within a shortcode, call the shortcode using [standard notation]. If you use [Markdown notation] the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop. + +[Markdown notation]: /content-management/shortcodes/#notation +[standard notation]: /content-management/shortcodes/#notation +{{< /note >}} [atx]: https://spec.commonmark.org/0.30/#atx-headings [setext]: https://spec.commonmark.org/0.30/#setext-headings diff --git a/content/en/methods/page/GitInfo.md b/content/en/methods/page/GitInfo.md index a05916d79..6aa85a2ca 100644 --- a/content/en/methods/page/GitInfo.md +++ b/content/en/methods/page/GitInfo.md @@ -13,9 +13,9 @@ toc: true The `GitInfo` method on a `Page` object returns an object with additional methods. -{{% note %}} +{{< note >}} Hugo's Git integration is performant, but may increase build times on large sites. -{{% /note %}} +{{< /note >}} ## Prerequisites @@ -33,13 +33,13 @@ Alternatively, use the command line flag when building your site: hugo --enableGitInfo ``` -{{% note %}} +{{< note >}} When you set `enableGitInfo` to `true`, or enable the feature with the command line flag, the last modification date for each content page will be the Author Date of the last commit for that file. This is configurable. See [details]. [details]: /getting-started/configuration/#configure-dates -{{% /note %}} +{{< /note >}} ## Methods diff --git a/content/en/methods/page/HasMenuCurrent.md b/content/en/methods/page/HasMenuCurrent.md index 24ce462c9..87dc069fc 100644 --- a/content/en/methods/page/HasMenuCurrent.md +++ b/content/en/methods/page/HasMenuCurrent.md @@ -28,8 +28,8 @@ If the `Page` object associated with the menu entry is a section, this method al See [menu templates] for a complete example. -{{% note %}} +{{< note >}} When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration. -{{% /note %}} +{{< /note >}} [menu templates]: /templates/menu/#example diff --git a/content/en/methods/page/InSection.md b/content/en/methods/page/InSection.md index 904f6ce75..45e39f18b 100644 --- a/content/en/methods/page/InSection.md +++ b/content/en/methods/page/InSection.md @@ -83,9 +83,9 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. -{{% note %}} +{{< note >}} Use the `$` to get the context passed into the template. -{{% /note %}} +{{< /note >}} ```go-html-template {{ with .Site.GetPage "/auctions" }} @@ -93,9 +93,9 @@ Use the `$` to get the context passed into the template. {{ end }} ``` -{{% note %}} +{{< note >}} Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +{{< /note >}} [`with`]: /functions/go-template/with/ [`else`]: /functions/go-template/else/ diff --git a/content/en/methods/page/IsAncestor.md b/content/en/methods/page/IsAncestor.md index 2613a2875..62db658b9 100644 --- a/content/en/methods/page/IsAncestor.md +++ b/content/en/methods/page/IsAncestor.md @@ -81,9 +81,9 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. -{{% note %}} +{{< note >}} Use the `$` to get the context passed into the template. -{{% /note %}} +{{< /note >}} ```go-html-template {{ with .Site.GetPage "/auctions" }} @@ -91,9 +91,9 @@ Use the `$` to get the context passed into the template. {{ end }} ``` -{{% note %}} +{{< note >}} Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +{{< /note >}} [`with`]: /functions/go-template/with/ [`else`]: /functions/go-template/else/ diff --git a/content/en/methods/page/IsDescendant.md b/content/en/methods/page/IsDescendant.md index 4ef7c6598..719497ead 100644 --- a/content/en/methods/page/IsDescendant.md +++ b/content/en/methods/page/IsDescendant.md @@ -80,9 +80,9 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. -{{% note %}} +{{< note >}} Use the `$` to get the context passed into the template. -{{% /note %}} +{{< /note >}} ```go-html-template {{ with .Site.GetPage "/auctions" }} @@ -90,9 +90,9 @@ Use the `$` to get the context passed into the template. {{ end }} ``` -{{% note %}} +{{< note >}} Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +{{< /note >}} [`with`]: /functions/go-template/with/ [`else`]: /functions/go-template/else/ diff --git a/content/en/methods/page/IsMenuCurrent.md b/content/en/methods/page/IsMenuCurrent.md index a16be51ee..9d387c6eb 100644 --- a/content/en/methods/page/IsMenuCurrent.md +++ b/content/en/methods/page/IsMenuCurrent.md @@ -26,8 +26,8 @@ aliases: [/functions/ismenucurrent] See [menu templates] for a complete example. -{{% note %}} +{{< note >}} When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration. -{{% /note %}} +{{< /note >}} [menu templates]: /templates/menu/#example diff --git a/content/en/methods/page/Page.md b/content/en/methods/page/Page.md index 1d6867792..0ea49aba5 100644 --- a/content/en/methods/page/Page.md +++ b/content/en/methods/page/Page.md @@ -29,8 +29,8 @@ The page title is: {{ .Page.Title }} To handle both scenarios, the partial template must be able to access the `Page` object with `Page.Page`. -{{% note %}} +{{< note >}} And yes, that means you can do `.Page.Page.Page.Page.Title` too. But don't. -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/page/Pages.md b/content/en/methods/page/Pages.md index 8efcde287..bbe2584f1 100644 --- a/content/en/methods/page/Pages.md +++ b/content/en/methods/page/Pages.md @@ -72,11 +72,11 @@ When rendering lesson-2, the `Pages` method returns: In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section. -{{% note %}} +{{< note >}} When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details]. [details]: /methods/site/pages/ -{{% /note %}} +{{< /note >}} ```go-html-template {{ range .Site.Pages.ByTitle }} diff --git a/content/en/methods/page/Paginate.md b/content/en/methods/page/Paginate.md index 9d98fbb2f..77552ee76 100644 --- a/content/en/methods/page/Paginate.md +++ b/content/en/methods/page/Paginate.md @@ -16,11 +16,11 @@ By default, the number of elements on each pager is determined by your [site con [site configuration]: /getting-started/configuration/#pagination -{{% note %}} +{{< note >}} There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection. The `Paginate` method is more flexible. -{{% /note %}} +{{< /note >}} You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates]. @@ -46,6 +46,6 @@ In the example above, we: 1. Range over the paginated page collection, rendering a link to each page 1. Call the embedded pagination template to create navigation links between pagers -{{% note %}} +{{< note >}} Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/page/Paginator.md b/content/en/methods/page/Paginator.md index c3161da6c..a1d2c91d7 100644 --- a/content/en/methods/page/Paginator.md +++ b/content/en/methods/page/Paginator.md @@ -32,14 +32,14 @@ You can invoke pagination on the [home template], [section templates], [taxonomy In the example above, the embedded pagination template creates navigation links between pagers. -{{% note %}} +{{< note >}} Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context. The [`Paginate`] method is more flexible, and strongly recommended. [`paginate`]: /methods/page/paginate/ -{{% /note %}} +{{< /note >}} -{{% note %}} +{{< note >}} Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/page/Parent.md b/content/en/methods/page/Parent.md index 4c182f8e1..b7ccf234e 100644 --- a/content/en/methods/page/Parent.md +++ b/content/en/methods/page/Parent.md @@ -18,11 +18,11 @@ action: {{% glossary-term section %}} -{{% note %}} +{{< note >}} The parent section of a regular page is the [current section]. [current section]: /methods/page/currentsection/ -{{% /note %}} +{{< /note >}} Consider this content structure: diff --git a/content/en/methods/page/Path.md b/content/en/methods/page/Path.md index 83ad01b94..1d3ea0d8f 100644 --- a/content/en/methods/page/Path.md +++ b/content/en/methods/page/Path.md @@ -22,14 +22,14 @@ The `Path` method on a `Page` object returns the [logical path](g) of the given This value is neither a file path nor a relative URL. It is a logical identifier for each page, independent of content format, language, and URL modifiers. -{{% note %}} +{{< note >}} Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release. The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024. [v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0 [v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0 -{{% /note %}} +{{< /note >}} To determine the logical path for pages backed by a file, Hugo starts with the file path, relative to the `content` directory, and then: @@ -117,9 +117,9 @@ Methods|Functions|Shortcodes [`Shortcode.Ref`]: /methods/shortcode/ref [`Shortcode.RelRef`]: /methods/shortcode/relref -{{% note %}} +{{< note >}} Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree. -{{% /note %}} +{{< /note >}} ## Logical tree @@ -149,6 +149,6 @@ A key difference between these trees is the relative path from p1 to p2: - In the file tree, the relative path from p1 to p2 is `../p2.md` - In the logical tree, the relative path is `p2` -{{% note %}} +{{< note >}} Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree. -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/page/PlainWords.md b/content/en/methods/page/PlainWords.md index 221fd741b..7c7a6f507 100644 --- a/content/en/methods/page/PlainWords.md +++ b/content/en/methods/page/PlainWords.md @@ -17,11 +17,11 @@ action: The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words. -{{% note %}} +{{< note >}} _Fields splits the string s around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only whitespace._ [`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace -{{% /note %}} +{{< /note >}} As a result, elements within the slice may contain leading or trailing punctuation. diff --git a/content/en/methods/page/RawContent.md b/content/en/methods/page/RawContent.md index 9dab9693e..f6e2b3e3a 100644 --- a/content/en/methods/page/RawContent.md +++ b/content/en/methods/page/RawContent.md @@ -23,10 +23,10 @@ The `RawContent` method on a `Page` object returns the raw content. The raw cont This is useful when rendering a page in a plain text [output format]. -{{% note %}} +{{< note >}} [Shortcodes](g) within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object. [`RenderShortcodes`]: /methods/page/rendershortcodes/ -{{% /note %}} +{{< /note >}} [output format]: /templates/output-formats/ diff --git a/content/en/methods/page/RegularPages.md b/content/en/methods/page/RegularPages.md index 08198fca4..6e5d35daa 100644 --- a/content/en/methods/page/RegularPages.md +++ b/content/en/methods/page/RegularPages.md @@ -69,11 +69,11 @@ When rendering lesson-2, the `RegularPages` method returns: In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section. -{{% note %}} +{{< note >}} When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details]. [details]: /methods/site/regularpages/ -{{% /note %}} +{{< /note >}} ```go-html-template {{ range .Site.RegularPages.ByTitle }} diff --git a/content/en/methods/page/RegularPagesRecursive.md b/content/en/methods/page/RegularPagesRecursive.md index 608287171..d9cb26fd4 100644 --- a/content/en/methods/page/RegularPagesRecursive.md +++ b/content/en/methods/page/RegularPagesRecursive.md @@ -81,6 +81,6 @@ When rendering lesson-2, the `RegularPagesRecursive` method returns: lessons/lesson-2/resources/task-list.md lessons/lesson-2/resources/worksheet.md -{{% note %}} +{{< note >}} The `RegularPagesRecursive` method is not available on a `Site` object. -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/page/Scratch.md b/content/en/methods/page/Scratch.md index 436005a94..8dc66bd0b 100644 --- a/content/en/methods/page/Scratch.md +++ b/content/en/methods/page/Scratch.md @@ -10,7 +10,7 @@ action: expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft) --- -{{% deprecated-in 0.138.0 %}} +{{< deprecated-in 0.138.0 >}} Use the [`PAGE.Store`] method instead. This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `PAGE.Store` as soon as possible. @@ -18,4 +18,4 @@ This is a soft deprecation. This method will be removed in a future release, but Beginning with v0.138.0 the `PAGE.Scratch` method is aliased to `PAGE.Store`. [`PAGE.Store`]: /methods/page/store/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/page/Summary.md b/content/en/methods/page/Summary.md index a875d62f0..ce2e03cc6 100644 --- a/content/en/methods/page/Summary.md +++ b/content/en/methods/page/Summary.md @@ -45,6 +45,6 @@ Depending on content length and how you define the summary, the summary may be e {{ end }} ``` -{{% note %}} +{{< note >}} The `Truncated` method returns `false` if you define the summary in front matter. -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/page/Truncated.md b/content/en/methods/page/Truncated.md index b4ec7ce16..971b2614f 100644 --- a/content/en/methods/page/Truncated.md +++ b/content/en/methods/page/Truncated.md @@ -26,6 +26,6 @@ The `Truncated` method returns `true` if the content length exceeds the summary {{ end }} ``` -{{% note %}} +{{< note >}} The `Truncated` method returns `false` if you define the summary in front matter. -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/pager/PageSize.md b/content/en/methods/pager/PageSize.md index d69c31207..68966d26a 100644 --- a/content/en/methods/pager/PageSize.md +++ b/content/en/methods/pager/PageSize.md @@ -10,8 +10,8 @@ action: expiryDate: 2026-06-09 # deprecated 2024-06-09 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`PAGER.PagerSize`] instead. [`PAGER.PagerSize`]: /methods/pager/pagersize/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/resource/Colors.md b/content/en/methods/resource/Colors.md index 08f63ae3f..42357ac9a 100644 --- a/content/en/methods/resource/Colors.md +++ b/content/en/methods/resource/Colors.md @@ -27,7 +27,7 @@ Luminance {{< new-in 0.125.0 />}} : (`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white. -{{% note %}} +{{< note >}} Image filters such as [`images.Dither`], [`images.Padding`], and [`images.Text`] accept either hexadecimal color values or `images.Color` objects as arguments. Hugo renders an `images.Color` object as a hexadecimal color value. @@ -35,7 +35,7 @@ Hugo renders an `images.Color` object as a hexadecimal color value. [`images.Dither`]: /functions/images/dither/ [`images.Padding`]: /functions/images/padding/ [`images.Text`]: /functions/images/text/ -{{% /note %}} +{{< /note >}} [hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color [relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance diff --git a/content/en/methods/resource/Err.md b/content/en/methods/resource/Err.md index 34ba6f9bc..11c1dd77b 100644 --- a/content/en/methods/resource/Err.md +++ b/content/en/methods/resource/Err.md @@ -12,11 +12,11 @@ action: expiryDate: 2027-01-16 # deprecated 2025-01-16 in v0.141.0 --- -{{% deprecated-in 0.141.0 %}} +{{< deprecated-in 0.141.0 >}} Use the `try` statement instead. See [example]. [example]: /functions/go-template/try/#example -{{% /deprecated-in %}} +{{< /deprecated-in >}} The `Err` method on a resource returned by the [`resources.GetRemote`] function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build. @@ -58,6 +58,6 @@ To log an error as a warning instead of an error: {{ end }} ``` -{{% note %}} +{{< note >}} An HTTP response with a 404 status code is not an HTTP request error. To handle 404 status codes, code defensively using the nested `with-else-end` construct as shown above. -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/resource/_common/global-page-remote-resources.md b/content/en/methods/resource/_common/global-page-remote-resources.md index e410df038..e1812dfad 100644 --- a/content/en/methods/resource/_common/global-page-remote-resources.md +++ b/content/en/methods/resource/_common/global-page-remote-resources.md @@ -2,6 +2,6 @@ _comment: Do not remove front matter. --- -{{% note %}} +{{< note >}} Use this method with [global resources](g), [page resources](g), or [remote resources](g). -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/shortcode/Get.md b/content/en/methods/shortcode/Get.md index 8874c7649..ec37fddd5 100644 --- a/content/en/methods/shortcode/Get.md +++ b/content/en/methods/shortcode/Get.md @@ -14,9 +14,9 @@ toc: true Specify the argument by position or by name. When calling a shortcode within Markdown, use either positional or named argument, but not both. -{{% note %}} +{{< note >}} Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details. -{{% /note %}} +{{< /note >}} ## Positional arguments @@ -46,6 +46,6 @@ To retrieve arguments by name: {{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world. {{< /code >}} -{{% note %}} +{{< note >}} Argument names are case-sensitive. -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/shortcode/Inner.md b/content/en/methods/shortcode/Inner.md index ef8d05ecb..bf70f0f9a 100644 --- a/content/en/methods/shortcode/Inner.md +++ b/content/en/methods/shortcode/Inner.md @@ -46,15 +46,15 @@ Is rendered to: ``` -{{% note %}} -Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`strings.TrimSpace`] function as shown above to remove both carriage returns and newlines. +{{< note >}} +Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`strings.TrimSpace`] function as shown above to remove carriage returns and newlines. [`strings.TrimSpace`]: /functions/strings/trimspace/ -{{% /note %}} +{{< /note >}} -{{% note %}} +{{< note >}} In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML. -{{% /note %}} +{{< /note >}} ## Use RenderString @@ -143,9 +143,11 @@ The difference between this and the previous example is subtle but required. Not ``` -{{% note %}} -When using the `{{%/* */%}}` notation, do not pass the value returned by `Inner` through the `RenderString` method or the `markdownify` function. -{{% /note %}} +{{< note >}} +Don't process the `Inner` value with `RenderString` or `markdownify` when using [Markdown notation] to call the shortcode. + +[Markdown notation]: /content-management/shortcodes/#notation +{{< /note >}} [commonmark]: https://commonmark.org/ [indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks diff --git a/content/en/methods/shortcode/Ordinal.md b/content/en/methods/shortcode/Ordinal.md index 41393fa22..6e70d134a 100644 --- a/content/en/methods/shortcode/Ordinal.md +++ b/content/en/methods/shortcode/Ordinal.md @@ -11,9 +11,9 @@ action: The `Ordinal` method returns the zero-based ordinal of the shortcode in relation to its parent. If the parent is the page itself, the ordinal represents the position of this shortcode in the page content. -{{% note %}} +{{< note >}} Hugo increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page. -{{% /note %}} +{{< /note >}} This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example: @@ -47,8 +47,8 @@ Hugo renders the page to: ``` -{{% note %}} +{{< note >}} In the shortcode template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top level context passed into the template. [`with`]: /functions/go-template/with/ -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/shortcode/Position.md b/content/en/methods/shortcode/Position.md index 6f047c01b..e3a60a456 100644 --- a/content/en/methods/shortcode/Position.md +++ b/content/en/methods/shortcode/Position.md @@ -28,6 +28,6 @@ In the absence of a "greeting" argument, Hugo will throw an error message and fa ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1" ``` -{{% note %}} +{{< note >}} The position can be expensive to calculate. Limit its use to error reporting. -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/shortcode/Scratch.md b/content/en/methods/shortcode/Scratch.md index 6dd882e24..c8be53724 100644 --- a/content/en/methods/shortcode/Scratch.md +++ b/content/en/methods/shortcode/Scratch.md @@ -10,7 +10,7 @@ action: expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft) --- -{{% deprecated-in 0.139.0 %}} +{{< deprecated-in 0.139.0 >}} Use the [`SHORTCODE.Store`] method instead. This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `SHORTCODE.Store` as soon as possible. @@ -18,4 +18,4 @@ This is a soft deprecation. This method will be removed in a future release, but Beginning with v0.139.0 the `SHORTCODE.Scratch` method is aliased to `SHORTCODE.Store`. [`SHORTCODE.Store`]: /methods/shortcode/store/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/shortcode/Store.md b/content/en/methods/shortcode/Store.md index 8d9a8596b..1517e1f7d 100644 --- a/content/en/methods/shortcode/Store.md +++ b/content/en/methods/shortcode/Store.md @@ -18,12 +18,12 @@ toc: true Use the `Store` method to create a [scratch pad](g) to store and manipulate data, scoped to the current shortcode. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below. -{{% note %}} +{{< note >}} With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete. [assign values to template variables]: https://go.dev/doc/go1.11#text/template [`newScratch`]: /functions/collections/newScratch/ -{{% /note %}} +{{< /note >}} {{% include "_common/store-methods.md" %}} diff --git a/content/en/methods/site/BaseURL.md b/content/en/methods/site/BaseURL.md index ea965a568..239b19a38 100644 --- a/content/en/methods/site/BaseURL.md +++ b/content/en/methods/site/BaseURL.md @@ -25,7 +25,7 @@ Template: {{ .Site.BaseURL }} → https://example.org/docs/ ``` -{{% note %}} +{{< note >}} There is almost never a good reason to use this method in your templates. Its usage tends to be fragile due to misconfiguration. Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead. @@ -34,4 +34,4 @@ Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions inst [`absLangURL`]: /functions/urls/absLangURL/ [`relURL`]: /functions/urls/relURL/ [`relLangURL`]: /functions/urls/relLangURL/ -{{% /note %}} +{{< /note >}} diff --git a/content/en/methods/site/Data.md b/content/en/methods/site/Data.md index 1021aad7d..16130fb79 100644 --- a/content/en/methods/site/Data.md +++ b/content/en/methods/site/Data.md @@ -17,11 +17,11 @@ Use the `Data` method on a `Site` object to access data within the `data` direct [mounted]: /hugo-modules/configuration/#module-configuration-mounts -{{% note %}} +{{< note >}} Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the `data` directory. You cannot access data within CSV files using this method. [`transform.Unmarshal`]: /functions/transform/unmarshal/ -{{% /note %}} +{{< /note >}} Consider this `data` directory: diff --git a/content/en/methods/site/DisqusShortname.md b/content/en/methods/site/DisqusShortname.md index f6fedf4e9..fac1b4f0b 100644 --- a/content/en/methods/site/DisqusShortname.md +++ b/content/en/methods/site/DisqusShortname.md @@ -10,8 +10,8 @@ action: expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 --- -{{% deprecated-in 0.120.0 %}} +{{< deprecated-in 0.120.0 >}} Use [`Site.Config.Services.Disqus.Shortname`] instead. [`Site.Config.Services.Disqus.Shortname`]: /methods/site/config/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/GoogleAnalytics.md b/content/en/methods/site/GoogleAnalytics.md index f87e1787e..b0633fab9 100644 --- a/content/en/methods/site/GoogleAnalytics.md +++ b/content/en/methods/site/GoogleAnalytics.md @@ -10,8 +10,8 @@ action: expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 --- -{{% deprecated-in 0.120.0 %}} +{{< deprecated-in 0.120.0 >}} Use [`Site.Config.Services.GoogleAnalytics.ID`] instead. [`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/IsDevelopment.md b/content/en/methods/site/IsDevelopment.md index 51783efb9..4ca4069a7 100644 --- a/content/en/methods/site/IsDevelopment.md +++ b/content/en/methods/site/IsDevelopment.md @@ -10,8 +10,8 @@ action: expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 --- -{{% deprecated-in 0.120.0 %}} +{{< deprecated-in 0.120.0 >}} Use [`hugo.IsDevelopment`] instead. [`hugo.IsDevelopment`]: /functions/hugo/isdevelopment/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/IsMultiLingual.md b/content/en/methods/site/IsMultiLingual.md index 10968f14d..d7b642f8c 100644 --- a/content/en/methods/site/IsMultiLingual.md +++ b/content/en/methods/site/IsMultiLingual.md @@ -10,8 +10,8 @@ action: expiryDate: 2026-03-16 # deprecated 2024-03-16 in 0.124.0 --- -{{% deprecated-in 0.124.0 %}} +{{< deprecated-in 0.124.0 >}} Use [`hugo.IsMultilingual`] instead. [`hugo.IsMultilingual`]: /functions/hugo/ismultilingual/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/IsServer.md b/content/en/methods/site/IsServer.md index 8fb5b7bf6..6d8817847 100644 --- a/content/en/methods/site/IsServer.md +++ b/content/en/methods/site/IsServer.md @@ -10,8 +10,8 @@ action: expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 --- -{{% deprecated-in 0.120.0 %}} +{{< deprecated-in 0.120.0 >}} Use [`hugo.IsServer`] instead. [`hugo.IsServer`]: /functions/hugo/isserver/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/LastChange.md b/content/en/methods/site/LastChange.md index f6017df04..0110cf855 100644 --- a/content/en/methods/site/LastChange.md +++ b/content/en/methods/site/LastChange.md @@ -10,8 +10,8 @@ action: expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0 --- -{{% deprecated-in 0.123.0 %}} +{{< deprecated-in 0.123.0 >}} Use [`.Site.Lastmod`] instead. [`.Site.Lastmod`]: /methods/site/lastmod/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/content/en/methods/site/Menus.md b/content/en/methods/site/Menus.md index e51980c2e..896d552e3 100644 --- a/content/en/methods/site/Menus.md +++ b/content/en/methods/site/Menus.md @@ -13,11 +13,11 @@ action: The `Menus` method on a `Site` object returns a collection of menus, where each menu contains one or more entries, either flat or nested. Each entry points to a page within the site, or to an external resource. -{{% note %}} +{{< note >}} Menus can be defined and localized in several ways. Please see the [menus] section for a complete explanation and examples. [menus]: /content-management/menus/ -{{% /note %}} +{{< /note >}} A site can have multiple menus. For example, a main menu and a footer menu: diff --git a/content/en/methods/site/Taxonomies.md b/content/en/methods/site/Taxonomies.md index ee98d2ac5..cad665d0d 100644 --- a/content/en/methods/site/Taxonomies.md +++ b/content/en/methods/site/Taxonomies.md @@ -89,13 +89,13 @@ Hugo renders this to: ``` -{{% note %}} +{{< note >}} Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages. Please see the [taxonomies] section for a complete explanation and examples. [taxonomies]: /content-management/taxonomies/ -{{% /note %}} +{{< /note >}} ## Examples diff --git a/content/en/methods/time/AddDate.md b/content/en/methods/time/AddDate.md index 8537d6e25..a4ef482ed 100644 --- a/content/en/methods/time/AddDate.md +++ b/content/en/methods/time/AddDate.md @@ -21,11 +21,11 @@ aliases: [/functions/adddate] {{ $d.AddDate -1 -1 -1 | time.Format "2006-01-02" }} → 2020-11-30 ``` -{{% note %}} +{{< note >}} When adding months or years, Hugo normalizes the final `time.Time` value if the resulting day does not exist. For example, adding one month to 31 January produces 2 March or 3 March, depending on the year. See [this explanation](https://github.com/golang/go/issues/31145#issuecomment-479067967) from the Go team. -{{% /note %}} +{{< /note >}} ```go-html-template {{ $d := "2023-01-31" | time.AsTime }} diff --git a/content/en/methods/time/Format.md b/content/en/methods/time/Format.md index 9a718b53b..928af0ee7 100644 --- a/content/en/methods/time/Format.md +++ b/content/en/methods/time/Format.md @@ -23,11 +23,11 @@ aliases: [/methods/time/format] {{ $t.Format $format }} → 27 Jan 2023 ``` -{{% note %}} +{{< note >}} To [localize](g) the return value, use the [`time.Format`] function instead. [`time.Format`]: /functions/time/format/ -{{% /note %}} +{{< /note >}} Use the `Format` method with any `time.Time` value, including the four predefined front matter dates: @@ -40,11 +40,11 @@ Use the `Format` method with any `time.Time` value, including the four predefine {{ .Lastmod.Format $format }} ``` -{{% note %}} +{{< note >}} Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset. [`time.Format`]: /functions/time/format/ -{{% /note %}} +{{< /note >}} ## Layout string diff --git a/content/en/render-hooks/_common/pageinner.md b/content/en/render-hooks/_common/pageinner.md index 6f2622880..96a12bf3b 100644 --- a/content/en/render-hooks/_common/pageinner.md +++ b/content/en/render-hooks/_common/pageinner.md @@ -33,11 +33,12 @@ Any render hook triggered while rendering `/posts/p2` will get: `PageInner` falls back to the value of `Page` if not relevant, and always returns a value. -{{% note %}} -The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using the `{{%/*..*/%}}` notation. +{{< note >}} +The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using [Markdown notation]. +[Markdown notation]: /content-management/shortcodes/#notation [`RenderShortcodes`]: /methods/page/rendershortcodes/ -{{% /note %}} +{{< /note >}} As a practical example, Hugo's embedded link and image render hooks use the `PageInner` method to resolve markdown link and image destinations. See the source code for each: diff --git a/content/en/render-hooks/blockquotes.md b/content/en/render-hooks/blockquotes.md index bdeb06af9..25daf5865 100755 --- a/content/en/render-hooks/blockquotes.md +++ b/content/en/render-hooks/blockquotes.md @@ -146,9 +146,9 @@ With the extended Markdown syntax, you may optionally include an alert sign and/ The extended syntax is compatible with [Obsidian]. -{{% note %}} +{{< note >}} The extended syntax is not compatible with GitHub or Typora. If you include an alert sign or an alert title, these applications render the Markdown as a blockquote. -{{% /note %}} +{{< /note >}} ### Example diff --git a/content/en/render-hooks/code-blocks.md b/content/en/render-hooks/code-blocks.md index 7999dbeb8..9622c3883 100755 --- a/content/en/render-hooks/code-blocks.md +++ b/content/en/render-hooks/code-blocks.md @@ -48,9 +48,9 @@ In the example above, the _highlighting options_ are `lineNos` and `tabWidth`. H [Chroma]: https://github.com/alecthomas/chroma/ [highlighting options]: /functions/transform/highlight/#options -{{% note %}} +{{< note >}} Although `style` is a global HTML attribute, when used in an info string it is a highlighting option. -{{% /note %}} +{{< /note >}} ## Context diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md index 63f294081..e0e5ce99b 100755 --- a/content/en/render-hooks/images.md +++ b/content/en/render-hooks/images.md @@ -79,9 +79,9 @@ block = true ## Examples -{{% note %}} +{{< note >}} With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text. -{{% /note %}} +{{< /note >}} In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing: @@ -135,11 +135,11 @@ enableDefault = true A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above. -{{% note %}} +{{< note >}} The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. [duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles -{{% /note %}} +{{< /note >}} The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination. diff --git a/content/en/render-hooks/introduction.md b/content/en/render-hooks/introduction.md index d086c91bb..f332043c5 100755 --- a/content/en/render-hooks/introduction.md +++ b/content/en/render-hooks/introduction.md @@ -21,13 +21,13 @@ When rendering Markdown to HTML, render hooks override the conversion. Each rend - [Passthrough elements](/render-hooks/passthrough) - [Tables](/render-hooks/tables) -{{% note %}} +{{< note >}} Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText. The render hook capability is limited to Markdown. You cannot create render hooks for the other content formats. [content formats]: /content-management/formats/ -{{% /note %}} +{{< /note >}} For example, consider this Markdown: diff --git a/content/en/render-hooks/links.md b/content/en/render-hooks/links.md index 89044c662..4c86557ea 100755 --- a/content/en/render-hooks/links.md +++ b/content/en/render-hooks/links.md @@ -58,9 +58,9 @@ Link render hook templates receive the following context: ## Examples -{{% note %}} +{{< note >}} With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text. -{{% /note %}} +{{< /note >}} In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing: @@ -103,11 +103,11 @@ enableDefault = true A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above. -{{% note %}} +{{< note >}} The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. [duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles -{{% /note %}} +{{< /note >}} The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource](g), then falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination. diff --git a/content/en/shortcodes/comment.md b/content/en/shortcodes/comment.md index 1600c09d3..c87765a6b 100755 --- a/content/en/shortcodes/comment.md +++ b/content/en/shortcodes/comment.md @@ -12,11 +12,11 @@ weight: expiryDate: 2025-01-22 # deprecated 2025-02-01 in v0.143.0 and immediately removed from the documentation --- -{{% note %}} +{{< note >}} To override Hugo's embedded `comment` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl comment %}} -{{% /note %}} +{{< /note >}} {{< new-in 0.137.1 />}} diff --git a/content/en/shortcodes/details.md b/content/en/shortcodes/details.md index f30f81d75..029429e2d 100755 --- a/content/en/shortcodes/details.md +++ b/content/en/shortcodes/details.md @@ -13,11 +13,11 @@ toc: true {{< new-in 0.140.0 />}} -{{% note %}} +{{< note >}} To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl details %}} -{{% /note %}} +{{< /note >}} ## Example diff --git a/content/en/shortcodes/figure.md b/content/en/shortcodes/figure.md index eb98598b6..69aafe894 100755 --- a/content/en/shortcodes/figure.md +++ b/content/en/shortcodes/figure.md @@ -11,11 +11,11 @@ weight: toc: true --- -{{% note %}} +{{< note >}} To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl figure %}} -{{% /note %}} +{{< /note >}} ## Example diff --git a/content/en/shortcodes/gist.md b/content/en/shortcodes/gist.md index 1c740bccb..8a247be8d 100755 --- a/content/en/shortcodes/gist.md +++ b/content/en/shortcodes/gist.md @@ -11,7 +11,7 @@ weight: expiryDate: 2027-02-01 # deprecated 2025-02-01 in v0.143.0 --- -{{% deprecated-in 0.143.0 %}} +{{< deprecated-in 0.143.0 >}} The `gist` shortcode was deprecated in version 0.143.0 and will be removed in a future release. To continue embedding GitHub Gists in your content, you'll need to create a custom shortcode: 1. Create a new file: Create a file named `gist.html` within the `layouts/shortcodes` directory. @@ -20,7 +20,7 @@ The `gist` shortcode was deprecated in version 0.143.0 and will be removed in a This will allow you to maintain the functionality of embedding GitHub Gists in your content after the deprecation of the original shortcode. [original source code]: {{% eturl gist %}} -{{% /deprecated-in %}} +{{< /deprecated-in >}} To display a GitHub gist with this URL: diff --git a/content/en/shortcodes/highlight.md b/content/en/shortcodes/highlight.md index 0a35aa4e6..b6ffe547f 100755 --- a/content/en/shortcodes/highlight.md +++ b/content/en/shortcodes/highlight.md @@ -11,19 +11,19 @@ weight: toc: true --- -{{% note %}} +{{< note >}} To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl highlight %}} -{{% /note %}} +{{< /note >}} -{{% note %}} +{{< note >}} With the Markdown [content format], the `highlight` shortcode is rarely needed because, by default, Hugo automatically applies syntax highlighting to fenced code blocks. The primary use case for the `highlight` shortcode in Markdown is to apply syntax highlighting to inline code snippets. [content format]: /content-management/formats/ -{{% /note %}} +{{< /note >}} The `highlight` shortcode calls the [`transform.Highlight`] function which uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [available styles]. diff --git a/content/en/shortcodes/instagram.md b/content/en/shortcodes/instagram.md index eb2bb7671..ffe739966 100755 --- a/content/en/shortcodes/instagram.md +++ b/content/en/shortcodes/instagram.md @@ -11,11 +11,11 @@ weight: toc: true --- -{{% note %}} +{{< note >}} To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl instagram %}} -{{% /note %}} +{{< /note >}} ## Example diff --git a/content/en/shortcodes/param.md b/content/en/shortcodes/param.md index bff659ec1..b7bd31e47 100755 --- a/content/en/shortcodes/param.md +++ b/content/en/shortcodes/param.md @@ -10,11 +10,11 @@ menu: weight: --- -{{% note %}} +{{< note >}} To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl param %}} -{{% /note %}} +{{< /note >}} The `param` shortcode renders a parameter from front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist. diff --git a/content/en/shortcodes/qr.md b/content/en/shortcodes/qr.md index a7a6d92cb..2a82b919f 100755 --- a/content/en/shortcodes/qr.md +++ b/content/en/shortcodes/qr.md @@ -13,11 +13,11 @@ toc: true {{< new-in 0.141.0 />}} -{{% note %}} +{{< note >}} To override Hugo's embedded `qr` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl qr %}} -{{% /note %}} +{{< /note >}} The `qr` shortcode encodes the given text into a [QR code] using the specified options and renders the resulting image. diff --git a/content/en/shortcodes/ref.md b/content/en/shortcodes/ref.md index af133447e..e5d7117c8 100755 --- a/content/en/shortcodes/ref.md +++ b/content/en/shortcodes/ref.md @@ -10,18 +10,18 @@ menu: weight: --- -{{% note %}} +{{< note >}} To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl ref %}} -{{% /note %}} +{{< /note >}} -{{% note %}} +{{< note >}} When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode. [content format]: /content-management/formats/ [link render hooks]: /render-hooks/images/#default -{{% /note %}} +{{< /note >}} The `ref` shortcode returns the permalink of the given page reference. @@ -43,6 +43,8 @@ Rendered: Post 1 ``` -{{% note %}} -Always use the `{{%/* */%}}` notation when calling this shortcode. -{{% /note %}} +{{< note >}} +Always use [Markdown notation] notation when calling this shortcode. + +[Markdown notation]: /content-management/shortcodes/#notation +{{< /note >}} diff --git a/content/en/shortcodes/relref.md b/content/en/shortcodes/relref.md index e98e82919..603427cb1 100755 --- a/content/en/shortcodes/relref.md +++ b/content/en/shortcodes/relref.md @@ -10,18 +10,18 @@ menu: weight: --- -{{% note %}} +{{< note >}} To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl relref %}} -{{% /note %}} +{{< /note >}} -{{% note %}} +{{< note >}} When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode. [content format]: /content-management/formats/ [link render hooks]: /render-hooks/links/ -{{% /note %}} +{{< /note >}} The `relref` shortcode returns the relative permalink of the given page reference. @@ -43,6 +43,8 @@ Rendered: Post 1 ``` -{{% note %}} -Always use the `{{%/* */%}}` notation when calling this shortcode. -{{% /note %}} +{{< note >}} +Always use [Markdown notation] notation when calling this shortcode. + +[Markdown notation]: /content-management/shortcodes/#notation +{{< /note >}} diff --git a/content/en/shortcodes/vimeo.md b/content/en/shortcodes/vimeo.md index 5ecdf5d02..2d852471a 100755 --- a/content/en/shortcodes/vimeo.md +++ b/content/en/shortcodes/vimeo.md @@ -11,11 +11,11 @@ weight: toc: true --- -{{% note %}} +{{< note >}} To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl vimeo %}} -{{% /note %}} +{{< /note >}} ## Example diff --git a/content/en/shortcodes/x.md b/content/en/shortcodes/x.md index e27bc996a..c2f7a58fe 100755 --- a/content/en/shortcodes/x.md +++ b/content/en/shortcodes/x.md @@ -13,11 +13,11 @@ toc: true {{< new-in 0.141.0 />}} -{{% note %}} +{{< note >}} To override Hugo's embedded `x` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl x %}} -{{% /note %}} +{{< /note >}} ## Example diff --git a/content/en/shortcodes/youtube.md b/content/en/shortcodes/youtube.md index 546529500..1c356c732 100755 --- a/content/en/shortcodes/youtube.md +++ b/content/en/shortcodes/youtube.md @@ -11,11 +11,11 @@ weight: toc: true --- -{{% note %}} +{{< note >}} To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory. [source code]: {{% eturl youtube %}} -{{% /note %}} +{{< /note >}} ## Example diff --git a/content/en/templates/_common/filter-sort-group.md b/content/en/templates/_common/filter-sort-group.md index 24bbee96e..f4955ef99 100644 --- a/content/en/templates/_common/filter-sort-group.md +++ b/content/en/templates/_common/filter-sort-group.md @@ -2,8 +2,8 @@ _comment: Do not remove front matter. --- -{{% note %}} +{{< note >}} The [page collections quick reference guide] describes methods and functions to filter, sort, and group page collections. [page collections quick reference guide]: /quick-reference/page-collections/ -{{% /note %}} +{{< /note >}} diff --git a/content/en/templates/base.md b/content/en/templates/base.md index 45320e3cf..b7e73378c 100644 --- a/content/en/templates/base.md +++ b/content/en/templates/base.md @@ -66,7 +66,7 @@ The default list template will inherit all of the code defined above and can the This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists. -{{% note %}} +{{< note >}} Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example: ```go-html-template @@ -76,7 +76,7 @@ Code that you put outside the block definitions *can* break your layout. This ev {{ end }} ``` [See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6) -{{% /note %}} +{{< /note >}} The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your default [single template]: diff --git a/content/en/templates/embedded.md b/content/en/templates/embedded.md index 2e571256e..059448cb4 100644 --- a/content/en/templates/embedded.md +++ b/content/en/templates/embedded.md @@ -14,14 +14,14 @@ aliases: [/templates/internal] ## Disqus -{{% note %}} +{{< note >}} To override Hugo's embedded Disqus template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: `{{ partial "disqus.html" . }}` [`partial`]: /functions/partials/include/ [source code]: {{% eturl disqus %}} -{{% /note %}} +{{< /note >}} Hugo includes an embedded template for [Disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up] for the free service. @@ -66,14 +66,14 @@ disable ## Google Analytics -{{% note %}} +{{< note >}} To override Hugo's embedded Google Analytics template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: `{{ partial "google_analytics.html" . }}` [`partial`]: /functions/partials/include/ [source code]: {{% eturl google_analytics %}} -{{% /note %}} +{{< /note >}} Hugo includes an embedded template supporting [Google Analytics 4]. @@ -110,14 +110,14 @@ respectDoNotTrack ## Open Graph -{{% note %}} +{{< note >}} To override Hugo's embedded Open Graph template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: `{{ partial "opengraph.html" . }}` [`partial`]: /functions/partials/include/ [source code]: {{% eturl opengraph %}} -{{% /note %}} +{{< /note >}} Hugo includes an embedded template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph. This format is used for Facebook and some other sites. @@ -169,14 +169,14 @@ If using YouTube this will produce a og:video tag like `}} Hugo includes an embedded template to render [microdata] `meta` elements within the `head` element of your templates. @@ -190,14 +190,14 @@ To include the embedded template: ## X (Twitter) Cards -{{% note %}} +{{< note >}} To override Hugo's embedded Twitter Cards template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: `{{ partial "twitter_cards.html" . }}` [`partial`]: /functions/partials/include/ [source code]: {{% eturl twitter_cards %}} -{{% /note %}} +{{< /note >}} Hugo includes an embedded template for [X (Twitter) Cards](https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards), metadata used to attach rich media to Tweets linking to your site. diff --git a/content/en/templates/home.md b/content/en/templates/home.md index 18114eb0f..22f71420c 100644 --- a/content/en/templates/home.md +++ b/content/en/templates/home.md @@ -33,9 +33,9 @@ Hugo's [template lookup order] determines the template path, allowing you to cre [template lookup order]: /templates/lookup-order/#home-templates -{{% note %}} +{{< note >}} You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format. -{{% /note %}} +{{< /note >}} ## Content and front matter diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md index b68ecf925..2635ebc59 100644 --- a/content/en/templates/introduction.md +++ b/content/en/templates/introduction.md @@ -19,7 +19,7 @@ A template is a file in the `layouts` directory of a project, theme, or module. [methods]: /methods/ [variables]: #variables -{{% note %}} +{{< note >}} Hugo uses Go's [text/template] and [html/template] packages. The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection. @@ -28,7 +28,7 @@ By default, Hugo uses the html/template package when rendering HTML files. [text/template]: https://pkg.go.dev/text/template [html/template]: https://pkg.go.dev/html/template -{{% /note %}} +{{< /note >}} For example, this HTML template initializes the `$v1` and `$v2` variables, then displays them and their product within an HTML paragraph. @@ -103,9 +103,9 @@ Hugo renders this to:

My Page Title - foo

``` -{{% note %}} +{{< note >}} Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context. -{{% /note %}} +{{< /note >}} ## Actions @@ -178,9 +178,9 @@ These are also equivalent: {{ 5 | add 2 | mul 6 }} → 42 ``` -{{% note %}} +{{< note >}} Remember that the piped value becomes the final argument to the function or method to which you are piping. -{{% /note %}} +{{< /note >}} ### Line splitting @@ -235,9 +235,9 @@ With variables that represent a slice or map, use the [`index`] function to retu {{ index $map "c" }} → baz ``` -{{% note %}} +{{< note >}} Slices and arrays are zero-based; element 0 is the first element. -{{% /note %}} +{{< /note >}} With variables that represent a map or object, [chain](g) identifiers to return the desired value or to access the desired method. @@ -249,9 +249,9 @@ With variables that represent a map or object, [chain](g) identifiers to return {{ $homePage.Title }} → My Homepage ``` -{{% note %}} +{{< note >}} As seen above, object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore. -{{% /note %}} +{{< /note >}} ## Functions @@ -323,11 +323,11 @@ Some methods take an argument. Separate the argument from the method with a spac ## Comments -{{% note %}} +{{< note >}} Do not attempt to use HTML comment delimiters to comment out template code. Hugo strips HTML comments when rendering a page, but first evaluates any template code within the HTML comment delimiters. Depending on the template code within the HTML comment delimiters, this could cause unexpected results or fail the build. -{{% /note %}} +{{< /note >}} Template comments are similar to template actions. Paired opening and closing braces represent the beginning and end of a comment. For example: @@ -389,9 +389,9 @@ Use the [`partial`] or [`partialCached`] function to include one or more [partia Create your partial templates in the layouts/partials directory. -{{% note %}} +{{< note >}} In the examples above, note that we are passing the current context (the dot) to each of the templates. -{{% /note %}} +{{< /note >}} ## Examples diff --git a/content/en/templates/lookup-order.md b/content/en/templates/lookup-order.md index c1a7b2676..926cbd84d 100644 --- a/content/en/templates/lookup-order.md +++ b/content/en/templates/lookup-order.md @@ -36,9 +36,9 @@ Type Section : Is relevant for `section`, `taxonomy` and `term` types. -{{% note %}} +{{< note >}} Templates can live in either the project's or the themes' `layout` directories, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes. -{{% /note %}} +{{< /note >}} ## Target a template diff --git a/content/en/templates/output-formats.md b/content/en/templates/output-formats.md index c81a81264..8d0d200ed 100644 --- a/content/en/templates/output-formats.md +++ b/content/en/templates/output-formats.md @@ -53,9 +53,9 @@ These media types are configured for your output formats. If you want to redefin mediaType = "text/html" {{}} -{{% note %}} +{{< note >}} For the above to work, you also need to add an `outputs` definition in your site configuration. -{{% /note %}} +{{< /note >}} ## Output format definitions diff --git a/content/en/templates/pagination.md b/content/en/templates/pagination.md index 674c6a565..9b1fdcd5e 100644 --- a/content/en/templates/pagination.md +++ b/content/en/templates/pagination.md @@ -20,9 +20,9 @@ Displaying a large page collection on a list page is not user-friendly: Improve usability by paginating `home`, `section`, `taxonomy`, and `term` pages. -{{% note %}} +{{< note >}} The most common templating mistake related to pagination is invoking pagination more than once for a given list page. See the [caching](#caching) section below. -{{% /note %}} +{{< /note >}} ## Terminology @@ -137,9 +137,9 @@ In the example above, we: ## Caching -{{% note %}} +{{< note >}} The most common templating mistake related to pagination is invoking pagination more than once for a given list page. -{{% /note %}} +{{< /note >}} Regardless of pagination method, the initial invocation is cached and cannot be changed. If you invoke pagination more than once for a given list page, subsequent invocations use the cached result. This means that subsequent invocations will not behave as written. @@ -189,14 +189,14 @@ The `terse` format has fewer controls and page slots, consuming less space when {{ template "_internal/pagination.html" (dict "page" . "format" "terse") }} ``` -{{% note %}} +{{< note >}} To override Hugo's embedded pagination template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: `{{ partial "pagination.html" . }}` [`partial`]: /functions/partials/include/ [source code]: {{% eturl pagination %}} -{{% /note %}} +{{< /note >}} Create custom navigation components using any of the `Pager` methods: diff --git a/content/en/templates/partial.md b/content/en/templates/partial.md index 996914b05..acf36d76c 100644 --- a/content/en/templates/partial.md +++ b/content/en/templates/partial.md @@ -39,13 +39,13 @@ All partials are called within your templates using the following pattern: {{ partial "/.html" . }} ``` -{{% note %}} +{{< note >}} One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/#context). -{{% /note %}} +{{< /note >}} -{{% note %}} +{{< note >}} `` including `baseof` is reserved. ([#5373](https://github.com/gohugoio/hugo/issues/5373)) -{{% /note %}} +{{< /note >}} As shown in the above example directory structure, you can nest your directories within `partials` for better source organization. You only need to call the nested partial's path relative to the `partials` directory: @@ -99,9 +99,9 @@ In addition to outputting markup, partials can be used to return a value of any {{ end }} ``` -{{% note %}} +{{< note >}} Only one `return` statement is allowed per partial file. -{{% /note %}} +{{< /note >}} ## Inline partials @@ -143,9 +143,9 @@ The following `header.html` partial template is used for [spf13.com](https://spf {{< /code >}} -{{% note %}} +{{< note >}} The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility. -{{% /note %}} +{{< /note >}} ### `footer.html` diff --git a/content/en/templates/robots.md b/content/en/templates/robots.md index 0e453c549..7e50459e6 100644 --- a/content/en/templates/robots.md +++ b/content/en/templates/robots.md @@ -46,7 +46,7 @@ Disallow: {{ .RelPermalink }} This template creates a robots.txt file with a `Disallow` directive for each page on the site. Search engines that honor the Robots Exclusion Protocol will not crawl any page on the site. -{{% note %}} +{{< note >}} To create a robots.txt file without using a template: 1. Set `enableRobotsTXT` to `false` in the site configuration. @@ -55,6 +55,6 @@ To create a robots.txt file without using a template: Remember that Hugo copies everything in the [`static` directory][static] to the root of `publishDir` (typically `public`) when you build your site. [static]: /getting-started/directory-structure/ -{{% /note %}} +{{< /note >}} [site configuration]: /getting-started/configuration/ diff --git a/content/en/templates/shortcode.md b/content/en/templates/shortcode.md index c73874673..84037423d 100644 --- a/content/en/templates/shortcode.md +++ b/content/en/templates/shortcode.md @@ -12,12 +12,12 @@ aliases: [/templates/shortcode-templates/] toc: true --- -{{% note %}} +{{< note >}} Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates. [shortcodes]: /content-management/shortcodes/ [content management]: /content-management/shortcodes/ -{{% /note %}} +{{< /note >}} ## Introduction @@ -142,13 +142,13 @@ The example above uses: [`get`]: /methods/shortcode/get/ [`with`]: /functions/go-template/with/ -{{% note %}} +{{< note >}} Make sure that you thoroughly understand the concept of context. The most common templating errors made by new users relate to context. Read more about context in the [introduction to templating]. [introduction to templating]: /templates/introduction/ -{{% /note %}} +{{< /note >}} ### Insert image with error handling @@ -208,9 +208,9 @@ Using the `Get` method with zero-indexed keys, we'll initialize variables with d {{- $alt := .Get 2 }} {{< /code >}} -{{% note %}} +{{< note >}} Positional arguments work well for frequently used shortcodes with one or two arguments. Since you'll use them often, the argument order will be easy to remember. For less frequently used shortcodes, or those with more than two arguments, named arguments improve readability and reduce the chance of errors. -{{% /note %}} +{{< /note >}} ### Named and positional arguments diff --git a/content/en/templates/types/index.md b/content/en/templates/types/index.md index 8369917bf..edcff0701 100644 --- a/content/en/templates/types/index.md +++ b/content/en/templates/types/index.md @@ -47,9 +47,9 @@ Hugo's [template lookup order] determines the template path, allowing you to cre [template lookup order]: /templates/lookup-order/ -{{% note %}} +{{< note >}} You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format. -{{% /note %}} +{{< /note >}} The purpose of each template type is described below. @@ -180,11 +180,11 @@ Learn more about [term templates](/templates/term/). A partial template is typically used to render a component of your site, though you may also create partial templates that return values. -{{% note %}} +{{< note >}} Unlike other template types, you cannot create partial templates to target a particular page kind, content type, section, language, or output format. Partial templates do not follow Hugo's [template lookup order]. [template lookup order]: /templates/lookup-order/ -{{% /note %}} +{{< /note >}} For example, the partial template below renders copyright information. diff --git a/content/en/troubleshooting/faq.md b/content/en/troubleshooting/faq.md index 2edb309be..97706fa2f 100644 --- a/content/en/troubleshooting/faq.md +++ b/content/en/troubleshooting/faq.md @@ -120,12 +120,12 @@ You can trigger content rendering with other methods as well. See next FAQ. The following methods on a `Page` object trigger content rendering: `Content`, `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`. -{{% note %}} +{{< note >}} For other questions please visit the [forum]. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question. [forum]: https://discourse.gohugo.io [requesting help]: https://discourse.gohugo.io/t/requesting-help/9132 -{{% /note %}} +{{< /note >}} [`Paginate`]: /methods/page/paginate/ [`Paginator`]: /methods/page/paginator/ diff --git a/content/en/troubleshooting/logging.md b/content/en/troubleshooting/logging.md index fc6838069..1cb9a8ebd 100644 --- a/content/en/troubleshooting/logging.md +++ b/content/en/troubleshooting/logging.md @@ -45,9 +45,9 @@ debug hugo --logLevel debug ``` -{{% note %}} +{{< note >}} If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed. -{{% /note %}} +{{< /note >}} ## Template functions diff --git a/content/en/troubleshooting/performance.md b/content/en/troubleshooting/performance.md index 2cf64477a..230c9ca06 100644 --- a/content/en/troubleshooting/performance.md +++ b/content/en/troubleshooting/performance.md @@ -24,9 +24,9 @@ For example, with Microsoft Defender Antivirus: Then type `hugo.exe` add press the **Add** button. -{{% note %}} +{{< note >}} Virus scanning exclusions are common, but use caution when changing these settings. See the [Microsoft Defender Antivirus documentation](https://support.microsoft.com/en-us/topic/how-to-add-a-file-type-or-process-exclusion-to-windows-security-e524cbc2-3975-63c2-f9d1-7c2eb5331e53) for details. -{{% /note %}} +{{< /note >}} Other virus scanners have similar exclusion mechanisms. See their respective documentation. @@ -95,17 +95,17 @@ template [`partial`]: /functions/partials/include/ [`partialCached`]: /functions/partials/includecached/ -{{% note %}} +{{< note >}} Hugo builds pages in parallel where multiple pages are generated simultaneously. Because of this parallelism, the sum of "cumulative duration" values is usually greater than the actual time it takes to build a site. -{{% /note %}} +{{< /note >}} ## Caching Some partial templates such as sidebars or menus are executed many times during a site build. Depending on the content within the partial template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for partial templates. -{{% note %}} +{{< note >}} Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details. -{{% /note %}} +{{< /note >}} ## Timers diff --git a/layouts/partials/layouts/blocks/alert.html b/layouts/partials/layouts/blocks/alert.html index 705ce0e7e..a16cca28a 100644 --- a/layouts/partials/layouts/blocks/alert.html +++ b/layouts/partials/layouts/blocks/alert.html @@ -1,8 +1,8 @@ -{{ $title := .title | default "" }} -{{ $color := .color | default "yellow" }} -{{ $icon := .icon | default "exclamation" }} -{{ $text := .text | default "" }} -{{ $class := .class | default "mt-6 mb-8" }} +{{- $title := .title | default "" }} +{{- $color := .color | default "yellow" }} +{{- $icon := .icon | default "exclamation" }} +{{- $text := .text | default "" }} +{{- $class := .class | default "mt-6 mb-8" }}
@@ -12,15 +12,13 @@
- {{ with $title }} + {{- with $title }}

{{ . }}

- {{ end }} + {{- end }}
-

- {{ $text }} -

+ {{ $text }}
diff --git a/layouts/shortcodes/deprecated-in.html b/layouts/shortcodes/deprecated-in.html index 0272ea4a6..c30d20cf0 100644 --- a/layouts/shortcodes/deprecated-in.html +++ b/layouts/shortcodes/deprecated-in.html @@ -1,17 +1,31 @@ -{{ $_hugo_config := `{ "version": 1 }` }} +{{- /* + Renders a callout indicating the version in which a feature was deprecated. -{{ with .Get 0 }} - {{ $version := printf "v%v" (strings.TrimLeft "vV" .) }} - {{ $href := printf "https://github.com/gohugoio/hugo/releases/tag/%s" $version }} - {{ $text := (printf `Deprecated in %s. -%s` $href $version $.Inner) | safeHTML }} + Include descriptive text between the opening and closing tags, or omit the + descriptive text and call the shortcode with a self-closing tag. - {{ partial "layouts/blocks/alert.html" (dict - "text" $text - "color" "orange" - "icon" "exclamation" - ) -}} -{{ else }} - {{ errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }} -{{ end }} + @param {string} 0 The semantic version string, with or without a leading v. + @returns {template.HTML} + + @examples + + {{< deprecated-in 0.144.0 />}} + + {{< deprecated-in 0.144.0 >}} + Some descriptive text here. + {{< /new-in >}} + +*/}} +{{- with $version := .Get 0 | strings.TrimPrefix "vV" }} + {{- $href := printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }} + {{- $inner := strings.TrimSpace $.Inner }} + {{- $text := printf "Deprecated in [v%s](%s)\n\n%s" $version $href $inner | $.Page.RenderString (dict "display" "block") }} + {{- partial "layouts/blocks/alert.html" (dict + "color" "orange" + "icon" "exclamation" + "text" $text + ) + }} +{{- else }} + {{- errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }} +{{- end }} diff --git a/layouts/shortcodes/gomodules-info.html b/layouts/shortcodes/gomodules-info.html index 126d846c0..f9cd9d765 100644 --- a/layouts/shortcodes/gomodules-info.html +++ b/layouts/shortcodes/gomodules-info.html @@ -1,12 +1,18 @@ -{{ $text := ` +{{- $text := ` Most of the commands for **Hugo Modules** require a newer version (>= 1.18) of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ). If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.19 or newer in your Environment settings. For more information about Go Modules, see: - * https://go.dev/wiki/Modules - * https://blog.golang.org/using-go-modules + - https://go.dev/wiki/Modules + - https://blog.golang.org/using-go-modules ` }} - -{{ partial "layouts/blocks/alert.html" (dict "title" "Go Modules" "text" ($text | markdownify) "color" "orange" "icon" "exclamation") }} +{{- $text = $text | strings.TrimSpace | .Page.RenderString (dict "display" "block") }} +{{- partial "layouts/blocks/alert.html" (dict + "color" "orange" + "icon" "exclamation" + "text" $text + "title" "Go Modules" + ) +}} diff --git a/layouts/shortcodes/new-in.html b/layouts/shortcodes/new-in.html index e99cc7bcf..823e1d174 100644 --- a/layouts/shortcodes/new-in.html +++ b/layouts/shortcodes/new-in.html @@ -1,5 +1,9 @@ {{- /* - Renders a "new in" button indicating the version in which a feature was added. + Renders a callout or badge indicating the version in which a feature was added. + + To render a callout, include descriptive text between the opening and closing + tags. To render a badge,omit the descriptive text and call the shortcode with + a self-closing tag. When comparing the current version to the specified version, the "new in" button will be hidden if any of the following conditions is true: @@ -7,25 +11,22 @@ - The major version difference exceeds the majorVersionDiffThreshold - The minor version difference exceeds the minorVersionDiffThreshold - @param {string} version The semantic version string, with or without a leading v. + @param {string} 0 The semantic version string, with or without a leading v. @returns {template.HTML} - @examples {{< new-in 0.100.0 / ->}} + @examples -{{< new-in 0.100.0 >}} -Some descriptive text here. -{{< /new-in >}} + {{< new-in 0.100.0 />}} + + {{< new-in 0.100.0 >}} + Some descriptive text here. + {{< /new-in >}} */}} -{{ $_hugo_config := `{ "version": 1 }` }} - -{{- /* Set defaults. */}} {{- $majorVersionDiffThreshold := 0 }} {{- $minorVersionDiffThreshold := 30 }} {{- $displayExpirationWarning := true }} -{{- /* Render. */}} -{{- with $version := .Get 0 | strings.TrimPrefix "v" }} +{{- with $version := .Get 0 | strings.TrimPrefix "vV" }} {{- $majorVersionDiff := sub (index (split hugo.Version ".") 0 | int) (index (split $version ".") 0 | int) }} {{- $minorVersionDiff := sub (index (split hugo.Version ".") 1 | int) (index (split $version ".") 1 | int) }} {{- if or (gt $majorVersionDiff $majorVersionDiffThreshold) (gt $minorVersionDiff $minorVersionDiffThreshold) }} @@ -35,14 +36,12 @@ Some descriptive text here. {{- else }} {{- $href := printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }} {{- with $.Inner }} - {{ $text := printf `

New in v%s.

%s` - $href $version (. | $.Page.RenderString (dict "display" "block")) - }} - + {{- $inner := strings.TrimSpace . }} + {{- $text := printf "New in [v%s](%s)\n\n%s" $version $href $inner | $.Page.RenderString (dict "display" "block") }} {{ partial "layouts/blocks/alert.html" (dict - "text" ($text | safeHTML) "color" "green" "icon" "exclamation" + "text" $text ) }} {{- else }} @@ -62,5 +61,5 @@ Some descriptive text here. {{- end }} {{- end }} {{- else }} - {{- errorf "The %q shortcode requires a positional parameter (version). See %s" .Name .Position }} -{{- end -}} + {{- errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }} +{{- end }} diff --git a/layouts/shortcodes/note.html b/layouts/shortcodes/note.html index b18d53bc7..564480df3 100644 --- a/layouts/shortcodes/note.html +++ b/layouts/shortcodes/note.html @@ -1,7 +1,18 @@ -{{ $_hugo_config := `{ "version": 1 }` }} -{{ partial "layouts/blocks/alert.html" (dict - "text" .Inner +{{- /* + Renders a callout. + + @returns {template.HTML} + + @examples + + {{< note >}} + Some descriptive text here. + {{< /note >}} +*/}} +{{- $text := .Inner | strings.TrimSpace | .Page.RenderString (dict "display" "block") }} +{{- partial "layouts/blocks/alert.html" (dict "color" "blue" "icon" "exclamation" + "text" $text ) }}