diff --git a/content/en/functions/fileExists.md b/content/en/functions/fileExists.md index bb84a1c09..2175453de 100644 --- a/content/en/functions/fileExists.md +++ b/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") -}} - -{{- 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 +``` diff --git a/content/en/functions/getenv.md b/content/en/functions/getenv.md index 9ada0d031..f7f71d35c 100644 --- a/content/en/functions/getenv.md +++ b/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 +``` diff --git a/content/en/functions/os.Stat.md b/content/en/functions/os.Stat.md index 8e4e79b01..a56f79735 100644 --- a/content/en/functions/os.Stat.md +++ b/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). diff --git a/content/en/functions/readdir.md b/content/en/functions/readdir.md index a70e1f8bc..70fe7b66c 100644 --- a/content/en/functions/readdir.md +++ b/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" >}}). diff --git a/content/en/functions/readfile.md b/content/en/functions/readfile.md index f89ac02d9..b0a88458b 100644 --- a/content/en/functions/readfile.md +++ b/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" >}}).