Merge commit '8d9511a08f14260cbfb73119e4afae50e5a9966d'

docs/content/en/functions/GetPage.md

@@ -20,7 +20,7 @@ aliases: []
 `.GetPage` returns a page of a given `path`. Both `Site` and `Page` implements this method. The `Page` variant will, if given a relative path -- i.e. a path without a leading `/` -- try look for the page relative to the current page.
 
 {{% note %}}
-**Note:** We overhauled and simplified the `.GetPage` API in Hugo 0.45. Before that you needed to provide a `Kind` attribute in addition to the path, e.g. `{{ .Site.GetPage "section" "blog" }}`. This will still work, but is now superflous.
+**Note:** We overhauled and simplified the `.GetPage` API in Hugo 0.45. Before that you needed to provide a `Kind` attribute in addition to the path, e.g. `{{ .Site.GetPage "section" "blog" }}`. This will still work, but is now superfluous.
 {{% /note %}}
 
 
@@ -28,7 +28,7 @@ aliases: []
 {{ with .Site.GetPage "/blog" }}{{ .Title }}{{ end }}
 ```
 
-This method wil return `nil` when no page could be found, so the above will not print anything if the blog section is not found.
+This method will return `nil` when no page could be found, so the above will not print anything if the blog section is not found.
 
 To find a regular page in the blog section::
 

docs/content/en/functions/dict.md

@@ -19,7 +19,7 @@ aliases: []
 
 `dict` is especially useful for passing more than one value to a partial template.
 
-Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deply nested structure, e.g.:
+Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.:
 
 ```go-text-template
 {{ $m := dict (slice "a" "b" "c") "value" }}

docs/content/en/functions/fileExists.md

@@ -2,27 +2,41 @@
 title: "fileExists"
 linktitle: "fileExists"
 date: 2017-08-31T22:38:22+02:00
-description: Checks whether a file exists under the given path.
+description: Checks for file or directory existence.
 publishdate: 2017-08-31T22:38:22+02:00
-lastmod: 2017-08-31T22:38:22+02:00
+lastmod: 2021-11-26
 categories: [functions]
 menu:
   docs:
     parent: "functions"
-signature: ["fileExists PATH"]
+signature: ["os.FileExists PATH","fileExists PATH"]
 workson: []
 hugoversion:
-relatedfuncs: []
+relatedfuncs: ['os.ReadDir','os.ReadFile','os.Stat']
 deprecated: false
 aliases: []
 ---
+The `os.FileExists` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`]({{< relref "getting-started/configuration#contentdir">}}). A leading path separator (`/`) is optional.
 
-`fileExists` allows you to check if a file exists under a given path, e.g. before inserting code into a template:
+With this directory structure:
 
-```
-{{ if (fileExists "static/img/banner.jpg") -}}
-<img src="{{ "img/banner.jpg" | absURL }}" />
-{{- end }}
+```text
+content/
+├── about.md
+├── contact.md
+└── news/
+    ├── article-1.md
+    └── article-2.md
 ```
 
-In the example above, a banner from the `static` folder should be shown if the given path points to an existing file.
+The function returns these values:
+
+```go-html-template
+{{ os.FileExists "content" }} --> true
+{{ os.FileExists "content/news" }} --> true
+{{ os.FileExists "content/news/article-1" }} --> false
+{{ os.FileExists "content/news/article-1.md" }} --> true
+{{ os.FileExists "news" }} --> true
+{{ os.FileExists "news/article-1" }} --> false
+{{ os.FileExists "news/article-1.md" }} --> true
+```

docs/content/en/functions/getenv.md

@@ -1,30 +1,43 @@
 ---
 title: getenv
-description: Returns the value of an environment variable.
+description: Returns the value of an environment variable, or an empty string if the environment variable is not set.
 date: 2017-02-01
 publishdate: 2017-02-01
-lastmod: 2017-02-01
+lastmod: 2021-11-26
 categories: [functions]
 menu:
   docs:
     parent: "functions"
 keywords: []
-signature: ["getenv VARIABLE"]
+signature: ["os.Getenv VARIABLE", "getenv VARIABLE"]
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
 aliases: []
 ---
+Examples:
 
