diff --git a/website/docs/reference/_category_.yml b/website/docs/reference/_category_.yml
new file mode 100644
index 0000000000..3c6ca5c58f
--- /dev/null
+++ b/website/docs/reference/_category_.yml
@@ -0,0 +1,2 @@
+position: 4
+label: Reference
diff --git a/website/docs/reference/cli.mdx b/website/docs/reference/cli.mdx
new file mode 100644
index 0000000000..5f5e329683
--- /dev/null
+++ b/website/docs/reference/cli.mdx
@@ -0,0 +1,118 @@
+---
+slug: /reference/cli
+sidebar_position: 1
+---
+
+# CLI Reference
+
+Task CLI commands have the following syntax:
+
+```shell
+task [--flags] [tasks...] [-- CLI_ARGS...]
+```
+
+:::tip
+
+If `--` is given, all remaining arguments will be assigned to a special
+`CLI_ARGS` variable
+
+## Flags
+
+:::
+
+| Short | Flag | Type | Default | Description |
+| ----- | --------------------------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-c` | `--color` | `bool` | `true` | Colored output. Enabled by default. Set flag to `false` or use `NO_COLOR=1` to disable. |
+| `-C` | `--concurrency` | `int` | `0` | Limit number tasks to run concurrently. Zero means unlimited. |
+| `-d` | `--dir` | `string` | Working directory | Sets directory of execution. |
+| `-n` | `--dry` | `bool` | `false` | Compiles and prints tasks in the order that they would be run, without executing them. |
+| `-x` | `--exit-code` | `bool` | `false` | Pass-through the exit code of the task command. |
+| `-f` | `--force` | `bool` | `false` | Forces execution even when the task is up-to-date. |
+| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/Taskfile.{yml,yaml}`. |
+| `-h` | `--help` | `bool` | `false` | Shows Task usage. |
+| `-i` | `--init` | `bool` | `false` | Creates a new Taskfile.yml in the current folder. |
+| `-I` | `--interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
+| `-l` | `--list` | `bool` | `false` | Lists tasks with description of current Taskfile. |
+| `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. |
+| | `--sort` | `string` | `default` | Changes the order of the tasks when listed.
`default` - Alphanumeric with root tasks first
`alphanumeric` - Alphanumeric
`none` - No sorting (As they appear in the Taskfile) |
+| | `--json` | `bool` | `false` | See [JSON Output](#json-output) |
+| `-o` | `--output` | `string` | Default set in the Taskfile or `intervealed` | Sets output style: [`interleaved`/`group`/`prefixed`]. |
+| | `--output-group-begin` | `string` | | Message template to print before a task's grouped output. |
+| | `--output-group-end` | `string` | | Message template to print after a task's grouped output. |
+| | `--output-group-error-only` | `bool` | `false` | Swallow command output on zero exit code. |
+| `-p` | `--parallel` | `bool` | `false` | Executes tasks provided on command line in parallel. |
+| `-s` | `--silent` | `bool` | `false` | Disables echoing. |
+| `-y` | `--yes` | `bool` | `false` | Assume "yes" as answer to all prompts. |
+| | `--status` | `bool` | `false` | Exits with non-zero exit code if any of the given tasks is not up-to-date. |
+| | `--summary` | `bool` | `false` | Show summary about a task. |
+| `-t` | `--taskfile` | `string` | `Taskfile.yml` or `Taskfile.yaml` | |
+| `-v` | `--verbose` | `bool` | `false` | Enables verbose mode. |
+| | `--version` | `bool` | `false` | Show Task version. |
+| `-w` | `--watch` | `bool` | `false` | Enables watch of the given task.
+
+## Exit Codes
+
+Task will sometimes exit with specific exit codes. These codes are split into
+three groups with the following ranges:
+
+- General errors (0-99)
+- Taskfile errors (100-199)
+- Task errors (200-299)
+
+A full list of the exit codes and their descriptions can be found below:
+
+| Code | Description |
+| ---- | ------------------------------------------------------------ |
+| 0 | Success |
+| 1 | An unknown error occurred |
+| 100 | No Taskfile was found |
+| 101 | A Taskfile already exists when trying to initialize one |
+| 102 | The Taskfile is invalid or cannot be parsed |
+| 103 | A remote Taskfile could not be downloaded |
+| 104 | A remote Taskfile was not trusted by the user |
+| 105 | A remote Taskfile was could not be fetched securely |
+| 106 | No cache was found for a remote Taskfile in offline mode |
+| 107 | No schema version was defined in the Taskfile |
+| 200 | The specified task could not be found |
+| 201 | An error occurred while executing a command inside of a task |
+| 202 | The user tried to invoke a task that is internal |
+| 203 | There a multiple tasks with the same name or alias |
+| 204 | A task was called too many times |
+| 205 | A task was cancelled by the user |
+| 206 | A task was not executed due to missing required variables |
+
+These codes can also be found in the repository in
+[`errors/errors.go`](https://github.com/go-task/task/blob/main/errors/errors.go).
+
+:::info
+
+When Task is run with the `-x`/`--exit-code` flag, the exit code of any failed
+commands will be passed through to the user instead.
+
+:::
+
+## JSON Output
+
+When using the `--json` flag in combination with either the `--list` or
+`--list-all` flags, the output will be a JSON object with the following
+structure:
+
+```json
+{
+ "tasks": [
+ {
+ "name": "",
+ "desc": "",
+ "summary": "",
+ "up_to_date": false,
+ "location": {
+ "line": 54,
+ "column": 3,
+ "taskfile": "/path/to/Taskfile.yml"
+ }
+ }
+ // ...
+ ],
+ "location": "/path/to/Taskfile.yml"
+}
+```
diff --git a/website/docs/reference/environment.mdx b/website/docs/reference/environment.mdx
new file mode 100644
index 0000000000..095b610832
--- /dev/null
+++ b/website/docs/reference/environment.mdx
@@ -0,0 +1,37 @@
+---
+slug: /reference/environment
+sidebar_position: 4
+---
+
+# Environment Reference
+
+Task allows you to configure some behavior using environment variables. This
+page lists all the environment variables that Task supports.
+
+| ENV | Default | Description |
+| --------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `TASK_TEMP_DIR` | `.task` | Location of the temp dir. Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. |
+| `FORCE_COLOR` | | Force color output usage. |
+
+## Custom Colors
+
+| ENV | Default | Description |
+| -------------------- | ------- | ----------------------- |
+| `TASK_COLOR_RESET` | `0` | Color used for white. |
+| `TASK_COLOR_BLUE` | `34` | Color used for blue. |
+| `TASK_COLOR_GREEN` | `32` | Color used for green. |
+| `TASK_COLOR_CYAN` | `36` | Color used for cyan. |
+| `TASK_COLOR_YELLOW` | `33` | Color used for yellow. |
+| `TASK_COLOR_MAGENTA` | `35` | Color used for magenta. |
+| `TASK_COLOR_RED` | `31` | Color used for red. |
+
+All color variables are [ANSI color codes][ansi]. You can specify multiple codes
+separated by a semicolon. For example: `31;1` will make the text bold and red.
+Task also supports 8-bit color (256 colors). You can specify these colors by
+using the sequence `38;2;R:G:B` for foreground colors and `48;2;R:G:B` for
+background colors where `R`, `G` and `B` should be replaced with values between
+0 and 255.
+
+For convenience, we allow foreground colors to be specified using shorthand,
+comma-separated syntax: `R,G,B`. For example, `255,0,0` is equivalent to
+`38;2;255:0:0`.
diff --git a/website/docs/api_reference.mdx b/website/docs/reference/schema.mdx
similarity index 61%
rename from website/docs/api_reference.mdx
rename to website/docs/reference/schema.mdx
index 246fda59ef..75d4b0a7e1 100644
--- a/website/docs/api_reference.mdx
+++ b/website/docs/reference/schema.mdx
@@ -1,172 +1,11 @@
---
-slug: /api/
-sidebar_position: 4
+slug: /reference/schema
+sidebar_position: 2
toc_min_heading_level: 2
toc_max_heading_level: 5
---
-# API Reference
-
-## CLI
-
-Task command line tool has the following syntax:
-
-```shell
-task [--flags] [tasks...] [-- CLI_ARGS...]
-```
-
-:::tip
-
-If `--` is given, all remaining arguments will be assigned to a special
-`CLI_ARGS` variable
-
-:::
-
-| Short | Flag | Type | Default | Description |
-| ----- | --------------------------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `-c` | `--color` | `bool` | `true` | Colored output. Enabled by default. Set flag to `false` or use `NO_COLOR=1` to disable. |
-| `-C` | `--concurrency` | `int` | `0` | Limit number tasks to run concurrently. Zero means unlimited. |
-| `-d` | `--dir` | `string` | Working directory | Sets directory of execution. |
-| `-n` | `--dry` | `bool` | `false` | Compiles and prints tasks in the order that they would be run, without executing them. |
-| `-x` | `--exit-code` | `bool` | `false` | Pass-through the exit code of the task command. |
-| `-f` | `--force` | `bool` | `false` | Forces execution even when the task is up-to-date. |
-| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/Taskfile.{yml,yaml}`. |
-| `-h` | `--help` | `bool` | `false` | Shows Task usage. |
-| `-i` | `--init` | `bool` | `false` | Creates a new Taskfile.yml in the current folder. |
-| `-I` | `--interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
-| `-l` | `--list` | `bool` | `false` | Lists tasks with description of current Taskfile. |
-| `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. |
-| | `--sort` | `string` | `default` | Changes the order of the tasks when listed.
`default` - Alphanumeric with root tasks first
`alphanumeric` - Alphanumeric
`none` - No sorting (As they appear in the Taskfile) |
-| | `--json` | `bool` | `false` | See [JSON Output](#json-output) |
-| `-o` | `--output` | `string` | Default set in the Taskfile or `intervealed` | Sets output style: [`interleaved`/`group`/`prefixed`]. |
-| | `--output-group-begin` | `string` | | Message template to print before a task's grouped output. |
-| | `--output-group-end` | `string` | | Message template to print after a task's grouped output. |
-| | `--output-group-error-only` | `bool` | `false` | Swallow command output on zero exit code. |
-| `-p` | `--parallel` | `bool` | `false` | Executes tasks provided on command line in parallel. |
-| `-s` | `--silent` | `bool` | `false` | Disables echoing. |
-| `-y` | `--yes` | `bool` | `false` | Assume "yes" as answer to all prompts. |
-| | `--status` | `bool` | `false` | Exits with non-zero exit code if any of the given tasks is not up-to-date. |
-| | `--summary` | `bool` | `false` | Show summary about a task. |
-| `-t` | `--taskfile` | `string` | `Taskfile.yml` or `Taskfile.yaml` | |
-| `-v` | `--verbose` | `bool` | `false` | Enables verbose mode. |
-| | `--version` | `bool` | `false` | Show Task version. |
-| `-w` | `--watch` | `bool` | `false` | Enables watch of the given task. |
-
-## Exit Codes
-
-Task will sometimes exit with specific exit codes. These codes are split into
-three groups with the following ranges:
-
-- General errors (0-99)
-- Taskfile errors (100-199)
-- Task errors (200-299)
-
-A full list of the exit codes and their descriptions can be found below:
-
-| Code | Description |
-| ---- | ------------------------------------------------------------ |
-| 0 | Success |
-| 1 | An unknown error occurred |
-| 100 | No Taskfile was found |
-| 101 | A Taskfile already exists when trying to initialize one |
-| 102 | The Taskfile is invalid or cannot be parsed |
-| 103 | A remote Taskfile could not be downloaded |
-| 104 | A remote Taskfile was not trusted by the user |
-| 105 | A remote Taskfile was could not be fetched securely |
-| 106 | No cache was found for a remote Taskfile in offline mode |
-| 107 | No schema version was defined in the Taskfile |
-| 200 | The specified task could not be found |
-| 201 | An error occurred while executing a command inside of a task |
-| 202 | The user tried to invoke a task that is internal |
-| 203 | There a multiple tasks with the same name or alias |
-| 204 | A task was called too many times |
-| 205 | A task was cancelled by the user |
-| 206 | A task was not executed due to missing required variables |
-
-These codes can also be found in the repository in
-[`errors/errors.go`](https://github.com/go-task/task/blob/main/errors/errors.go).
-
-:::info
-
-When Task is run with the `-x`/`--exit-code` flag, the exit code of any failed
-commands will be passed through to the user instead.
-
-:::
-
-## JSON Output
-
-When using the `--json` flag in combination with either the `--list` or
-`--list-all` flags, the output will be a JSON object with the following
-structure:
-
-```json
-{
- "tasks": [
- {
- "name": "",
- "desc": "",
- "summary": "",
- "up_to_date": false,
- "location": {
- "line": 54,
- "column": 3,
- "taskfile": "/path/to/Taskfile.yml"
- }
- }
- // ...
- ],
- "location": "/path/to/Taskfile.yml"
-}
-```
-
-## Special Variables
-
-There are some special variables that is available on the templating system:
-
-| Var | Description |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `CLI_ARGS` | Contain all extra arguments passed after `--` when calling Task through the CLI. |
-| `CLI_FORCE` | A boolean containing whether the `--force` or `--force-all` flags were set. |
-| `TASK` | The name of the current task. |
-| `TASK_EXE` | The Task executable name or path. |
-| `ROOT_TASKFILE` | The absolute path of the root Taskfile. |
-| `ROOT_DIR` | The absolute path of the root Taskfile directory. |
-| `TASKFILE` | The absolute path of the included Taskfile. |
-| `TASKFILE_DIR` | The absolute path of the included Taskfile directory. |
-| `USER_WORKING_DIR` | The absolute path of the directory `task` was called from. |
-| `CHECKSUM` | The checksum of the files listed in `sources`. Only available within the `status` prop and if method is set to `checksum`. |
-| `TIMESTAMP` | The date object of the greatest timestamp of the files listed in `sources`. Only available within the `status` prop and if method is set to `timestamp`. |
-| `TASK_VERSION` | The current version of task. |
-| `ITEM` | The value of the current iteration when using the `for` property. Can be changed to a different variable name using `as:`. |
-
-## ENV
-
-Some environment variables can be overridden to adjust Task behavior.
-
-| ENV | Default | Description |
-| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
-| `TASK_TEMP_DIR` | `.task` | Location of the temp dir. Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. |
-| `TASK_COLOR_RESET` | `0` | Color used for white. |
-| `TASK_COLOR_BLUE` | `34` | Color used for blue. |
-| `TASK_COLOR_GREEN` | `32` | Color used for green. |
-| `TASK_COLOR_CYAN` | `36` | Color used for cyan. |
-| `TASK_COLOR_YELLOW` | `33` | Color used for yellow. |
-| `TASK_COLOR_MAGENTA` | `35` | Color used for magenta. |
-| `TASK_COLOR_RED` | `31` | Color used for red. |
-| `FORCE_COLOR` | | Force color output usage. |
-
-All color variables are [ANSI color codes][ansi]. You can specify multiple codes
-separated by a semicolon. For example: `31;1` will make the text bold and red.
-Task also supports 8-bit color (256 colors). You can specify these colors by
-using the sequence `38;2;R:G:B` for foreground colors and `48;2;R:G:B` for
-background colors where `R`, `G` and `B` should be replaced with values between
-0 and 255.
-
-For convenience, we allow foreground colors to be specified using shorthand,
-comma-separated syntax: `R,G,B`. For example, `255,0,0` is equivalent to
-`38;2;255:0:0`.
-
-## Taskfile Schema
+# Schema Reference
| Attribute | Type | Default | Description |
| ---------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -184,7 +23,7 @@ comma-separated syntax: `R,G,B`. For example, `255,0,0` is equivalent to
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). |
| `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
-### Include
+## Include
| Attribute | Type | Default | Description |
| ---------- | --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -207,7 +46,7 @@ includes:
:::
-### Variable
+## Variable
| Attribute | Type | Default | Description |
| --------- | -------- | ------- | ------------------------------------------------------------------------ |
@@ -240,7 +79,7 @@ vars:
:::
-### Task
+## Task
| Attribute | Type | Default | Description |
| --------------- | ---------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -290,7 +129,7 @@ tasks:
:::
-#### Command
+### Command
| Attribute | Type | Default | Description |
| -------------- | ---------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -319,7 +158,7 @@ tasks:
:::
-#### Dependency
+### Dependency
| Attribute | Type | Default | Description |
| --------- | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
@@ -340,7 +179,7 @@ tasks:
:::
-#### For
+### For
The `for` parameter can be defined as a string, a list of strings or a map. If
it is defined as a string, you can give it any of the following values:
@@ -360,7 +199,7 @@ variable to define the values to loop over:
| `split` | `string` | (any whitespace) | What string the variable should be split on. |
| `as` | `string` | `ITEM` | The name of the iterator variable. |
-#### Precondition
+### Precondition
| Attribute | Type | Default | Description |
| --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
@@ -380,7 +219,7 @@ tasks:
:::
-#### Requires
+### Requires
| Attribute | Type | Default | Description |
| --------- | ---------- | ------- | -------------------------------------------------------------------------------------------------- |
diff --git a/website/docs/reference/templating.mdx b/website/docs/reference/templating.mdx
new file mode 100644
index 0000000000..5a06582e2a
--- /dev/null
+++ b/website/docs/reference/templating.mdx
@@ -0,0 +1,406 @@
+---
+slug: /reference/templating/
+sidebar_position: 3
+toc_min_heading_level: 2
+toc_max_heading_level: 5
+---
+
+# Templating Reference
+
+Task's templating engine uses Go's [text/template][text/template] package to
+interpolate values. For detailed information about the usage of Go's templating
+engine, we recommend reading [the official documentation][text/template].
+However, we will provide a basic overview of the main features here.
+
+## Basic Usage
+
+Most string values in Task (though, not all) can be templated. The templating
+engine uses double curly braces `{{` and `}}` to denote a template. Anything
+inside the curly braces will be executed as a Go template and the result will be
+inserted into the resulting string. For example:
+
+```yaml
+version: '3'
+
+tasks:
+ hello:
+ vars:
+ MESSAGE: 'Hello, World!'
+ cmds:
+ - 'echo {{.MESSAGE}}'
+```
+
+In this example, we have a task called `hello` with a single variable, `MESSAGE`
+defined. When the command is run, the templating engine will evaluate the
+variable and replace `{{.MESSAGE}}` with the variable's contents. This task will
+output `Hello, World!` to the terminal. Note that when referring to a variable,
+you must use dot notation.
+
+You are also able to do more complex things in templates, such as conditional
+logic:
+
+```yaml
+version: '3'
+
+tasks:
+ maybe-happy:
+ vars:
+ SMILE: ':\)'
+ FROWN: ':\('
+ HAPPY: true
+ cmds:
+ - 'echo {{if .HAPPY}}{{.SMILE}}{{else}}{{.FROWN}}{{end}}'
+```
+
+```txt
+:)
+```
+
+...calling functions and piping values:
+
+```yaml
+version: '3'
+
+tasks:
+ uniq:
+ vars:
+ NUMBERS: '0,1,1,1,2,2,3'
+ cmds:
+ - 'echo {{splitList "," .NUMBERS | uniq | join ", " }}!'
+```
+
+```txt
+0, 1, 2, 3
+```
+
+...looping over values with control flow operators:
+
+```yaml
+version: '3'
+
+tasks:
+ loop:
+ vars:
+ NUMBERS: [0, 1, 1, 1, 2, 2, 3]
+ cmds:
+ # Ranges over NUMBERS and prints the index and value of each number until it finds a number greater than 1
+ - "{{range $index, $num := .NUMBERS}}{{if gt $num 1 }}{{break}}{{end}}echo {{$index}}: {{$num}}\n{{end}}"
+```
+
+```txt
+0: 0
+1: 1
+2: 1
+3: 1
+```
+
+## Special Variables
+
+Task defines some special variables that are always available to the templating
+engine. If you define a variable with the same name as a special variable, the
+special variable will be overridden.
+
+| Var | Description |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CLI_ARGS` | Contain all extra arguments passed after `--` when calling Task through the CLI. |
+| `CLI_FORCE` | A boolean containing whether the `--force` or `--force-all` flags were set. |
+| `TASK` | The name of the current task. |
+| `TASK_EXE` | The Task executable name or path. |
+| `ROOT_TASKFILE` | The absolute path of the root Taskfile. |
+| `ROOT_DIR` | The absolute path of the root Taskfile directory. |
+| `TASKFILE` | The absolute path of the included Taskfile. |
+| `TASKFILE_DIR` | The absolute path of the included Taskfile directory. |
+| `USER_WORKING_DIR` | The absolute path of the directory `task` was called from. |
+| `CHECKSUM` | The checksum of the files listed in `sources`. Only available within the `status` prop and if method is set to `checksum`. |
+| `TIMESTAMP` | The date object of the greatest timestamp of the files listed in `sources`. Only available within the `status` prop and if method is set to `timestamp`. |
+| `TASK_VERSION` | The current version of task. |
+| `ITEM` | The value of the current iteration when using the `for` property. Can be changed to a different variable name using `as:`. |
+
+## Functions
+
+Functions are provided at a few different levels in Task. Below, we list all the
+functions available for use in Task.
+
+:::note
+
+Functions marked with an astrix (\*) also have `must` variants that will panic
+rather than erroring.
+
+:::
+
+### Built-in Functions
+
+The first set of functions are [provided by Golang
+itself][go-template-functions]:
+
+| Function | Description |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `and` | Returns the boolean AND of its arguments by returning the first empty argument or the last argument. That is, `and x y` behaves as `if x then y else x`. Evaluation proceeds through the arguments left to right and returns when the result is determined. |
+| `call` | Returns the result of calling the first argument, which must be a function, with the remaining arguments as parameters. Thus `call .X.Y 1 2` is, in Go notation, `dot.X.Y(1, 2)` where `Y` is a func-valued field, map entry, or the like. The first argument must be the result of an evaluation that yields a value of function type (as distinct from a predefined function such as print). The function must return either one or two result values, the second of which is of type error. If the arguments don't match the function or the returned error value is non-nil, execution stops. |
+| `html` | Returns the escaped HTML equivalent of the textual representation of its arguments. This function is unavailable in [html/template][html/template], with a few exceptions. |
+| `index` | Returns the result of indexing its first argument by the following arguments. Thus `index x 1 2 3` is, in Go syntax, `x[1][2][3]`. Each indexed item must be a map, slice, or array. |
+| `slice` | slice returns the result of slicing its first argument by the remaining arguments. Thus `slice x 1 2` is, in Go syntax, `x[1:2]`, while `slice x` is `x[:]`, `slice x 1` is `x[1:]`, and `slice x 1 2 3` is `x[1:2:3]`. The first argument must be a string, slice, or array. |
+| `js` | Returns the escaped JavaScript equivalent of the textual representation of its arguments. |
+| `len` | Returns the integer length of its argument. |
+| `not` | Returns the boolean negation of its single argument. |
+| `or` | Returns the boolean OR of its arguments by returning the first non-empty argument or the last argument, that is, `or x y` behaves as `if x then x else y`. Evaluation proceeds through the arguments left to right and returns when the result is determined. |
+| `print` | An alias for `fmt.Sprint`. |
+| `printf` | An alias for `fmt.Sprintf`. |
+| `println` | An alias for `fmt.Sprintln`. |
+| `urlquery` | Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query. This function is unavailable in [html/template][html/template], with a few exceptions. |
+
+### Slim-Sprig Functions
+
+In addition to the built-in functions, Task also provides a set of functions
+imported via the [slim-sprig][slim-sprig] package. We only provide a very basic
+descroption here for completeness. For detailed usage, please refer to the
+[slim-sprig documentation][slim-sprig]:
+
+#### [String Functions][string-functions]
+
+| Function | Description |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `trim` | Removes space from either side of a string. |
+| `trimAll` | Removes given characters from the front or back of a string. |
+| `trimSuffix` | Trims just the suffix from a string. |
+| `trimPrefix` | Trims just the prefix from a string. |
+| `upper` | Converts the entire string to uppercase. |
+| `lower` | Converts the entire string to lowercase. |
+| `title` | Converts to title case. |
+| `repeat` | Repeats a string multiple times. |
+| `substr` | Gets a substring from a string. |
+| `trunc` | Truncates a string. |
+| `contains` | Tests to see if one string is contained inside of another. |
+| `hasPrefix` | Tests whether a string has a given prefix. |
+| `hasSuffix` | Tests whether a string has a given suffix. |
+| `quote` | Wraps a string in double quotes. |
+| `squote` | Wraps a string in single quotes. |
+| `cat` | Concatenates multiple strings together into one, separating them with spaces. |
+| `indent` | Indents every line in a given string to the specified indent width. |
+| `nindent` | Identical to `indent`, but prepends a new line to the beginning of the string. |
+| `replace` | Replaces a string. |
+| `plural` | Pluralizes a string. |
+| `regexMatch`\* | Returns true if the input string contains any match of the regular expression. |
+| `regexFindAll`\* | Returns a slice of all matches of the regular expression in the input string. |
+| `regexFind`\* | Returns the first (left most) match of the regular expression in the input string. |
+| `regexReplaceAll`\* | Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement. |
+| `regexReplaceAllLiteral`\* | Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement without expanding `$`. |
+| `regexSplit`\* | Slices the input string into substrings separated by the expression and returns a slice of the substrings between those expression matches. |
+| `regexQuoteMeta`\* | Returns a string that escapes all regular expression metacharacters inside the argument text. |
+
+#### [String Slice Functions][string-list-functions]
+
+| Function | Description |
+| ----------- | ----------------------------------------------------------------------- |
+| `join` | Joins a list of strings into a single string, with the given separator. |
+| `splitList` | Splits a string into a list of strings. |
+| `split` | Splits a string into a map of strings where each key is an index. |
+| `splitn` | Identical to `split`, but stops splitting after `n` values. |
+| `sortAlpha` | Sorts a list of strings into alphabetical (lexicographical) order. |
+
+#### [Integer Functions][math-functions]
+
+| Function | Description |
+| --------- | ------------------------------------------------------------------------------------------------------- |
+| `add` | Sum a set of numbers. |
+| `add1` | Increments a number by 1. |
+| `sub` | Subtracts one number from another. |
+| `div` | Performs integer division. |
+| `mod` | Modulo. |
+| `mul` | Multiplies a set of numbers. |
+| `max` | Returns the largest of a set of integers. |
+| `min` | Returns the smallest of a set of integers. |
+| `floor` | Returns the greatest float value less than or equal to input value |
+| `ceil` | Returns the greatest float value greater than or equal to input value |
+| `round` | Returns a float value with the remainder rounded to the given number to digits after the decimal point. |
+| `randInt` | Returns a random integer value from min (inclusive) to max (exclusive). |
+
+#### [Integer Slice Functions][integer-list-functions]
+
+| Function | Description |
+| ----------- | --------------------------------------------------------------------------- |
+| `until` | Builds a range of integers. |
+| `untilStep` | Builds a range of integers, but allows you to define a start, stop and step |
+| `seq` | Works like the bash `seq` command. |
+
+#### [Date Functions][date-functions]
+
+| Function | Description |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `now` | Gets the current date/time. |
+| `ago` | Returns the duration since the given date/time. |
+| `date` | Formats a date. |
+| `dateInZone` | Identical to `date`, but with the given timezone. |
+| `duration` | Formats the number of seconds into a string. |
+| `durationRound` | Identical to `duration`, but rounds the duration to the most significant unit. |
+| `unixEpoch` | Returns the seconds since the unix epoch for the given date/time. |
+| `dateModify`\* | Modifies a date using the given input string. |
+| `htmlDate` | Formats a date for inserting into an HTML date picker input field. |
+| `htmlDateInZone` | Identical to `htmlDate`, but with the given timezone. |
+| `toDate`\* | Converts a string to a date/time. |
+
+#### [Default Functions][default-functions]
+
+| Function | Description |
+| ---------- | ------------------------------------------------------------------------ |
+| `default` | Uses a default value if the given value is considered "zero" or "empty". |
+| `empty` | Returns true if a value is considered "zero" or "empty". |
+| `coalesce` | Takes a list of values and returns the first non-empty one. |
+| `all` | Returns true if all values are non-empty. |
+| `any` | Returns true if any value is non-empty. |
+| `ternary` | |
+
+#### [Encoding Functions][encoding-functions]
+
+| Function | Description |
+| ---------------- | ------------------------------------------------------------------ |
+| `fromJson`\* | Decodes a JSON string into an object. |
+| `toJson`\* | Encodes an object as a JSON string. |
+| `toPrettyJson`\* | Encodes an object as a JSON string with new lines and indentarion. |
+| `toRawJson`\* | Encodes an object as a JSON string with HTML characters unescaped. |
+| `b64enc` | Encodes a string into base 64. |
+| `b64dec` | Decodes a string from base 64. |
+| `b32enc` | Encodes a string into base 32. |
+| `b32dec` | Decodes a string from base 32. |
+
+#### [List Functions][list-functions]
+
+| Function | Description |
+| ----------- | ---------------------------------------------------------------- |
+| `list` | Creates a list from a set of values. |
+| `first`\* | Gets the first value in a list. |
+| `rest`\* | Gets all values except the first value in the list. |
+| `last`\* | Gets the last value in the list. |
+| `initial`\* | Get all values except the last value in the list. |
+| `append`\* | Adds a new value to the end of the list. |
+| `prepend`\* | Adds a new value to the start of the list. |
+| `concat` | Joins two or more lists together. |
+| `reverse`\* | Reverses the order of a list. |
+| `uniq`\* | Generate a list with all of the duplicates removed. |
+| `without`\* | Filters matching items out of a list. |
+| `has`\* | Tests to see if a list has a particular element. |
+| `compact`\* | Removes entries with empty values. |
+| `slice`\* | Returns a partial copy of a list given start and end parameters. |
+| `chunk` | Splits a list into chunks of given size. |
+
+#### [Dictionary Functions][dictionary-functions]
+
+| Function | Description |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| `dict` | Creates a dictionary from a set of key/value pairs. |
+| `get` | Gets the value from the dictionary with the given key. |
+| `set` | Adds a new key/value pair to a dictionary. |
+| `unset` | Deletes a key from a dictionary. |
+| `hasKey` | Returns true if a dictionary contains the given key. |
+| `pluck` | Gets a list of all of the matching values in a set of maps given a key. |
+| `dig` | Returns the value in a nested map given a path of keys. |
+| `merge`\* | Merges two or more dictionaries into one. |
+| `mergeOverwrite`\* | Identical to `merge`, but giving precedence from right to left. |
+| `keys` | Returns a list of all of the keys in a dictionary. |
+| `pick` | Creates a new dictionary containing only the given keys of an existing map. |
+| `omit` | Creates a new dictionary containing all the keys of an existing map except the ones given. |
+| `values` | Returns a list of all the values in a dictionary. |
+
+#### [Type Conversion Functions][type-conversion-functions]
+
+| Function | Description |
+| ----------- | ------------------------------------------------------ |
+| `atoi` | Converts a string to an integer. |
+| `float64` | Converts to a float64. |
+| `int` | Converts to an int at the system's width. |
+| `int64` | Converts to an int64. |
+| `toDecimal` | Converts a unix octal to a int64. |
+| `toString` | Converts to a string. |
+| `toStrings` | Converts a list, slice, or array to a list of strings. |
+| `toStrings` | Produces a slice of strings from any list. |
+| `toDecimal` | Given a unix octal permission, produce a decimal. |
+
+#### [Path and Filepath Functions][path-functions]
+
+| Function | Description |
+| --------- | ----------------------------------------- |
+| `base` | Returns the last element of a path. |
+| `dir` | Returns the directory of a path. |
+| `clean` | Cleans up a path. |
+| `ext` | Returns the file extention of a path. |
+| `isAbs` | Checks if a path is absolute. |
+| `osBase` | Returns the last element of a filepath. |
+| `osDir` | Returns the directory of a filepath. |
+| `osClean` | Cleans up a filepath. |
+| `osExt` | Returns the file extention of a filepath. |
+| `osIsAbs` | Checks if a filepath is absolute. |
+
+#### [Flow Control Functions][flow-control-functions]
+
+| Function | Description |
+| -------- | ----------------------------------------------------------------------------- |
+| `fail` | Unconditionally returns an empty string and an error with the specified text. |
+
+#### [OS Functions][os-functions]
+
+| Function | Description |
+| ----------- | --------------------------------------------- |
+| `env` | Reads an environment variable. |
+| `expandenv` | Substitutes environment variables in a string |
+
+#### [Reflection Functions][reflection-functions]
+
+| Function | Description |
+| ------------ | ------------------------------------------------------ |
+| `kindOf` | Returns the kind of a value. |
+| `kindIs` | Verifies that a value is a particular kind. |
+| `typeOf` | Returns the underlying type of a value. |
+| `typeIs` | Verifies that a value is of a particular type. |
+| `typeIsLike` | Identical to `typeIs`, but also dereferences pointers. |
+| `deepEqual` | Returns true if two values are "deeply equal". |
+
+#### [Cryptographic and Security Functions][crypto-functions]
+
+| Function | Description |
+| ------------ | -------------------------------------- |
+| `sha1sum` | Computes a string's SHA1 digest. |
+| `sha256sum` | Computes a string's SHA256 digest. |
+| `adler32sum` | Computes a string's Adler-32 checksum. |
+
+### Task Functions
+
+Lastly, Task itself provides a few functions:
+
+| Function | Description |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `OS` | Returns the operating system. Possible values are `windows`, `linux`, `darwin` (macOS) and `freebsd`. |
+| `ARCH` | return the architecture Task was compiled to: `386`, `amd64`, `arm` or `s390x`. |
+| `splitLines` | Splits Unix (`\n`) and Windows (`\r\n`) styled newlines. |
+| `catLines` | Replaces Unix (`\n`) and Windows (`\r\n`) styled newlines with a space. |
+| `toSlash` | Does nothing on Unix, but on Windows converts a string from `\` path format to `/`. |
+| `fromSlash` | Opposite of `toSlash`. Does nothing on Unix, but on Windows converts a string from `/` path format to `\`. |
+| `exeExt` | Returns the right executable extension for the current OS (`".exe"` for Windows, `""` for others). |
+| `shellQuote` | (aliased to `q`): Quotes a string to make it safe for use in shell scripts. Task uses [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/syntax#Quote) for this. The Bash dialect is assumed. |
+| `splitArgs` | Splits a string as if it were a command's arguments. Task uses [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/shell#Fields). |
+| `joinPath` | Joins any number of arguments into a path. The same as Go's [filepath.Join](https://pkg.go.dev/path/filepath#Join). |
+| `relPath` | Converts an absolute path (second argument) into a relative path, based on a base path (first argument). The same as Go's [filepath.Rel](https://pkg.go.dev/path/filepath#Rel). |
+| `merge` | Creates a new map that is a copy of the first map with the keys of each subsequent map merged into it. If there is a duplicate key, the value of the last map with that key is used. |
+| `spew` | Returns the Go representation of a specific variable. Useful for debugging. Uses the [davecgh/go-spew](https://github.com/davecgh/go-spew) package. |
+
+{/* prettier-ignore-start */}
+[text/template]: https://pkg.go.dev/text/template
+[html/template]: https://pkg.go.dev/html/template
+[go-template-functions]: https://pkg.go.dev/text/template#hdr-Functions
+[slim-sprig]: https://go-task.github.io/slim-sprig/
+[os-functions]: https://go-task.github.io/slim-sprig/os.html
+[string-functions]: https://go-task.github.io/slim-sprig/strings.html
+[string-list-functions]: https://go-task.github.io/slim-sprig/string_slice.html
+[math-functions]: https://go-task.github.io/slim-sprig/math.html
+[integer-list-functions]: https://go-task.github.io/slim-sprig/integer_slice.html
+[date-functions]: https://go-task.github.io/slim-sprig/date.html
+[default-functions]: https://go-task.github.io/slim-sprig/defaults.html
+[encoding-functions]: https://go-task.github.io/slim-sprig/encoding.html
+[list-functions]: https://go-task.github.io/slim-sprig/lists.html
+[dictionary-functions]: https://go-task.github.io/slim-sprig/dicts.html
+[type-conversion-functions]: https://go-task.github.io/slim-sprig/conversion.html
+[path-functions]: https://go-task.github.io/slim-sprig/paths.html
+[flow-control-functions]: https://go-task.github.io/slim-sprig/flow_control.html
+[os-functions]: https://go-task.github.io/slim-sprig/os.html
+[reflection-functions]: https://go-task.github.io/slim-sprig/reflection.html
+[crypto-functions]: https://go-task.github.io/slim-sprig/crypto.html
+{/* prettier-ignore-end */}
diff --git a/website/docs/usage.mdx b/website/docs/usage.mdx
index b5088ce87d..87b28cdb18 100644
--- a/website/docs/usage.mdx
+++ b/website/docs/usage.mdx
@@ -966,8 +966,9 @@ you're interested in this functionality, we would appreciate your feedback.
:::
-Variables can be set in many places in a Taskfile. When executing templates,
-Task will look for variables in the order listed below (most important first):
+Variables can be set in many places in a Taskfile. When executing
+[templates][templating-reference], Task will look for variables in the order
+listed below (most important first):
- Variables declared in the task definition
- Variables given while calling a task from another (See
@@ -1383,81 +1384,6 @@ commands are executed in the reverse order if you schedule multiple of them.
:::
-## Go's template engine
-
-Task parse commands as [Go's template engine][gotemplate] before executing them.
-Variables are accessible through dot syntax (`.VARNAME`).
-
-All functions by the Go's
-[slim-sprig lib](https://go-task.github.io/slim-sprig/) are available. The
-following example gets the current date in a given format:
-
-```yaml
-version: '3'
-
-tasks:
- print-date:
- cmds:
- - echo {{now | date "2006-01-02"}}
-```
-
-Task also adds the following functions:
-
-- `OS`: Returns the operating system. Possible values are `windows`, `linux`,
- `darwin` (macOS) and `freebsd`.
-- `ARCH`: return the architecture Task was compiled to: `386`, `amd64`, `arm` or
- `s390x`.
-- `splitLines`: Splits Unix (`\n`) and Windows (`\r\n`) styled newlines.
-- `catLines`: Replaces Unix (`\n`) and Windows (`\r\n`) styled newlines with a
- space.
-- `toSlash`: Does nothing on Unix, but on Windows converts a string from `\`
- path format to `/`.
-- `fromSlash`: Opposite of `toSlash`. Does nothing on Unix, but on Windows
- converts a string from `/` path format to `\`.
-- `exeExt`: Returns the right executable extension for the current OS (`".exe"`
- for Windows, `""` for others).
-- `shellQuote` (aliased to `q`): Quotes a string to make it safe for use in shell scripts. Task
- uses [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/syntax#Quote)
- for this. The Bash dialect is assumed.
-- `splitArgs`: Splits a string as if it were a command's arguments. Task uses
- [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/shell#Fields)
-- `joinPath`: Joins any number of arguments into a path. The same as Go's
- [filepath.Join](https://pkg.go.dev/path/filepath#Join).
-- `relPath`: Converts an absolute path (second argument) into a relative path,
- based on a base path (first argument). The same as Go's
- [filepath.Rel](https://pkg.go.dev/path/filepath#Rel).
-- `merge`: Creates a new map that is a copy of the first map with the keys of
- each subsequent map merged into it. If there is a duplicate key, the value of
- the last map with that key is used.
-- `spew`: Returns the Go representation of a specific variable. Useful for
- debugging. Uses the [davecgh/go-spew](https://github.com/davecgh/go-spew)
- package.
-
-Example:
-
-```yaml
-version: '3'
-
-tasks:
- print-os:
- cmds:
- - echo '{{OS}} {{ARCH}}'
- - echo '{{if eq OS "windows"}}windows-command{{else}}unix-command{{end}}'
- # This will be path/to/file on Unix but path\to\file on Windows
- - echo '{{fromSlash "path/to/file"}}'
- enumerated-file:
- vars:
- CONTENT: |
- foo
- bar
- cmds:
- - |
- cat << EOF > output.txt
- {{range $i, $line := .CONTENT | splitLines -}}
- {{printf "%3d" $i}}: {{$line}}
- {{end}}EOF
-```
-
## Help
Running `task --list` (or `task -l`) lists all tasks with a description. The
@@ -1996,4 +1922,5 @@ if called by another task, either directly or as a dependency.
{/* prettier-ignore-start */}
[gotemplate]: https://golang.org/pkg/text/template/
[map-variables]: ./experiments/map_variables.mdx
+[templating-reference]: ./reference/templating.mdx
{/* prettier-ignore-end */}