docs: resolve chaotic heading hierarchy in task-arguments.md by muzimuzhi · Pull Request #8644 · jdx/mise

muzimuzhi · 2026-03-18T17:01:32Z

Before

H2 "Complete Usage Specification Reference" part appears in between two h3 recommended methods, thus messes the heading hierarchy.

After

The whole h2 "Complete Usage Specification Reference" part is moved right after "Recommended Methods" h2.

gemini-code-assist · 2026-03-18T17:01:53Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request improves the clarity and logical flow of the task-arguments.md documentation. It addresses an issue where heading levels were inconsistent, by repositioning a key section to ensure a proper hierarchy. Additionally, an internal link was introduced to enhance user navigation within the document, making it easier to find detailed specifications.

Highlights

Documentation Structure: Reordered sections within docs/tasks/task-arguments.md to correct a chaotic heading hierarchy, specifically by moving the 'File Task Headers' section to a more logical position.
Navigation Improvement: Added an internal link to the 'Complete Usage Specification Reference' section to improve navigation and accessibility within the document.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

greptile-apps · 2026-03-18T17:02:47Z

Greptile Summary

This PR fixes a broken heading hierarchy in docs/tasks/task-arguments.md. Previously, the ## Complete Usage Specification Reference H2 section appeared in the middle of two H3 sections (### 1. Usage Field and ### 2. File Task Headers) that were both supposed to be children of ## Recommended Methods, causing a structurally invalid and visually confusing document outline.

The fix:

Moves ### 2. File Task Headers to immediately follow ### 1. Usage Field (Preferred), keeping both H3 sections inside ## Recommended Methods
Moves ## Complete Usage Specification Reference to come after the entire ## Recommended Methods H2, which is the correct logical order
Adds a forward-reference link (See Complete Usage Specification Reference for more details.) in the Usage Field section to maintain discoverability of the reference section

The restructuring is purely cosmetic/structural — no content was changed.

Confidence Score: 5/5