-Takes a string containing the name of the variable as input. Returns
-an empty string if the variable is not set, otherwise returns the
-value of the variable.
-
-```
-{{ getenv "HOME" }}
+```go-html-template
+{{ os.Getenv "HOME" }} --> /home/victor
+{{ os.Getenv "USER" }} --> victor
 ```
 
-{{% note %}}
-In Unix-like environments, the variable must also be exported in order to be seen by `hugo`.
-{{% /note %}}
+You can pass values when building your site:
+
+```bash
+MY_VAR1=foo MY_VAR2=bar hugo
+
+OR
+
+export MY_VAR1=foo
+export MY_VAR2=bar
+hugo
+```
+
+And then retrieve the values within a template:
+
+```go-html-template
+{{ os.Getenv "MY_VAR1" }} --> foo
+{{ os.Getenv "MY_VAR2" }} --> bar
+```

docs/content/en/functions/os.Stat.md

@@ -1,9 +1,9 @@
 ---
 title: os.Stat
-description: Gets a file information of a given path.
+description: Returns a FileInfo structure describing a file or directory.
 date: 2018-08-07
 publishdate: 2018-08-07
-lastmod: 2018-08-07
+lastmod: 2021-11-26
 categories: [functions]
 menu:
   docs:
@@ -12,21 +12,21 @@ keywords: [files]
 signature: ["os.Stat PATH"]
 workson: []
 hugoversion:
-relatedfuncs: [readDir]
+relatedfuncs: ['os.FileExists','os.ReadDir','os.ReadFile']
 deprecated: false
 aliases: []
 ---
+The `os.Stat` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`]({{< relref "getting-started/configuration#contentdir">}}). A leading path separator (`/`) is optional.
 
-If your current project working directory has a single file named `README.txt` (30 bytes):
-```
-{{ $stat := os.Stat "README.txt" }}
-{{ $stat.Name }} → "README.txt"
-{{ $stat.Size }} → 30
+```go-html-template
+{{ $f := os.Stat "README.md" }}
+{{ $f.IsDir }}    --> false (bool)
+{{ $f.ModTime }}  --> 2021-11-25 10:06:49.315429236 -0800 PST (time.Time)
+{{ $f.Name }}     --> README.md (string)
+{{ $f.Size }}     --> 241 (int64)
+
+{{ $d := os.Stat "content" }}
+{{ $d.IsDir }}    --> true (bool)
 ```
 
-Function [`os.Stat`][Stat] returns [`os.FileInfo`][osfileinfo].
-For further information of `os.FileInfo`, see [golang page][osfileinfo].
-
-
-[Stat]: /functions/os.Stat/
-[osfileinfo]: https://golang.org/pkg/os/#FileInfo
+Details of the `FileInfo` structure are available in the [Go documentation](https://pkg.go.dev/io/fs#FileInfo).

docs/content/en/functions/readdir.md

@@ -1,28 +1,51 @@
 ---
 title: readDir
-description: Gets a directory listing from a directory relative to the current working directory.
-date: 2017-02-01
+description: Returns an array of FileInfo structures sorted by filename, one element for each directory entry.
 publishdate: 2017-02-01
-lastmod: 2017-02-01
+lastmod: 2021-11-26
 categories: [functions]
 menu:
   docs:
     parent: "functions"
 keywords: [files]
-signature: ["readDir PATH"]
+signature: ["os.ReadDir PATH", "readDir PATH"]
 workson: []
 hugoversion:
-relatedfuncs: [readFile]
+relatedfuncs: ['os.FileExists','os.ReadFile','os.Stat']
 deprecated: false
 aliases: []
 ---
+The `os.ReadDir` function resolves the path relative to the root of your project directory. A leading path separator (`/`) is optional.
 
-If your current project working directory has a single file named `README.txt`:
+With this directory structure:
 
-```
-{{ range (readDir ".") }}{{ .Name }}{{ end }} → "README.txt"
+```text
+content/
+├── about.md
+├── contact.md
+└── news/
+    ├── article-1.md
+    └── article-2.md
 ```
 
-For more information on using `readDir` and `readFile` in your templates, see [Local File Templates][local].
+This template code:
 
