如何向Docfx中被包含的文件传递参数？

Docfx原生的[!include[]()]语法确实不支持直接传递参数，但我们可以通过两种可靠的方法实现你想要的类似Jekyll带变量的include效果：

方法1：启用Liquid模板支持（推荐） #

Docfx从v2.59版本开始支持Liquid模板引擎，借助它可以轻松实现带参数的文件引用：

1. 先配置Docfx启用Liquid
   在你的docfx.json的build节点下添加Liquid启用配置：

   "build": {
     "markdownEngineOptions": {
       "enableLiquid": true
     },
     // 保留你的其他构建配置
   }
   

2. 组织文件结构
   在Docfx项目的根目录创建templates/includes文件夹，把需要被包含的file2.md放在这里：

   your-docfx-project/
   ├── templates/
   │   └── includes/
   │       └── file2.md
   ├── docfx.json
   └── 你的主文档.md
   

3. 在主文档中带参数引用
   在主文档里用Liquid的include语法传递参数：

   {% include "includes/file2.md" name: "x" %}
   

4. 在被包含文件中使用参数
   file2.md的内容保持你想要的变量形式：

   # Hi {{name}}
   

   这样构建后，主文档里会渲染出# Hi x的内容。如果需要传递多个参数，直接在include里追加即可，比如{% include "includes/file2.md" name: "x", age: 30 %}，然后在file2.md里用{{age}}引用。

方法2：用预处理器脚本自定义替换 #

如果你的Docfx版本较低，或者不想依赖Liquid，可以写一个简单的预处理器脚本（比如Node.js/PowerShell），在Docfx构建前完成变量替换：

1. 定义自定义include语法
   在主文档里用自定义标记，比如：

   {% includeParam "file2.md" {"name": "x"} %}
   

2. 编写预处理器脚本
   以Node.js为例，写一个脚本扫描所有md文件，匹配自定义标记，读取目标文件内容，替换{{name}}为对应参数值，再把替换后的内容写回主文件。

3. 把脚本加入构建流程
   在docfx.json的build节点里添加prebuild命令，让Docfx构建前先执行脚本：

   "build": {
     "prebuild": "node preprocess-includes.js",
     // 其他配置
   }
   

注意事项 #

• 使用Liquid时，如果你的文档里本来就有{{}}格式的内容（比如代码示例），需要用{% raw %}...{% endraw %}包裹，避免被Liquid解析：

  {% raw %}
  这是不会被解析的代码：{{example}}
  {% endraw %}
  

• 用预处理器脚本时，要注意处理文件路径的正确性，避免找不到被包含的文件。

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