Add methods deprecated in v0.120.0

Closes #2323
2026-08-24 23:38:53 +00:00 · 2023-11-11 11:58:03 -08:00
parent e1c6ecd0f1
commit 0f0ab2adee
24 changed files with 216 additions and 47 deletions
@@ -10,7 +10,7 @@ menu:
 weight: 50
 toc: true
 ---
-{{< new-in "0.93.0" >}}
+{{< new-in 0.93.0 >}}

 ## GoAT diagrams (Ascii)

@@ -110,7 +110,7 @@ Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. U

 ### Process

-{{< new-in "0.119.0" >}}
+{{< new-in 0.119.0 >}}

 {{% note %}}
 The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process).
@@ -205,7 +205,7 @@ Sometimes it can be useful to create the filter chain once and then reuse it.

 ### Colors

-{{< new-in "0.104.0" >}}
+{{< new-in 0.104.0 >}}

 `.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method.

@@ -97,7 +97,7 @@ weight

 ### Changes in Hugo 0.112.0

-{{< new-in "0.112.0" >}}
+{{< new-in 0.112.0 >}}

 In Hugo `v0.112.0` we consolidated all configuration options, and improved how the languages and their parameters are merged with the main configuration. But while testing this on Hugo sites out there, we received some error reports and reverted some of the changes in favor of deprecation warnings:

@@ -65,7 +65,7 @@ We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 di

 ## Index content headings in related content

-{{< new-in "0.111.0" >}}
+{{< new-in 0.111.0 >}}

 Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration:

@@ -140,16 +140,16 @@ toLower
 name
 : (`string`) The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.

-type {{< new-in "0.111.0" >}} 
+type {{< new-in 0.111.0 >}} 
 : (`string`) One of `basic`(default) or `fragments`.

-applyFilter {{< new-in "0.111.0" >}}
+applyFilter {{< new-in 0.111.0 >}}
 : (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type.

 weight
 : (`int`) An integer weight that indicates _how important_ this parameter is relative to the other parameters.  It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best.

-cardinalityThreshold {{< new-in "0.111.0" >}}
+cardinalityThreshold {{< new-in 0.111.0 >}}
 : (`int`) A percentage (0-100) used to remove common keywords from the index. As an example, setting this to `50` will remove all keywords that are used in more than 50% of the documents in the index. Default is `0`.

 pattern
@@ -41,7 +41,7 @@ Options:
 * `linenostart=199`: starts the line number count from 199.
 * `anchorlinenos`: Configure anchors on line numbers. Valid values are `true` or `false`;
 * `lineanchors`: Configure a prefix for the anchors on line numbers. Will be suffixed with `-`, so linking to the line number 1 with the option `lineanchors=prefix` adds the anchor `prefix-1` to the page.  
-* `hl_inline`  Highlight inside a `<code>` (inline HTML element) tag. Valid values are `true` or `false`. The `code` tag will get a class with name `code-inline`. {{< new-in "0.101.0" >}}
+* `hl_inline`  Highlight inside a `<code>` (inline HTML element) tag. Valid values are `true` or `false`. The `code` tag will get a class with name `code-inline`. {{< new-in 0.101.0 >}}

 ### Example: highlight shortcode

@@ -196,9 +196,55 @@ Rendered:

 These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.

+### deprecated-in
+
+Use the “deprecated-in” shortcode to indicate that a feature is deprecated:
+
+```text
+{{%/* deprecated-in 0.120.0 */%}}
+Use [`hugo.IsServer`] instead.
+
+[`hugo.IsServer`]: /functions/hugo/isserver
+{{%/* /deprecated-in */%}}
+```
+
+Rendered:
+
+{{% deprecated-in 0.120.0 %}}
+Use [`hugo.IsServer`] instead.
+
+[`hugo.IsServer`]: /functions/hugo/isserver
+{{% /deprecated-in %}}
+
+### code
+
+Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments:
+
+copy
+: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
+
+file
+: (`string`) The file name to display.
+
+lang
+: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is "html", sets the code language to `go-html-template`. Default is `text`.
+
+### code-toggle
+
+Use the "code-toggle" shortcode to display examples of site configuration, front matter, or data files. See the [code examples] above. This shortcode takes these arguments:
+
+copy
+: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
+
+file
+: (`string`) The file name to display. Omit the file extension for site configuration examples.
+
+fm
+: (`bool`) Whether the example is front matter. Default is `false`.
+
 ### new-in

-Use the "new-in" shortcode to indicate a new feature.
+Use the "new-in" shortcode to indicate a new feature:

 ```text
 {{</* new-in 0.120.0 */>}}
