使用jazzy生成文档时无法导入全部MD文件的问题咨询

问题场景 #

使用Jazzy生成文档时，无法将目标目录下所有Markdown文件纳入渲染，遇到两类错误：

• 执行jazzy --xcodebuild-arguments -scheme,MyCustomSchemeName --documentation=./*.md时，zsh报错：zsh: no matches found: --documentation=./*.md
• 尝试避免Shell扩展执行jazzy --documentation Full/Path_ToDoc.docc/**.md --xcodebuild-arguments -scheme,MyCustomSchemeName时，报错：Leftover unused command-line text: ["Full/Path_ToDoc.docc/File2.md", "Full/Path_ToDoc.docc/File1.md"]

核心原因 #

Jazzy的--documentation参数设计为接收单个路径模式，而Shell会提前扩展通配符（如*.md、**.md）为多个独立文件路径，导致Jazzy无法识别这些额外参数。

解决方案 #

1. 用单引号包裹通配符，让Jazzy自行处理扩展 #

通过单引号阻止Shell解析通配符，让Jazzy内部处理递归匹配所有Markdown文件：

jazzy --xcodebuild-arguments -scheme,MyCustomSchemeName --documentation='./**.md'

指定完整路径的版本：

jazzy --xcodebuild-arguments -scheme,MyCustomSchemeName --documentation='Full/Path_ToDoc.docc/**.md'

注意：此方法需要Jazzy支持内部解析**递归通配符，建议使用较新版本。

2. 临时开启zsh的globstar选项 #

如果zsh默认不支持**递归匹配，可临时开启globstar选项后执行命令：

setopt globstar && jazzy --xcodebuild-arguments -scheme,MyCustomSchemeName --documentation=./**.md

3. 手动列举所有Markdown文件（适合文件数量少的场景） #

直接将所有目标Markdown文件路径作为--documentation的参数传入：

jazzy --xcodebuild-arguments -scheme,MyCustomSchemeName --documentation Full/Path_ToDoc.docc/File1.md Full/Path_ToDoc.docc/File2.md Full/Path_ToDoc.docc/OtherFiles.md

4. 用find命令生成文件列表传递 #

通过find命令递归查找所有Markdown文件，再传递给Jazzy：

jazzy --xcodebuild-arguments -scheme,MyCustomSchemeName --documentation $(find Full/Path_ToDoc.docc -name "*.md")

若文件名包含空格，改用xargs处理：

find Full/Path_ToDoc.docc -name "*.md" | xargs -I {} jazzy --xcodebuild-arguments -scheme,MyCustomSchemeName --documentation {}

内容的提问来源于stack exchange，提问作者Richard Topchii