docs: improved experimental docs formatting

docs/docs/deprecations/template.md

@@ -6,11 +6,16 @@ sidebar_position: -1 # Always push to the top
 draft: true # Hide in production
 ---
 
-# \{Name of Deprecated Feature\}
+# \{Name of Deprecated Feature\} (#\{Issue\})
 
-- Issue: #\{issue\}
-- Breaks:
-  - \{list any existing functionality that will be broken by this experiment\}
+:::warning
+
+This deprecation breaks the following functionality:
+
+- \{list any existing functionality that will be broken by this deprecation\}
+- \{if there are no breaking changes, remove this admonition\}
+
+:::
 
 \{Short description of the feature/behavior and why it is being deprecated\}
 

docs/docs/deprecations/version_2_schema.md

@@ -2,12 +2,16 @@
 slug: /deprecations/version-2-schema/
 ---
 
-# Version 2 Schema
+# Version 2 Schema (#1197)
 
-- Issue: #1197
-- Breaks:
-  - Any Taskfiles that use the version 2 schema
-  - `Taskvar.yml` files
+:::warning
+
+This deprecation breaks the following functionality:
+
+- Any Taskfiles that use the version 2 schema
+- `Taskvar.yml` files
+
+:::
 
 The Taskfile v2 schema was introduced in March 2018 and replaced by version 3 in
 August the following year. Users have had a long time to update and so we feel

docs/docs/experiments/any_variables.md

@@ -2,12 +2,31 @@
 slug: /experiments/any-variables/
 ---
 
-# Any Variables
+# Any Variables (#1415)
 
-- Issue: #1415
-- Environment variable: `TASK_X_ANY_VARIABLES=1`
-- Breaks:
-  - Dynamically defined variables (using the `sh` keyword)
+:::caution
+
+All experimental features are subject to breaking changes and/or removal _at any
+time_. We strongly recommend that you do not use these features in a production
+environment. They are intended for testing and feedback only.
+
+:::
+
+:::warning
+
+This experiment breaks the following functionality:
+
+- Dynamically defined variables (using the `sh` keyword)
+
+:::
+
+:::info
+
+To enable this experiment, set the environment variable:
+`TASK_X_ANY_VARIABLES=1`. Check out [our guide to enabling experiments
+][enabling-experiments] for more information.
+
+:::
 
 Currently, Task only supports string variables. This experiment allows you to
 specify and use the following variable types:
@@ -179,5 +198,6 @@ will now need to escape the `$` with a backslash (`\`) to stop Task from
 executing it as a command.
 
 <!-- prettier-ignore-start -->
+[enabling-experiments]: /experiments/#enabling-experiments
 [slim-sprig]: https://go-task.github.io/slim-sprig/
 <!-- prettier-ignore-end -->

docs/docs/experiments/experiments.md

@@ -22,7 +22,9 @@ the current set of experimental features and their status in the
 You can view a full list of active experiments in the "Experiments" section of
 the sidebar.
 
-You can enable an experimental feature by:
+## Enabling Experiments
+
+You can enable an experimental feature by doing one of the following:
 
 1. Using the relevant environment variable in front of a task command. For
    example, `TASK_X_{FEATURE}=1 task {my-task}`. This is intended for one-off
@@ -31,10 +33,10 @@ You can enable an experimental feature by:
    `.zshrc` etc.). This is intended for permanently enabling experimental
    features in your environment.
 1. Creating a `.env` file in the same directory as your root Taskfile that
-   contains the relevant environment variables. e.g.
+   contains the relevant environment variables. This allows you to enable an
+   experimental feature at a project level. For example:
 
-```shell
-# .env
+```shell title=".env"
 TASK_X_FEATURE=1
 ```
 

docs/docs/experiments/gentle_force.md

@@ -2,12 +2,31 @@
 slug: /experiments/gentle-force/
 ---
 
-# Gentle Force
+# Gentle Force (#1200)
 
-- Issue: #1200
-- Environment variable: `TASK_X_FORCE=1`
-- Breaks:
-  - `--force` flag
+:::caution
+
+All experimental features are subject to breaking changes and/or removal _at any
+time_. We strongly recommend that you do not use these features in a production
+environment. They are intended for testing and feedback only.
+
+:::
+
+:::warning
+
+This experiment breaks the following functionality:
+
+- The `--force` flag
+
+:::
+
+:::info
+
+To enable this experiment, set the environment variable: `TASK_X_FORCE=1`. Check
+out [our guide to enabling experiments ][enabling-experiments] for more
+information.
+
+:::
 
 The `--force` flag currently forces _all_ tasks to run regardless of the status
 checks. This can be useful, but we have found that most of the time users only
@@ -24,3 +43,7 @@ If you want to migrate, but continue to force all dependant tasks to run, you
 should replace all uses of the `--force` flag with `--force-all`. Alternatively,
 if you want to adopt the new behavior, you can continue to use the `--force`
 flag as you do now!
+
+<!-- prettier-ignore-start -->
+[enabling-experiments]: /experiments/#enabling-experiments
+<!-- prettier-ignore-end -->

docs/docs/experiments/remote_taskfiles.md

@@ -2,10 +2,23 @@
 slug: /experiments/remote-taskfiles/
 ---
 
-# Remote Taskfiles
+# Remote Taskfiles (#1317)
 
-- Issue: #1317
-- Environment variable: `TASK_X_REMOTE_TASKFILES=1`
+:::caution
+
+All experimental features are subject to breaking changes and/or removal _at any
+time_. We strongly recommend that you do not use these features in a production
+environment. They are intended for testing and feedback only.
+
+:::
+
+:::info
+
+To enable this experiment, set the environment variable:
+`TASK_X_REMOTE_TASKFILES=1`. Check out [our guide to enabling experiments
+][enabling-experiments] for more information.
+
+:::
 
 This experiment allows you to specify a remote Taskfile URL when including a
 Taskfile. For example:
@@ -87,5 +100,6 @@ the `--timeout` flag and specifying a duration. For example, `--timeout 5s` will
 set the timeout to 5 seconds.
 
 <!-- prettier-ignore-start -->
+[enabling-experiments]: /experiments/#enabling-experiments
 [man-in-the-middle-attacks]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
 <!-- prettier-ignore-end -->

docs/docs/experiments/template.md

@@ -6,15 +6,37 @@ sidebar_position: -1 # Always push to the top
 draft: true # Hide in production
 ---
 
-# \{Name of Experiment\}
+# \{Name of Experiment\} (#\{Issue\})
 
-- Issue: #\{issue\}
-- Environment variable: `TASK_X_{feature}`
-- Breaks:
-  - \{list any existing functionality that will be broken by this experiment\}
-- Deprecations:
-  - \{link to any deprecation pages related to this experiment\}
+:::caution
+
+All experimental features are subject to breaking changes and/or removal _at any
+time_. We strongly recommend that you do not use these features in a production
+environment. They are intended for testing and feedback only.
+
+:::
+
+:::warning
+
+This experiment breaks the following functionality:
+
+- \{list any existing functionality that will be broken by this experiment\}
+- \{if there are no breaking changes, remove this admonition\}
+
+:::
+
+:::info
+
+To enable this experiment, set the environment variable: `TASK_X_{feature}=1`.
+Check out [our guide to enabling experiments ][enabling-experiments] for more
+information.
+
+:::
 
 \{Short description of the feature\}
 
 \{Short explanation of how users should migrate to the new behavior\}
+
+<!-- prettier-ignore-start -->
+[enabling-experiments]: /experiments/#enabling-experiments
+<!-- prettier-ignore-end -->

docs/docs/styleguide.md

@@ -14,21 +14,6 @@ followed. Feel free to disagree and proceed differently at some point if you
 need or want to. Also, feel free to open issues or pull requests with
 improvements to this guide.
 
-## Use `Taskfile.yml` and not `taskfile.yml`
-
-```yaml
-# bad
-taskfile.yml
-
-
-# good
-Taskfile.yml
-```
-
-This is important especially for Linux users. Windows and macOS have case
-insensitive filesystems, so `taskfile.yml` will end up working, even that not
-officially supported. On Linux, only `Taskfile.yml` will work, though.
-
 ## Use the correct order of keywords
 
 - `version:`