@@ -228,31 +274,37 @@ Use the [`math.Mod`] function to control...
 [`math.Mod`]: /functions/math/mod/
 {{% /code %}}

-### code-toggle
+## New features

-Use the "code-toggle" shortcode to display examples of site configuration, front matter, or data files. See the [code examples] above. This shortcode takes these arguments:
+Use the "new-in" shortcode to indicate a new feature:

-copy
-: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
+{{< code file=content/something/foo.md lang=text >}}
+{{</* new-in 0.120.0 */>}}
+{{< /code >}}

-file
-: (`string`) The file name to display. Omit the file extension for site configuration examples.
+## Deprecated features

-fm
-: (`bool`) Whether the example is front matter. Default is `false`.
+Use the "deprecated-in" shortcode to indicate that a feature is deprecated:

-### code
+{{< code file=content/something/foo.md >}}
+{{%/* deprecated-in 0.120.0 */%}}
+Use [`hugo.IsServer`] instead.

-Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments:
+[`hugo.IsServer`]: /functions/hugo/isserver
+{{%/* /deprecated-in */%}}
+{{< /code >}}

-copy
-: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
+When deprecating a function or method, add this to front matter:

-file
-: (`string`) The file name to display.
+{{< code-toggle file=content/something/foo.md fm=true >}}
+expiryDate: 2024-10-30 
+_build:
+  list: never
+{{< /code-toggle >}}

-lang
-: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is "html", sets the code language to `go-html-template`. Default is `text`.
+Set the `exipiryDate` to one year from the date of deprecation, and add a brief front matter comment to explain the settings.
+
+Users will be able to search for the page, but the page will not appear in any list views, including section menus.

 ## GitHub workflow

@@ -10,7 +10,7 @@ action:
  signatures: [debug.Timer NAME] 
 ---

-{{< new-in "0.120.0" >}}
+{{< new-in 0.120.0 >}}

 Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottle necks in templates.

@@ -10,6 +10,8 @@ action:
  signatures: [hugo.IsDevelopment]
 ---

+{{< new-in 0.120.0 >}}
+
 ```go-html-template
 {{ hugo.IsDevelopment }} → true/false
 ```
@@ -10,6 +10,8 @@ action:
  signatures: [hugo.IsServer]
 ---

+{{< new-in 0.120.0 >}}
+
 ```go-html-template
 {{ hugo.IsServer }} → true/false
 ```
@@ -13,6 +13,8 @@ action:
 toc: true
 ---

+{{< new-in 0.120.0 >}}
+
 The last argument is the canvas color, expressed as an RGB or RGBA [hexadecimal color]. The default value is `ffffffff` (opaque white). The preceding arguments are the padding values, in pixels, using the CSS [shorthand property] syntax. Negative padding values will crop the image.

 [hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
@@ -35,7 +35,7 @@ Multiple site configuration files can be specified as a comma-separated string t

 In Hugo 0.110.0 we changed the default configuration base file name to `hugo`, e.g. `hugo.toml`. We will still look for `config.toml` etc., but we recommend you eventually rename it (but you need to wait if you want to support older Hugo versions). The main reason we're doing this is to make it easier for code editors and build tools to identify this as a Hugo configuration file and project.

-{{< new-in "0.110.0" >}}
+{{< new-in 0.110.0 >}}

 ## Configuration directory

@@ -190,12 +190,10 @@ See [Configure File Caches](#configure-file-caches)

 ### cascade

-Pass down down default configuration values (front matter) to pages in the content tree. 
-The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade). 
+Pass down down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade).

 {{% note %}}
