使用Slate时，如何让includes内容添加到文档开头而非末尾？

这里有几种可行的方案，按操作复杂度排序：

方案1：预处理Markdown文件（最简单） #

Widdershins生成Markdown后，直接用脚本把你的引言文件内容拼接到生成文件的开头，再交给Slate处理：

• 用shell命令快速合并：

  cat your-intro.md generated-by-widdershins.md > combined.md
  

• 如果是自动化构建场景，也可以用Node.js/Python写个简单脚本完成合并逻辑。

方案2：自定义Widdershins模板 #

Widdershins基于Nunjucks模板生成Markdown，你可以修改模板逻辑，把includes内容放到文档开头：

1. 找到Widdershins的默认模板（通常在node_modules/widdershins/templates/main.md.njk），复制一份到本地目录，命名为custom-template.md.njk
2. 在自定义模板的最顶部添加引入includes文件的代码，再保留原模板的所有内容：

   {% for include in includes %}
   {% include include %}
   {% endfor %}
   
   {# 以下为原模板内容 #}
   # {{ info.title | safe }}
   {% if info.description %}
   {{ info.description | markdownify }}
   {% endif %}
   ...
   

3. 运行Widdershins时指定自定义模板：

   widdershins --template custom-template.md.njk your-openapi-spec.yaml -o output.md
   

方案3：修改Slate的入口模板 #

如果想在Slate层面统一控制开头内容，可以直接修改Slate的入口模板：

1. 打开Slate项目的source/index.html.md.erb文件
2. 在文件最开头添加引言内容，或者用ERB语法引入本地的引言文件：

   <%= File.read(File.join(__dir__, 'intro.md')) %>
   
   {# 保留原有的Widdershins生成文件引入逻辑 #}
   <%= File.read(File.join(__dir__, 'generated-api.md')) %>
   

3. 重新构建Slate站点即可生效。

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