docs: getting started (#2086)

* docs: getting started

* docs: update intro with links to getting started docs

website/docs/community.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /community/
-sidebar_position: 9
+sidebar_position: 10
 ---
 
 # Community

website/docs/contributing.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /contributing/
-sidebar_position: 11
+sidebar_position: 12
 ---
 
 # Contributing

website/docs/deprecations/deprecations.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /deprecations/
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 # Deprecations

website/docs/experiments/experiments.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /experiments/
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 import Tabs from '@theme/Tabs';

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 */}

website/docs/integrations.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /integrations/
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 # Integrations

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
 
 <table class="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 */}

website/docs/reference/_category_.yml

@@ -1,2 +1,2 @@
-position: 4
+position: 5
 label: Reference

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.

website/docs/taskfile_versions.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /taskfile-versions/
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # Taskfile Versions

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'