diff --git a/website/docs/community.mdx b/website/docs/community.mdx index 316b4a17..a0d49b7c 100644 --- a/website/docs/community.mdx +++ b/website/docs/community.mdx @@ -1,6 +1,6 @@ --- slug: /community/ -sidebar_position: 9 +sidebar_position: 10 --- # Community diff --git a/website/docs/contributing.mdx b/website/docs/contributing.mdx index 2c820ffd..546129de 100644 --- a/website/docs/contributing.mdx +++ b/website/docs/contributing.mdx @@ -1,6 +1,6 @@ --- slug: /contributing/ -sidebar_position: 11 +sidebar_position: 12 --- # Contributing diff --git a/website/docs/deprecations/deprecations.mdx b/website/docs/deprecations/deprecations.mdx index aa5011a8..f09a95cb 100644 --- a/website/docs/deprecations/deprecations.mdx +++ b/website/docs/deprecations/deprecations.mdx @@ -1,6 +1,6 @@ --- slug: /deprecations/ -sidebar_position: 7 +sidebar_position: 8 --- # Deprecations diff --git a/website/docs/experiments/experiments.mdx b/website/docs/experiments/experiments.mdx index f8850ebf..a3284ff8 100644 --- a/website/docs/experiments/experiments.mdx +++ b/website/docs/experiments/experiments.mdx @@ -1,6 +1,6 @@ --- slug: /experiments/ -sidebar_position: 6 +sidebar_position: 7 --- import Tabs from '@theme/Tabs'; diff --git a/website/docs/getting_started.mdx b/website/docs/getting_started.mdx new file mode 100644 index 00000000..bef3482e --- /dev/null +++ b/website/docs/getting_started.mdx @@ -0,0 +1,143 @@ +--- +slug: /getting-started/ +sidebar_position: 3 +--- + +# Getting Started + +The following guide will help introduce you to the basics of Task. We'll cover +how to create a Taskfile, how to write a basic task and how to call it. If you +haven't installed Task yet, head over to our [installation +guide][installation]. + +## Creating your first Taskfile + +Once Task is installed, you can create your first Taskfile by running: + +```shell +task --init +``` + +This will create a file called `Taskfile.yml` in the current directory. If you +want to create the file in another directory, you can pass an absolute or +relative path to the directory into the command: + +```shell +task --init ./subdirectory +``` + +Or if you want the Taskfile to have a specific name, you can pass in the name of +the file: + +```shell +task --init Custom.yml +``` + +This will create a Taskfile that looks something like this: + +```yaml +version: '3' + +vars: + GREETING: Hello, World! + +tasks: + default: + cmds: + - echo "{{.GREETING}}" + silent: true +``` + +As you can see, all Taskfiles are written in [YAML format][yaml]. The `version` +attribute specifies the minimum version of Task that can be used to run this +file. The `vars` attribute is used to define variables that can be used in +tasks. In this case, we are creating a string variable called `GREETING` with a +value of `Hello, World!`. + +Finally, the `tasks` attribute is used to define the tasks that can be run. In +this case, we have a task called `default` that echoes the value of the +`GREETING` variable. The `silent` attribute is set to `true`, which means that +the task metadata will not be printed when the task is run - only the output of +the commands. + +## Calling a task + +To call the task, you simply invoke `task` followed by the name of the task you +want to run. In this case, the name of the task is `default`, so you should run: + +```shell +task default +``` + +Note that we don't have to specify the name of the Taskfile. Task will +automatically look for a file called `Taskfile.yml` (or any of Task's [supported +file names][supported-file-names]) in the current directory. Additionally, tasks +with the name `default` are special. They can also be run without specifying the +task name. + +If you created a Taskfile in a different directory, you can run it by passing +the absolute or relative path to the directory as an argument using the `--dir` +flag: + +```shell +task --dir ./subdirectory +``` + +Or if you created a Taskfile with a different name, you can run it by passing +the name of the Taskfile as an argument using the `--taskfile` flag: + +```shell +task --taskfile Custom.yml +``` + +## Adding a build task + +Let's create a task to build a program in Go. Start by adding a new task called +`build` below the existing `default` task. We can then add a `cmds` attribute +with a single command to build the program. + +Task uses [mvdan/sh][mvdan/sh], a native Go sh interpreter. So you can write +sh/bash-like commands - even in environments where `sh` or `bash` are usually +not available (like Windows). Just remember any executables called must be +available as a built-in or in the system's `PATH`. + +When you're done, it should look something like this: + +```yaml +version: '3' + +vars: + GREETING: Hello, World! + +tasks: + default: + cmds: + - echo "{{.GREETING}}" + silent: true + + build: + cmds: + - go build ./cmd/main.go +``` + +Call the task by running: + +```shell +task build +``` + +That's about it for the basics, but there's _so much_ more that you can do with +Task. Check out the rest of the documentation to learn more about all the +features Task has to offer! We recommend taking a look at the [usage +guide][usage] next. Alternatively, you can check out our reference docs for the +[Taskfile schema][schema] and [CLI][cli]. + +{/* prettier-ignore-start */} +[yaml]: https://yaml.org/ +[installation]: /installation/ +[supported-file-names]: /usage/#supported-file-names +[mvdan/sh]: https://github.com/mvdan/sh +[usage]: /usage/ +[schema]: /reference/schema/ +[cli]: /reference/cli/ +{/* prettier-ignore-end */} diff --git a/website/docs/integrations.mdx b/website/docs/integrations.mdx index 3f2364c8..bf1f8e69 100644 --- a/website/docs/integrations.mdx +++ b/website/docs/integrations.mdx @@ -1,6 +1,6 @@ --- slug: /integrations/ -sidebar_position: 8 +sidebar_position: 9 --- # Integrations diff --git a/website/docs/intro.mdx b/website/docs/intro.mdx index 5a97531c..1791f670 100644 --- a/website/docs/intro.mdx +++ b/website/docs/intro.mdx @@ -17,24 +17,6 @@ Since it's written in [Go][go], Task is just a single binary and has no other dependencies, which means you don't need to mess with any complicated install setups just to use a build tool. -Once [installed](/installation), you just need to describe your build tasks -using a simple [YAML][yaml] schema in a file called `Taskfile.yml`: - -```yaml title="Taskfile.yml" -version: '3' - -tasks: - hello: - cmds: - - echo 'Hello World from Task!' - silent: true -``` - -And call it by running `task hello` from your terminal. - -The above example is just the start, you can take a look at the [usage](/usage) -guide to check the full schema documentation and Task features. - ## Features - [Easy installation](/installation): just download a single binary, add to @@ -50,6 +32,15 @@ guide to check the full schema documentation and Task features. of files haven't changed since last run (based either on its timestamp or content). +## Documentation + +- If you're new to Task, we recommend taking a look at our [getting started + guide][getting-started] for an quick introduction. +- You can also browse our [usage documentation][usage] for more details on how + all the features work. +- Or use our quick reference documentation for the [Taskfile schema][schema] or + [CLI][cli]. + ## Gold Sponsors @@ -70,4 +61,8 @@ guide to check the full schema documentation and Task features. [snapcraft]: https://snapcraft.io/ [scoop]: https://scoop.sh/ [sh]: https://github.com/mvdan/sh +[getting-started]: /getting-started/ +[usage]: /usage/ +[schema]: /reference/schema/ +[cli]: /reference/cli/ {/* prettier-ignore-end */} diff --git a/website/docs/reference/_category_.yml b/website/docs/reference/_category_.yml index 3c6ca5c5..20a3c06b 100644 --- a/website/docs/reference/_category_.yml +++ b/website/docs/reference/_category_.yml @@ -1,2 +1,2 @@ -position: 4 +position: 5 label: Reference diff --git a/website/docs/styleguide.mdx b/website/docs/styleguide.mdx index eaab37cc..1213e4a0 100644 --- a/website/docs/styleguide.mdx +++ b/website/docs/styleguide.mdx @@ -1,9 +1,9 @@ --- slug: /styleguide/ -sidebar_position: 10 +sidebar_position: 11 --- -# Style guide +# Style Guide This is the official style guide for `Taskfile.yml` files. It provides basic instructions for keeping your Taskfiles clean and familiar to other users. diff --git a/website/docs/taskfile_versions.mdx b/website/docs/taskfile_versions.mdx index 507715e8..23c8ac02 100644 --- a/website/docs/taskfile_versions.mdx +++ b/website/docs/taskfile_versions.mdx @@ -1,6 +1,6 @@ --- slug: /taskfile-versions/ -sidebar_position: 5 +sidebar_position: 6 --- # Taskfile Versions diff --git a/website/docs/usage.mdx b/website/docs/usage.mdx index d57a0ffe..4c48f5d7 100644 --- a/website/docs/usage.mdx +++ b/website/docs/usage.mdx @@ -1,6 +1,6 @@ --- slug: /usage/ -sidebar_position: 3 +sidebar_position: 4 --- import Tabs from '@theme/Tabs'; @@ -8,56 +8,29 @@ import TabItem from '@theme/TabItem'; # Usage -## Getting started +## Running Taskfiles -Create a file called `Taskfile.yml` in the root of your project. The `cmds` -attribute should contain the commands of a task. The example below allows -compiling a Go app and uses [esbuild](https://esbuild.github.io/) to concat and -minify multiple CSS files into a single one. +Specific Taskfiles can be called by specifying the `--taskfile` flag. If you +don't specify a Taskfile, Task will automatically look for a file with one of +the [supported file names](#supported-file-names) in the current directory. If +you want to search in a different directory, you can use the `--dir` flag. -```yaml -version: '3' +### Supported file names -tasks: - build: - cmds: - - go build -v -i main.go +Task looks for files with the following names, in order of priority: - assets: - cmds: - - esbuild --bundle --minify css/index.css > public/bundle.css -``` +- `Taskfile.yml` +- `taskfile.yml` +- `Taskfile.yaml` +- `taskfile.yaml` +- `Taskfile.dist.yml` +- `taskfile.dist.yml` +- `Taskfile.dist.yaml` +- `taskfile.dist.yaml` -Running the tasks is as simple as running: - -```shell -task assets build -``` - -Task uses [mvdan.cc/sh](https://mvdan.cc/sh/), a native Go sh interpreter. So -you can write sh/bash commands, and it will work even on Windows, where `sh` or -`bash` are usually not available. Just remember any executable called must be -available by the OS or in PATH. - -If you omit a task name, "default" will be assumed. - -## Supported file names - -Task will look for the following file names, in order of priority: - -- Taskfile.yml -- taskfile.yml -- Taskfile.yaml -- taskfile.yaml -- Taskfile.dist.yml -- taskfile.dist.yml -- Taskfile.dist.yaml -- taskfile.dist.yaml - -The intention of having the `.dist` variants is to allow projects to have one -committed version (`.dist`) while still allowing individual users to override -the Taskfile by adding an additional `Taskfile.yml` (which would be on -`.gitignore`). +The `.dist` variants allow projects to have one committed file (`.dist`) while +still allowing individual users to override the Taskfile by adding an additional +`Taskfile.yml` (which would be in your `.gitignore`). ### Running a Taskfile from a subdirectory @@ -263,11 +236,7 @@ Taskfile. ### OS-specific Taskfiles -With `version: '2'`, task automatically includes any `Taskfile_{{OS}}.yml` if it -exists (for example: `Taskfile_windows.yml`, `Taskfile_linux.yml` or -`Taskfile_darwin.yml`). Since this behavior was a bit too implicit, it was -removed on version 3, but you still can have a similar behavior by explicitly -importing these files: +You can include OS-specific Taskfiles by using a templating function: ```yaml version: '3'