docs: add MISE and USAGE syntax hl queries to neovim cookbook

docs/mise-cookbook/neovim.md

@@ -2,15 +2,18 @@
 
 Here are some tips for an improved mise workflow with [Neovim](https://github.com/neovim/neovim).
 
-## Code highlight for run commands
+## Syntax highlighting
 
-Use [Treesitter](https://github.com/nvim-treesitter/nvim-treesitter) to highlight code in the run commands of your mise files as shown on the left side of the image:
+### Run commands
+
+Use [Treesitter](https://github.com/nvim-treesitter/nvim-treesitter) to enable syntax highlighting for the code in the run commands of your mise files.
+See the example here on the left side of the image:
 
 ![image](https://github.com/user-attachments/assets/2961163b-1e6b-4ff6-b2e6-29eb53afc7e5)
 
 In your neovim config, create a `after/queries/toml/injections.scm` file with these queries:
 
-```scm
+```query
 ; extends
 
 (pair
@@ -55,7 +58,8 @@ In your neovim config, create a `after/queries/toml/injections.scm` file with th
 )
 ```
 
-To only apply the highlighting on mise files instead of all toml files, the `is-mise?` predicate is used. If you don't care for this distinction, the lines containing `(#is-mise?)` can be removed.
+To only apply the highlighting on mise files instead of all toml files, the `is-mise?` predicate is used.
+If you don't care for this distinction, the lines containing `(#is-mise?)` can be removed.
 Otherwise, make sure to also create the predicate somewhere in your neovim config.
 
 For example, using [`lazy.nvim`](https://github.com/folke/lazy.nvim):
@@ -75,6 +79,123 @@ For example, using [`lazy.nvim`](https://github.com/folke/lazy.nvim):
 
 This will consider any `toml` file containing `mise` in its name as a mise file.
 
+### MISE and USAGE comments in file tasks
+
+You can also use Treesitter to enable syntax highlighting for `"#MISE` and `#USAGE` comments in file based tasks.
+See the example here on the left side of the image:
+
+![image](https://github.com/user-attachments/assets/6dd5e9dd-785c-4717-a48a-c305641f9e08)
+
+In your neovim config, create a `after/queries/bash/injections.scm` file with these queries:
+
+```query
+; extends
+
+; ============================================================================
+; #MISE comments - TOML injection
+; ============================================================================
+; This injection captures comment lines starting with "#MISE " or "#[MISE]" or
+; "# [MISE]" and treats them as TOML code blocks for syntax highlighting.
+;
+; #MISE format
+; The (#offset!) directive skips the "#MISE " prefix (6 characters) from the source
+((comment) @injection.content
+  (#lua-match? @injection.content "^#MISE ")
+  (#offset! @injection.content 0 6 0 1)
+  (#set! injection.language "toml"))
+
+; #[MISE] format
+((comment) @injection.content
+  (#lua-match? @injection.content "^#%[MISE%] ")
+  (#offset! @injection.content 0 8 0 1)
+  (#set! injection.language "toml"))
+
+; # [MISE] format
+((comment) @injection.content
+  (#lua-match? @injection.content "^# %[MISE%] ")
+  (#offset! @injection.content 0 9 0 1)
+  (#set! injection.language "toml"))
+
+; ============================================================================
+; #USAGE comments - KDL injection
+; ============================================================================
+; This injection captures consecutive comment lines starting with "#USAGE " or
+; "#[USAGE]" or "# [USAGE]" and treats them as a single KDL code block for
+; syntax highlighting.
+;
+; #USAGE format
+((comment) @injection.content
+  (#lua-match? @injection.content "^#USAGE ")
+  ; Extend the range one byte to the right, to include the trailing newline.
+  ; see https://github.com/neovim/neovim/discussions/36669#discussioncomment-15054154
+  (#offset! @injection.content 0 7 0 1)
+  (#set! injection.combined)
+  (#set! injection.language "kdl"))
+
+; #[USAGE] format
+((comment) @injection.content
+  (#lua-match? @injection.content "^#%[USAGE%] ")
+  (#offset! @injection.content 0 9 0 1)
+  (#set! injection.combined)
+  (#set! injection.language "kdl"))
+
+; # [USAGE] format
+((comment) @injection.content
+  (#lua-match? @injection.content "^# %[USAGE%] ")
+  (#offset! @injection.content 0 10 0 1)
+  (#set! injection.combined)
+  (#set! injection.language "kdl"))
+
+; NOTE: on neovim >= 0.12, you can use the multi node pattern instead of
+; combining injections:
+;
+; ((comment)+ @injection.content
+;   (#lua-match? @injection.content "^#USAGE ")
+;   (#offset! @injection.content 0 7 0 1)
+;   (#set! injection.language "kdl"))
+;
+; this is the preferred way as combined injections have multiple
+; limitations:
+; https://github.com/neovim/neovim/issues/32635
+
+```
+
+The same queries work as is for all languages that use `#` as a comment delimiter.
+Due to TS injections being per language, you need to put the same queries to the language specific query files.
+For example, put them to `after/queries/python/injections.scm` to enable them for `Python` in addition to `bash`.
+
+For languages that use `//` as a comment delimiter, you need to modify the queries a bit:
+
+```query
+((comment) @injection.content
+  (#lua-match? @injection.content "^//MISE ")
+  (#offset! @injection.content 0 7 0 1)
+  (#set! injection.language "toml"))
+((comment) @injection.content
+  (#lua-match? @injection.content "^//%[MISE%] ")
+  (#offset! @injection.content 0 9 0 1)
+  (#set! injection.language "toml"))
+((comment) @injection.content
+  (#lua-match? @injection.content "^// %[MISE%] ")
+  (#offset! @injection.content 0 10 0 1)
+  (#set! injection.language "toml"))
+((comment) @injection.content
+  (#lua-match? @injection.content "^//USAGE ")
+  (#offset! @injection.content 0 8 0 1)
+  (#set! injection.combined)
+  (#set! injection.language "kdl"))
+((comment) @injection.content
+  (#lua-match? @injection.content "^//%[USAGE%] ")
+  (#offset! @injection.content 0 10 0 1)
+  (#set! injection.combined)
+  (#set! injection.language "kdl"))
+((comment) @injection.content
+  (#lua-match? @injection.content "^// %[USAGE%] ")
+  (#offset! @injection.content 0 11 0 1)
+  (#set! injection.combined)
+  (#set! injection.language "kdl"))
+```
+
 ## Enable LSP for embedded lang in run commands
 
 Use [`otter.nvim`](https://github.com/jmbuhr/otter.nvim) to enable LSP features and code completion for code embedded in your mise files.
@@ -99,4 +220,4 @@ Again using [`lazy.nvim`](https://github.com/folke/lazy.nvim):
 },
 ```
 
-This will only work if the [TS injection queries](#code-highlight-for-run-commands) are also set up.
+This will only work if the [TS injection queries](#run-commands) are also set up.