-[local]: /templates/files/
+```go-html-template
+{{ range os.ReadDir "content" }}
+  {{ .Name }} --> {{ .IsDir }}
+{{ end }}
+```
+
+Produces:
+
+```html
+about.md --> false
+contact.md --> false
+news --> true
+```
+
+Note that `os.ReadDir` is not recursive.
+
+Details of the `FileInfo` structure are available in the [Go documentation](https://pkg.go.dev/io/fs#FileInfo).
+
+For more information on using `readDir` and `readFile` in your templates, see [Local File Templates]({{< relref "/templates/files" >}}).

docs/content/en/functions/readfile.md

@@ -1,32 +1,41 @@
 ---
 title: readFile
-description: Reads a file from disk relative to the current project working directory and returns a string.
+description: Returns the contents of a file.
 date: 2017-02-01
 publishdate: 2017-02-01
-lastmod: 2017-04-30
+lastmod: 2021-11-26
 categories: [functions]
 menu:
   docs:
     parent: "functions"
 keywords: [files]
-signature: ["readFile PATH"]
+signature: ["os.ReadFile PATH", "readFile PATH"]
 workson: []
 hugoversion:
-relatedfuncs: [readDir]
+relatedfuncs: ['os.FileExists','os.ReadDir','os.Stat']
 deprecated: false
 aliases: []
 ---
+The `os.ReadFile` function attempts to resolve the path relative to the root of your project directory. If a matching file is not found, it will attempt to resolve the path relative to the [`contentDir`]({{< relref "getting-started/configuration#contentdir">}}). A leading path separator (`/`) is optional.
 
-Note that the filename must be relative to the current project working directory, or the project's `/content` folder. 
+With a file named README.md in the root of your project directory:
 
-So, if you have a file with the name `README.txt` in the root of your project with the content `Hugo Rocks!`:
-
-```
-{{readFile "README.txt"}} → "Hugo Rocks!"
+```text
+This is **bold** text.
 ```
 
-If you receive a "file doesn't exist" error with a path listed, do take note that the path is the last one checked by the function, and may not accurately reflect your target. You should generally double-check your path for mistakes.
+This template code:
 
-For more information on using `readDir` and `readFile` in your templates, see [Local File Templates][local].
+```go-html-template
+{{ os.ReadFile "README.md" }}
+```
 
-[local]: /templates/files/
+Produces:
+
+```html
+This is **bold** text.
+```
+
+Note that `os.ReadFile` returns raw (uninterpreted) content.
+
+For more information on using `readDir` and `readFile` in your templates, see [Local File Templates]({{< relref "/templates/files" >}}).

docs/content/en/functions/substr.md

@@ -22,7 +22,7 @@ It normally takes two parameters: `start` and `length`. It can also take one par
 
 To extract characters from the end of the string, use a negative start number.
 
-In addition, borrowing from the extended behavior described at https://php.net substr, if `length` is given and is negative, that number of characters will be omitted from the end of string.
+If `length` is given and is negative, that number of characters will be omitted from the end of string.
 
 ```
 {{ substr "abcdef" 0 }} → "abcdef"

docs/content/en/functions/unix.md

@@ -1,35 +1,31 @@
 ---
 title: .Unix
-draft: false
-description: .Unix returns the local Time corresponding to the given Unix time, sec seconds and nsec nanoseconds since January 1, 1970 UTC.
+description: Converts a time.Time value to the number of seconds elapsed since the Unix epoch, excluding leap seconds. The Unix epoch is 00:00:00 UTC on 1 January 1970.
 date: 2017-02-01
-publishdate: 2017-02-01
-lastmod: 2017-02-01
 keywords: [dates,time]
 categories: [functions]
 menu:
   docs:
     parent: "functions"
-signature: [".Unix"]
-workson: [times]
-hugoversion:
+signature: [".Unix",".UnixMilli",".UnixMicro",".UnixNano"]
 relatedfuncs: [Format,dateFormat,now,time]
-deprecated: false
-aliases: []
 ---
 
-## Example: Time Passed Since Last Modification
+The `Milli`, `Micro`, and `Nano` variants return the number of milliseconds, microseconds, and nanoseconds (respectively) elapsed since the Unix epoch.
 
-This very simple one-liner uses `now.Unix` to calculate the amount of time that has passed between the `.LastMod` for the current page and the last build of the current page.
+```go-html-template
+.Date.Unix        --> 1637259694
+.ExpiryDate.Unix  --> 1672559999
+.Lastmod.Unix     --> 1637361786
+.PublishDate.Unix --> 1637421261
 
-{{< code file="time-passed.html" >}}
-{{ div (sub now.Unix .Lastmod.Unix) 86400 }}
-{{< /code >}}
+("1970-01-01T00:00:00-00:00" | time.AsTime).Unix --> 0
+("1970-01-01T00:00:42-00:00" | time.AsTime).Unix --> 42
+("1970-04-11T01:48:29-08:00" | time.AsTime).Unix --> 8675309
+("2026-05-02T20:09:31-07:00" | time.AsTime).Unix --> 1777777771
 
-Since both values are integers, they can be subtracted and then divided by the number of seconds in a day (i.e., `60 * 60 * 24 == 86400`).
-
-{{% note %}}
-Hugo's output is *static*. For the example above to be realistic, the site needs to be built every day.
- {{% /note %}}
-
-[partial template]: /templates/partials/
+now.Unix      --> 1637447841
+now.UnixMilli --> 1637447841347
+now.UnixMicro --> 1637447841347378
+now.UnixNano  --> 1637447841347378799
+```