-For a website in a single language, define the `[[cascade]]` in [Front Matter](/content-management/front-matter#front-matter-cascade).   
-For a multilingual website, define the `[[cascade]]` in [Site Config](../../getting-started/configuration/#cascade).
+For a website in a single language, define the `[[cascade]]` in [Front Matter](/content-management/front-matter#front-matter-cascade). For a multilingual website, define the `[[cascade]]` in [Site Config](../../getting-started/configuration/#cascade).

 To remain consistent and prevent unexpected behaviour, do not mix these strategies.
 {{% /note %}}
@@ -523,7 +521,7 @@ The `build` configuration section contains global build-related configuration op

 {{< code-toggle config=build />}}

-buildStats {{< new-in "0.115.1" >}}
+buildStats {{< new-in 0.115.1 >}}
 : When enabled, creates a `hugo_stats.json` file in the root of your project. This file contains arrays of the `class` attributes, `id` attributes, and tags of every HTML element within your published site. Use this file as data source when [removing unused CSS] from your site. This process is also known as pruning, purging, or tree shaking.

 [removing unused CSS]: /hugo-pipes/postprocess/#css-purging-with-postcss
@@ -553,7 +551,7 @@ useResourceCacheWhen

 ## Configure cache busters

-{{< new-in "0.112.0" >}}
+{{< new-in 0.112.0 >}}

 The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this:

@@ -630,7 +628,7 @@ Setting `force=true` will make a redirect even if there is existing content in t

 ## 404 server error page {#_404-server-error-page}

-{{< new-in "0.103.0" >}}
+{{< new-in 0.103.0 >}}

 Hugo will, by default, render all 404 errors when running `hugo server` with the `404.html` template. Note that if you have already added one or more redirects to your [server configuration](#configure-server), you need to add the 404 redirect explicitly, e.g:

@@ -851,7 +849,7 @@ This can be set using the `cacheDir` config option or via the OS env variable `H
 If this is not set, Hugo will use, in order of preference:

 1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml).
-1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir](https://pkg.go.dev/os#UserCacheDir). On Unix systems, this is `$XDG_CACHE_HOME` as specified by [basedir-spec-latest](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. {{< new-in "0.116.0" >}}
+1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir](https://pkg.go.dev/os#UserCacheDir). On Unix systems, this is `$XDG_CACHE_HOME` as specified by [basedir-spec-latest](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. {{< new-in 0.116.0 >}}
 1. In a  `hugo_cache_$USER` directory below the OS temp dir.

 If you want to know the current value of `cacheDir`, you can run `hugo config`, e.g: `hugo config | grep cachedir`.
@@ -133,7 +133,7 @@ Also see the [CLI Doc](/commands/hugo_mod_clean/).

 ## Module workspaces

-{{< new-in "0.109.0" >}}
+{{< new-in 0.109.0 >}}

 Workspace support was added in [Go 1.18](https://go.dev/blog/get-familiar-with-workspaces) and Hugo got solid support for it in the `v0.109.0` version.

@@ -82,7 +82,7 @@ URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+San
 Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file.
 Hugo will look for imports relative to the module mount and will respect theme overrides.

-skipInlineImportsNotFound {{< new-in "0.99.0" >}}
+skipInlineImportsNotFound {{< new-in 0.99.0 >}}
 : (`bool`) Default is `false`. Before Hugo 0.99.0 when `inlineImports` was enabled and we failed to resolve an import, we logged it as a warning. We now fail the build. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set `skipInlineImportsNotFound` to true.

 {{< code file=layouts/partials/css.html >}}
@@ -88,7 +88,7 @@ HUGO_ENVIRONMENT
 : The value e.g. set with `hugo -e production` (defaults to `production` for `hugo` and `development` for `hugo server`).

 HUGO_PUBLISHDIR
-: {{< new-in "0.109.0" >}} The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this folder from PostCSS when running the server, you could run the server with one of these flags:
+: {{< new-in 0.109.0 >}} The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this folder from PostCSS when running the server, you could run the server with one of these flags:

 ```sh
 hugo server --renderToDisk
@@ -42,7 +42,7 @@ transpiler
 targetPath
 : (`string`) If not set, the transformed resource's target path will be the original path of the asset file with its extension replaced by `.css`.

-vars {{< new-in "0.109.0" >}}
+vars {{< new-in 0.109.0 >}}
 : (`map`) A map of key/value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/).

 ```scss
@@ -62,7 +62,7 @@ precision
 enableSourceMap
 : (`bool`) If `true`, generates a source map.

-sourceMapIncludeSources {{< new-in "0.108.0" >}}
+sourceMapIncludeSources {{< new-in 0.108.0 >}}
 : (`bool`) If `true`, embeds sources in the generated source map. Not applicable to LibSass.

 includePaths
@@ -0,0 +1,20 @@
+---
+title: DisqusShortname
+description: Returns the Disqus shortname as defined in the site configuration.
+categories: []
+keywords: []
+action:
+  related: []
+  returnType: string
+  signatures: [SITE.DisqusShortname]
+# deprecated 2023-10-30
+expiryDate: 2024-10-30 
+_build:
+  list: never
+---
+
+{{% deprecated-in 0.120.0 %}}
+Use [`Site.Config.Services.Disqus.Shortname`] instead.
+
+[`Site.Config.Services.Disqus.Shortname`]: /methods/site/config
+{{% /deprecated-in %}}
@@ -0,0 +1,20 @@
+---
+title: GoogleAnalytics
+description: Returns the Google Analytics tracking ID as defined in the site configuration.
+categories: []
+keywords: []
+action:
+  related: []
+  returnType: string
+  signatures: [SITE.GoogleAnalytics]
+# deprecated 2023-10-30
+expiryDate: 2024-10-30 
+_build:
+  list: never
+---
+
+{{% deprecated-in 0.120.0 %}}
+Use [`Site.Config.Services.GoogleAnalytics.ID`] instead.
+
+[`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config
+{{% /deprecated-in %}}
@@ -0,0 +1,20 @@
+---
+title: IsDevelopment
+description: Reports whether the current running environment is “development”.
+categories: []
+keywords: []
+action:
+  related: []
+  returnType: bool
+  signatures: [SITE.IsDevelopment]
+# deprecated 2023-10-30
+expiryDate: 2024-10-30 
+_build:
+  list: never
+---
+
+{{% deprecated-in 0.120.0 %}}
+Use [`hugo.IsDevelopment`] instead.
+
+[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment
+{{% /deprecated-in %}}
@@ -0,0 +1,20 @@
+---
+title: IsServer
+description: Reports whether the built-in development server is running.
+categories: []
+keywords: []
+action:
+  related: []
+  returnType: bool
+  signatures: [SITE.IsServer]
+# deprecated 2023-10-30
+expiryDate: 2024-10-30 
+_build:
+  list: never
+---
+
+{{% deprecated-in 0.120.0 %}}
+Use [`hugo.IsServer`] instead.
+
+[`hugo.IsServer`]: /functions/hugo/isserver
+{{% /deprecated-in %}}
@@ -23,7 +23,7 @@ The hook kinds currently supported are:
 * `image`
 * `link`
 * `heading`
-* `codeblock`{{< new-in "0.93.0" >}}
+* `codeblock`{{< new-in 0.93.0 >}}

 You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this:

@@ -91,10 +91,10 @@ Attributes (map)

 The `render-image` templates will also receive:

-IsBlock {{< new-in "0.108.0" >}}
+IsBlock {{< new-in 0.108.0 >}}
 : Returns true if this is a standalone image and the configuration option [markup.goldmark.parser.wrapStandAloneImageWithinParagraph](/getting-started/configuration-markup/#goldmark) is disabled.

-Ordinal  {{< new-in "0.108.0" >}}
+Ordinal  {{< new-in 0.108.0 >}}
 : Zero-based ordinal for all the images in the current document.

 ### Link with title markdown example
@@ -145,7 +145,7 @@ The rendered html will be

 ## Render hooks for code blocks

-{{< new-in "0.93.0" >}}
+{{< new-in 0.93.0 >}}

 You can add a hook template for either all code blocks or for a specific type/language (`bash` in the example below):

@@ -25,8 +25,7 @@ Think of deprecation as a statement of intent. This Wikipedia [article] describe
 - The feature is considered extraneous, and will be removed in the future in order to simplify the system as a whole.
 - A future version of the software will make major structural changes, making it impossible or impractical to support older features.
 - Standardization or increased consistency in naming.
- A feature that once was available only independently is now combined with its co-feature. 
-
+- A feature that once was available only independently is now combined with its co-feature.

 After the project team deprecates something in code, Hugo will:

@@ -0,0 +1,14 @@
+{{ $_hugo_config := `{ "version": 1 }` }}
+
+{{ with .Get 0 }}
+  {{ $version := printf "v%v" (strings.TrimLeft "vV" .) }}
+  {{ $href := printf "https://github.com/gohugoio/hugo/releases/tag/%s" $version }}
+  <aside>
+    <div class="admonition-content bl bw2 b--dark-red" >
+      <p>Deprecated in <a href="{{ $href }}">{{ $version }}</a></p>
+      {{ $.Inner }}
+    </div>
+  </aside>
+{{ else }}
+  {{ errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }}
+{{ end }}
@@ -0,0 +1,13 @@
+{{ $version := .Get 0 }}
+{{ if not $version }}
+  {{ errorf "Missing version in new-in shortcode " }}
+{{ end }}
+{{ $version = $version | strings.TrimPrefix "v" }}
+<button
+  class="bg-white hover:bg-gray-100 text-gray-800 font-semibold py-2 mr2 px-4 border border-gray-400 rounded shadow">
+  <a
+    href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}"
+    target="_blank"
+    >New in v{{ $version }}</a
+  >
+</button>
@@ -0,0 +1,7 @@
+{{ $_hugo_config := `{ "version": 1 }` }}
+
+<aside>
+  <div class="admonition-content bl bw2 b--blue" >
+    {{ .Inner }}
+  </div>
+</aside>