My Project

重要说明段落（注入时不会被触碰）

项目尾部内容

然后运行 `mise generate task-docs --inject --output README.md`，两个标记之间的内容即被替换为最新任务文档。`--inject` 需要配合 `--output` 使用，因为注入的对象是一个磁盘文件。

## 多文件输出：`--multi` 与 `--index`

当任务数量较多、希望每个任务拥有独立文档页面时，使用 `-m, --multi`。该模式要求 `--output` 指向一个**目录**，命令会为每个任务生成一个独立的 Markdown 文件：

```bash
mkdir -p docs/tasks
mise generate task-docs --multi --output docs/tasks

文件命名规则从源码可见（src/cli/generate/task_docs.rs#L74-L76）：任务名中的 : 与 / 会被替换为 -，再拼接 .md 后缀，例如任务 build:linux 会生成 build-linux.md。

配合 -I, --index 可以额外生成一个索引文件 index.md，其中以列表形式列出全部任务并链接到各自的文档文件，同时附带每个任务的描述：

mise generate task-docs --multi --index --output docs/tasks

索引文件的格式为：

# Tasks

- [build](https://gitcode.com/GitHub_Trending/mi/mise/blob/5e6a800da6f878ec56b7ffa70a76a6c595c632b5/docs/cli/oci/build.md?utm_source=gitcode_repo_files) - 构建产物
- test - 运行测试

源码中还有一个有趣的防御逻辑（src/cli/generate/task_docs.rs#L88-L98）：如果存在名为 index 的任务，index.md 会与之冲突，此时 mise 会发出警告“task named "index" will be overwritten by index.md”。

另外注意：--multi 模式下如果 --output 不是目录，命令会直接报错 --output must be a directory when --multi is set。

搜索范围：--root

-r, --root 用于指定搜索任务的根目录。默认情况下命令从当前工作目录（dirs::CWD）出发加载任务；需要为其他目录生成文档时，可以通过该参数显式指定：

mise generate task-docs --root /path/to/project

底层实现：任务文档是如何渲染出来的

每个任务渲染为 Markdown 的核心方法是 Task::render_markdown（src/task/mod.rs#L2183-L2192）：

pub(crate) async fn render_markdown(&self, config: &Arc<Config>) -> Result<String> {
    let mut spec = self.parse_usage_spec_for_display(config).await?;
    if spec.about.is_some() && spec.cmd.help.as_deref() == Some(self.description.as_str()) {
        spec.cmd.help = None;
    }
    let ctx = usage::docs::markdown::MarkdownRenderer::new(spec)
        .with_replace_pre_with_code_fences(true)
        .with_header_level(2);
    Ok(ctx.render_spec()?)
}

这段实现揭示了几个重要细节：

1. 基于 usage spec 渲染：mise 复用自家 usage 生态的 MarkdownRenderer 来渲染任务文档，这与 mise run --help 等命令使用的是同一套 CLI 规格体系；
2. 标题级别固定为 H2：渲染出的每个任务章节使用 ## 级别的标题（如 ## \test``），方便直接嵌入 README 中 H1 之下的位置；
3. 描述去重：当任务 description 与 usage spec 中的 help 重复时，会清除 help，避免文档中同一描述出现两次；
4. 代码块兼容：with_replace_pre_with_code_fences(true) 会将 <pre> 标签替换为标准代码围栏（code fences），保证输出是纯 Markdown。

parse_usage_spec_for_display（src/task/mod.rs#L2080-L2103）则负责构建每个任务的 Usage 规格：

• 文件任务：解析脚本中内嵌的 usage 注释，例如 //USAGE flag "-v --verbose" help="Enable verbose output"；
• TOML 任务：通过 TaskScriptParser 从 run 脚本中解析内嵌的 {{arg(...)}}、{{flag(...)}}、{{option(...)}} 等模板指令，据此推导出任务的参数、选项与默认值。

因此，只要在任务中声明了参数（TOML 模板语法或文件任务中的 USAGE 注释），mise generate task-docs --style detailed 就会自动在文档中呈现完整的参数说明、帮助文本与别名，无需手工维护。

实战示例：一次完整的任务文档生成流程

假设项目 mise.toml 内容如下：

[tasks.build]
run = "cargo build"
description = "构建项目"
alias = ["b"]

[tasks.test]
run = "cargo test -- {{arg(name='filter')}}"
description = "运行测试，可按名称过滤"

在项目根目录执行：

mise generate task-docs --style detailed

输出将包含类似如下的结构（## 级别的每个任务章节，含 Usage 与别名信息）：

## `build`

- **Usage:** `build`
- **Aliases:** `b`

构建项目

## `test`

- **Usage:** `test [FILTER]`

运行测试，可按名称过滤

随后将其落盘并注入 README：

mise generate task-docs --output TASKS.md
mise generate task-docs --inject --output README.md