This PR is safe to merge — it is a documentation-only structural fix with no code changes.
The change is a pure documentation restructure that corrects the heading hierarchy. No code, configuration, or logic is modified. The new structure is correct and consistent with the described intent. The added cross-reference link uses a valid anchor (#complete-usage-specification-reference) that exists in the same file.
No files require special attention.

Important Files Changed

Filename	Overview
docs/tasks/task-arguments.md	Heading hierarchy fix: moves "### 2. File Task Headers" before "## Complete Usage Specification Reference" so both recommended-method H3s are contained within the "## Recommended Methods" H2, and adds a forward-reference link from the Usage Field section. No content was altered.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph After["After (Fixed)"]
        A2[H1: Task Arguments] --> B2
        B2[H2: Recommended Methods] --> C2
        B2 --> D2
        C2["H3: 1. Usage Field (Preferred)"]
        D2["H3: 2. File Task Headers"]
        A2 --> E2
        E2[H2: Complete Usage Specification Reference]
        A2 --> F2
        F2[H2: Bash Variable Expansion]
        A2 --> G2
        G2[H2: Deprecated Method]
    end

    subgraph Before["Before (Broken)"]
        A1[H1: Task Arguments] --> B1
        B1[H2: Recommended Methods] --> C1
        C1["H3: 1. Usage Field (Preferred)"]
        A1 --> E1
        E1["H2: Complete Usage Specification Reference ⚠️ misplaced"]
        A1 --> D1
        D1["H3: 2. File Task Headers ⚠️ orphaned H3"]
        A1 --> F1
        F1[H2: Bash Variable Expansion]
    end

_{Last reviewed commit: "docs: resolve chaoti..."}

gemini-code-assist

Code Review

This pull request focuses on improving the heading hierarchy in the task-arguments.md documentation file. It moves the "Complete Usage Specification Reference" section to a more logical position after the "Recommended Methods" section and introduces a new section on "File Task Headers".

gemini-code-assist · 2026-03-18T17:05:47Z


 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.


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.

gemini-code-assist · 2026-03-18T17:05:47Z

+::: 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.
+:::


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.

@tdragon

### 🐛 Bug Fixes - **(config)** resolve trust hash collision for same-name directories by @tdragon in [#8628](#8628) - **(docs)** fix width of tools table by @himkt in [#8625](#8625) - **(docs)** prevent homepage hero atmosphere overflow by @nygmaaa in [#8642](#8642) - **(doctor)** detect PATH ordering issues when mise is activated by @jdx in [#8585](#8585) - **(git)** use origin as remote name by @bentinata in [#8626](#8626) - **(installer)** normalize current version before comparison by @tak848 in [#8649](#8649) - **(lockfile)** Resolve symlink when updating lockfiles by @chancez in [#8589](#8589) - **(python)** verify checksums for precompiled binary downloads by @malept in [#8593](#8593) - **(rust)** resolve relative CARGO_HOME/RUSTUP_HOME to absolute paths by @simonepri in [#8604](#8604) - **(task)** correctly resolve task name for _default files with extensions by @youta1119 in [#8646](#8646) - **(tasks)** global file tasks not properly marked as such by @roele in [#8618](#8618) - **(tasks)** handle broken pipe in table print and task completion output by @vmaleze in [#8608](#8608) - use dark/light logo variants in README for GitHub dark mode by @jdx in [#8656](#8656) - failing rebuild of runtime symlinks for shared tools by @roele in [#8647](#8647) - add spaces around current element operator in flutter version_expr by @roele in [#8616](#8616) - complete task arguments correctly by @KevSlashNull in [#8601](#8601) ### 📚 Documentation - switch body font to DM Sans and darken dark mode background by @jdx in [6e3ad34](6e3ad34) - use Cormorant Garamond for headers and Roc Grotesk for body text by @jdx in [010812a](010812a) - resolve chaotic heading hierarchy in task-arguments.md by @muzimuzhi in [#8644](#8644) ### 🧪 Testing - fix test_java and mark as slow by @roele in [#8634](#8634) ### 📦️ Dependency Updates - update docker/dockerfile:1 docker digest to 4a43a54 by @renovate[bot] in [#8657](#8657) - update ghcr.io/jdx/mise:alpine docker digest to 2584470 by @renovate[bot] in [#8658](#8658) ### 📦 Registry - add viteplus (npm:vite-plus) by @risu729 in [#8594](#8594) - remove backend.options for podman by @roele in [#8633](#8633) - add pi.dev coding agent by @dector in [#8635](#8635) - add ormolu ([github:tweag/ormolu](https://github.com/tweag/ormolu)) by @3w36zj6 in [#8617](#8617) - use version_expr for dart and sort versions by @roele in [#8631](#8631) ### New Contributors - @bentinata made their first contribution in [#8626](#8626) - @tdragon made their first contribution in [#8628](#8628) - @nygmaaa made their first contribution in [#8642](#8642) - @youta1119 made their first contribution in [#8646](#8646) - @chancez made their first contribution in [#8589](#8589) - @dector made their first contribution in [#8635](#8635) - @tak848 made their first contribution in [#8649](#8649) ## 📦 Aqua Registry Updates #### New Packages (5) - [`acsandmann/rift`](https://github.com/acsandmann/rift) - [`alltuner/mise-completions-sync`](https://github.com/alltuner/mise-completions-sync) - [`berbicanes/apiark`](https://github.com/berbicanes/apiark) - [`gitlab.com/graphviz/graphviz`](https://github.com/gitlab.com/graphviz/graphviz) - [`jorgelbg/pinentry-touchid`](https://github.com/jorgelbg/pinentry-touchid) #### Updated Packages (7) - [`UpCloudLtd/upcloud-cli`](https://github.com/UpCloudLtd/upcloud-cli) - [`aquaproj/registry-tool`](https://github.com/aquaproj/registry-tool) - [`go-swagger/go-swagger`](https://github.com/go-swagger/go-swagger) - [`gopinath-langote/1build`](https://github.com/gopinath-langote/1build) - [`sassman/t-rec-rs`](https://github.com/sassman/t-rec-rs) - [`sharkdp/fd`](https://github.com/sharkdp/fd) - [`temporalio/cli`](https://github.com/temporalio/cli)

gemini-code-assist Bot reviewed Mar 18, 2026

View reviewed changes

muzimuzhi force-pushed the docs/move-usage-spec branch from b8f891a to 6823da2 Compare March 18, 2026 17:53

muzimuzhi changed the title ~~docs: resolve choitic heading hierarchy in task-argument.md~~ docs: resolve chaotic heading hierarchy in task-arguments.md Mar 18, 2026

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

79f24b2

muzimuzhi force-pushed the docs/move-usage-spec branch from 6823da2 to 79f24b2 Compare March 18, 2026 17:53

jdx merged commit 36da65d into jdx:main Mar 19, 2026
33 of 35 checks passed

mise-en-dev mentioned this pull request Mar 19, 2026

chore: release 2026.3.10 #8592

Merged

muzimuzhi deleted the docs/move-usage-spec branch March 20, 2026 09:59

mise-en-dev mentioned this pull request Mar 21, 2026

chore: release 2026.3.11 #8676

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

docs: resolve chaotic heading hierarchy in task-arguments.md#8644
jdx merged 1 commit intojdx:mainfrom
muzimuzhi:docs/move-usage-spec

muzimuzhi commented Mar 18, 2026

Uh oh!

gemini-code-assist Bot commented Mar 18, 2026

Uh oh!

greptile-apps Bot commented Mar 18, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Mar 18, 2026

Uh oh!

gemini-code-assist Bot Mar 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		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.

Uh oh!

Conversation

muzimuzhi commented Mar 18, 2026

Uh oh!

gemini-code-assist Bot commented Mar 18, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

greptile-apps Bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

greptile-apps Bot commented Mar 18, 2026 •

edited

Loading