Update OS functions

Corrections and clarifications.

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:
 
-```
+```text
-{{ if (fileExists "static/img/banner.jpg") -}}
+content/
-<img src="{{ "img/banner.jpg" | absURL }}" />
+├── about.md
-{{- end }}
+├── 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
+```

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
+```go-html-template
-an empty string if the variable is not set, otherwise returns the
+{{ os.Getenv "HOME" }} --> /home/victor
-value of the variable.
+{{ os.Getenv "USER" }} --> victor
-
-```
-{{ getenv "HOME" }}
 ```
 
-{{% note %}}
+You can pass values when building your site:
-In Unix-like environments, the variable must also be exported in order to be seen by `hugo`.
+
-{{% /note %}}
+```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
+```

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):
+```go-html-template
-```
+{{ $f := os.Stat "README.md" }}
-{{ $stat := os.Stat "README.txt" }}
+{{ $f.IsDir }}    --> false (bool)
-{{ $stat.Name }} → "README.txt"
+{{ $f.ModTime }}  --> 2021-11-25 10:06:49.315429236 -0800 PST (time.Time)
-{{ $stat.Size }} → 30
+{{ $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].
+Details of the `FileInfo` structure are available in the [Go documentation](https://pkg.go.dev/io/fs#FileInfo).
-For further information of `os.FileInfo`, see [golang page][osfileinfo].
-
-
-[Stat]: /functions/os.Stat/
-[osfileinfo]: https://golang.org/pkg/os/#FileInfo

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.
+description: Returns an array of FileInfo structures sorted by filename, one element for each directory entry.
-date: 2017-02-01
 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:
 
-```
+```text
-{{ range (readDir ".") }}{{ .Name }}{{ end }} → "README.txt"
+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" >}}).

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!`:
+```text
-
+This is **bold** text.
-```
-{{readFile "README.txt"}} → "Hugo Rocks!"
 ```
 
-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" >}}).