Skip to content

docs: resolve chaotic heading hierarchy in task-arguments.md #8644

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jdx merged 1 commit into from
Mar 19, 2026
+31 −29
Merged

docs: resolve chaotic heading hierarchy in task-arguments.md #8644

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 31 additions & 29 deletions docs/tasks/task-arguments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ Task arguments allow you to pass parameters to tasks, making them more flexible

The **usage field** is the recommended approach for defining task arguments. It provides a clean, declarative syntax that works with both TOML tasks and file tasks.

See [Complete Usage Specification Reference](#complete-usage-specification-reference) for more details.

@gemini-code-assist gemini-code-assist Bot Mar 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Adding this link helps users quickly navigate to the complete usage specification reference. Consider adding similar links throughout the document where relevant sections are mentioned to improve navigation.


#### Quick Example

```mise-toml [mise.toml]
Expand Down Expand Up @@ -85,6 +87,35 @@ Options:
-h, --help Print help
```

### 2. File Task Headers {#file-task-headers}

For file tasks, you can define arguments directly in the file using special `#MISE` or `#USAGE` comment syntax:

```bash [.mise/tasks/deploy]
#!/usr/bin/env bash
#MISE description "Deploy application"
#USAGE arg "<environment>" help="Deployment environment" {
#USAGE choices "dev" "staging" "prod"
#USAGE }
#USAGE flag "--dry-run" help="Preview changes without deploying"
#USAGE flag "--region <region>" help="AWS region" default="us-east-1" env="AWS_REGION"

ENVIRONMENT="${usage_environment?}"
REGION="${usage_region?}"
DRY_RUN="${usage_dry_run:-false}"

if [[ "$DRY_RUN" == "true" ]]; then
echo "DRY RUN: Would deploy to $ENVIRONMENT in $REGION"
else
echo "Deploying to $ENVIRONMENT in $REGION..."
./scripts/deploy.sh "$ENVIRONMENT" "$REGION"
fi
```

::: tip Syntax Options
Use `#MISE` (uppercase, recommended) or `#USAGE` for defining arguments in file tasks. `# [MISE]` or `# [USAGE]` are also accepted as workarounds for formatters.
:::
Comment on lines +115 to +117

@gemini-code-assist gemini-code-assist Bot Mar 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The use of :::: for the tip formatting seems inconsistent with other markdown elements. Consider using a more standard markdown formatting for tips, such as blockquotes with a specific class or callouts, to ensure consistency and better rendering across different platforms.


## Complete Usage Specification Reference

### Positional Arguments (`arg`)
Expand Down Expand Up @@ -398,35 +429,6 @@ fi
'''
```

### 2. File Task Headers {#file-task-headers}

For file tasks, you can define arguments directly in the file using special `#MISE` or `#USAGE` comment syntax:

```bash [.mise/tasks/deploy]
#!/usr/bin/env bash
#MISE description "Deploy application"
#USAGE arg "<environment>" help="Deployment environment" {
#USAGE choices "dev" "staging" "prod"
#USAGE }
#USAGE flag "--dry-run" help="Preview changes without deploying"
#USAGE flag "--region <region>" help="AWS region" default="us-east-1" env="AWS_REGION"

ENVIRONMENT="${usage_environment?}"
REGION="${usage_region?}"
DRY_RUN="${usage_dry_run:-false}"

if [[ "$DRY_RUN" == "true" ]]; then
echo "DRY RUN: Would deploy to $ENVIRONMENT in $REGION"
else
echo "Deploying to $ENVIRONMENT in $REGION..."
./scripts/deploy.sh "$ENVIRONMENT" "$REGION"
fi
```

::: tip Syntax Options
Use `#MISE` (uppercase, recommended) or `#USAGE` for defining arguments in file tasks. `# [MISE]` or `# [USAGE]` are also accepted as workarounds for formatters.
:::

## Bash Variable Expansion for Usage Variables {#bash-variable-expansion}

When accessing usage-defined variables in bash scripts, use parameter expansion syntax to help [shellcheck](https://www.shellcheck.net/) understand these variables and provide default values for boolean flags.
Expand Down
Loading