如何在MkDocs（或mike）中引入脚本生成的内容？

针对你提到的不想手动转录--help输出到Markdown的需求，有两种实用方案可选，可根据场景灵活选择：

一、构建时嵌入Shell命令自动生成（推荐） #

直接在Markdown源码中插入命令，借助MkDocs插件让构建过程自动执行命令并渲染成表格，完全实时同步程序最新参数。

具体步骤 #

1. 安装mkdocs-macros-plugin插件，它支持在Markdown中执行代码并替换内容：

   pip install mkdocs-macros-plugin
   

2. 在mkdocs.yml中启用插件：

   plugins:
     - macros
   

3. 在文档Markdown文件里，插入执行命令和转换逻辑：

   ### 程序命令行参数
   {{ run('your-program --help | python scripts/help-to-table.py') }}
   

   这里需要一个小脚本scripts/help-to-table.py，将--help的纯文本输出转换成Markdown表格。示例脚本如下（需适配你程序的--help格式调整正则）：

   import sys
   import re
   
   help_text = sys.stdin.read()
   # 匹配参数行，示例格式为"  -f, --foo  Description text"
   arg_pattern = re.compile(r"\s+(-\w, )?(--[\w-]+)\s+(.*)", re.MULTILINE)
   table_rows = []
   
   for match in arg_pattern.finditer(help_text):
       short_arg = match.group(1).strip() if match.group(1) else "-"
       long_arg = match.group(2).strip()
       desc = match.group(3).strip()
       table_rows.append(f"| {short_arg} | {long_arg} | {desc} |")
   
   # 输出标准Markdown表格
   print("| 短参数 | 长参数 | 描述 |")
   print("|--------|--------|------|")
   print("\n".join(table_rows))
   

这种方式的核心优势是每次构建文档都会拉取最新的--help输出，彻底避免手动维护导致的不一致，适合开发阶段参数频繁变动的场景。

二、预先生成Markdown文件 #

编写脚本定期或在CI流程中执行，提前将--help输出转换成Markdown表格文件，再在主文档中引入。

具体操作 #

1. 编写生成脚本（Python/Shell均可），调用程序--help并解析输出，将结果写入单独的cli-args.md文件，逻辑可参考上面的help-to-table.py，只需将输出从标准输出改为写入文件。
2. 在CI构建流程（如GitHub Actions、GitLab CI）中添加执行该脚本的步骤，确保每次文档构建前都更新cli-args.md。
3. 在主文档中用mkdocs-include-markdown-plugin插件引入生成的文件：
   • 安装插件：pip install mkdocs-include-markdown-plugin
   • 在mkdocs.yml中启用：

     plugins:
       - include-markdown
     

   • 在Markdown中引入：

     ### 程序命令行参数
     {% include "./cli-args.md" %}
     

这种方式适合需要对生成的表格做额外编辑（如添加备注），或者文档构建环境无法直接运行你的程序的场景。

注意事项 #

• 无论采用哪种方案，都要确保构建环境能正常运行你的程序，或在构建前完成编译/安装步骤。
• 解析--help的脚本需适配你程序的输出格式，不同语言框架生成的--help格式存在差异，需针对性调整正则或解析逻辑。

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